git.gag.com Git - fw/openocd/blob - 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 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 struct jim_nvp yn[] = {
  66  *          { "yes", 1 },
  67  *          { "no" , 0 },
  68  *          { "yep", 1 },
  69  *          { "nope", 0 },
  70  *          { NULL, -1 },
  71  *      };
  72  *
  73  *  struct 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 struct jim_nvp {
  85         const char *name;
  86         int value;
  87 };
  88
  89 int jim_get_nvp(Jim_Interp *interp,
  90                 Jim_Obj *objptr,
  91                 const struct jim_nvp *nvp_table,
  92                 const struct jim_nvp **result);
  93
  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);
  98
  99 int jim_nvp_name2value(Jim_Interp *interp,
 100                 const struct jim_nvp *nvp_table,
 101                 const char *name,
 102                 struct jim_nvp **result);
 103 int jim_nvp_name2value_nocase(Jim_Interp *interp,
 104                 const struct jim_nvp *nvp_table,
 105                 const char *name,
 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);
 108
 109 int jim_nvp_name2value_obj(Jim_Interp *interp,
 110                 const struct jim_nvp *nvp_table,
 111                 Jim_Obj *name_obj,
 112                 struct jim_nvp **result);
 113 int jim_nvp_name2value_obj_nocase(Jim_Interp *interp,
 114                 const struct jim_nvp *nvp_table,
 115                 Jim_Obj *name_obj,
 116                 struct jim_nvp **result);
 117 int jim_nvp_value2name_obj(Jim_Interp *interp,
 118                 const struct jim_nvp *nvp_table,
 119                 Jim_Obj *value_obj,
 120                 struct jim_nvp **result);
 121
 122 /** prints a nice 'unknown' parameter error message to the 'result' */
 123 void jim_set_result_nvp_unknown(Jim_Interp *interp,
 124                 Jim_Obj *param_name,
 125                 Jim_Obj *param_value,
 126                 const struct 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_argv_string(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 struct jim_getopt_info {
 161         Jim_Interp *interp;
 162         int argc;
 163         Jim_Obj *const *argv;
 164         int isconfigure;                /* non-zero if configure */
 165 };
 166
 167 /** GetOpt - how to.
 168  *
 169  * Example (short and incomplete):
 170  * \code
 171  *   struct jim_getopt_info 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_nvp_unknown(&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_nvp_unknown(&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  *     struct jim_getopt_info  goi;
 218  *
 219  *     Jim_GetOptSetup(&goi, interp, argc, argv);
 220  * \endcode
 221  */
 222
 223 int jim_getopt_setup(struct jim_getopt_info *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(struct jim_getopt_info *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(struct jim_getopt_info *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(struct jim_getopt_info *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(struct jim_getopt_info *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(struct jim_getopt_info *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(struct jim_getopt_info *goi, const struct jim_nvp *lookup, struct 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_nvp_unknown(&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_nvp_unknown(&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_nvp_unknown(struct jim_getopt_info *goi, const struct 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(struct jim_getopt_info *goi, const char *const *lookup, int *puthere);
 328
 329 /*
 330  * DEPRECATED API
 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
 333  */
 334
 335 static inline __attribute__ ((deprecated))
 336 const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 337 {
 338         return jim_debug_argv_string(interp, argc, argv);
 339 }
 340
 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)
 343 {
 344         return jim_get_nvp(interp, objptr, nvp_table, result);
 345 }
 346
 347 static inline __attribute__ ((deprecated))
 348 void Jim_GetOpt_Debug(struct jim_getopt_info *goi)
 349 {
 350         jim_getopt_debug(goi);
 351 }
 352
 353 static inline __attribute__ ((deprecated))
 354 int Jim_GetOpt_Double(struct jim_getopt_info *goi, double *puthere)
 355 {
 356         return jim_getopt_double(goi, puthere);
 357 }
 358
 359 static inline __attribute__ ((deprecated))
 360 int Jim_GetOpt_Enum(struct jim_getopt_info *goi, const char *const *lookup, int *puthere)
 361 {
 362         return jim_getopt_enum(goi, lookup, puthere);
 363 }
 364
 365 static inline __attribute__ ((deprecated))
 366 int Jim_GetOpt_Nvp(struct jim_getopt_info *goi, const struct jim_nvp *lookup, struct jim_nvp **puthere)
 367 {
 368         return jim_getopt_nvp(goi, lookup, puthere);
 369 }
 370
 371 static inline __attribute__ ((deprecated))
 372 void Jim_GetOpt_NvpUnknown(struct jim_getopt_info *goi, const struct jim_nvp *lookup, int hadprefix)
 373 {
 374         jim_getopt_nvp_unknown(goi, lookup, hadprefix);
 375 }
 376
 377 static inline __attribute__ ((deprecated))
 378 int Jim_GetOpt_Obj(struct jim_getopt_info *goi, Jim_Obj **puthere)
 379 {
 380         return jim_getopt_obj(goi, puthere);
 381 }
 382
 383 static inline __attribute__ ((deprecated))
 384 int Jim_GetOpt_Setup(struct jim_getopt_info *goi, Jim_Interp *interp, int argc, Jim_Obj *const *argv)
 385 {
 386         return jim_getopt_setup(goi, interp, argc, argv);
 387 }
 388
 389 static inline __attribute__ ((deprecated))
 390 int Jim_GetOpt_String(struct jim_getopt_info *goi, const char **puthere, int *len)
 391 {
 392         return jim_getopt_string(goi, puthere, len);
 393 }
 394
 395 static inline __attribute__ ((deprecated))
 396 int Jim_GetOpt_Wide(struct jim_getopt_info *goi, jim_wide *puthere)
 397 {
 398         return jim_getopt_wide(goi, puthere);
 399 }
 400
 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)
 403 {
 404         return jim_nvp_name2value(interp, nvp_table, name, result);
 405 }
 406
 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)
 410 {
 411         return jim_nvp_name2value_nocase(interp, nvp_table, name, result);
 412 }
 413
 414 static inline __attribute__ ((deprecated))
 415 struct jim_nvp *Jim_Nvp_name2value_nocase_simple(const struct jim_nvp *nvp_table, const char *name)
 416 {
 417         return jim_nvp_name2value_nocase_simple(nvp_table, name);
 418 }
 419
 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)
 423 {
 424         return jim_nvp_name2value_obj(interp, nvp_table, name_obj, result);
 425 }
 426
 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)
 430 {
 431         return jim_nvp_name2value_obj_nocase(interp, nvp_table, name_obj, result);
 432 }
 433
 434 static inline __attribute__ ((deprecated))
 435 struct jim_nvp *Jim_Nvp_name2value_simple(const struct jim_nvp *nvp_table, const char *name)
 436 {
 437         return jim_nvp_name2value_simple(nvp_table, name);
 438 }
 439
 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)
 442 {
 443         return jim_nvp_value2name(interp, nvp_table, value, result);
 444 }
 445
 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)
 449 {
 450         return jim_nvp_value2name_obj(interp, nvp_table, value_obj, result);
 451 }
 452
 453 static inline __attribute__ ((deprecated))
 454 struct jim_nvp *Jim_Nvp_value2name_simple(const struct jim_nvp *nvp_table, int v)
 455 {
 456         return jim_nvp_value2name_simple(nvp_table, v);
 457 }
 458
 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)
 462 {
 463         jim_set_result_nvp_unknown(interp, param_name, param_value, nvp_table);
 464 }
 465
 466 typedef struct jim_getopt_info Jim_GetOptInfo __attribute__ ((deprecated));
 467 typedef struct jim_nvp Jim_Nvp __attribute__ ((deprecated));
 468
 469 #endif /* OPENOCD_HELPER_JIM_NVP_H */