|
- /* Jim - A small embeddable Tcl interpreter
- *
- * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
- * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
- * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
- * Copyright 2008 oharboe - Øyvind Harboe - oyvind.harboe@zylin.com
- * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
- * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
- * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
- * Copyright 2008 Steve Bennett <steveb@workware.net.au>
- * Copyright 2009 Nico Coesel <ncoesel@dealogic.nl>
- * Copyright 2009 Zachary T Welch zw@superlucidity.net
- * Copyright 2009 David Brownell
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
- * are met:
- *
- * 1. Redistributions of source code must retain the above copyright
- * notice, this list of conditions and the following disclaimer.
- * 2. Redistributions in binary form must reproduce the above
- * copyright notice, this list of conditions and the following
- * disclaimer in the documentation and/or other materials
- * provided with the distribution.
- *
- * THIS SOFTWARE IS PROVIDED BY THE JIM TCL PROJECT ``AS IS'' AND ANY
- * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
- * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
- * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
- * JIM TCL PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
- * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
- * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
- * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
- * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * The views and conclusions contained in the software and documentation
- * are those of the authors and should not be interpreted as representing
- * official policies, either expressed or implied, of the Jim Tcl Project.
- */
-
- #ifndef JIM_NVP_H
- #define JIM_NVP_H
-
- #include <jim.h>
-
- /** Name Value Pairs, aka: NVP
- * - Given a string - return the associated int.
- * - Given a number - return the associated string.
- * .
- *
- * Very useful when the number is not a simple index into an array of
- * known string, or there may be multiple strings (aliases) that mean then same
- * thing.
- *
- * An NVP Table is terminated with ".name = NULL".
- *
- * During the 'name2value' operation, if no matching string is found
- * the pointer to the terminal element (with p->name == NULL) is returned.
- *
- * Example:
- * \code
- * const Jim_Nvp yn[] = {
- * { "yes", 1 },
- * { "no" , 0 },
- * { "yep", 1 },
- * { "nope", 0 },
- * { NULL, -1 },
- * };
- *
- * Jim_Nvp *result
- * e = Jim_Nvp_name2value(interp, yn, "y", &result);
- * returns &yn[0];
- * e = Jim_Nvp_name2value(interp, yn, "n", &result);
- * returns &yn[1];
- * e = Jim_Nvp_name2value(interp, yn, "Blah", &result);
- * returns &yn[4];
- * \endcode
- *
- * During the number2name operation, the first matching value is returned.
- */
- typedef struct {
- const char *name;
- int value;
- } Jim_Nvp;
-
-
- int Jim_GetNvp (Jim_Interp *interp,
- Jim_Obj *objPtr,
- const Jim_Nvp *nvp_table,
- const Jim_Nvp **result);
-
- /* Name Value Pairs Operations */
- Jim_Nvp *Jim_Nvp_name2value_simple(const Jim_Nvp *nvp_table, const char *name);
- Jim_Nvp *Jim_Nvp_name2value_nocase_simple(const Jim_Nvp *nvp_table, const char *name);
- Jim_Nvp *Jim_Nvp_value2name_simple(const Jim_Nvp *nvp_table, int v);
-
- int Jim_Nvp_name2value(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
- int Jim_Nvp_name2value_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, const char *name, Jim_Nvp **result);
- int Jim_Nvp_value2name(Jim_Interp *interp, const Jim_Nvp *nvp_table, int value, Jim_Nvp **result);
-
- int Jim_Nvp_name2value_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
- int Jim_Nvp_name2value_obj_nocase(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *name_obj, Jim_Nvp **result);
- int Jim_Nvp_value2name_obj(Jim_Interp *interp, const Jim_Nvp *nvp_table, Jim_Obj *value_obj, Jim_Nvp **result);
-
- /** prints a nice 'unknown' parameter error message to the 'result' */
- void Jim_SetResult_NvpUnknown(Jim_Interp *interp,
- Jim_Obj *param_name,
- Jim_Obj *param_value,
- const Jim_Nvp *nvp_table);
-
-
- /** Debug: convert argc/argv into a printable string for printf() debug
- *
- * \param interp - the interpeter
- * \param argc - arg count
- * \param argv - the objects
- *
- * \returns string pointer holding the text.
- *
- * Note, next call to this function will free the old (last) string.
- *
- * For example might want do this:
- * \code
- * fp = fopen("some.file.log", "a");
- * fprintf(fp, "PARAMS are: %s\n", Jim_DebugArgvString(interp, argc, argv));
- * fclose(fp);
- * \endcode
- */
- const char *Jim_Debug_ArgvString(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
-
-
- /** A TCL -ish GetOpt like code.
- *
- * Some TCL objects have various "configuration" values.
- * For example - in Tcl/Tk the "buttons" have many options.
- *
- * Usefull when dealing with command options.
- * that may come in any order...
- *
- * Does not support "-foo = 123" type options.
- * Only supports tcl type options, like "-foo 123"
- */
-
- typedef struct jim_getopt {
- Jim_Interp *interp;
- int argc;
- Jim_Obj * const * argv;
- int isconfigure; /* non-zero if configure */
- } Jim_GetOptInfo;
-
- /** GetOpt - how to.
- *
- * Example (short and incomplete):
- * \code
- * Jim_GetOptInfo goi;
- *
- * Jim_GetOpt_Setup(&goi, interp, argc, argv);
- *
- * while (goi.argc) {
- * e = Jim_GetOpt_Nvp(&goi, nvp_options, &n);
- * if (e != JIM_OK) {
- * Jim_GetOpt_NvpUnknown(&goi, nvp_options, 0);
- * return e;
- * }
- *
- * switch (n->value) {
- * case ALIVE:
- * printf("Option ALIVE specified\n");
- * break;
- * case FIRST:
- * if (goi.argc < 1) {
- * .. not enough args error ..
- * }
- * Jim_GetOpt_String(&goi, &cp, NULL);
- * printf("FIRSTNAME: %s\n", cp);
- * case AGE:
- * Jim_GetOpt_Wide(&goi, &w);
- * printf("AGE: %d\n", (int)(w));
- * break;
- * case POLITICS:
- * e = Jim_GetOpt_Nvp(&goi, nvp_politics, &n);
- * if (e != JIM_OK) {
- * Jim_GetOpt_NvpUnknown(&goi, nvp_politics, 1);
- * return e;
- * }
- * }
- * }
- *
- * \endcode
- *
- */
-
- /** Setup GETOPT
- *
- * \param goi - get opt info to be initialized
- * \param interp - jim interp
- * \param argc - argc count.
- * \param argv - argv (will be copied)
- *
- * \code
- * Jim_GetOptInfo goi;
- *
- * Jim_GetOptSetup(&goi, interp, argc, argv);
- * \endcode
- */
-
- int Jim_GetOpt_Setup(Jim_GetOptInfo *goi,
- Jim_Interp *interp,
- int argc,
- Jim_Obj * const * argv);
-
-
- /** Debug - Dump parameters to stderr
- * \param goi - current parameters
- */
- void Jim_GetOpt_Debug(Jim_GetOptInfo *goi);
-
-
-
- /** Remove argv[0] from the list.
- *
- * \param goi - get opt info
- * \param puthere - where param is put
- *
- */
- int Jim_GetOpt_Obj(Jim_GetOptInfo *goi, Jim_Obj **puthere);
-
- /** Remove argv[0] as string.
- *
- * \param goi - get opt info
- * \param puthere - where param is put
- * \param len - return its length
- */
- int Jim_GetOpt_String(Jim_GetOptInfo *goi, char **puthere, int *len);
-
- /** Remove argv[0] as double.
- *
- * \param goi - get opt info
- * \param puthere - where param is put.
- *
- */
- int Jim_GetOpt_Double(Jim_GetOptInfo *goi, double *puthere);
-
- /** Remove argv[0] as wide.
- *
- * \param goi - get opt info
- * \param puthere - where param is put.
- */
- int Jim_GetOpt_Wide(Jim_GetOptInfo *goi, jim_wide *puthere);
-
- /** Remove argv[0] as NVP.
- *
- * \param goi - get opt info
- * \param lookup - nvp lookup table
- * \param puthere - where param is put.
- *
- */
- int Jim_GetOpt_Nvp(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, Jim_Nvp **puthere);
-
- /** Create an appropriate error message for an NVP.
- *
- * \param goi - options info
- * \param lookup - the NVP table that was used.
- * \param hadprefix - 0 or 1 if the option had a prefix.
- *
- * This function will set the "interp->result" to a human readable
- * error message listing the available options.
- *
- * This function assumes the previous option argv[-1] is the unknown string.
- *
- * If this option had some prefix, then pass "hadprefix = 1" else pass "hadprefix = 0"
- *
- * Example:
- * \code
- *
- * while (goi.argc) {
- * // Get the next option
- * e = Jim_GetOpt_Nvp(&goi, cmd_options, &n);
- * if (e != JIM_OK) {
- * // option was not recognized
- * // pass 'hadprefix = 0' because there is no prefix
- * Jim_GetOpt_NvpUnknown(&goi, cmd_options, 0);
- * return e;
- * }
- *
- * switch (n->value) {
- * case OPT_SEX:
- * // handle: --sex male | female | lots | needmore
- * e = Jim_GetOpt_Nvp(&goi, &nvp_sex, &n);
- * if (e != JIM_OK) {
- * Jim_GetOpt_NvpUnknown(&ogi, nvp_sex, 1);
- * return e;
- * }
- * printf("Code: (%d) is %s\n", n->value, n->name);
- * break;
- * case ...:
- * [snip]
- * }
- * }
- * \endcode
- *
- */
- void Jim_GetOpt_NvpUnknown(Jim_GetOptInfo *goi, const Jim_Nvp *lookup, int hadprefix);
-
-
- /** Remove argv[0] as Enum
- *
- * \param goi - get opt info
- * \param lookup - lookup table.
- * \param puthere - where param is put.
- *
- */
- int Jim_GetOpt_Enum(Jim_GetOptInfo *goi, const char * const * lookup, int *puthere);
-
- #endif
|