[Lldb-commits] [PATCH] Add help flag to 'command script add'

[Ari Grant]

Currently the help command in LLDB will print the __doc__ string for any python commands a user has added. However, when help is called without any arguments all commands are listed and the help shown for python commands is unhelpful. The message is a vague description the includes no more than the function name the command calls into.

This adds a help flag to specify a one line, brief help string for use in this case. Now a person can invoke:

(lldb) command script add -f somePyModule.somePyFunc -h "A quick hint about what this is."

and then calling 'help' will show the help string for the user added commands.

http://llvm-reviews.chandlerc.com/D2495

Files:
  include/lldb/lldb-enumerations.h
  source/Commands/CommandObjectCommands.cpp
  source/Interpreter/CommandObject.cpp

Index: include/lldb/lldb-enumerations.h
===================================================================
--- include/lldb/lldb-enumerations.h
+++ include/lldb/lldb-enumerations.h
@@ -394,6 +394,7 @@
         eArgTypeFunctionName,
         eArgTypeFunctionOrSymbol,
         eArgTypeGDBFormat,
+        eArgTypeHelpString,
         eArgTypeIndex,
         eArgTypeLanguage,
         eArgTypeLineNum,
Index: source/Commands/CommandObjectCommands.cpp
===================================================================
--- source/Commands/CommandObjectCommands.cpp
+++ source/Commands/CommandObjectCommands.cpp
@@ -1261,10 +1261,11 @@
     CommandObjectPythonFunction (CommandInterpreter &interpreter,
                                  std::string name,
                                  std::string funct,
+                                 std::string help,
                                  ScriptedCommandSynchronicity synch) :
         CommandObjectRaw (interpreter,
                           name.c_str(),
-                          (std::string("Run Python function ") + funct).c_str(),
+                          (help == "" ? (std::string("Run Python function ") + funct) : help).c_str(),
                           NULL),
         m_function_name(funct),
         m_synchro(synch),
@@ -1537,7 +1538,10 @@
         m_options (interpreter)
     {
         CommandArgumentEntry arg1;
+        CommandArgumentEntry arg2;
+
         CommandArgumentData cmd_arg;
+        CommandArgumentData help_arg;
         
         // Define the first (and only) variant of this arg.
         cmd_arg.arg_type = eArgTypeCommandName;
@@ -1545,9 +1549,17 @@
         
         // There is only one variant this argument could be; put it into the argument entry.
         arg1.push_back (cmd_arg);
-        
-        // Push the data for the first argument into the m_arguments vector.
+
+        // Define the first (and only) variant of this arg.
+        help_arg.arg_type = eArgTypeHelpString;
+        help_arg.arg_repetition = eArgRepeatPlain;
+
+        // There is only one variant this argument could be; put it into the argument entry.
+        arg2.push_back (help_arg);
+
+        // Push the data for the second argument into the m_arguments vector.
         m_arguments.push_back (arg1);
+        m_arguments.push_back (arg2);
     }
     
     ~CommandObjectCommandsScriptAdd ()
@@ -1585,6 +1597,9 @@
                 case 'f':
                     m_funct_name = std::string(option_arg);
                     break;
+                case 'h':
+                    m_help_string = std::string(option_arg);
+                    break;
                 case 's':
                     m_synchronous = (ScriptedCommandSynchronicity) Args::StringToOptionEnum(option_arg, g_option_table[option_idx].enum_values, 0, error);
                     if (!error.Success())
@@ -1602,6 +1617,7 @@
         OptionParsingStarting ()
         {
             m_funct_name = "";
+            m_help_string = "";
             m_synchronous = eScriptedCommandSynchronicitySynchronous;
         }
         
@@ -1618,6 +1634,7 @@
         // Instance variables to hold the values for command options.
         
         std::string m_funct_name;
+        std::string m_help_string;
         ScriptedCommandSynchronicity m_synchronous;
     };
 
@@ -1729,6 +1746,7 @@
             CommandObjectSP command_obj_sp(new CommandObjectPythonFunction(m_interpreter,
                                                                            m_cmd_name,
                                                                            funct_name_str.c_str(),
+                                                                           "",
                                                                            m_synchronous));
             
             if (!m_interpreter.AddUserCommand(m_cmd_name, command_obj_sp, true))
@@ -1798,6 +1816,7 @@
             CommandObjectSP new_cmd(new CommandObjectPythonFunction(m_interpreter,
                                                                     cmd_name,
                                                                     m_options.m_funct_name,
+                                                                    m_options.m_help_string,
                                                                     m_options.m_synchronous));
             if (m_interpreter.AddUserCommand(cmd_name, new_cmd, true))
             {
@@ -1829,6 +1848,7 @@
 CommandObjectCommandsScriptAdd::CommandOptions::g_option_table[] =
 {
     { LLDB_OPT_SET_1, false, "function", 'f', OptionParser::eRequiredArgument, NULL, 0, eArgTypePythonFunction,        "Name of the Python function to bind to this command name."},
+    { LLDB_OPT_SET_1, false, "help", 'h', OptionParser::eRequiredArgument, NULL, 0, eArgTypeHelpString,        "A string that briefly describes the command."},
     { LLDB_OPT_SET_1, false, "synchronicity", 's', OptionParser::eRequiredArgument, g_script_synchro_type, 0, eArgTypeScriptedCommandSynchronicity,        "Set the synchronicity of this command's executions with regard to LLDB event system."},
     { 0, false, NULL, 0, 0, NULL, 0, eArgTypeNone, NULL }
 };
Index: source/Interpreter/CommandObject.cpp
===================================================================
--- source/Interpreter/CommandObject.cpp
+++ source/Interpreter/CommandObject.cpp
@@ -1110,6 +1110,7 @@
     { eArgTypeFunctionName, "function-name", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function." },
     { eArgTypeFunctionOrSymbol, "function-or-symbol", CommandCompletions::eNoCompletion, { NULL, false }, "The name of a function or symbol." },
     { eArgTypeGDBFormat, "gdb-format", CommandCompletions::eNoCompletion, { GDBFormatHelpTextCallback, true }, NULL },
+    { eArgTypeHelpString, "help-string", CommandCompletions::eNoCompletion, { NULL, false }, "A brief help string summarizing a function or symbol." },
     { eArgTypeIndex, "index", CommandCompletions::eNoCompletion, { NULL, false }, "An index into a list." },
     { eArgTypeLanguage, "language", CommandCompletions::eNoCompletion, { LanguageTypeHelpTextCallback, true }, NULL },
     { eArgTypeLineNum, "linenum", CommandCompletions::eNoCompletion, { NULL, false }, "Line number in a source file." },
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D2495.1.patch
Type: text/x-patch
Size: 6309 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20131231/db5380e6/attachment.bin>