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 OPENOCD_HELPER_JIM_NVP_H 45 #define OPENOCD_HELPER_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 interpreter 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 * Useful 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, const 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 /* OPENOCD_HELPER_JIM_NVP_H */ 330