jim-nvp is moving from jimtcl to openocd
[openocd.git] / src / helper / jim-nvp.h
1 #ifndef JIM_NVP_H
2 #define JIM_NVP_H
3
4 #include <jim.h>
5
6 /** Name Value Pairs, aka: NVP
7 * - Given a string - return the associated int.
8 * - Given a number - return the associated string.
9 * .
10 *
11 * Very useful when the number is not a simple index into an array of
12 * known string, or there may be multiple strings (aliases) that mean then same
13 * thing.
14 *
15 * An NVP Table is terminated with ".name = NULL".
16 *
17 * During the 'name2value' operation, if no matching string is found
18 * the pointer to the terminal element (with p->name == NULL) is returned.
19 *
20 * Example:
21 * \code
22 * const Jim_Nvp yn[] = {
23 * { "yes", 1 },
24 * { "no" , 0 },
25 * { "yep", 1 },
26 * { "nope", 0 },
27 * { NULL, -1 },
28 * };
29 *
30 * Jim_Nvp *result
31 * e = Jim_Nvp_name2value(interp, yn, "y", &result);
32 * returns &yn[0];
33 * e = Jim_Nvp_name2value(interp, yn, "n", &result);
34 * returns &yn[1];
35 * e = Jim_Nvp_name2value(interp, yn, "Blah", &result);
36 * returns &yn[4];
37 * \endcode
38 *
39 * During the number2name operation, the first matching value is returned.
40 */
41 typedef struct {
42 const char *name;
43 int value;
44 } Jim_Nvp;
45
46
47 int Jim_GetNvp (Jim_Interp *interp,
48 Jim_Obj *objPtr,
49 const Jim_Nvp *nvp_table,
50 const Jim_Nvp **result);
51
52 /* Name Value Pairs Operations */
53 Jim_Nvp *Jim_Nvp_name2value_simple(const Jim_Nvp *nvp_table, const char *name);
54 Jim_Nvp *Jim_Nvp_name2value_nocase_simple(const Jim_Nvp *nvp_table, const char *name);
55 Jim_Nvp *Jim_Nvp_value2name_simple(const Jim_Nvp *nvp_table, int v);
56
57 int Jim_Nvp_name2value(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
58 int Jim_Nvp_name2value_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
59 int Jim_Nvp_value2name(Jim_Interp *interp, const Jim_Nvp *nvp_table, int value, Jim_Nvp **result);
60
61 int Jim_Nvp_name2value_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
62 int Jim_Nvp_name2value_obj_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
63 int Jim_Nvp_value2name_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *value_obj, Jim_Nvp **result);
64
65 /** prints a nice 'unknown' parameter error message to the 'result' */
66 void Jim_SetResult_NvpUnknown(Jim_Interp *interp,
67 Jim_Obj *param_name,
68 Jim_Obj *param_value,
69 const Jim_Nvp *nvp_table);
70
71
72 /** Debug: convert argc/argv into a printable string for printf() debug
73 *
74 * \param interp - the interpeter
75 * \param argc - arg count
76 * \param argv - the objects
77 *
78 * \returns string pointer holding the text.
79 *
80 * Note, next call to this function will free the old (last) string.
81 *
82 * For example might want do this:
83 * \code
84 * fp = fopen("some.file.log", "a");
85 * fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
86 * fclose(fp);
87 * \endcode
88 */
89 const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
90
91
92 /** A TCL -ish GetOpt like code.
93 *
94 * Some TCL objects have various "configuration" values.
95 * For example - in Tcl/Tk the "buttons" have many options.
96 *
97 * Usefull when dealing with command options.
98 * that may come in any order...
99 *
100 * Does not support "-foo = 123" type options.
101 * Only supports tcl type options, like "-foo 123"
102 */
103
104 typedef struct jim_getopt {
105 Jim_Interp *interp;
106 int argc;
107 Jim_Obj * const * argv;
108 int isconfigure; /* non-zero if configure */
109 } Jim_GetOptInfo;
110
111 /** GetOpt - how to.
112 *
113 * Example (short and incomplete):
114 * \code
115 * Jim_GetOptInfo goi;
116 *
117 * Jim_GetOpt_Setup(&goi, interp, argc, argv);
118 *
119 * while (goi.argc) {
120 * e = Jim_GetOpt_Nvp(&goi, nvp_options, &n);
121 * if (e != JIM_OK) {
122 * Jim_GetOpt_NvpUnknown(&goi, nvp_options, 0);
123 * return e;
124 * }
125 *
126 * switch (n->value) {
127 * case ALIVE:
128 * printf("Option ALIVE specified\n");
129 * break;
130 * case FIRST:
131 * if (goi.argc < 1) {
132 * .. not enough args error ..
133 * }
134 * Jim_GetOpt_String(&goi, &cp, NULL);
135 * printf("FIRSTNAME: %s\n", cp);
136 * case AGE:
137 * Jim_GetOpt_Wide(&goi, &w);
138 * printf("AGE: %d\n", (int)(w));
139 * break;
140 * case POLITICS:
141 * e = Jim_GetOpt_Nvp(&goi, nvp_politics, &n);
142 * if (e != JIM_OK) {
143 * Jim_GetOpt_NvpUnknown(&goi, nvp_politics, 1);
144 * return e;
145 * }
146 * }
147 * }
148 *
149 * \endcode
150 *
151 */
152
153 /** Setup GETOPT
154 *
155 * \param goi - get opt info to be initialized
156 * \param interp - jim interp
157 * \param argc - argc count.
158 * \param argv - argv (will be copied)
159 *
160 * \code
161 * Jim_GetOptInfo goi;
162 *
163 * Jim_GetOptSetup(&goi, interp, argc, argv);
164 * \endcode
165 */
166
167 int Jim_GetOpt_Setup(Jim_GetOptInfo *goi,
168 Jim_Interp *interp,
169 int argc,
170 Jim_Obj * const * argv);
171
172
173 /** Debug - Dump parameters to stderr
174 * \param goi - current parameters
175 */
176 void Jim_GetOpt_Debug(Jim_GetOptInfo *goi);
177
178
179
180 /** Remove argv[0] from the list.
181 *
182 * \param goi - get opt info
183 * \param puthere - where param is put
184 *
185 */
186 int Jim_GetOpt_Obj(Jim_GetOptInfo *goi, Jim_Obj **puthere);
187
188 /** Remove argv[0] as string.
189 *
190 * \param goi - get opt info
191 * \param puthere - where param is put
192 * \param len - return its length
193 */
194 int Jim_GetOpt_String(Jim_GetOptInfo *goi, char **puthere, int *len);
195
196 /** Remove argv[0] as double.
197 *
198 * \param goi - get opt info
199 * \param puthere - where param is put.
200 *
201 */
202 int Jim_GetOpt_Double(Jim_GetOptInfo *goi, double *puthere);
203
204 /** Remove argv[0] as wide.
205 *
206 * \param goi - get opt info
207 * \param puthere - where param is put.
208 */
209 int Jim_GetOpt_Wide(Jim_GetOptInfo *goi, jim_wide *puthere);
210
211 /** Remove argv[0] as NVP.
212 *
213 * \param goi - get opt info
214 * \param lookup - nvp lookup table
215 * \param puthere - where param is put.
216 *
217 */
218 int Jim_GetOpt_Nvp(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, Jim_Nvp **puthere);
219
220 /** Create an appropriate error message for an NVP.
221 *
222 * \param goi - options info
223 * \param lookup - the NVP table that was used.
224 * \param hadprefix - 0 or 1 if the option had a prefix.
225 *
226 * This function will set the "interp->result" to a human readable
227 * error message listing the available options.
228 *
229 * This function assumes the previous option argv[-1] is the unknown string.
230 *
231 * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
232 *
233 * Example:
234 * \code
235 *
236 * while (goi.argc) {
237 * // Get the next option
238 * e = Jim_GetOpt_Nvp(&goi, cmd_options, &n);
239 * if (e != JIM_OK) {
240 * // option was not recognized
241 * // pass 'hadprefix = 0' because there is no prefix
242 * Jim_GetOpt_NvpUnknown(&goi, cmd_options, 0);
243 * return e;
244 * }
245 *
246 * switch (n->value) {
247 * case OPT_SEX:
248 * // handle: --sex male | female | lots | needmore
249 * e = Jim_GetOpt_Nvp(&goi, &nvp_sex, &n);
250 * if (e != JIM_OK) {
251 * Jim_GetOpt_NvpUnknown(&ogi, nvp_sex, 1);
252 * return e;
253 * }
254 * printf("Code: (%d) is %s\n", n->value, n->name);
255 * break;
256 * case ...:
257 * [snip]
258 * }
259 * }
260 * \endcode
261 *
262 */
263 void Jim_GetOpt_NvpUnknown(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, int hadprefix);
264
265
266 /** Remove argv[0] as Enum
267 *
268 * \param goi - get opt info
269 * \param lookup - lookup table.
270 * \param puthere - where param is put.
271 *
272 */
273 int Jim_GetOpt_Enum(Jim_GetOptInfo *goi, const char * const * lookup, int *puthere);
274
275 #endif