[Lldb-commits] [lldb] Add the ability to define a Python based command that uses CommandObjectParsed (PR #70734)

[Med Ismail Bennani via lldb-commits]

================
@@ -0,0 +1,321 @@
+"""
+This module implements a couple of utility classes to make writing
+lldb parsed commands more Pythonic.
+The way to use it is to make a class for your command that inherits from ParsedCommandBase.
+That will make an LLDBOptionValueParser which you will use for your
+option definition, and to fetch option values for the current invocation
+of your command.  Access to the OV parser is through:
+
+ParsedCommandBase.get_parser()
+
+Next, implement setup_command_definition() in your new command class, and call:
+
+  self.get_parser().add_option()
+
+to add all your options.  The order doesn't matter for options, lldb will sort them
+alphabetically for you when it prints help.
+
+Similarly you can define the arguments with:
+
+  self.get_parser().add_argument()
+
+At present, lldb doesn't do as much work as it should verifying arguments, it
+only checks that commands that take no arguments don't get passed arguments.
+
+Then implement the execute function for your command as:
+
+    def __call__(self, debugger, args_list, exe_ctx, result):
+
+The arguments will be a list of strings.  
+
+You can access the option values using the 'dest' string you passed in when defining the option.
+And if you need to know whether a given option was set by the user or not, you can
+use the was_set API.  
+
+So for instance, if you have an option whose "dest" is "my_option", then:
+
+    self.get_parser().my_option
+
+will fetch the value, and:
+
+    self.get_parser().was_set("my_option")
+
+will return True if the user set this option, and False if it was left at its default
+value.
+
+There are example commands in the lldb testsuite at:
+
+llvm-project/lldb/test/API/commands/command/script/add/test_commands.py
+"""
----------------
medismailben wrote:

Although I really like this kind of narrated documentation style, I don't think its concise enough for users and might discourage some from using this feature because the documentation was too long to read.

I think we should keep this, but still provide docstrings comments with arguments and return types for every methods of this class, like we do in the scripted process base class implementation:

https://github.com/llvm/llvm-project/blob/2c3ba9f6225612caf7d2d5ba6613ba1454d52dc3/lldb/examples/python/templates/scripted_process.py#L64-L75

Or at least the methods that the user might use.

https://github.com/llvm/llvm-project/pull/70734