rdline: save return status before paging, and return it once finished
[libcmdline.git] / 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_ */