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 /* return status for parsing */
  72 #define CMDLINE_PARSE_SUCCESS        0
  73 #define CMDLINE_PARSE_AMBIGUOUS     -1
  74 #define CMDLINE_PARSE_NOMATCH       -2
  75 #define CMDLINE_PARSE_BAD_ARGS      -3
  76 #define CMDLINE_PARSE_UNTERMINATED_QUOTE -4
  77
  78 /* return status for completion */
  79 #define CMDLINE_PARSE_COMPLETE_FINISHED 0
  80 #define CMDLINE_PARSE_COMPLETE_AGAIN    1
  81 #define CMDLINE_PARSE_COMPLETED_BUFFER  2
  82
  83 #define CMDLINE_MAX_TOKEN_SIZE 128 /* including '\0' */
  84 #define CMDLINE_MAX_DSTBUF_SIZE 1024
  85
  86 /**
  87  * Stores a pointer to the ops struct, and the offset: the place to
  88  * write the parsed result in the destination structure.
  89  */
  90 struct cmdline_token_hdr {
  91         struct cmdline_token_ops *ops;
  92         unsigned int offset;
  93 };
  94 typedef struct cmdline_token_hdr cmdline_parse_token_hdr_t;
  95
  96 /**
  97  * A token is defined by this structure.
  98  *
  99  * parse() takes the token as first argument, then the source buffer
 100  * starting at the token we want to parse. The 3rd arg is a pointer
 101  * where we store the parsed data (as binary), and the 4th arg is the
 102  * size of this area. It returns 0 on success and a negative value on
 103  * error.
 104  *
 105  * complete_get_nb() returns the number of possible values for this
 106  * token if completion is possible. If it is NULL or if it returns 0,
 107  * no completion is possible.
 108  *
 109  * complete_get_elt() copy in dstbuf (the size is specified in the
 110  * parameter) the i-th possible completion for this token. Return 0
 111  * on success or a negative value on error.
 112  *
 113  * get_help() fills the dstbuf with the help for the token. It returns
 114  * -1 on error and 0 on success.
 115  */
 116 struct cmdline_token_ops {
 117         /** parse(token ptr, buf, res pts) */
 118         int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *,
 119                      unsigned int);
 120         /** return the num of possible choices for this token */
 121         int (*complete_get_nb)(cmdline_parse_token_hdr_t *);
 122         /** return the elt x for this token (token, idx, dstbuf, size) */
 123         int (*complete_get_elt)(cmdline_parse_token_hdr_t *, int, char *,
 124                                 unsigned int);
 125         /** get help for this token (token, dstbuf, size) */
 126         int (*get_help)(cmdline_parse_token_hdr_t *, char *, unsigned int);
 127 };
 128
 129 struct cmdline;
 130 /**
 131  * Store a instruction, which is a pointer to a callback function and
 132  * its parameter that is called when the instruction is parsed, a help
 133  * string, and a list of token composing this instruction.
 134  */
 135 struct cmdline_inst {
 136         /* f(parsed_struct, data) */
 137         void (*f)(void *, struct cmdline *, void *);
 138         void *data;
 139         char *help_str;
 140         cmdline_parse_token_hdr_t *tokens[];
 141 };
 142 typedef struct cmdline_inst cmdline_parse_inst_t;
 143
 144 /**
 145  * A context is identified by its name, and contains a list of
 146  * instruction
 147  *
 148  */
 149 typedef cmdline_parse_inst_t *cmdline_parse_ctx_t;
 150
 151 /**
 152  * Try to parse a buffer according to the specified context. The
 153  * argument buf must ends with "\n\0". The function returns
 154  * CMDLINE_PARSE_AMBIGUOUS, CMDLINE_PARSE_NOMATCH or
 155  * CMDLINE_PARSE_BAD_ARGS on error. Else it calls the associated
 156  * function (defined in the context) and returns 0
 157  * (CMDLINE_PARSE_SUCCESS).
 158  */
 159 int cmdline_parse(struct cmdline *cl, const char *buf);
 160
 161 /**
 162  * complete() must be called with *state==0 (try to complete) or
 163  * with *state==-1 (just display choices), then called without
 164  * modifying *state until it returns CMDLINE_PARSE_COMPLETED_BUFFER or
 165  * CMDLINE_PARSE_COMPLETED_BUFFER.
 166  *
 167  * It returns < 0 on error.
 168  *
 169  * Else it returns:
 170  *   - CMDLINE_PARSE_COMPLETED_BUFFER on completion (one possible
 171  *     choice). In this case, the chars are appended in dst buffer.
 172  *   - CMDLINE_PARSE_COMPLETE_AGAIN if there is several possible
 173  *     choices. In this case, you must call the function again,
 174  *     keeping the value of state intact.
 175  *   - CMDLINE_PARSE_COMPLETED_BUFFER when the iteration is
 176  *     finished. The dst is not valid for this last call.
 177  *
 178  * The returned dst buf ends with \0.
 179  */
 180 int cmdline_complete(struct cmdline *cl, const char *buf, int *state,
 181                      char *dst, unsigned int size);
 182
 183
 184 /* return true if(!c || iscomment(c) || isblank(c) ||
 185  * isendofline(c)) */
 186 int cmdline_isendoftoken(char c);
 187
 188 /* quote a string and escape original quotes */
 189 int cmdline_quote_token(char *dst, unsigned dstlen, const char *src);
 190
 191 /* remove quote and stop when we reach the end of token */
 192 int cmdline_unquote_token(char *dst, unsigned dstlen, const char *src);
 193
 194 #endif /* _CMDLINE_PARSE_H_ */