Add command support for Guile.

	* Makefile.in (SUBDIR_GUILE_OBS): Add scm-cmd.o.
	(SUBDIR_GUILE_SRCS): Add scm-cmd.c.
	(scm-cmd.o): New rule.
	* guile/guile-internal.h (gdbscm_gc_xstrdup): Declare.
	(gdbscm_user_error_p): Declare.
	(gdbscm_parse_command_name): Declare.
	(gdbscm_valid_command_class_p): Declare.
	(gdbscm_initialize_commands): Declare.
	* guile/guile.c (initialize_gdb_module): Call
	gdbscm_initialize_commands.
	* guile/lib/gdb.scm: Export command symbols.
	* guile/lib/gdb/init.scm (%exception-keys): Add gdb:user-error.
	(throw-user-error): New function.
	* guile/scm-cmd.c: New file.
	* guile/scm-exception.c (user_error_symbol): New static global.
	(gdbscm_user_error_p): New function.
	(gdbscm_initialize_exceptions): Set user_error_symbol.
	* scm-utils.c (gdbscm_gc_xstrdup): New function.

	testsuite/
	* gdb.guile/scm-cmd.c: New file.
	* gdb.guile/scm-cmd.exp: New file.

	doc/
	* guile.texi (Guile API): Add entry for Commands In Guile.
	(Basic Guile) <parse-and-eval>: Add reference.
	(Basic Guile) <string->argv>: Move definition to Commands In Guile.
	(GDB Scheme Data Types): Mention <gdb:command> object.
	(Commands In Guile): New node.

1 files changed, 287 insertions, 6 deletions

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 23c8398..70fbd16 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -141,6 +141,7 @@ from the Guile interactive prompt.
 * Guile Pretty Printing API:: Pretty-printing values with Guile
 * Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer
 * Writing a Guile Pretty-Printer:: Writing a pretty-printer
+* Commands In Guile::        Implementing new commands in Guile
 * Progspaces In Guile::      Program spaces
 * Objfiles In Guile::        Object files in Guile
 * Frames In Guile::          Accessing inferior stack frames from Guile
@@ -293,16 +294,14 @@ Parse @var{expression} as an expression in the current language,
 evaluate it, and return the result as a @code{<gdb:value>}.
 The @var{expression} must be a string.
 
-This function is useful when computing values.
+This function can be useful when implementing a new command
+(@pxref{Commands In Guile}), as it provides a way to parse the
+command's arguments as an expression.
+It is also is useful when computing values.
 For example, it is the only way to get the value of a
 convenience variable (@pxref{Convenience Vars}) as a @code{<gdb:value>}.
 @end deffn
 
-@deffn {Scheme Procedure} string->argv string
-Convert a string to a list of strings split up according to
-@value{GDBN}'s argv parsing rules.
-@end deffn
-
 @node Guile Configuration
 @subsubsection Guile Configuration
 @cindex guile configuration
@@ -358,6 +357,9 @@ as a symbol.
 @item <gdb:breakpoint>
 @xref{Breakpoints In Guile}.
 
+@item <gdb:command>
+@xref{Commands In Guile}.
+
 @item <gdb:exception>
 @xref{Guile Exception Handling}.
 
@@ -1665,6 +1667,285 @@ my_library.so:
     bar
 @end smallexample
 
+@node Commands In Guile
+@subsubsection Commands In Guile
+
+@cindex commands in guile
+@cindex guile commands
+You can implement new @value{GDBN} CLI commands in Guile.  A CLI
+command object is created with the @code{make-command} Guile function,
+and added to @value{GDBN} with the @code{register-command!} Guile function.
+This two-step approach is taken to separate out the side-effect of adding
+the command to @value{GDBN} from @code{make-command}.
+
+There is no support for multi-line commands, that is commands that
+consist of multiple lines and are terminated with @code{end}.
+
+@c TODO: line length
+@deffn {Scheme Procedure} (make-command name @r{[}#:invoke invoke{]} @r{[}#:command-class command-class@r{]} @r{[}#:completer-class completer{]} @r{[}#:prefix? prefix@r{]} @r{[}#:doc doc-string{]})
+
+The argument @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.
+
+The result is the @code{<gdb:command>} object representing the command.
+The command is not usable until it has been registered with @value{GDBN}
+with @code{register-command!}.
+
+The rest of the arguments are optional.
+
+The argument @var{invoke} is a procedure of three arguments: @var{self},
+@var{args} and @var{from-tty}.  The argument @var{self} is the
+@code{<gdb:command>} object representing the command.
+The argument @var{args} is a string representing the arguments passed to
+the command, after leading and trailing whitespace has been stripped.
+The argument @var{from-tty} is a boolean flag and specifies whether the
+command should consider itself to have been originated from the user
+invoking it interactively.  If this function throws an exception,
+it is turned into a @value{GDBN} @code{error} call.
+Otherwise, the return value is ignored.
+
+The argument @var{command-class} is one of the @samp{COMMAND_} constants
+defined below.  This argument tells @value{GDBN} how to categorize the
+new command in the help system.  The default is @code{COMMAND_NONE}.
+
+The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_}
+constants defined below, or a procedure, also defined below.
+This argument tells @value{GDBN} how to perform completion
+for this command.  If not provided or if the value is @code{#f},
+then no completion is performed on the command.
+
+The argument @var{prefix} is a boolean flag indicating whether the new
+command is a prefix command; sub-commands of this command may be
+registered.
+
+The argument @var{doc-string} is help text for the new command.
+If no documentation string is provided, the default value ``This command is
+not documented.'' is used.
+@end deffn
+
+@deffn {Scheme Procedure} register-command! command
+Add @var{command}, a @code{<gdb:command>} object, to @value{GDBN}'s
+list of commands.
+It is an error to register a command more than once.
+The result is unspecified.
+@end deffn
+
+@deffn {Scheme Procedure} command? object
+Return @code{#t} if @var{object} is a @code{<gdb:command>} object.
+Otherwise return @code{#f}.
+@end deffn
+
+@cindex don't repeat Guile command
+@deffn {Scheme Procedure} 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} function.  This is similar
+to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}.
+@end deffn
+
+@deffn {Scheme Procedure} string->argv string
+Convert a string to a list of strings split up according to
+@value{GDBN}'s argv parsing rules.
+It is recommended to use this for consistency.
+Arguments are separated by spaces and may be quoted.
+Example:
+
+@smallexample
+scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
+$1 = ("1" "2 \"3" "4 \"5" "6 '7")
+@end smallexample
+@end deffn
+
+@deffn {Scheme Procedure} throw-user-error message . args
+Throw a @code{gdb:user-error} exception.
+The argument @var{message} is the error message as a format string, like the 
+@var{fmt} argument to the @code{format} Scheme function.
+@xref{Formatted Output,,, guile, GNU Guile Reference Manual}.
+The argument @var{args} is a list of the optional arguments of @var{message}.
+
+This is used when the command detects a user error of some kind,
+say a bad command argument.
+
+@smallexample
+(gdb) guile (use-modules (gdb))
+(gdb) guile
+(register-command! (make-command "test-user-error"
+  #:command-class COMMAND_OBSCURE
+  #:invoke (lambda (self arg from-tty)
+    (throw-user-error "Bad argument ~a" arg))))
+end
+(gdb) test-user-error ugh
+ERROR: Bad argument ugh
+@end smallexample
+@end deffn
+
+@cindex completion of Guile commands
+@deffn completer self text word
+If the @var{completer} option to @code{make-command} is a procedure,
+it takes three arguments: @var{self} which is the @code{<gdb:command>}
+object, and @var{text} and @var{word} which are both strings.
+The argument @var{text} holds the complete command line up to the cursor's
+location.  The argument @var{word} holds the last word of the command line;
+this is computed using a word-breaking heuristic.
+
+All forms of completion are handled by this function, that is,
+the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}),
+and the @code{complete} command (@pxref{Help, complete}).
+
+This procedure can return several kinds of values:
+
+@itemize @bullet
+@item
+If the return value is a list, the contents of the list are used as the
+completions.  It is up to @var{completer} to ensure that the
+contents actually do complete the word.  An empty list is
+allowed, it means that there were no completions available.  Only
+string elements of the list are used; other elements in the
+list are ignored.
+
+@item
+If the return value is a @code{<gdb:iterator>} object, it is iterated over to
+obtain the completions.  It is up to @code{completer-procedure} to ensure
+that the results actually do complete the word.  Only
+string elements of the result are used; other elements in the
+sequence are ignored.
+
+@item
+All other results are treated as though there were no available
+completions.
+@end itemize
+@end deffn
+
+When a new command is registered, it will have been 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:
+
+@vtable @code
+@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.
+This is the default.
+
+@item COMMAND_RUNNING
+The command is related to running the inferior.  For example,
+@code{start}, @code{step}, and @code{continue} are in this category.
+Type @kbd{help running} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@item COMMAND_DATA
+The command is related to data or variables.  For example,
+@code{call}, @code{find}, and @code{print} are in this category.  Type
+@kbd{help data} at the @value{GDBN} prompt to see a list of commands
+in this category.
+
+@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 @kbd{help stack} at the @value{GDBN} prompt to see a
+list of commands in this category.
+
+@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 @kbd{help files} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@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
+@kbd{help support} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@item COMMAND_STATUS
+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 @kbd{help status} at the
+@value{GDBN} prompt to see a list of commands in this category.
+
+@item COMMAND_BREAKPOINTS
+The command has to do with breakpoints.  For example, @code{break},
+@code{clear}, and @code{delete} are in this category.  Type @kbd{help
+breakpoints} at the @value{GDBN} prompt to see a list of commands in
+this category.
+
+@item COMMAND_TRACEPOINTS
+The command has to do with tracepoints.  For example, @code{trace},
+@code{actions}, and @code{tfind} are in this category.  Type
+@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of
+commands in this category.
+
+@item COMMAND_USER
+The command is a general purpose command for the user, and typically
+does not fit in one of the other categories.
+Type @kbd{help user-defined} at the @value{GDBN} prompt to see
+a list of commands in this category, as well as the list of gdb macros
+(@pxref{Sequences}).
+
+@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 @kbd{help
+obscure} at the @value{GDBN} prompt to see a list of commands in this
+category.
+
+@item COMMAND_MAINTENANCE
+The command is only useful to @value{GDBN} maintainers.  The
+@code{maintenance} and @code{flushregs} commands are in this category.
+Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
+commands in this category.
+@end vtable
+
+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{completer} procedure.  These predefined completion
+constants are all defined in the @code{gdb} module:
+
+@vtable @code
+@item COMPLETE_NONE
+This constant means that no completion should be done.
+
+@item COMPLETE_FILENAME
+This constant means that filename completion should be performed.
+
+@item COMPLETE_LOCATION
+This constant means that location completion should be done.
+@xref{Specify Location}.
+
+@item COMPLETE_COMMAND
+This constant means that completion should examine @value{GDBN}
+command names.
+
+@item COMPLETE_SYMBOL
+This constant means that completion should be done using symbol names
+as the source.
+
+@item COMPLETE_EXPRESSION
+This constant means that completion should be done on expressions.
+Often this means completing on symbol names, but some language
+parsers also have support for completing on field names.
+@end vtable
+
+The following code snippet shows how a trivial CLI command can be
+implemented in Guile:
+
+@smallexample
+(gdb) guile
+(register-command! (make-command "hello-world"
+  #:command-class COMMAND_USER
+  #:doc "Greet the whole world."
+  #:invoke (lambda (self args from-tty) (display "Hello, World!\n"))))
+end
+(gdb) hello-world
+Hello, World!
+@end smallexample
+
 @node Progspaces In Guile
 @subsubsection Program Spaces In Guile