diff options
Diffstat (limited to 'gdb/doc/gdb.texinfo')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index a2ed0b8..354b888 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -18064,6 +18064,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Basic Python:: Basic Python Functions. * Exception Handling:: * Values From Inferior:: +* Commands In Python:: Implementing new commands in Python. @end menu @node Basic Python @@ -18246,6 +18247,259 @@ The optional @var{errors} argument is the same as the corresponding argument to Python's @code{string.decode} method. @end defmethod +@node Commands In Python +@subsubsection Commands In Python + +@cindex commands in python +@cindex python commands +@tindex Command +@tindex gdb.Command +You can implement new @value{GDBN} CLI commands in Python. A CLI +command is implemented using an instance of the @code{gdb.Command} +class, most commonly using a subclass. + +@defmethod Command __init__ name @var{command-class} @r{[}@var{completer-class} @var{prefix}@r{]} +The object initializer for @code{Command} 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. If @var{name} consists of +multiple words, then the initial words are looked for as prefix +commands. In this case, if one of the prefix commands does not exist, +an exception is raised. + +There is no support for multi-line commands. + +@var{command-class} should be one of the @samp{COMMAND_} constants +defined below. This argument tells @value{GDBN} how to categorize the +new command in the help system. + +@var{completer-class} is an optional argument. If given, it should be +one of the @samp{COMPLETE_} constants defined below. This argument +tells @value{GDBN} how to perform completion for this command. If not +given, @value{GDBN} will attempt to complete using the object's +@code{complete} method (see below); if no such method is found, an +error will occur when completion is attempted. + +@var{prefix} is an optional argument. If @code{True}, then the new +command is a prefix command; sub-commands of this command may be +registered. + +The help text for the new command is taken from the Python +documentation string for the command's class, if there is one. If no +documentation string is provided, the default value ``This command is +not documented.'' is used. +@end defmethod + +@defmethod Command dont_repeat +By default, a @value{GDBN} command is repeated when the user enters a +blank line at the command prompt. A command can suppress this +behavior by invoking the @code{dont_repeat} method. This is similar +to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. +@end defmethod + +@defmethod Command invoke argument from_tty +This method is called by @value{GDBN} when this command is invoked. + +@var{argument} is a string. It is the argument to the command, after +leading and trailing whitespace has been stripped. + +@var{from_tty} is a boolean argument. When true, this means that the +command was entered by the user at the terminal; when false it means +that the command came from elsewhere. + +If this method throws an exception, it is turned into a @value{GDBN} +@code{error} call. Otherwise, the return value is ignored. +@end defmethod + +@defmethod Command complete text word +This method is called by @value{GDBN} when the user attempts +completion on this command. All forms of completion are handled by +this method, that is, the @key{TAB} and @key{M-?} key bindings, and +the @code{complete} command. + +The arguments @var{text} and @var{word} are both strings. @var{text} +holds the complete command line up to the cursor's location. +@var{word} holds the last word of the command line; this is computed +using a word-breaking heuristic. + +The @code{complete} method can return several values: +@itemize @bullet +@item +If the return value is a sequence, the contents of the sequence are +used as the completions. It is up to @code{complete} to ensure that the +contents actually do complete the word. A zero-length sequence is +allowed, it means that there were no completions available. Only +string elements of the sequence are used; other elements in the +sequence are ignored. + +@item +If the return value is one of the @samp{COMPLETE_} constants defined +below, then the corresponding @value{GDBN}-internal completion +function is invoked, and its result is used. + +@item +All other results are treated as though there were no available +completions. +@end itemize +@end defmethod + + +When a new command is registered, it must be declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the @code{gdb} module: + +@table @code +@findex COMMAND_NONE +@findex gdb.COMMAND_NONE +@item COMMAND_NONE +The command does not belong to any particular class. A command in +this category will not be displayed in any of the help categories. + +@findex COMMAND_RUNNING +@findex gdb.COMMAND_RUNNING +@item COMMAND_RUN +The command is related to running the inferior. For example, +@code{start}, @code{step}, and @code{continue} are in this category. +Type @code{help running} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_DATA +@findex gdb.COMMAND_DATA +@item COMMAND_VARS +The command is related to data or variables. For example, +@code{call}, @code{find}, and @code{print} are in this category. Type +@code{help data} at the @value{GDBN} prompt to see a list of commands +in this category. + +@findex COMMAND_STACK +@findex gdb.COMMAND_STACK +@item COMMAND_STACK +The command has to do with manipulation of the stack. For example, +@code{backtrace}, @code{frame}, and @code{return} are in this +category. Type @code{help stack} at the @value{GDBN} prompt to see a +list of commands in this category. + +@findex COMMAND_FILES +@findex gdb.COMMAND_FILES +@item COMMAND_FILES +This class is used for file-related commands. For example, +@code{file}, @code{list} and @code{section} are in this category. +Type @code{help files} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_SUPPORT +@findex gdb.COMMAND_SUPPORT +@item COMMAND_SUPPORT +This should be used for ``support facilities'', generally meaning +things that are useful to the user when interacting with @value{GDBN}, +but not related to the state of the inferior. For example, +@code{help}, @code{make}, and @code{shell} are in this category. Type +@code{help support} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_STATUS +@findex gdb.COMMAND_STATUS +@item COMMAND_INFO +The command is an @samp{info}-related command, that is, related to the +state of @value{GDBN} itself. For example, @code{info}, @code{macro}, +and @code{show} are in this category. Type @code{help status} at the +@value{GDBN} prompt to see a list of commands in this category. + +@findex COMMAND_BREAKPOINTS +@findex gdb.COMMAND_BREAKPOINTS +@item COMMAND_BREAKPOINT +The command has to do with breakpoints. For example, @code{break}, +@code{clear}, and @code{delete} are in this category. Type @code{help +breakpoints} at the @value{GDBN} prompt to see a list of commands in +this category. + +@findex COMMAND_TRACEPOINTS +@findex gdb.COMMAND_TRACEPOINTS +@item COMMAND_TRACE +The command has to do with tracepoints. For example, @code{trace}, +@code{actions}, and @code{tfind} are in this category. Type +@code{help tracepoints} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_OBSCURE +@findex gdb.COMMAND_OBSCURE +@item COMMAND_OBSCURE +The command is only used in unusual circumstances, or is not of +general interest to users. For example, @code{checkpoint}, +@code{fork}, and @code{stop} are in this category. Type @code{help +obscure} at the @value{GDBN} prompt to see a list of commands in this +category. + +@findex COMMAND_MAINTENANCE +@findex gdb.COMMAND_MAINTENANCE +@item COMMAND_MAINTENANCE +The command is only useful to @value{GDBN} maintainers. The +@code{maintenance} and @code{flushregs} commands are in this category. +Type @code{help internals} at the @value{GDBN} prompt to see a list of +commands in this category. +@end table + + +A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it +from the @code{complete} method. These predefined completion +constants are all defined in the @code{gdb} module: + +@table @code +@findex COMPLETE_NONE +@findex gdb.COMPLETE_NONE +@item COMPLETE_NONE +This constant means that no completion should be done. + +@findex COMPLETE_FILENAME +@findex gdb.COMPLETE_FILENAME +@item COMPLETE_FILENAME +This constant means that filename completion should be performed. + +@findex COMPLETE_LOCATION +@findex gdb.COMPLETE_LOCATION +@item COMPLETE_LOCATION +This constant means that location completion should be done. +@xref{Specify Location}. + +@findex COMPLETE_COMMAND +@findex gdb.COMPLETE_COMMAND +@item COMPLETE_COMMAND +This constant means that completion should examine @value{GDBN} +command names. + +@findex COMPLETE_SYMBOL +@findex gdb.COMPLETE_SYMBOL +@item COMPLETE_SYMBOL +This constant means that completion should be done using symbol names +as the source. +@end table + +The following code snippet shows how a trivial CLI command can be +implemented in Python: + +@smallexample +class HelloWorld (gdb.Command): + """Greet the whole world.""" + + def __init__ (self): + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE) + + def invoke (self, arg, from_tty): + print "Hello, World!" + +HelloWorld () +@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 Interpreters @chapter Command Interpreters @cindex command interpreters |