[Lldb-commits] [PATCH] Add help flag to 'command script add'
Enrico Granata
egranata at apple.com
Tue Jan 7 18:01:03 PST 2014
Hi Ari,
sorry for the delay in looking at this patch
I have a gut feeling it would be best, if possible, to let the command itself provide a docstring, rather than rely on command-line artifacts for such purposes
While in practice, I expect most commands to be added through __lldb_init_module calls rather than manually, it still feels hacky to me to have a flag for “help string”
I can see a couple solutions here.
One would be to, say, extract the first line of the __doc__ attribute and use that as the “short help”, keeping the full __doc__string for “long help”
Or we could add a custom attribute, say __lldb_helpstring__ to the function object, and if available, fetch and use it as the short help
I am not specifically wed to either approach, and definitely open to other alternatives, it just strikes me as unclean to have the command add operation also provide a short help string, instead of somehow keeping this as much as possible within the command itself.
Let me know your thoughts
Enrico Granata
📩 egranata@.com
☎️ 27683
On Dec 31, 2013, at 3:49 PM, Ari Grant <ari.grant at me.com> wrote:
> 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." },
> <D2495.1.patch>_______________________________________________
> lldb-commits mailing list
> lldb-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/lldb-commits
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20140107/50aa88e5/attachment.html>
More information about the lldb-commits
mailing list