Re: [PATCH 8/9] Implement gdb.execute_mi

[Tom Tromey <tromey@adacore.com>]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> +Conversely, it is possible to execute @sc{GDB/MI} commands from
Eli>                                          ^^^^^^^^^^^
Eli> In print, @sc produces "small caps" only for lower-case letters, so
Eli> the above should use @sc{gdb/mi} (here and elsewhere).

Alright.  I was just copying something I saw somewhere else.
I'll go fix those up.

>> +Invoke a @sc{GDB/MI} command.  @var{command} is the name of the
>> +command, a string.  (Note that the leading @samp{-} should be omitted
>> +here.)

Eli> Why is it a good idea to omit the leading dash?

In MI, the leading '-' is not really part of the command name.  It seems
to be some kind of syntactic marker, though I have no idea why, as there
aren't any other possible such markers as far as I can tell.

Eli> And what does it mean for command switches, which start with two
Eli> dashes?

Nothing.

>> +This function returns a Python dictionary whose contents reflect the
>> +corresponding @sc{GDB/MI} command's output.  Refer to the
>> +documentation for these commands for details.  Lists are represented
>> +as Python lists, and tuples are represented as Python dictionaries.

Eli> Is this description enough to understand what will be returned?  What
Eli> about error messages, for example -- how are those returned?

I added a bit of text about this, and also a new test.

If the command fails, it will raise a Python exception.

It's possible in theory for a command to print some kind of warning but
still succeed.  (I don't know if this ever really happens.)  In this
case there's no way to know that this occurred.

I've appended the updated python.texi patch.

Tom


diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 5d714ee1ca3..99417802453 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4584,6 +4584,42 @@ commands have been added:
 (@value{GDBP})
 @end smallexample
 
+Conversely, it is possible to execute @sc{gdb/mi} commands from
+Python, with the results being a Python object and not a
+specially-formatted string.  This is done with the
+@code{gdb.execute_mi} function.
+
+@findex gdb.execute_mi
+@defun gdb.execute_mi (command @r{[}, arg @r{]}@dots{})
+Invoke a @sc{gdb/mi} command.  @var{command} is the name of the
+command, a string.
+
+Note that the leading @samp{-} that is normally used with @sc{gdb/mi}
+is not technically part of the command name, and so should be omitted
+here.
+
+The arguments, @var{arg}, are passed to the command.  Each argument
+must also be a string.
+
+This function returns a Python dictionary whose contents reflect the
+corresponding @sc{GDB/MI} command's output.  Refer to the
+documentation for these commands for details.  Lists are represented
+as Python lists, and tuples are represented as Python dictionaries.
+
+If the command fails, it will raise a Python exception.
+@end defun
+
+Here is how this works using the commands from the example above:
+
+@smallexample
+(@value{GDBP}) python print(gdb.execute_mi("echo-dict", "abc", "def", "ghi"))
+@{'dict': @{'argv': ['abc', 'def', 'ghi']@}@}
+(@value{GDBP}) python print(gdb.execute_mi("echo-list", "abc", "def", "ghi"))
+@{'list': ['abc', 'def', 'ghi']@}
+(@value{GDBP}) python print(gdb.execute_mi("echo-string", "abc", "def", "ghi"))
+@{'string': 'abc, def, ghi'@}
+@end smallexample
+
 @node Parameters In Python
 @subsubsection Parameters In Python