improve 'help' command

Rewrites 'help' command in C, using new 'cmd_help' for display.  Adds the
built-in 'help' COMMAND_HANDLER to provide better output than the
TCL-based script command (e.g. heirarchical listing of commands).

The help string is stored in the command structure, though it conitnues
to be pushed into the Jim environment.  The current idiomatic usage
suggests the addition of a usage field as well, to provide two levels
of detail for users to consume (i.e. terse usage list, or verbose help).

diff --git a/src/helper/command.c b/src/helper/command.c
index 87a898f293eb9b868a3ea1287e7ce82c788f60c5..f135bb03cb2f8dbed1e7d75a2d2ed042e3e424ef 100644 (file)
--- a/src/helper/command.c
+++ b/src/helper/command.c
@@ -250,6 +250,8 @@ static struct command *command_new(struct command_context *cmd_ctx,
        memset(c, 0, sizeof(struct command));
 
        c->name = strdup(name);
+       if (help)
+               c->help = strdup(help);
        c->parent = parent;
        c->handler = handler;
        c->mode = mode;
@@ -273,6 +275,8 @@ static void command_free(struct command *c)
 
        if (c->name)
                free(c->name);
+       if (c->help)
+               free((void*)c->help);
        free(c);
 }
 
@@ -721,6 +725,52 @@ static int jim_capture(Jim_Interp *interp, int argc, Jim_Obj *const *argv)
        return retcode;
 }
 
+static COMMAND_HELPER(command_help_find, struct command *head,
+               struct command **out)
+{
+       if (0 == CMD_ARGC)
+               return ERROR_INVALID_ARGUMENTS;
+       *out = command_find(head, CMD_ARGV[0]);
+       if (NULL == *out)
+               return ERROR_INVALID_ARGUMENTS;
+       if (--CMD_ARGC == 0)
+               return ERROR_OK;
+       CMD_ARGV++;
+       return CALL_COMMAND_HANDLER(command_help_find, (*out)->children, out);
+}
+
+static COMMAND_HELPER(command_help_show, struct command *c, unsigned n);
+
+static COMMAND_HELPER(command_help_show_list, struct command *head, unsigned n)
+{
+       for (struct command *c = head; NULL != c; c = c->next)
+               CALL_COMMAND_HANDLER(command_help_show, c, n);
+       return ERROR_OK;
+}
+static COMMAND_HELPER(command_help_show, struct command *c, unsigned n)
+{
+       command_run_linef(CMD_CTX, "cmd_help {%s} {%s} %d", command_name(c, ' '),
+                       c->help ? : "no help available", n);
+
+       if (++n >= 2)
+               return ERROR_OK;
+
+       return CALL_COMMAND_HANDLER(command_help_show_list, c->children, n);
+}
+COMMAND_HANDLER(handle_help_command)
+{
+       struct command *c = CMD_CTX->commands;
+
+       if (0 == CMD_ARGC)
+               return CALL_COMMAND_HANDLER(command_help_show_list, c, 0);
+
+       int retval = CALL_COMMAND_HANDLER(command_help_find, c, &c);
+       if (ERROR_OK != retval)
+               return retval;
+
+       return CALL_COMMAND_HANDLER(command_help_show, c, 0);
+}
+
 /* sleep command sleeps for <n> miliseconds
  * this is useful in target startup scripts
  */
@@ -831,6 +881,10 @@ struct command_context* command_init(const char *startup_tcl)
                        "<n> [busy] - sleep for n milliseconds. "
                        "\"busy\" means busy wait");
 
+       register_command(context, NULL, "help",
+                       &handle_help_command, COMMAND_ANY,
+                       "[<command_name> ...] - show built-in command help");
+
        return context;
 }
 
@@ -977,5 +1031,3 @@ COMMAND_HELPER(handle_command_parse_bool, bool *out, const char *label)
        }
        return ERROR_OK;
 }
-
-

diff --git a/src/helper/command.h b/src/helper/command.h
index a7b422adf899594a818dd8d05ac27634b40158e3..837b4bdd2cc77339f5a252e5f2bc3018d74a95b3 100644 (file)
--- a/src/helper/command.h
+++ b/src/helper/command.h
@@ -159,6 +159,7 @@ typedef __COMMAND_HANDLER((*command_handler_t));
 struct command
 {
        char *name;
+       const char *help;
        struct command *parent;
        struct command *children;
        command_handler_t handler;

diff --git a/src/helper/startup.tcl b/src/helper/startup.tcl
index 30dc184f7f6fa65270a756130e4730c74f97a617..ddfef1dc9ae1181d537f58d21b12a1e12e9c2e07 100644 (file)
--- a/src/helper/startup.tcl
+++ b/src/helper/startup.tcl
@@ -58,24 +58,6 @@ proc cmd_help {cmdname h indent} {
        }
 }
 
-#Print help text for a command. Word wrap
-#help text that is too wide inside column.
-proc help {args} {
-       global ocd_helptext
-       set cmd $args
-       foreach a [lsort $ocd_helptext] {
-               if {[string length $cmd] == 0 || \
-                       [string first $cmd $a] != -1 || \
-                       [string first $cmd [lindex $a 1]] != -1} \
-               {
-                       cmd_help [lindex $a 0] [lindex $a 1] 0
-               }
-       }
-}
-
-add_help_text help "Tcl implementation of help command"
-
-
 # If a fn is unknown to Tcl, we try to execute it as an OpenOCD command
 #
 # We also support two level commands. "flash banks" is translated to