src/helper/jim-nvp.h

   1 /* SPDX-License-Identifier: BSD-2-Clause-Views */
   2
   3 /* Jim - A small embeddable Tcl interpreter
   4  *
   5  * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
   6  * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
   7  * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
   8  * Copyright 2008 oharboe - Øyvind Harboe - oyvind.harboe@zylin.com
   9  * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
  10  * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
  11  * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
  12  * Copyright 2008 Steve Bennett <steveb@workware.net.au>
  13  * Copyright 2009 Nico Coesel <ncoesel@dealogic.nl>
  14  * Copyright 2009 Zachary T Welch zw@superlucidity.net
  15  * Copyright 2009 David Brownell
  16  * Copyright (c) 2005-2011 Jim Tcl Project. All rights reserved.
  17  */
  18
  19 #ifndef OPENOCD_HELPER_JIM_NVP_H
  20 #define OPENOCD_HELPER_JIM_NVP_H
  21
  22 #include <jim.h>
  23
  24 /** Name Value Pairs, aka: NVP
  25  *   -  Given a string - return the associated int.
  26  *   -  Given a number - return the associated string.
  27  *   .
  28  *
  29  * Very useful when the number is not a simple index into an array of
  30  * known string, or there may be multiple strings (aliases) that mean then same
  31  * thing.
  32  *
  33  * An NVP Table is terminated with ".name = NULL".
  34  *
  35  * During the 'name2value' operation, if no matching string is found
  36  * the pointer to the terminal element (with p->name == NULL) is returned.
  37  *
  38  * Example:
  39  * \code
  40  *      const struct jim_nvp yn[] = {
  41  *          { "yes", 1 },
  42  *          { "no" , 0 },
  43  *          { "yep", 1 },
  44  *          { "nope", 0 },
  45  *          { NULL, -1 },
  46  *      };
  47  *
  48  *  struct jim_nvp *result
  49  *  e = jim_nvp_name2value(interp, yn, "y", &result);
  50  *         returns &yn[0];
  51  *  e = jim_nvp_name2value(interp, yn, "n", &result);
  52  *         returns &yn[1];
  53  *  e = jim_nvp_name2value(interp, yn, "Blah", &result);
  54  *         returns &yn[4];
  55  * \endcode
  56  *
  57  * During the number2name operation, the first matching value is returned.
  58  */
  59 struct jim_nvp {
  60         const char *name;
  61         int value;
  62 };
  63
  64 int jim_get_nvp(Jim_Interp *interp,
  65                 Jim_Obj *objptr,
  66                 const struct jim_nvp *nvp_table,
  67                 const struct jim_nvp **result);
  68
  69 /* Name Value Pairs Operations */
  70 struct jim_nvp *jim_nvp_name2value_simple(const struct jim_nvp *nvp_table, const char *name);
  71 struct jim_nvp *jim_nvp_name2value_nocase_simple(const struct jim_nvp *nvp_table, const char *name);
  72 struct jim_nvp *jim_nvp_value2name_simple(const struct jim_nvp *nvp_table, int v);
  73
  74 int jim_nvp_name2value(Jim_Interp *interp,
  75                 const struct jim_nvp *nvp_table,
  76                 const char *name,
  77                 struct jim_nvp **result);
  78 int jim_nvp_name2value_nocase(Jim_Interp *interp,
  79                 const struct jim_nvp *nvp_table,
  80                 const char *name,
  81                 struct jim_nvp **result);
  82 int jim_nvp_value2name(Jim_Interp *interp, const struct jim_nvp *nvp_table, int value, struct jim_nvp **result);
  83
  84 int jim_nvp_name2value_obj(Jim_Interp *interp,
  85                 const struct jim_nvp *nvp_table,
  86                 Jim_Obj *name_obj,
  87                 struct jim_nvp **result);
  88 int jim_nvp_name2value_obj_nocase(Jim_Interp *interp,
  89                 const struct jim_nvp *nvp_table,
  90                 Jim_Obj *name_obj,
  91                 struct jim_nvp **result);
  92 int jim_nvp_value2name_obj(Jim_Interp *interp,
  93                 const struct jim_nvp *nvp_table,
  94                 Jim_Obj *value_obj,
  95                 struct jim_nvp **result);
  96
  97 /** prints a nice 'unknown' parameter error message to the 'result' */
  98 void jim_set_result_nvp_unknown(Jim_Interp *interp,
  99                 Jim_Obj *param_name,
 100                 Jim_Obj *param_value,
 101                 const struct jim_nvp *nvp_table);
 102
 103 /** Debug: convert argc/argv into a printable string for printf() debug
 104  *
 105  * \param interp - the interpreter
 106  * \param argc   - arg count
 107  * \param argv   - the objects
 108  *
 109  * \returns string pointer holding the text.
 110  *
 111  * Note, next call to this function will free the old (last) string.
 112  *
 113  * For example might want do this:
 114  * \code
 115  *     fp = fopen("some.file.log", "a");
 116  *     fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
 117  *     fclose(fp);
 118  * \endcode
 119  */
 120 const char *jim_debug_argv_string(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
 121
 122
 123 /** A TCL -ish GetOpt like code.
 124  *
 125  * Some TCL objects have various "configuration" values.
 126  * For example - in Tcl/Tk the "buttons" have many options.
 127  *
 128  * Useful when dealing with command options.
 129  * that may come in any order...
 130  *
 131  * Does not support "-foo = 123" type options.
 132  * Only supports tcl type options, like "-foo 123"
 133  */
 134
 135 struct jim_getopt_info {
 136         Jim_Interp *interp;
 137         int argc;
 138         Jim_Obj *const *argv;
 139         int isconfigure;                /* non-zero if configure */
 140 };
 141
 142 /** GetOpt - how to.
 143  *
 144  * Example (short and incomplete):
 145  * \code
 146  *   struct jim_getopt_info goi;
 147  *
 148  *   jim_getopt_setup(&goi, interp, argc, argv);
 149  *
 150  *   while (goi.argc) {
 151  *         e = jim_getopt_nvp(&goi, nvp_options, &n);
 152  *         if (e != JIM_OK) {
 153  *               jim_getopt_nvp_unknown(&goi, nvp_options, 0);
 154  *               return e;
 155  *         }
 156  *
 157  *         switch (n->value) {
 158  *         case ALIVE:
 159  *             printf("Option ALIVE specified\n");
 160  *             break;
 161  *         case FIRST:
 162  *             if (goi.argc < 1) {
 163  *                     .. not enough args error ..
 164  *             }
 165  *             jim_getopt_string(&goi, &cp, NULL);
 166  *             printf("FIRSTNAME: %s\n", cp);
 167  *         case AGE:
 168  *             jim_getopt_wide(&goi, &w);
 169  *             printf("AGE: %d\n", (int)(w));
 170  *             break;
 171  *         case POLITICS:
 172  *             e = jim_getopt_nvp(&goi, nvp_politics, &n);
 173  *             if (e != JIM_OK) {
 174  *                 jim_getopt_nvp_unknown(&goi, nvp_politics, 1);
 175  *                 return e;
 176  *             }
 177  *         }
 178  *  }
 179  *
 180  * \endcode
 181  *
 182  */
 183
 184 /** Setup GETOPT
 185  *
 186  * \param goi    - get opt info to be initialized
 187  * \param interp - jim interp
 188  * \param argc   - argc count.
 189  * \param argv   - argv (will be copied)
 190  *
 191  * \code
 192  *     struct jim_getopt_info  goi;
 193  *
 194  *     Jim_GetOptSetup(&goi, interp, argc, argv);
 195  * \endcode
 196  */
 197
 198 int jim_getopt_setup(struct jim_getopt_info *goi,
 199                 Jim_Interp *interp,
 200                 int argc,
 201                 Jim_Obj *const *argv);
 202
 203
 204 /** Debug - Dump parameters to stderr
 205  * \param goi - current parameters
 206  */
 207 void jim_getopt_debug(struct jim_getopt_info *goi);
 208
 209 /** Remove argv[0] from the list.
 210  *
 211  * \param goi - get opt info
 212  * \param puthere - where param is put
 213  *
 214  */
 215 int jim_getopt_obj(struct jim_getopt_info *goi, Jim_Obj **puthere);
 216
 217 /** Remove argv[0] as string.
 218  *
 219  * \param goi     - get opt info
 220  * \param puthere - where param is put
 221  * \param len     - return its length
 222  */
 223 int jim_getopt_string(struct jim_getopt_info *goi, const char **puthere, int *len);
 224
 225 /** Remove argv[0] as double.
 226  *
 227  * \param goi     - get opt info
 228  * \param puthere - where param is put.
 229  *
 230  */
 231 int jim_getopt_double(struct jim_getopt_info *goi, double *puthere);
 232
 233 /** Remove argv[0] as wide.
 234  *
 235  * \param goi     - get opt info
 236  * \param puthere - where param is put.
 237  */
 238 int jim_getopt_wide(struct jim_getopt_info *goi, jim_wide *puthere);
 239
 240 /** Remove argv[0] as NVP.
 241  *
 242  * \param goi     - get opt info
 243  * \param lookup  - nvp lookup table
 244  * \param puthere - where param is put.
 245  *
 246  */
 247 int jim_getopt_nvp(struct jim_getopt_info *goi, const struct jim_nvp *lookup, struct jim_nvp **puthere);
 248
 249 /** Create an appropriate error message for an NVP.
 250  *
 251  * \param goi - options info
 252  * \param lookup - the NVP table that was used.
 253  * \param hadprefix - 0 or 1 if the option had a prefix.
 254  *
 255  * This function will set the "interp->result" to a human readable
 256  * error message listing the available options.
 257  *
 258  * This function assumes the previous option argv[-1] is the unknown string.
 259  *
 260  * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
 261  *
 262  * Example:
 263  * \code
 264  *
 265  *  while (goi.argc) {
 266  *     // Get the next option
 267  *     e = jim_getopt_nvp(&goi, cmd_options, &n);
 268  *     if (e != JIM_OK) {
 269  *          // option was not recognized
 270  *          // pass 'hadprefix = 0' because there is no prefix
 271  *          jim_getopt_nvp_unknown(&goi, cmd_options, 0);
 272  *          return e;
 273  *     }
 274  *
 275  *     switch (n->value) {
 276  *     case OPT_SEX:
 277  *          // handle:  --sex male | female | lots | needmore
 278  *          e = jim_getopt_nvp(&goi, &nvp_sex, &n);
 279  *          if (e != JIM_OK) {
 280  *               jim_getopt_nvp_unknown(&ogi, nvp_sex, 1);
 281  *               return e;
 282  *          }
 283  *          printf("Code: (%d) is %s\n", n->value, n->name);
 284  *          break;
 285  *     case ...:
 286  *          [snip]
 287  *     }
 288  * }
 289  * \endcode
 290  *
 291  */
 292 void jim_getopt_nvp_unknown(struct jim_getopt_info *goi, const struct jim_nvp *lookup, int hadprefix);
 293
 294
 295 /** Remove argv[0] as Enum
 296  *
 297  * \param goi     - get opt info
 298  * \param lookup  - lookup table.
 299  * \param puthere - where param is put.
 300  *
 301  */
 302 int jim_getopt_enum(struct jim_getopt_info *goi, const char *const *lookup, int *puthere);
 303
 304 #endif /* OPENOCD_HELPER_JIM_NVP_H */