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