jim: add missing jim license
[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
90 int Jim_GetNvp (Jim_Interp *interp,
91 Jim_Obj *objPtr,
92 const Jim_Nvp *nvp_table,
93 const Jim_Nvp **result);
94
95 /* Name Value Pairs Operations */
96 Jim_Nvp *Jim_Nvp_name2value_simple(const Jim_Nvp *nvp_table, const char *name);
97 Jim_Nvp *Jim_Nvp_name2value_nocase_simple(const Jim_Nvp *nvp_table, const char *name);
98 Jim_Nvp *Jim_Nvp_value2name_simple(const Jim_Nvp *nvp_table, int v);
99
100 int Jim_Nvp_name2value(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
101 int Jim_Nvp_name2value_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
102 int Jim_Nvp_value2name(Jim_Interp *interp, const Jim_Nvp *nvp_table, int value, Jim_Nvp **result);
103
104 int Jim_Nvp_name2value_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
105 int Jim_Nvp_name2value_obj_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
106 int Jim_Nvp_value2name_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *value_obj, Jim_Nvp **result);
107
108 /** prints a nice 'unknown' parameter error message to the 'result' */
109 void Jim_SetResult_NvpUnknown(Jim_Interp *interp,
110 Jim_Obj *param_name,
111 Jim_Obj *param_value,
112 const Jim_Nvp *nvp_table);
113
114
115 /** Debug: convert argc/argv into a printable string for printf() debug
116 *
117 * \param interp - the interpeter
118 * \param argc - arg count
119 * \param argv - the objects
120 *
121 * \returns string pointer holding the text.
122 *
123 * Note, next call to this function will free the old (last) string.
124 *
125 * For example might want do this:
126 * \code
127 * fp = fopen("some.file.log", "a");
128 * fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
129 * fclose(fp);
130 * \endcode
131 */
132 const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
133
134
135 /** A TCL -ish GetOpt like code.
136 *
137 * Some TCL objects have various "configuration" values.
138 * For example - in Tcl/Tk the "buttons" have many options.
139 *
140 * Usefull when dealing with command options.
141 * that may come in any order...
142 *
143 * Does not support "-foo = 123" type options.
144 * Only supports tcl type options, like "-foo 123"
145 */
146
147 typedef struct jim_getopt {
148 Jim_Interp *interp;
149 int argc;
150 Jim_Obj * const * argv;
151 int isconfigure; /* non-zero if configure */
152 } Jim_GetOptInfo;
153
154 /** GetOpt - how to.
155 *
156 * Example (short and incomplete):
157 * \code
158 * Jim_GetOptInfo goi;
159 *
160 * Jim_GetOpt_Setup(&goi, interp, argc, argv);
161 *
162 * while (goi.argc) {
163 * e = Jim_GetOpt_Nvp(&goi, nvp_options, &n);
164 * if (e != JIM_OK) {
165 * Jim_GetOpt_NvpUnknown(&goi, nvp_options, 0);
166 * return e;
167 * }
168 *
169 * switch (n->value) {
170 * case ALIVE:
171 * printf("Option ALIVE specified\n");
172 * break;
173 * case FIRST:
174 * if (goi.argc < 1) {
175 * .. not enough args error ..
176 * }
177 * Jim_GetOpt_String(&goi, &cp, NULL);
178 * printf("FIRSTNAME: %s\n", cp);
179 * case AGE:
180 * Jim_GetOpt_Wide(&goi, &w);
181 * printf("AGE: %d\n", (int)(w));
182 * break;
183 * case POLITICS:
184 * e = Jim_GetOpt_Nvp(&goi, nvp_politics, &n);
185 * if (e != JIM_OK) {
186 * Jim_GetOpt_NvpUnknown(&goi, nvp_politics, 1);
187 * return e;
188 * }
189 * }
190 * }
191 *
192 * \endcode
193 *
194 */
195
196 /** Setup GETOPT
197 *
198 * \param goi - get opt info to be initialized
199 * \param interp - jim interp
200 * \param argc - argc count.
201 * \param argv - argv (will be copied)
202 *
203 * \code
204 * Jim_GetOptInfo goi;
205 *
206 * Jim_GetOptSetup(&goi, interp, argc, argv);
207 * \endcode
208 */
209
210 int Jim_GetOpt_Setup(Jim_GetOptInfo *goi,
211 Jim_Interp *interp,
212 int argc,
213 Jim_Obj * const * argv);
214
215
216 /** Debug - Dump parameters to stderr
217 * \param goi - current parameters
218 */
219 void Jim_GetOpt_Debug(Jim_GetOptInfo *goi);
220
221
222
223 /** Remove argv[0] from the list.
224 *
225 * \param goi - get opt info
226 * \param puthere - where param is put
227 *
228 */
229 int Jim_GetOpt_Obj(Jim_GetOptInfo *goi, Jim_Obj **puthere);
230
231 /** Remove argv[0] as string.
232 *
233 * \param goi - get opt info
234 * \param puthere - where param is put
235 * \param len - return its length
236 */
237 int Jim_GetOpt_String(Jim_GetOptInfo *goi, char **puthere, int *len);
238
239 /** Remove argv[0] as double.
240 *
241 * \param goi - get opt info
242 * \param puthere - where param is put.
243 *
244 */
245 int Jim_GetOpt_Double(Jim_GetOptInfo *goi, double *puthere);
246
247 /** Remove argv[0] as wide.
248 *
249 * \param goi - get opt info
250 * \param puthere - where param is put.
251 */
252 int Jim_GetOpt_Wide(Jim_GetOptInfo *goi, jim_wide *puthere);
253
254 /** Remove argv[0] as NVP.
255 *
256 * \param goi - get opt info
257 * \param lookup - nvp lookup table
258 * \param puthere - where param is put.
259 *
260 */
261 int Jim_GetOpt_Nvp(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, Jim_Nvp **puthere);
262
263 /** Create an appropriate error message for an NVP.
264 *
265 * \param goi - options info
266 * \param lookup - the NVP table that was used.
267 * \param hadprefix - 0 or 1 if the option had a prefix.
268 *
269 * This function will set the "interp->result" to a human readable
270 * error message listing the available options.
271 *
272 * This function assumes the previous option argv[-1] is the unknown string.
273 *
274 * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
275 *
276 * Example:
277 * \code
278 *
279 * while (goi.argc) {
280 * // Get the next option
281 * e = Jim_GetOpt_Nvp(&goi, cmd_options, &n);
282 * if (e != JIM_OK) {
283 * // option was not recognized
284 * // pass 'hadprefix = 0' because there is no prefix
285 * Jim_GetOpt_NvpUnknown(&goi, cmd_options, 0);
286 * return e;
287 * }
288 *
289 * switch (n->value) {
290 * case OPT_SEX:
291 * // handle: --sex male | female | lots | needmore
292 * e = Jim_GetOpt_Nvp(&goi, &nvp_sex, &n);
293 * if (e != JIM_OK) {
294 * Jim_GetOpt_NvpUnknown(&ogi, nvp_sex, 1);
295 * return e;
296 * }
297 * printf("Code: (%d) is %s\n", n->value, n->name);
298 * break;
299 * case ...:
300 * [snip]
301 * }
302 * }
303 * \endcode
304 *
305 */
306 void Jim_GetOpt_NvpUnknown(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, int hadprefix);
307
308
309 /** Remove argv[0] as Enum
310 *
311 * \param goi - get opt info
312 * \param lookup - lookup table.
313 * \param puthere - where param is put.
314 *
315 */
316 int Jim_GetOpt_Enum(Jim_GetOptInfo *goi, const char * const * lookup, int *puthere);
317
318 #endif