199 lines
8.1 KiB
TeX
199 lines
8.1 KiB
TeX
\section{\module{cmd} ---
|
|
Support for line-oriented command interpreters}
|
|
|
|
\declaremodule{standard}{cmd}
|
|
\sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
|
|
\modulesynopsis{Build line-oriented command interpreters.}
|
|
|
|
|
|
The \class{Cmd} class provides a simple framework for writing
|
|
line-oriented command interpreters. These are often useful for
|
|
test harnesses, administrative tools, and prototypes that will
|
|
later be wrapped in a more sophisticated interface.
|
|
|
|
\begin{classdesc}{Cmd}{\optional{completekey\optional{,
|
|
stdin\optional{, stdout}}}}
|
|
A \class{Cmd} instance or subclass instance is a line-oriented
|
|
interpreter framework. There is no good reason to instantiate
|
|
\class{Cmd} itself; rather, it's useful as a superclass of an
|
|
interpreter class you define yourself in order to inherit
|
|
\class{Cmd}'s methods and encapsulate action methods.
|
|
|
|
The optional argument \var{completekey} is the \refmodule{readline} name
|
|
of a completion key; it defaults to \kbd{Tab}. If \var{completekey} is
|
|
not \constant{None} and \refmodule{readline} is available, command completion
|
|
is done automatically.
|
|
|
|
The optional arguments \var{stdin} and \var{stdout} specify the
|
|
input and output file objects that the Cmd instance or subclass
|
|
instance will use for input and output. If not specified, they
|
|
will default to \var{sys.stdin} and \var{sys.stdout}.
|
|
|
|
\versionchanged[The \var{stdin} and \var{stdout} parameters were added]{2.3}
|
|
\end{classdesc}
|
|
|
|
\subsection{Cmd Objects}
|
|
\label{Cmd-objects}
|
|
|
|
A \class{Cmd} instance has the following methods:
|
|
|
|
\begin{methoddesc}{cmdloop}{\optional{intro}}
|
|
Repeatedly issue a prompt, accept input, parse an initial prefix off
|
|
the received input, and dispatch to action methods, passing them the
|
|
remainder of the line as argument.
|
|
|
|
The optional argument is a banner or intro string to be issued before the
|
|
first prompt (this overrides the \member{intro} class member).
|
|
|
|
If the \refmodule{readline} module is loaded, input will automatically
|
|
inherit \program{bash}-like history-list editing (e.g. \kbd{Control-P}
|
|
scrolls back to the last command, \kbd{Control-N} forward to the next
|
|
one, \kbd{Control-F} moves the cursor to the right non-destructively,
|
|
\kbd{Control-B} moves the cursor to the left non-destructively, etc.).
|
|
|
|
An end-of-file on input is passed back as the string \code{'EOF'}.
|
|
|
|
An interpreter instance will recognize a command name \samp{foo} if
|
|
and only if it has a method \method{do_foo()}. As a special case,
|
|
a line beginning with the character \character{?} is dispatched to
|
|
the method \method{do_help()}. As another special case, a line
|
|
beginning with the character \character{!} is dispatched to the
|
|
method \method{do_shell()} (if such a method is defined).
|
|
|
|
This method will return when the \method{postcmd()} method returns a
|
|
true value. The \var{stop} argument to \method{postcmd()} is the
|
|
return value from the command's corresponding \method{do_*()} method.
|
|
|
|
If completion is enabled, completing commands will be done
|
|
automatically, and completing of commands args is done by calling
|
|
\method{complete_foo()} with arguments \var{text}, \var{line},
|
|
\var{begidx}, and \var{endidx}. \var{text} is the string prefix we
|
|
are attempting to match: all returned matches must begin with it.
|
|
\var{line} is the current input line with leading whitespace removed,
|
|
\var{begidx} and \var{endidx} are the beginning and ending indexes
|
|
of the prefix text, which could be used to provide different
|
|
completion depending upon which position the argument is in.
|
|
|
|
All subclasses of \class{Cmd} inherit a predefined \method{do_help()}.
|
|
This method, called with an argument \code{'bar'}, invokes the
|
|
corresponding method \method{help_bar()}. With no argument,
|
|
\method{do_help()} lists all available help topics (that is, all
|
|
commands with corresponding \method{help_*()} methods), and also lists
|
|
any undocumented commands.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{onecmd}{str}
|
|
Interpret the argument as though it had been typed in response to the
|
|
prompt. This may be overridden, but should not normally need to be;
|
|
see the \method{precmd()} and \method{postcmd()} methods for useful
|
|
execution hooks. The return value is a flag indicating whether
|
|
interpretation of commands by the interpreter should stop. If there
|
|
is a \method{do_*()} method for the command \var{str}, the return
|
|
value of that method is returned, otherwise the return value from the
|
|
\method{default()} method is returned.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{emptyline}{}
|
|
Method called when an empty line is entered in response to the prompt.
|
|
If this method is not overridden, it repeats the last nonempty command
|
|
entered.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{default}{line}
|
|
Method called on an input line when the command prefix is not
|
|
recognized. If this method is not overridden, it prints an
|
|
error message and returns.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{completedefault}{text, line, begidx, endidx}
|
|
Method called to complete an input line when no command-specific
|
|
\method{complete_*()} method is available. By default, it returns an
|
|
empty list.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{precmd}{line}
|
|
Hook method executed just before the command line \var{line} is
|
|
interpreted, but after the input prompt is generated and issued. This
|
|
method is a stub in \class{Cmd}; it exists to be overridden by
|
|
subclasses. The return value is used as the command which will be
|
|
executed by the \method{onecmd()} method; the \method{precmd()}
|
|
implementation may re-write the command or simply return \var{line}
|
|
unchanged.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{postcmd}{stop, line}
|
|
Hook method executed just after a command dispatch is finished. This
|
|
method is a stub in \class{Cmd}; it exists to be overridden by
|
|
subclasses. \var{line} is the command line which was executed, and
|
|
\var{stop} is a flag which indicates whether execution will be
|
|
terminated after the call to \method{postcmd()}; this will be the
|
|
return value of the \method{onecmd()} method. The return value of
|
|
this method will be used as the new value for the internal flag which
|
|
corresponds to \var{stop}; returning false will cause interpretation
|
|
to continue.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{preloop}{}
|
|
Hook method executed once when \method{cmdloop()} is called. This
|
|
method is a stub in \class{Cmd}; it exists to be overridden by
|
|
subclasses.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{postloop}{}
|
|
Hook method executed once when \method{cmdloop()} is about to return.
|
|
This method is a stub in \class{Cmd}; it exists to be overridden by
|
|
subclasses.
|
|
\end{methoddesc}
|
|
|
|
Instances of \class{Cmd} subclasses have some public instance variables:
|
|
|
|
\begin{memberdesc}{prompt}
|
|
The prompt issued to solicit input.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{identchars}
|
|
The string of characters accepted for the command prefix.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{lastcmd}
|
|
The last nonempty command prefix seen.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{intro}
|
|
A string to issue as an intro or banner. May be overridden by giving
|
|
the \method{cmdloop()} method an argument.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{doc_header}
|
|
The header to issue if the help output has a section for documented
|
|
commands.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{misc_header}
|
|
The header to issue if the help output has a section for miscellaneous
|
|
help topics (that is, there are \method{help_*()} methods without
|
|
corresponding \method{do_*()} methods).
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{undoc_header}
|
|
The header to issue if the help output has a section for undocumented
|
|
commands (that is, there are \method{do_*()} methods without
|
|
corresponding \method{help_*()} methods).
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{ruler}
|
|
The character used to draw separator lines under the help-message
|
|
headers. If empty, no ruler line is drawn. It defaults to
|
|
\character{=}.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{use_rawinput}
|
|
A flag, defaulting to true. If true, \method{cmdloop()} uses
|
|
\function{raw_input()} to display a prompt and read the next command;
|
|
if false, \method{sys.stdout.write()} and
|
|
\method{sys.stdin.readline()} are used. (This means that by
|
|
importing \refmodule{readline}, on systems that support it, the
|
|
interpreter will automatically support \program{Emacs}-like line editing
|
|
and command-history keystrokes.)
|
|
\end{memberdesc}
|