Add docs and an example use of the scripted command get_flags API.

[jimingham]

The API is present, and we even have a test for it, but it isn't documented so no one probably knows you can set requirements for your scripted commands. This just adds docs and uses it appropriately in the framestats example command.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: None (jimingham)

Changes

The API is present, and we even have a test for it, but it isn't documented so no one probably knows you can set requirements for your scripted commands. This just adds docs and uses it appropriately in the framestats example command.

---

Full diff: https://github.com/llvm/llvm-project/pull/109176.diff

2 Files Affected:

• (modified) lldb/docs/use/python-reference.rst (+6)
• (modified) lldb/examples/python/cmdtemplate.py (+3)

diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst
index 041e541a96f083..b12048f1af067d 100644
--- a/lldb/docs/use/python-reference.rst
+++ b/lldb/docs/use/python-reference.rst
@@ -562,6 +562,12 @@ which should implement the following interface:
           this call should return the short help text for this command[1]
       def get_long_help(self):
           this call should return the long help text for this command[1]
+      def get_flags(self):
+          this will be called when the command is added to the command interpreter,
+          and should return a flag field made from or-ing together the appropriate
+          elements of the lldb.CommandFlags enum to specify the requirements of this command.
+          The CommandInterpreter will make sure all these requirements are met, and will
+          return the standard lldb error if they are not.[1]
       def get_repeat_command(self, command):
           The auto-repeat command is what will get executed when the user types just
           a return at the next prompt after this command is run.  Even if your command
diff --git a/lldb/examples/python/cmdtemplate.py b/lldb/examples/python/cmdtemplate.py
index 9a96888508b6f2..b6a21cba7113e6 100644
--- a/lldb/examples/python/cmdtemplate.py
+++ b/lldb/examples/python/cmdtemplate.py
@@ -25,6 +25,9 @@ def register_lldb_command(cls, debugger, module_name):
             '--help" for detailed help.'.format(cls.program)
         )
 
+    def get_flags(self):
+        return lldb.eCommandRequiresFrame | lldb.eCommandProcessMustBePaused
+
     def setup_command_definition(self):
 
         self.ov_parser.add_option(

[medismailben]

LGTM!