lib/librte_cmdline/cmdline_parse.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
   5  *   All rights reserved.
   6  *
   7  *   Redistribution and use in source and binary forms, with or without
   8  *   modification, are permitted provided that the following conditions
   9  *   are met:
  10  *
  11  *     * Redistributions of source code must retain the above copyright
  12  *       notice, this list of conditions and the following disclaimer.
  13  *     * Redistributions in binary form must reproduce the above copyright
  14  *       notice, this list of conditions and the following disclaimer in
  15  *       the documentation and/or other materials provided with the
  16  *       distribution.
  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 FOR
  24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  32  */
  33
  34 /*
  35  * Copyright (c) 2009, Olivier MATZ <zer0@droids-corp.org>
  36  * All rights reserved.
  37  * Redistribution and use in source and binary forms, with or without
  38  * modification, are permitted provided that the following conditions are met:
  39  *
  40  *     * Redistributions of source code must retain the above copyright
  41  *       notice, this list of conditions and the following disclaimer.
  42  *     * Redistributions in binary form must reproduce the above copyright
  43  *       notice, this list of conditions and the following disclaimer in the
  44  *       documentation and/or other materials provided with the distribution.
  45  *     * Neither the name of the University of California, Berkeley nor the
  46  *       names of its contributors may be used to endorse or promote products
  47  *       derived from this software without specific prior written permission.
  48  *
  49  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  50  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  51  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  52  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  53  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  54  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  55  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  56  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  57  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  58  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  59  */
  60
  61 #ifndef _CMDLINE_PARSE_H_
  62 #define _CMDLINE_PARSE_H_
  63
  64 #ifdef __cplusplus
  65 extern "C" {
  66 #endif
  67
  68 #ifndef offsetof
  69 #define offsetof(type, field)  ((size_t) &( ((type *)0)->field) )
  70 #endif
  71
  72 /* return status for parsing */
  73 #define CMDLINE_PARSE_SUCCESS        0
  74 #define CMDLINE_PARSE_AMBIGUOUS     -1
  75 #define CMDLINE_PARSE_NOMATCH       -2
  76 #define CMDLINE_PARSE_BAD_ARGS      -3
  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 /* maximum buffer size for parsed result */
  84 #define CMDLINE_PARSE_RESULT_BUFSIZE 8192
  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). It returns the number of
 102  * parsed chars on success and a negative value on error.
 103  *
 104  * complete_get_nb() returns the number of possible values for this
 105  * token if completion is possible. If it is NULL or if it returns 0,
 106  * no completion is possible.
 107  *
 108  * complete_get_elt() copy in dstbuf (the size is specified in the
 109  * parameter) the i-th possible completion for this token.  returns 0
 110  * on success or and a negative value on error.
 111  *
 112  * get_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, buf len) */
 117         int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *,
 118                 unsigned int);
 119         /** return the num of possible choices for this token */
 120         int (*complete_get_nb)(cmdline_parse_token_hdr_t *);
 121         /** return the elt x for this token (token, idx, dstbuf, size) */
 122         int (*complete_get_elt)(cmdline_parse_token_hdr_t *, int, char *,
 123                 unsigned int);
 124         /** get help for this token (token, dstbuf, size) */
 125         int (*get_help)(cmdline_parse_token_hdr_t *, char *, unsigned int);
 126 };
 127
 128 struct cmdline;
 129 /**
 130  * Store a instruction, which is a pointer to a callback function and
 131  * its parameter that is called when the instruction is parsed, a help
 132  * string, and a list of token composing this instruction.
 133  *
 134  * When no tokens are defined (tokens[0] == NULL), they are retrieved
 135  * dynamically by calling f() as follows:
 136  *
 137  * @code
 138  *
 139  * f((struct cmdline_token_hdr **)&token_p,
 140  *   NULL,
 141  *   (struct cmdline_token_hdr **)&inst->tokens[num]);
 142  *
 143  * @endcode
 144  *
 145  * The address of the resulting token is expected at the location pointed by
 146  * the first argument. Can be set to NULL to end the list.
 147  *
 148  * The cmdline argument (struct cmdline *) is always NULL.
 149  *
 150  * The last argument points to the inst->tokens[] entry to retrieve, which
 151  * is not necessarily inside allocated memory and should neither be read nor
 152  * written. Its sole purpose is to deduce the token entry index of interest
 153  * as described in the example below.
 154  *
 155  * Note about constraints:
 156  *
 157  * - Only the address of these tokens is dynamic, their storage should be
 158  *   static like normal tokens.
 159  * - Dynamic token lists that need to maintain an internal context (e.g. in
 160  *   order to determine the next token) must store it statically also. This
 161  *   context must be reinitialized when the first token is requested, that
 162  *   is, when &inst->tokens[0] is provided as the third argument.
 163  * - Dynamic token lists must be NULL-terminated to generate usable
 164  *   commands.
 165  *
 166  * @code
 167  *
 168  * // Assuming first and third arguments are respectively named "token_p"
 169  * // and "token":
 170  *
 171  * int index = token - inst->tokens;
 172  *
 173  * if (!index) {
 174  *     [...] // Clean up internal context if any.
 175  * }
 176  * [...] // Then set up dyn_token according to index.
 177  *
 178  * if (no_more_tokens)
 179  *     *token_p = NULL;
 180  * else
 181  *     *token_p = &dyn_token;
 182  *
 183  * @endcode
 184  */
 185 struct cmdline_inst {
 186         /* f(parsed_struct, data) */
 187         void (*f)(void *, struct cmdline *, void *);
 188         void *data;
 189         const char *help_str;
 190         cmdline_parse_token_hdr_t *tokens[];
 191 };
 192 typedef struct cmdline_inst cmdline_parse_inst_t;
 193
 194 /**
 195  * A context is identified by its name, and contains a list of
 196  * instruction
 197  *
 198  */
 199 typedef cmdline_parse_inst_t *cmdline_parse_ctx_t;
 200
 201 /**
 202  * Try to parse a buffer according to the specified context. The
 203  * argument buf must ends with "\n\0". The function returns
 204  * CMDLINE_PARSE_AMBIGUOUS, CMDLINE_PARSE_NOMATCH or
 205  * CMDLINE_PARSE_BAD_ARGS on error. Else it calls the associated
 206  * function (defined in the context) and returns 0
 207  * (CMDLINE_PARSE_SUCCESS).
 208  */
 209 int cmdline_parse(struct cmdline *cl, const char *buf);
 210
 211 /**
 212  * complete() must be called with *state==0 (try to complete) or
 213  * with *state==-1 (just display choices), then called without
 214  * modifying *state until it returns CMDLINE_PARSE_COMPLETED_BUFFER or
 215  * CMDLINE_PARSE_COMPLETED_BUFFER.
 216  *
 217  * It returns < 0 on error.
 218  *
 219  * Else it returns:
 220  *   - CMDLINE_PARSE_COMPLETED_BUFFER on completion (one possible
 221  *     choice). In this case, the chars are appended in dst buffer.
 222  *   - CMDLINE_PARSE_COMPLETE_AGAIN if there is several possible
 223  *     choices. In this case, you must call the function again,
 224  *     keeping the value of state intact.
 225  *   - CMDLINE_PARSE_COMPLETED_BUFFER when the iteration is
 226  *     finished. The dst is not valid for this last call.
 227  *
 228  * The returned dst buf ends with \0.
 229  */
 230 int cmdline_complete(struct cmdline *cl, const char *buf, int *state,
 231                      char *dst, unsigned int size);
 232
 233
 234 /* return true if(!c || iscomment(c) || isblank(c) ||
 235  * isendofline(c)) */
 236 int cmdline_isendoftoken(char c);
 237
 238 /* return true if(!c || iscomment(c) || isendofline(c)) */
 239 int cmdline_isendofcommand(char c);
 240
 241 #ifdef __cplusplus
 242 }
 243 #endif
 244
 245 #endif /* _CMDLINE_PARSE_H_ */