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 tclmod_cmd_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         tclmod_cmd_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 flags;                                 /* JIM_MODFLAG_... plus custom flags */
  32         const char *description;                /* Description of the subcommand */
  33 } jim_subcmd_type;
  34
  35 /**
  36  * Looks up the appropriate subcommand in the given command table and return
  37  * the command function which implements the subcommand.
  38  * NULL will be returned and an appropriate error will be set if the subcommand or
  39  * arguments are invalid.
  40  *
  41  * Typical usage is:
  42  *  {
  43  *    const jim_subcmd_type *ct = Jim_ParseSubCmd(interp, command_table, argc, argv);
  44  *
  45  *    return Jim_CallSubCmd(interp, ct, argc, argv);
  46  *  }
  47  *
  48  */
  49 const jim_subcmd_type *
  50 Jim_ParseSubCmd(Jim_Interp *interp, const jim_subcmd_type *command_table, int argc, Jim_Obj *const *argv);
  51
  52 /**
  53  * Parses the args against the given command table and executes the subcommand if found
  54  * or sets an appropriate error if the subcommand or arguments is invalid.
  55  *
  56  * Can be used directly with Jim_CreateCommand() where the ClientData is the command table.
  57  *
  58  * e.g. Jim_CreateCommand(interp, "mycmd", Jim_SubCmdProc, command_table, NULL);
  59  */
  60 int Jim_SubCmdProc(Jim_Interp *interp, int argc, Jim_Obj *const *argv);
  61
  62 /**
  63  * Invokes the given subcmd with the given args as returned
  64  * by Jim_ParseSubCmd()
  65  *
  66  * If ct is NULL, returns JIM_ERR, leaving any message.
  67  * Otherwise invokes ct->function
  68  *
  69  * If ct->function returns -1, sets an error message and returns JIM_ERR.
  70  * Otherwise returns the result of ct->function.
  71  */
  72 int Jim_CallSubCmd(Jim_Interp *interp, const jim_subcmd_type *ct, int argc, Jim_Obj *const *argv);
  73
  74 /**
  75  * Standard processing for a command.
  76  *
  77  * This does the '-help' and '-usage' check and the number of args checks.
  78  * for a top level command against a single 'jim_subcmd_type' structure.
  79  *
  80  * Additionally, if command_table->function is set, it should point to a sub command table
  81  * and '-subhelp ?subcmd?', '-subusage' and '-subcommands' are then also recognised.
  82  *
  83  * Returns 0 if user requested usage, -1 on arg error, 1 if OK to process.
  84  */
  85 int
  86 Jim_CheckCmdUsage(Jim_Interp *interp, const jim_subcmd_type *command_table, int argc, Jim_Obj *const *argv);
  87
  88 #ifdef __cplusplus
  89 }
  90 #endif
  91
  92 #endif