[PATCH 5/5] gdb/python: document GDB/MI commands in Python

[Jan Vrany]

---
 gdb/NEWS            |  2 ++
 gdb/doc/python.texi | 80 +++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 76 insertions(+), 6 deletions(-)

diff --git a/gdb/NEWS b/gdb/NEWS
index 8c13cefb22f..60f157b9c82 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -146,6 +146,8 @@ show debug lin-lwp
   ** New function gdb.host_charset(), returns a string, which is the
      name of the current host charset.
 
+  ** New GDB/MI commands can now be written in Python.
+
 * New features in the GDB remote stub, GDBserver
 
   ** GDBserver is now supported on OpenRISC GNU/Linux.
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 38fce5b38e3..1c17fc1fe2d 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -204,7 +204,8 @@ optional arguments while skipping others.  Example:
 * Events In Python::            Listening for events from @value{GDBN}.
 * Threads In Python::           Accessing inferior threads from Python.
 * Recordings In Python::        Accessing recordings from Python.
-* Commands In Python::          Implementing new commands in Python.
+* CLI Commands In Python::      Implementing new CLI commands in Python.
+* GDB/MI Commands In Python::   Implementing new @sc{GDB/MI} commands in Python.
 * Parameters In Python::        Adding new @value{GDBN} parameters.
 * Functions In Python::         Writing new convenience functions.
 * Progspaces In Python::        Program spaces.
@@ -388,7 +389,8 @@ the current language, evaluate it, and return the result as a
 @code{gdb.Value}.
 
 This function can be useful when implementing a new command
-(@pxref{Commands In Python}), as it provides a way to parse the
+(@pxref{CLI Commands In Python}, @pxref{GDB/MI Commands In Python}),
+as it provides a way to parse the
 command's argument as an expression.  It is also useful simply to
 compute values.
 @end defun
@@ -2105,7 +2107,7 @@ must contain the frames that are being elided wrapped in a suitable
 frame decorator.  If no frames are being elided this function may
 return an empty iterable, or @code{None}.  Elided frames are indented
 from normal frames in a @code{CLI} backtrace, or in the case of
-@code{GDB/MI}, are placed in the @code{children} field of the eliding
+@sc{GDB/MI}, are placed in the @code{children} field of the eliding
 frame.
 
 It is the frame filter's task to also filter out the elided frames from
@@ -3809,9 +3811,10 @@ def countrange (filename, linerange):
     return count
 @end smallexample
 
-@node Commands In Python
-@subsubsection Commands In Python
+@node CLI Commands In Python
+@subsubsection CLI Commands In Python
 
+@cindex CLI commands in python
 @cindex commands in python
 @cindex python commands
 You can implement new @value{GDBN} CLI commands in Python.  A CLI
@@ -4092,6 +4095,71 @@ registration of the command with @value{GDBN}.  Depending on how the
 Python code is read into @value{GDBN}, you may need to import the
 @code{gdb} module explicitly.
 
+@node GDB/MI Commands In Python
+@subsubsection @sc{GDB/MI} Commands In Python
+
+@cindex MI commands in python
+@cindex commands in python
+@cindex python commands
+You can implement new @sc{GDB/MI} (@pxref{GDB/MI}) commands in Python.  A @sc{GDB/MI}
+command is implemented using an instance of the @code{gdb.MICommand}
+class, most commonly using a subclass.
+
+@defun Command.__init__ (name)
+The object initializer for @code{MICommand} registers the new command
+with @value{GDBN}.  This initializer is normally invoked from the
+subclass' own @code{__init__} method.
+
+@var{name} is the name of the command.  It must be a valid @sc{GDB/MI}
+command and must start with hyphen (-).
+@end defun
+
+@defun Command.invoke (arguments)
+This method is called by @value{GDBN} when this command is invoked.
+
+@var{arguments} is a list of strings.  Note, that @code{--thread}
+and @code{--frame} arguments are handled by @value{GDBN} itself therefore
+they do not show up in @code{arguments}.
+
+If this method throws an exception, it is turned into a @sc{GDB/MI}
+@code{^error} response.  Otherwise, the return value is converted
+to @sc{GDB/MI} value (@pxref{GDB/MI Output Syntax}) as follows:
+
+@itemize
+@item If the value is Python sequence or iterator, it is converted to
+@sc{GDB/MI} @emph{list} with elements converted recursively.
+
+@item If the value is Python dictionary, it is converted to
+@sc{GDB/MI} @emph{tuple}.  Keys in that dictionary must be strings.
+Values are converted recursively.
+
+@item Otherwise, value is first converted to Python string using
+@code{str ()} and then converted to @sc{GDB/MI} @emph{const}.
+@end itemize
+
+@end defun
+
+The following code snippet shows how a trivial MI command can be
+implemented in Python:
+
+@smallexample
+class MIEcho(gdb.MICommand):
+    """Echo parameters"""
+
+    def __init__ (self):
+        super (MIEcho, self).__init__ ("-echo")
+
+    def invoke (self, argv):
+        return @{'argv' : argv @}
+
+MIEcho ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the command with @value{GDBN}.  Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
 @node Parameters In Python
 @subsubsection Parameters In Python
 
@@ -4129,7 +4197,7 @@ If @var{name} consists of multiple words, and no prefix parameter group
 can be found, an exception is raised.
 
 @var{command-class} should be one of the @samp{COMMAND_} constants
-(@pxref{Commands In Python}).  This argument tells @value{GDBN} how to
+(@pxref{CLI Commands In Python}).  This argument tells @value{GDBN} how to
 categorize the new parameter in the help system.
 
 @var{parameter-class} should be one of the @samp{PARAM_} constants
-- 
2.30.2