jim-subcmd.h

   1 /* Provides a common approach to implementing Tcl commands
   2  * which implement subcommands
   3  */
   4 #ifndef JIM_SUBCMD_H
   5 #define JIM_SUBCMD_H
   6
   7 #include <jim.h>
   8
   9 #ifdef __cplusplus
  10 extern "C" {
  11 #endif
  12
  13
  14 #define JIM_MODFLAG_HIDDEN   0x0001             /* Don't show the subcommand in usage or commands */
  15 #define JIM_MODFLAG_FULLARGV 0x0002             /* Subcmd proc gets called with full argv */
  16
  17 /* Custom flags start at 0x0100 */
  18
  19 /**
  20  * Returns JIM_OK if OK, JIM_ERR (etc.) on error, break, continue, etc.
  21  * Returns -1 if invalid args.
  22  */
  23 typedef int jim_subcmd_function(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
  24
  25 typedef struct {
  26         const char *cmd;                                /* Name of the (sub)command */
  27         const char *args;                               /* Textual description of allowed args */
  28         jim_subcmd_function *function;  /* Function implementing the subcommand */
  29         short minargs;                                  /* Minimum required arguments */
  30         short maxargs;                                  /* Maximum allowed arguments or -1 if no limit */
  31         unsigned short flags;                   /* JIM_MODFLAG_... plus custom flags */
  32 } jim_subcmd_type;
  33
  34 /**
  35  * Looks up the appropriate subcommand in the given command table and return
  36  * the command function which implements the subcommand.
  37  * NULL will be returned and an appropriate error will be set if the subcommand or
  38  * arguments are invalid.
  39  *
  40  * Typical usage is:
  41  *  {
  42  *    const jim_subcmd_type *ct = Jim_ParseSubCmd(interp, command_table, argc, argv);
  43  *
  44  *    return Jim_CallSubCmd(interp, ct, argc, argv);
  45  *  }
  46  *
  47  */
  48 const jim_subcmd_type *
  49 Jim_ParseSubCmd(Jim_Interp *interp, const jim_subcmd_type *command_table, int argc, Jim_Obj *const *argv);
  50
  51 /**
  52  * Parses the args against the given command table and executes the subcommand if found
  53  * or sets an appropriate error if the subcommand or arguments is invalid.
  54  *
  55  * Can be used directly with Jim_CreateCommand() where the ClientData is the command table.
  56  *
  57  * e.g. Jim_CreateCommand(interp, "mycmd", Jim_SubCmdProc, command_table, NULL);
  58  */
  59 int Jim_SubCmdProc(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
  60
  61 /**
  62  * Invokes the given subcmd with the given args as returned
  63  * by Jim_ParseSubCmd()
  64  *
  65  * If ct is NULL, returns JIM_ERR, leaving any message.
  66  * Otherwise invokes ct->function
  67  *
  68  * If ct->function returns -1, sets an error message and returns JIM_ERR.
  69  * Otherwise returns the result of ct->function.
  70  */
  71 int Jim_CallSubCmd(Jim_Interp *interp, const jim_subcmd_type *ct, int argc, Jim_Obj *const *argv);
  72
  73 #ifdef __cplusplus
  74 }
  75 #endif
  76
  77 #endif