1 /* Jim - A small embeddable Tcl interpreter
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
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
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.
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.
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.
44 #ifndef OPENOCD_HELPER_JIM_NVP_H
45 #define OPENOCD_HELPER_JIM_NVP_H
49 /** Name Value Pairs, aka: NVP
50 * - Given a string - return the associated int.
51 * - Given a number - return the associated string.
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
58 * An NVP Table is terminated with ".name = NULL".
60 * During the 'name2value' operation, if no matching string is found
61 * the pointer to the terminal element (with p->name == NULL) is returned.
65 * const struct jim_nvp yn[] = {
73 * struct jim_nvp *result
74 * e = jim_nvp_name2value(interp, yn, "y", &result);
76 * e = jim_nvp_name2value(interp, yn, "n", &result);
78 * e = jim_nvp_name2value(interp, yn, "Blah", &result);
82 * During the number2name operation, the first matching value is returned.
89 int jim_get_nvp(Jim_Interp *interp,
91 const struct jim_nvp *nvp_table,
92 const struct jim_nvp **result);
94 /* Name Value Pairs Operations */
95 struct jim_nvp *jim_nvp_name2value_simple(const struct jim_nvp *nvp_table, const char *name);
96 struct jim_nvp *jim_nvp_name2value_nocase_simple(const struct jim_nvp *nvp_table, const char *name);
97 struct jim_nvp *jim_nvp_value2name_simple(const struct jim_nvp *nvp_table, int v);
99 int jim_nvp_name2value(Jim_Interp *interp,
100 const struct jim_nvp *nvp_table,
102 struct jim_nvp **result);
103 int jim_nvp_name2value_nocase(Jim_Interp *interp,
104 const struct jim_nvp *nvp_table,
106 struct jim_nvp **result);
107 int jim_nvp_value2name(Jim_Interp *interp, const struct jim_nvp *nvp_table, int value, struct jim_nvp **result);
109 int jim_nvp_name2value_obj(Jim_Interp *interp,
110 const struct jim_nvp *nvp_table,
112 struct jim_nvp **result);
113 int jim_nvp_name2value_obj_nocase(Jim_Interp *interp,
114 const struct jim_nvp *nvp_table,
116 struct jim_nvp **result);
117 int jim_nvp_value2name_obj(Jim_Interp *interp,
118 const struct jim_nvp *nvp_table,
120 struct jim_nvp **result);
122 /** prints a nice 'unknown' parameter error message to the 'result' */
123 void jim_set_result_nvp_unknown(Jim_Interp *interp,
125 Jim_Obj *param_value,
126 const struct jim_nvp *nvp_table);
128 /** Debug: convert argc/argv into a printable string for printf() debug
130 * \param interp - the interpreter
131 * \param argc - arg count
132 * \param argv - the objects
134 * \returns string pointer holding the text.
136 * Note, next call to this function will free the old (last) string.
138 * For example might want do this:
140 * fp = fopen("some.file.log", "a");
141 * fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
145 const char *jim_debug_argv_string(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
148 /** A TCL -ish GetOpt like code.
150 * Some TCL objects have various "configuration" values.
151 * For example - in Tcl/Tk the "buttons" have many options.
153 * Useful when dealing with command options.
154 * that may come in any order...
156 * Does not support "-foo = 123" type options.
157 * Only supports tcl type options, like "-foo 123"
160 struct jim_getopt_info {
163 Jim_Obj *const *argv;
164 int isconfigure; /* non-zero if configure */
169 * Example (short and incomplete):
171 * struct jim_getopt_info goi;
173 * jim_getopt_setup(&goi, interp, argc, argv);
176 * e = jim_getopt_nvp(&goi, nvp_options, &n);
178 * jim_getopt_nvp_unknown(&goi, nvp_options, 0);
182 * switch (n->value) {
184 * printf("Option ALIVE specified\n");
187 * if (goi.argc < 1) {
188 * .. not enough args error ..
190 * jim_getopt_string(&goi, &cp, NULL);
191 * printf("FIRSTNAME: %s\n", cp);
193 * jim_getopt_wide(&goi, &w);
194 * printf("AGE: %d\n", (int)(w));
197 * e = jim_getopt_nvp(&goi, nvp_politics, &n);
199 * jim_getopt_nvp_unknown(&goi, nvp_politics, 1);
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)
217 * struct jim_getopt_info goi;
219 * Jim_GetOptSetup(&goi, interp, argc, argv);
223 int jim_getopt_setup(struct jim_getopt_info *goi,
226 Jim_Obj *const *argv);
229 /** Debug - Dump parameters to stderr
230 * \param goi - current parameters
232 void jim_getopt_debug(struct jim_getopt_info *goi);
234 /** Remove argv[0] from the list.
236 * \param goi - get opt info
237 * \param puthere - where param is put
240 int jim_getopt_obj(struct jim_getopt_info *goi, Jim_Obj **puthere);
242 /** Remove argv[0] as string.
244 * \param goi - get opt info
245 * \param puthere - where param is put
246 * \param len - return its length
248 int jim_getopt_string(struct jim_getopt_info *goi, const char **puthere, int *len);
250 /** Remove argv[0] as double.
252 * \param goi - get opt info
253 * \param puthere - where param is put.
256 int jim_getopt_double(struct jim_getopt_info *goi, double *puthere);
258 /** Remove argv[0] as wide.
260 * \param goi - get opt info
261 * \param puthere - where param is put.
263 int jim_getopt_wide(struct jim_getopt_info *goi, jim_wide *puthere);
265 /** Remove argv[0] as NVP.
267 * \param goi - get opt info
268 * \param lookup - nvp lookup table
269 * \param puthere - where param is put.
272 int jim_getopt_nvp(struct jim_getopt_info *goi, const struct jim_nvp *lookup, struct jim_nvp **puthere);
274 /** Create an appropriate error message for an NVP.
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.
280 * This function will set the "interp->result" to a human readable
281 * error message listing the available options.
283 * This function assumes the previous option argv[-1] is the unknown string.
285 * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
291 * // Get the next option
292 * e = jim_getopt_nvp(&goi, cmd_options, &n);
294 * // option was not recognized
295 * // pass 'hadprefix = 0' because there is no prefix
296 * jim_getopt_nvp_unknown(&goi, cmd_options, 0);
300 * switch (n->value) {
302 * // handle: --sex male | female | lots | needmore
303 * e = jim_getopt_nvp(&goi, &nvp_sex, &n);
305 * jim_getopt_nvp_unknown(&ogi, nvp_sex, 1);
308 * printf("Code: (%d) is %s\n", n->value, n->name);
317 void jim_getopt_nvp_unknown(struct jim_getopt_info *goi, const struct jim_nvp *lookup, int hadprefix);
320 /** Remove argv[0] as Enum
322 * \param goi - get opt info
323 * \param lookup - lookup table.
324 * \param puthere - where param is put.
327 int jim_getopt_enum(struct jim_getopt_info *goi, const char *const *lookup, int *puthere);
331 * Do not use these API anymore, as they do not comply with OpenOCD coding style
332 * They are listed here to avoid breaking build after merge of patches already queued in gerrit
335 static inline __attribute__ ((deprecated))
336 const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
338 return jim_debug_argv_string(interp, argc, argv);
341 static inline __attribute__ ((deprecated))
342 int Jim_GetNvp(Jim_Interp *interp, Jim_Obj *objptr, const struct jim_nvp *nvp_table, const struct jim_nvp **result)
344 return jim_get_nvp(interp, objptr, nvp_table, result);
347 static inline __attribute__ ((deprecated))
348 void Jim_GetOpt_Debug(struct jim_getopt_info *goi)
350 jim_getopt_debug(goi);
353 static inline __attribute__ ((deprecated))
354 int Jim_GetOpt_Double(struct jim_getopt_info *goi, double *puthere)
356 return jim_getopt_double(goi, puthere);
359 static inline __attribute__ ((deprecated))
360 int Jim_GetOpt_Enum(struct jim_getopt_info *goi, const char *const *lookup, int *puthere)
362 return jim_getopt_enum(goi, lookup, puthere);
365 static inline __attribute__ ((deprecated))
366 int Jim_GetOpt_Nvp(struct jim_getopt_info *goi, const struct jim_nvp *lookup, struct jim_nvp **puthere)
368 return jim_getopt_nvp(goi, lookup, puthere);
371 static inline __attribute__ ((deprecated))
372 void Jim_GetOpt_NvpUnknown(struct jim_getopt_info *goi, const struct jim_nvp *lookup, int hadprefix)
374 jim_getopt_nvp_unknown(goi, lookup, hadprefix);
377 static inline __attribute__ ((deprecated))
378 int Jim_GetOpt_Obj(struct jim_getopt_info *goi, Jim_Obj **puthere)
380 return jim_getopt_obj(goi, puthere);
383 static inline __attribute__ ((deprecated))
384 int Jim_GetOpt_Setup(struct jim_getopt_info *goi, Jim_Interp *interp, int argc, Jim_Obj *const *argv)
386 return jim_getopt_setup(goi, interp, argc, argv);
389 static inline __attribute__ ((deprecated))
390 int Jim_GetOpt_String(struct jim_getopt_info *goi, const char **puthere, int *len)
392 return jim_getopt_string(goi, puthere, len);
395 static inline __attribute__ ((deprecated))
396 int Jim_GetOpt_Wide(struct jim_getopt_info *goi, jim_wide *puthere)
398 return jim_getopt_wide(goi, puthere);
401 static inline __attribute__ ((deprecated))
402 int Jim_Nvp_name2value(Jim_Interp *interp, const struct jim_nvp *nvp_table, const char *name, struct jim_nvp **result)
404 return jim_nvp_name2value(interp, nvp_table, name, result);
407 static inline __attribute__ ((deprecated))
408 int Jim_Nvp_name2value_nocase(Jim_Interp *interp, const struct jim_nvp *nvp_table, const char *name,
409 struct jim_nvp **result)
411 return jim_nvp_name2value_nocase(interp, nvp_table, name, result);
414 static inline __attribute__ ((deprecated))
415 struct jim_nvp *Jim_Nvp_name2value_nocase_simple(const struct jim_nvp *nvp_table, const char *name)
417 return jim_nvp_name2value_nocase_simple(nvp_table, name);
420 static inline __attribute__ ((deprecated))
421 int Jim_Nvp_name2value_obj(Jim_Interp *interp, const struct jim_nvp *nvp_table, Jim_Obj *name_obj,
422 struct jim_nvp **result)
424 return jim_nvp_name2value_obj(interp, nvp_table, name_obj, result);
427 static inline __attribute__ ((deprecated))
428 int Jim_Nvp_name2value_obj_nocase(Jim_Interp *interp, const struct jim_nvp *nvp_table, Jim_Obj *name_obj,
429 struct jim_nvp **result)
431 return jim_nvp_name2value_obj_nocase(interp, nvp_table, name_obj, result);
434 static inline __attribute__ ((deprecated))
435 struct jim_nvp *Jim_Nvp_name2value_simple(const struct jim_nvp *nvp_table, const char *name)
437 return jim_nvp_name2value_simple(nvp_table, name);
440 static inline __attribute__ ((deprecated))
441 int Jim_Nvp_value2name(Jim_Interp *interp, const struct jim_nvp *nvp_table, int value, struct jim_nvp **result)
443 return jim_nvp_value2name(interp, nvp_table, value, result);
446 static inline __attribute__ ((deprecated))
447 int Jim_Nvp_value2name_obj(Jim_Interp *interp, const struct jim_nvp *nvp_table, Jim_Obj *value_obj,
448 struct jim_nvp **result)
450 return jim_nvp_value2name_obj(interp, nvp_table, value_obj, result);
453 static inline __attribute__ ((deprecated))
454 struct jim_nvp *Jim_Nvp_value2name_simple(const struct jim_nvp *nvp_table, int v)
456 return jim_nvp_value2name_simple(nvp_table, v);
459 static inline __attribute__ ((deprecated))
460 void Jim_SetResult_NvpUnknown(Jim_Interp *interp, Jim_Obj *param_name, Jim_Obj *param_value,
461 const struct jim_nvp *nvp_table)
463 jim_set_result_nvp_unknown(interp, param_name, param_value, nvp_table);
466 typedef struct jim_getopt_info Jim_GetOptInfo __attribute__ ((deprecated));
467 typedef struct jim_nvp Jim_Nvp __attribute__ ((deprecated));
469 #endif /* OPENOCD_HELPER_JIM_NVP_H */