Handle function parameters of RunCommandInterpreter (script bridge)

[lubgr]

Summary

This issue goes back to this SO answer by Jim Ingham, suggesting to fix the python bindings for RunCommandInterpreter. The reference parameters aren't properly handled by SWIG, but we can use the default typemaps library to generate the necessary glue. The new test captures this behavior (it fails without the adjustment in SBDebugger.i).

This is my first patch, so let me know if any additional tests/background/info would be helpful.

[jingham]

LGTM, thanks for doing this and for the test! Can I ask you to write a doc string showing how to call this and what it returns in Python. It's not entirely obvious. There are %feature("docstring" examples around in that file that you can copy from.

[lubgr]

I added the docstring for RunCommandInterpreter, including a simple example invocation.

[jingham]

Excellent, thanks! Can you check this in or do you need me to?

[lubgr]

No, I don't have the permissions. Thanks in advance for comitting this.

packages/Python/lldbsuite/test/python_api/interpreter/TestRunCommandInterpreterAPI.py

+"""Test the RunCommandInterpreter API."""
+
+import os
+import lldb
+from lldbsuite.test.decorators import *
+from lldbsuite.test.lldbtest import *
+
+class CommandRunInterpreterAPICase(TestBase):
+
+    mydir = TestBase.compute_mydir(__file__)
+
+    def setUp(self):
+        TestBase.setUp(self)
+
+        self.stdin_path = self.getBuildArtifact("stdin.txt")
+
+        with open(self.stdin_path, 'w') as input_handle:
+            input_handle.write("nonexistingcommand\nquit")
+
+        with open(self.stdin_path, 'r') as input_handle:
+            self.dbg.SetInputFileHandle(input_handle, False)
+
+        # No need to track the output
+        devnull = open(os.devnull, 'w')
+        self.dbg.SetOutputFileHandle(devnull, False)
+        self.dbg.SetErrorFileHandle(devnull, False)
+
+    @add_test_categories(['pyapi'])
+    def test_run_session_with_error_and_quit(self):
+        """Run non-existing and quit command returns appropriate values"""
+
+        n_errors, quit_requested, has_crashed = self.dbg.RunCommandInterpreter(
+                True, False, lldb.SBCommandInterpreterRunOptions(), 0, False,
+                False)
+
+        self.assertGreater(n_errors, 0)
+        self.assertTrue(quit_requested)
+        self.assertFalse(has_crashed)

scripts/interface/SBDebugger.i

public:
     GetSummaryForType (lldb::SBTypeNameSpecifier);
 
     lldb::SBTypeFilter
     GetFilterForType (lldb::SBTypeNameSpecifier);
 
     lldb::SBTypeSynthetic
     GetSyntheticForType (lldb::SBTypeNameSpecifier);
 
+    %feature("docstring",
+"Launch a command interpreter session. Commands are read from standard input or
+from the input handle specified for the debugger object. Output/errors are
+similarly redirected to standard output/error or the configured handles.
+
+@param[in] auto_handle_events If true, automatically handle resulting events.
+@param[in] spawn_thread If true, start a new thread for IO handling.
+@param[in] options Parameter collection of type SBCommandInterpreterRunOptions.
+@param[in] num_errors Initial error counter.
+@param[in] quit_requested Initial quit request flag.
+@param[in] stopped_for_crash Initial crash flag.
+
+@return
+A tuple with the number of errors encountered by the interpreter, a boolean
+indicating whether quitting the interpreter was requested and another boolean
+set to True in case of a crash.
+
+Example:
+
+# Start an interactive lldb session from a script (with a valid debugger object
+# created beforehand):
+n_errors, quit_requested, has_crashed = debugger.RunCommandInterpreter(True,
+    False, lldb.SBCommandInterpreterRunOptions(), 0, False, False)") RunCommandInterpreter;
+    %apply int& INOUT { int& num_errors };
+    %apply bool& INOUT { bool& quit_requested };
+    %apply bool& INOUT { bool& stopped_for_crash };
     void
     RunCommandInterpreter (bool auto_handle_events,
                            bool spawn_thread,
                            SBCommandInterpreterRunOptions &options,
                            int  &num_errors,
                            bool &quit_requested,
                            bool &stopped_for_crash);