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 #define JIM_MODFLAG_HIDDEN   0x0001             /* Don't show the subcommand in usage or commands */
  10 #define JIM_MODFLAG_FULLARGV 0x0002             /* Subcmd proc gets called with full argv */
  11
  12 /* Custom flags start at 0x0100 */
  13
  14 /**
  15  * Returns JIM_OK if OK, JIM_ERR (etc.) on error, break, continue, etc.
  16  * Returns -1 if invalid args.
  17  */
  18 typedef int tclmod_cmd_function(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
  19
  20 typedef struct {
  21         const char *cmd;                                /* Name of the (sub)command */
  22         const char *args;                               /* Textual description of allowed args */
  23         tclmod_cmd_function *function;  /* Function implementing the subcommand */
  24         short minargs;                                  /* Minimum required arguments */
  25         short maxargs;                                  /* Maximum allowed arguments or -1 if no limit */
  26         unsigned flags;                                 /* JIM_MODFLAG_... plus custom flags */
  27         const char *description;                /* Description of the subcommand */
  28 } jim_subcmd_type;
  29
  30 /**
  31  * Looks up the appropriate subcommand in the given command table and return
  32  * the command function which implements the subcommand.
  33  * NULL will be returned and an appropriate error will be set if the subcommand or
  34  * arguments are invalid.
  35  *
  36  * Typical usage is:
  37  *  {
  38  *    const jim_subcmd_type *ct = Jim_ParseSubCmd(interp, command_table, argc, argv);
  39  *
  40  *    return Jim_CallSubCmd(interp, ct, argc, argv);
  41  *  }
  42  *
  43  */
  44 const jim_subcmd_type *
  45 Jim_ParseSubCmd(Jim_Interp *interp, const jim_subcmd_type *command_table, int argc, Jim_Obj *const *argv);
  46
  47 /**
  48  * Parses the args against the given command table and executes the subcommand if found
  49  * or sets an appropriate error if the subcommand or arguments is invalid.
  50  *
  51  * Can be used directly with Jim_CreateCommand() where the ClientData is the command table.
  52  *
  53  * e.g. Jim_CreateCommand(interp, "mycmd", Jim_SubCmdProc, command_table, NULL);
  54  */
  55 int Jim_SubCmdProc(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
  56
  57 /**
  58  * Invokes the given subcmd with the given args as returned
  59  * by Jim_ParseSubCmd()
  60  *
  61  * If ct is NULL, returns JIM_ERR, leaving any message.
  62  * Otherwise invokes ct->function
  63  *
  64  * If ct->function returns -1, sets an error message and returns JIM_ERR.
  65  * Otherwise returns the result of ct->function.
  66  */
  67 int Jim_CallSubCmd(Jim_Interp *interp, const jim_subcmd_type *ct, int argc, Jim_Obj *const *argv);
  68
  69 /**
  70  * Standard processing for a command.
  71  *
  72  * This does the '-help' and '-usage' check and the number of args checks.
  73  * for a top level command against a single 'jim_subcmd_type' structure.
  74  *
  75  * Additionally, if command_table->function is set, it should point to a sub command table
  76  * and '-subhelp ?subcmd?', '-subusage' and '-subcommands' are then also recognised.
  77  *
  78  * Returns 0 if user requested usage, -1 on arg error, 1 if OK to process.
  79  */
  80 int
  81 Jim_CheckCmdUsage(Jim_Interp *interp, const jim_subcmd_type *command_table, int argc, Jim_Obj *const *argv);
  82
  83 #endif