05d79c4a7d899d5c519f908853c70bfa9895221c
[openocd.git] / src / helper / jim-nvp.h
1 /* Jim - A small embeddable Tcl interpreter
2 *
3 * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
4 * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
5 * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
6 * Copyright 2008 oharboe - √ėyvind Harboe - oyvind.harboe@zylin.com
7 * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
8 * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
9 * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
10 * Copyright 2008 Steve Bennett <steveb@workware.net.au>
11 * Copyright 2009 Nico Coesel <ncoesel@dealogic.nl>
12 * Copyright 2009 Zachary T Welch zw@superlucidity.net
13 * Copyright 2009 David Brownell
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 *
19 * 1. Redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer.
21 * 2. Redistributions in binary form must reproduce the above
22 * copyright notice, this list of conditions and the following
23 * disclaimer in the documentation and/or other materials
24 * provided with the distribution.
25 *
26 * THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
27 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
28 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
29 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
30 * JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
31 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
32 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
33 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
34 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
35 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
37 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 *
39 * The views and conclusions contained in the software and documentation
40 * are those of the authors and should not be interpreted as representing
41 * official policies, either expressed or implied, of the Jim Tcl Project.
42 */
43
44 #ifndef JIM_NVP_H
45 #define JIM_NVP_H
46
47 #include <jim.h>
48
49 /** Name Value Pairs, aka: NVP
50 * - Given a string - return the associated int.
51 * - Given a number - return the associated string.
52 * .
53 *
54 * Very useful when the number is not a simple index into an array of
55 * known string, or there may be multiple strings (aliases) that mean then same
56 * thing.
57 *
58 * An NVP Table is terminated with ".name = NULL".
59 *
60 * During the 'name2value' operation, if no matching string is found
61 * the pointer to the terminal element (with p->name == NULL) is returned.
62 *
63 * Example:
64 * \code
65 * const Jim_Nvp yn[] = {
66 * { "yes", 1 },
67 * { "no" , 0 },
68 * { "yep", 1 },
69 * { "nope", 0 },
70 * { NULL, -1 },
71 * };
72 *
73 * Jim_Nvp *result
74 * e = Jim_Nvp_name2value(interp, yn, "y", &result);
75 * returns &yn[0];
76 * e = Jim_Nvp_name2value(interp, yn, "n", &result);
77 * returns &yn[1];
78 * e = Jim_Nvp_name2value(interp, yn, "Blah", &result);
79 * returns &yn[4];
80 * \endcode
81 *
82 * During the number2name operation, the first matching value is returned.
83 */
84 typedef struct {
85 const char *name;
86 int value;
87 } Jim_Nvp;
88
89 int Jim_GetNvp(Jim_Interp *interp,
90 Jim_Obj *objPtr,
91 const Jim_Nvp *nvp_table,
92 const Jim_Nvp **result);
93
94 /* Name Value Pairs Operations */
95 Jim_Nvp *Jim_Nvp_name2value_simple(const Jim_Nvp *nvp_table, const char *name);
96 Jim_Nvp *Jim_Nvp_name2value_nocase_simple(const Jim_Nvp *nvp_table, const char *name);
97 Jim_Nvp *Jim_Nvp_value2name_simple(const Jim_Nvp *nvp_table, int v);
98
99 int Jim_Nvp_name2value(Jim_Interp *interp,
100 const Jim_Nvp *nvp_table,
101 const char *name,
102 Jim_Nvp **result);
103 int Jim_Nvp_name2value_nocase(Jim_Interp *interp,
104 const Jim_Nvp *nvp_table,
105 const char *name,
106 Jim_Nvp **result);
107 int Jim_Nvp_value2name(Jim_Interp *interp, const Jim_Nvp *nvp_table, int value, Jim_Nvp **result);
108
109 int Jim_Nvp_name2value_obj(Jim_Interp *interp,
110 const Jim_Nvp *nvp_table,
111 Jim_Obj *name_obj,
112 Jim_Nvp **result);
113 int Jim_Nvp_name2value_obj_nocase(Jim_Interp *interp,
114 const Jim_Nvp *nvp_table,
115 Jim_Obj *name_obj,
116 Jim_Nvp **result);
117 int Jim_Nvp_value2name_obj(Jim_Interp *interp,
118 const Jim_Nvp *nvp_table,
119 Jim_Obj *value_obj,
120 Jim_Nvp **result);
121
122 /** prints a nice 'unknown' parameter error message to the 'result' */
123 void Jim_SetResult_NvpUnknown(Jim_Interp *interp,
124 Jim_Obj *param_name,
125 Jim_Obj *param_value,
126 const Jim_Nvp *nvp_table);
127
128 /** Debug: convert argc/argv into a printable string for printf() debug
129 *
130 * \param interp - the interpeter
131 * \param argc - arg count
132 * \param argv - the objects
133 *
134 * \returns string pointer holding the text.
135 *
136 * Note, next call to this function will free the old (last) string.
137 *
138 * For example might want do this:
139 * \code
140 * fp = fopen("some.file.log", "a");
141 * fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
142 * fclose(fp);
143 * \endcode
144 */
145 const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
146
147
148 /** A TCL -ish GetOpt like code.
149 *
150 * Some TCL objects have various "configuration" values.
151 * For example - in Tcl/Tk the "buttons" have many options.
152 *
153 * Usefull when dealing with command options.
154 * that may come in any order...
155 *
156 * Does not support "-foo = 123" type options.
157 * Only supports tcl type options, like "-foo 123"
158 */
159
160 typedef struct jim_getopt {
161 Jim_Interp *interp;
162 int argc;
163 Jim_Obj *const *argv;
164 int isconfigure; /* non-zero if configure */
165 } Jim_GetOptInfo;
166
167 /** GetOpt - how to.
168 *
169 * Example (short and incomplete):
170 * \code
171 * Jim_GetOptInfo goi;
172 *
173 * Jim_GetOpt_Setup(&goi, interp, argc, argv);
174 *
175 * while (goi.argc) {
176 * e = Jim_GetOpt_Nvp(&goi, nvp_options, &n);
177 * if (e != JIM_OK) {
178 * Jim_GetOpt_NvpUnknown(&goi, nvp_options, 0);
179 * return e;
180 * }
181 *
182 * switch (n->value) {
183 * case ALIVE:
184 * printf("Option ALIVE specified\n");
185 * break;
186 * case FIRST:
187 * if (goi.argc < 1) {
188 * .. not enough args error ..
189 * }
190 * Jim_GetOpt_String(&goi, &cp, NULL);
191 * printf("FIRSTNAME: %s\n", cp);
192 * case AGE:
193 * Jim_GetOpt_Wide(&goi, &w);
194 * printf("AGE: %d\n", (int)(w));
195 * break;
196 * case POLITICS:
197 * e = Jim_GetOpt_Nvp(&goi, nvp_politics, &n);
198 * if (e != JIM_OK) {
199 * Jim_GetOpt_NvpUnknown(&goi, nvp_politics, 1);
200 * return e;
201 * }
202 * }
203 * }
204 *
205 * \endcode
206 *
207 */
208
209 /** Setup GETOPT
210 *
211 * \param goi - get opt info to be initialized
212 * \param interp - jim interp
213 * \param argc - argc count.
214 * \param argv - argv (will be copied)
215 *
216 * \code
217 * Jim_GetOptInfo goi;
218 *
219 * Jim_GetOptSetup(&goi, interp, argc, argv);
220 * \endcode
221 */
222
223 int Jim_GetOpt_Setup(Jim_GetOptInfo *goi,
224 Jim_Interp *interp,
225 int argc,
226 Jim_Obj *const *argv);
227
228
229 /** Debug - Dump parameters to stderr
230 * \param goi - current parameters
231 */
232 void Jim_GetOpt_Debug(Jim_GetOptInfo *goi);
233
234 /** Remove argv[0] from the list.
235 *
236 * \param goi - get opt info
237 * \param puthere - where param is put
238 *
239 */
240 int Jim_GetOpt_Obj(Jim_GetOptInfo *goi, Jim_Obj **puthere);
241
242 /** Remove argv[0] as string.
243 *
244 * \param goi - get opt info
245 * \param puthere - where param is put
246 * \param len - return its length
247 */
248 int Jim_GetOpt_String(Jim_GetOptInfo *goi, char **puthere, int *len);
249
250 /** Remove argv[0] as double.
251 *
252 * \param goi - get opt info
253 * \param puthere - where param is put.
254 *
255 */
256 int Jim_GetOpt_Double(Jim_GetOptInfo *goi, double *puthere);
257
258 /** Remove argv[0] as wide.
259 *
260 * \param goi - get opt info
261 * \param puthere - where param is put.
262 */
263 int Jim_GetOpt_Wide(Jim_GetOptInfo *goi, jim_wide *puthere);
264
265 /** Remove argv[0] as NVP.
266 *
267 * \param goi - get opt info
268 * \param lookup - nvp lookup table
269 * \param puthere - where param is put.
270 *
271 */
272 int Jim_GetOpt_Nvp(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, Jim_Nvp **puthere);
273
274 /** Create an appropriate error message for an NVP.
275 *
276 * \param goi - options info
277 * \param lookup - the NVP table that was used.
278 * \param hadprefix - 0 or 1 if the option had a prefix.
279 *
280 * This function will set the "interp->result" to a human readable
281 * error message listing the available options.
282 *
283 * This function assumes the previous option argv[-1] is the unknown string.
284 *
285 * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
286 *
287 * Example:
288 * \code
289 *
290 * while (goi.argc) {
291 * // Get the next option
292 * e = Jim_GetOpt_Nvp(&goi, cmd_options, &n);
293 * if (e != JIM_OK) {
294 * // option was not recognized
295 * // pass 'hadprefix = 0' because there is no prefix
296 * Jim_GetOpt_NvpUnknown(&goi, cmd_options, 0);
297 * return e;
298 * }
299 *
300 * switch (n->value) {
301 * case OPT_SEX:
302 * // handle: --sex male | female | lots | needmore
303 * e = Jim_GetOpt_Nvp(&goi, &nvp_sex, &n);
304 * if (e != JIM_OK) {
305 * Jim_GetOpt_NvpUnknown(&ogi, nvp_sex, 1);
306 * return e;
307 * }
308 * printf("Code: (%d) is %s\n", n->value, n->name);
309 * break;
310 * case ...:
311 * [snip]
312 * }
313 * }
314 * \endcode
315 *
316 */
317 void Jim_GetOpt_NvpUnknown(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, int hadprefix);
318
319
320 /** Remove argv[0] as Enum
321 *
322 * \param goi - get opt info
323 * \param lookup - lookup table.
324 * \param puthere - where param is put.
325 *
326 */
327 int Jim_GetOpt_Enum(Jim_GetOptInfo *goi, const char *const *lookup, int *puthere);
328
329 #endif