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