src/lib/cmdline_parse.h

   1 /*-
   2  * Copyright (c) <2010>, Intel Corporation
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * - Redistributions of source code must retain the above copyright
  10  *   notice, this list of conditions and the following disclaimer.
  11  *
  12  * - Redistributions in binary form must reproduce the above copyright
  13  *   notice, this list of conditions and the following disclaimer in
  14  *   the documentation and/or other materials provided with the
  15  *   distribution.
  16  *
  17  * - Neither the name of Intel Corporation nor the names of its
  18  *   contributors may be used to endorse or promote products derived
  19  *   from this software without specific prior written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  27  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  28  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  30  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  31  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  32  * OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 /*
  36  * Copyright (c) 2009, Olivier MATZ <zer0@droids-corp.org>
  37  * All rights reserved.
  38  * Redistribution and use in source and binary forms, with or without
  39  * modification, are permitted provided that the following conditions are met:
  40  *
  41  *     * Redistributions of source code must retain the above copyright
  42  *       notice, this list of conditions and the following disclaimer.
  43  *     * Redistributions in binary form must reproduce the above copyright
  44  *       notice, this list of conditions and the following disclaimer in the
  45  *       documentation and/or other materials provided with the distribution.
  46  *     * Neither the name of the University of California, Berkeley nor the
  47  *       names of its contributors may be used to endorse or promote products
  48  *       derived from this software without specific prior written permission.
  49  *
  50  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  51  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  52  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  53  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  54  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  55  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  56  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  57  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  58  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  59  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  60  */
  61
  62 #ifndef _CMDLINE_PARSE_H_
  63 #define _CMDLINE_PARSE_H_
  64
  65 #include <sys/types.h>
  66
  67 #ifndef offsetof
  68 #define offsetof(type, field)  ((size_t) &( ((type *)0)->field) )
  69 #endif
  70
  71 #define CMDLINE_MAX_TOKEN_SIZE 128 /* including '\0' */
  72 #define CMDLINE_MAX_DSTBUF_SIZE 1024
  73
  74 /**
  75  * Stores a pointer to the ops struct, and the offset: the place to
  76  * write the parsed result in the destination structure.
  77  */
  78 struct cmdline_token_hdr {
  79         struct cmdline_token_ops *ops;
  80         unsigned int offset;
  81 };
  82 typedef struct cmdline_token_hdr cmdline_parse_token_hdr_t;
  83
  84 /**
  85  * A token is defined by this structure.
  86  *
  87  * parse() takes the token as first argument, then the source buffer
  88  * containing the token we want to parse. The 3rd arg is a pointer
  89  * where we store the parsed data (as binary), and the 4th arg is the
  90  * size of this area. It returns 0 on success and a negative value on
  91  * error.
  92  *
  93  * complete_start() prepares a completion operation. The first
  94  * argument is the token to complete. The second argument is the token
  95  * to complete, and the third arg is an opaque pointer that will be
  96  * given to complete_iterate() function. It can be used to store
  97  * private data for this completion. For each complete_start() call,
  98  * the user must call complete_end() at the end of iterations (if
  99  * defined). Return a negative value if completion is not possible, or
 100  * 0 on success.
 101  *
 102  * complete_iterate() copy in dstbuf (the size is specified in the
 103  * parameter) the next possible completion for this token. Return 0 on
 104  * success (final completion), 1 if it's an intermediate completion,
 105  * or a negative value on error (or when there is no more
 106  * completion). Refer to cmdline_complete_string_iterate() for an
 107  * example.
 108  *
 109  * complete_end() is called when the iteration on this token is finished,
 110  * this function should free all things allocated during complete_start().
 111  *
 112  * help() fills the dstbuf with the help for the token. It returns
 113  * -1 on error and 0 on success.
 114  */
 115 struct cmdline_token_ops {
 116         /** parse(token ptr, buf, res pts) */
 117         int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *,
 118                      unsigned int);
 119         /** prepare a completion on this token */
 120         int (*complete_start)(cmdline_parse_token_hdr_t *, const char *,
 121                               void **);
 122         /** fill dstbuf for this token (token, opaque, dstbuf, size) */
 123         int (*complete_iterate)(cmdline_parse_token_hdr_t *, void **, char *,
 124                                 unsigned int);
 125         /* end of completion, used to free the opaque structure */
 126         void (*complete_end)(cmdline_parse_token_hdr_t *, void **);
 127         /** get help for this token (token, dstbuf, size) */
 128         int (*help)(cmdline_parse_token_hdr_t *, char *, unsigned int);
 129 };
 130
 131 struct cmdline;
 132 /**
 133  * Store a instruction, which is a pointer to a callback function and
 134  * its parameter that is called when the instruction is parsed, a help
 135  * string, and a list of token composing this instruction.
 136  */
 137 struct cmdline_inst {
 138         /* f(parsed_struct, data) */
 139         void (*f)(void *, struct cmdline *, void *);
 140         void *data;
 141         char *help_str;
 142         cmdline_parse_token_hdr_t *tokens[];
 143 };
 144 typedef struct cmdline_inst cmdline_parse_inst_t;
 145
 146 /**
 147  * A context is identified by its name, and contains a list of
 148  * instruction
 149  *
 150  */
 151 struct cmdline_parse_ctx {
 152         const char *name;
 153         cmdline_parse_inst_t *insts[];
 154 };
 155 typedef struct cmdline_parse_ctx cmdline_parse_ctx_t;
 156
 157 /* return status for parsing */
 158 #define CMDLINE_PARSE_SUCCESS        0
 159 #define CMDLINE_PARSE_EMPTY         -1
 160 #define CMDLINE_PARSE_NOMATCH       -2
 161 #define CMDLINE_PARSE_AMBIGUOUS     -3
 162 #define CMDLINE_PARSE_UNTERMINATED_QUOTE -4
 163
 164 /**
 165  * Try to parse a buffer according to the specified context. The
 166  * argument linebuf must end with "\n\0".
 167  *
 168  * The function returns:
 169  * - CMDLINE_PARSE_SUCCESS (0) on success
 170  * - CMDLINE_PARSE_EMPTY if there is nothing to parse
 171  * - CMDLINE_PARSE_NOMATCH if line does not match any command
 172  * - CMDLINE_PARSE_AMBIGUOUS if several commands match
 173  * - CMDLINE_PARSE_UNTERMINATED_QUOTE if a quote is used incorrectly
 174  */
 175 int cmdline_parse(cmdline_parse_ctx_t *ctx, const char *linebuf, void *opaque);
 176
 177 /* return status for completion */
 178 #define CMDLINE_COMPLETE_APPEND    0
 179 #define CMDLINE_COMPLETE_NONE     -1
 180 #define CMDLINE_COMPLETE_MANY     -2
 181
 182 /**
 183  * cmdline_complete() tries to complete the buffer given as a parameter.
 184  *
 185  * It returns:
 186  *   - CMDLINE_COMPLETE_APPEND (0) on success, when a completion is
 187  *     done (one possible choice). In this case, the chars are
 188  *     appended in dst buffer.
 189  *   - CMDLINE_COMPLETE_NONE: error, no possible completion
 190  *   - CMDLINE_COMPLETE_MANY: error, many possble completions, need to call
 191  *     cmdline_help() function to see all the possibilities.
 192  */
 193 int cmdline_complete(cmdline_parse_ctx_t *ctx, const char *buf,
 194                      char *dst, unsigned int size);
 195
 196 /**
 197  * callback given to rdline_help() to display the content of the
 198  * help. The first argument is an opaque pointer. The other args
 199  * are buffer and size.
 200  */
 201 typedef ssize_t (cmdline_write_t)(void *, void *, size_t);
 202
 203 /**
 204  * Display a contextual help using the write_buf() function pointer
 205  * given as parameter (called with its opaque pointer). The contextual
 206  * help depends on the buffer given.
 207  */
 208 int cmdline_help(cmdline_parse_ctx_t *ctx, const char *buf,
 209                  cmdline_write_t *write_buf, void *opaque);
 210
 211 /* return true if(!c || iscomment(c) || isblank(c) ||
 212  * isendofline(c)) */
 213 int cmdline_isendoftoken(char c);
 214
 215 /* quote a string and escape original quotes */
 216 int cmdline_quote_token(char *dst, unsigned dstlen, const char *src);
 217
 218 /* remove quote and stop when we reach the end of token */
 219 int cmdline_unquote_token(char *dst, unsigned dstlen, const char *src);
 220
 221 #endif /* _CMDLINE_PARSE_H_ */