From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from eggs.gnu.org (eggs.gnu.org [209.51.188.92]) by sourceware.org (Postfix) with ESMTPS id 8FC713858022 for ; Mon, 17 Jan 2022 13:15:19 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8FC713858022 Received: from [2001:470:142:3::e] (port=36992 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n9Rqw-00073U-OM; Mon, 17 Jan 2022 08:15:18 -0500 Received: from [87.69.77.57] (port=4015 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n9Rqt-0004vR-UO; Mon, 17 Jan 2022 08:15:19 -0500 Date: Mon, 17 Jan 2022 15:15:05 +0200 Message-Id: <83lezewlk6.fsf@gnu.org> From: Eli Zaretskii To: Jan Vrany Cc: gdb-patches@sourceware.org In-Reply-To: <20220117124425.2658516-6-jan.vrany@labware.com> (message from Jan Vrany via Gdb-patches on Mon, 17 Jan 2022 12:44:25 +0000) Subject: Re: [PATCH 5/5] gdb/python: document GDB/MI commands in Python References: <20220117124425.2658516-1-jan.vrany@labware.com> <20220117124425.2658516-6-jan.vrany@labware.com> X-Spam-Status: No, score=1.2 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, RCVD_IN_BARRACUDACENTRAL, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=no autolearn_force=no version=3.4.4 X-Spam-Level: * X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 17 Jan 2022 13:15:23 -0000 > Date: Mon, 17 Jan 2022 12:44:25 +0000 > From: Jan Vrany via Gdb-patches > Cc: Jan Vrany > > --- 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. The "new" part here took me by surprise. Why do we need it? Or how about this rewording: ** It is now possible to add GDB/MI commands implemented in Python. > +* GDB/MI Commands In Python:: Implementing new @sc{GDB/MI} commands in Python. ^^^^^^^^^^^ The argument of @sc should be in lower case. > +@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've added a second copy of the last two index entries, without any qualifier. This will cause makeinfo to generate index entries "commands in python" and "commands is python<2>", without giving the reader any clue what is the difference between these two instances. It is much better to qualify each instance with some unique qualifier. Here, I'd use ", CLI" and ", GDB/MI" as the qualifiers. > +You can implement new @sc{GDB/MI} (@pxref{GDB/MI}) commands in Python. Same comment as for the NEWS entry. With a possibly similar solution. > +@var{name} is the name of the command. It must be a valid @sc{GDB/MI} > +command and must start with hyphen (-). What does "It must be a valid @sc{GDB/MI} command" mean here? Did you mean to say "It must be a valid @sc{GDB/MI} command name" instead? If so, I suggest It must be a valid name of a @sc{GDB/MI} command, and in particular must start with a 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 > >