src/lib/cmdline_parse.h

   1 /*
   2  * Copyright (c) 2009, Olivier MATZ <zer0@droids-corp.org>
   3  * All rights reserved.
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are met:
   6  *
   7  *     * Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *     * Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *     * Neither the name of the University of California, Berkeley nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY
  17  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS AND CONTRIBUTORS BE LIABLE FOR ANY
  20  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27
  28 #ifndef _CMDLINE_PARSE_H_
  29 #define _CMDLINE_PARSE_H_
  30
  31 #include <sys/types.h>
  32
  33 #ifndef offsetof
  34 #define offsetof(type, field)  ((size_t) &( ((type *)0)->field) )
  35 #endif
  36
  37 /* return status for parsing */
  38 #define CMDLINE_PARSE_SUCCESS        0
  39 #define CMDLINE_PARSE_AMBIGUOUS     -1
  40 #define CMDLINE_PARSE_NOMATCH       -2
  41 #define CMDLINE_PARSE_BAD_ARGS      -3
  42
  43 /* return status for completion */
  44 #define CMDLINE_PARSE_COMPLETE_FINISHED 0
  45 #define CMDLINE_PARSE_COMPLETE_AGAIN    1
  46 #define CMDLINE_PARSE_COMPLETED_BUFFER  2
  47
  48 /**
  49  * Stores a pointer to the ops struct, and the offset: the place to
  50  * write the parsed result in the destination structure.
  51  */
  52 struct cmdline_token_hdr {
  53         struct cmdline_token_ops *ops;
  54         unsigned int offset;
  55 };
  56 typedef struct cmdline_token_hdr cmdline_parse_token_hdr_t;
  57
  58 /**
  59  * A token is defined by this structure.
  60  *
  61  * parse() takes the token as first argument, then the source buffer
  62  * starting at the token we want to parse. The 3rd arg is a pointer
  63  * where we store the parsed data (as binary). It returns the number of
  64  * parsed chars on success and a negative value on error.
  65  *
  66  * complete_get_nb() returns the number of possible values for this
  67  * token if completion is possible. If it is NULL or if it returns 0,
  68  * no completion is possible.
  69  *
  70  * complete_get_elt() copy in dstbuf (the size is specified in the
  71  * parameter) the i-th possible completion for this token.  returns 0
  72  * on success or and a negative value on error.
  73  *
  74  * get_help() fills the dstbuf with the help for the token. It returns
  75  * -1 on error and 0 on success.
  76  */
  77 struct cmdline_token_ops {
  78         /** parse(token ptr, buf, res pts) */
  79         int (*parse)(cmdline_parse_token_hdr_t *, const char *, void *);
  80         /** return the num of possible choices for this token */
  81         int (*complete_get_nb)(cmdline_parse_token_hdr_t *);
  82         /** return the elt x for this token (token, idx, dstbuf, size) */
  83         int (*complete_get_elt)(cmdline_parse_token_hdr_t *, int, char *, unsigned int);
  84         /** get help for this token (token, dstbuf, size) */
  85         int (*get_help)(cmdline_parse_token_hdr_t *, char *, unsigned int);
  86 };
  87
  88 struct cmdline;
  89 /**
  90  * Store a instruction, which is a pointer to a callback function and
  91  * its parameter that is called when the instruction is parsed, a help
  92  * string, and a list of token composing this instruction.
  93  */
  94 struct cmdline_inst {
  95         /* f(parsed_struct, data) */
  96         void (*f)(void *, struct cmdline *, void *);
  97         void *data;
  98         char *help_str;
  99         cmdline_parse_token_hdr_t *tokens[];
 100 };
 101 typedef struct cmdline_inst cmdline_parse_inst_t;
 102
 103 /**
 104  * A context is identified by its name, and contains a list of
 105  * instruction
 106  *
 107  */
 108 typedef cmdline_parse_inst_t *cmdline_parse_ctx_t;
 109
 110 /**
 111  * Try to parse a buffer according to the specified context. The
 112  * argument buf must ends with "\n\0". The function returns
 113  * CMDLINE_PARSE_AMBIGUOUS, CMDLINE_PARSE_NOMATCH or
 114  * CMDLINE_PARSE_BAD_ARGS on error. Else it calls the associated
 115  * function (defined in the context) and returns 0
 116  * (CMDLINE_PARSE_SUCCESS).
 117  */
 118 int cmdline_parse(struct cmdline *cl, const char *buf);
 119
 120 /**
 121  * complete() must be called with *state==0 (try to complete) or
 122  * with *state==-1 (just display choices), then called without
 123  * modifying *state until it returns CMDLINE_PARSE_COMPLETED_BUFFER or
 124  * CMDLINE_PARSE_COMPLETED_BUFFER.
 125  *
 126  * It returns < 0 on error.
 127  *
 128  * Else it returns:
 129  *   - CMDLINE_PARSE_COMPLETED_BUFFER on completion (one possible
 130  *     choice). In this case, the chars are appended in dst buffer.
 131  *   - CMDLINE_PARSE_COMPLETE_AGAIN if there is several possible
 132  *     choices. In this case, you must call the function again,
 133  *     keeping the value of state intact.
 134  *   - CMDLINE_PARSE_COMPLETED_BUFFER when the iteration is
 135  *     finished. The dst is not valid for this last call.
 136  *
 137  * The returned dst buf ends with \0.
 138  */
 139 int cmdline_complete(struct cmdline *cl, const char *buf, int *state,
 140                      char *dst, unsigned int size);
 141
 142
 143 /* return true if(!c || iscomment(c) || isblank(c) ||
 144  * isendofline(c)) */
 145 int cmdline_isendoftoken(char c);
 146
 147 #endif /* _CMDLINE_PARSE_H_ */