135 lines
4.6 KiB
TeX
135 lines
4.6 KiB
TeX
% Documentation by ESR
|
|
\section{Standard Module \module{cmd}}
|
|
\stmodindex{cmd}
|
|
\label{module-cmd}
|
|
|
|
The \code{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}{}
|
|
A \class{Cmd} instance or subclass instance is a line-oriented
|
|
interpreter framework. There is no good reason to instantiate Cmd
|
|
itself; rather, it's useful as a superclass of an interpreter class
|
|
you define yourself in order to inherit Cmd's methods and encapsulate
|
|
action functions.
|
|
\end{classdesc}
|
|
|
|
\subsection{Cmd Objects}
|
|
\label{Cmd-objects}
|
|
|
|
A \class{Cmd} instance has the following methods:
|
|
|
|
\begin{methoddesc}{cmdloop}{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 \module{readline} module is loaded, input will automatically
|
|
inherit Emacs-like history-list editing (e.g. Ctrl-P scrolls back to
|
|
the last command, Ctrl-N forward to the next one, Ctrl-F moves the
|
|
cursor to the right non-destructively, Ctrl-B moves the cursor to the
|
|
left non-destructively, etc.).
|
|
|
|
An end-of-file on input is passed back as the string "EOF".
|
|
|
|
An interpreter instance will recognize a command name \code{foo} if
|
|
and only if it has a method named \method{do_foo}. As a special case,
|
|
a line containing only the character `?' is dispatched to the method
|
|
\method{do_help}. As another special case, a line containing only the
|
|
character `!' is dispatched to the method \method{do_shell} (if such a method
|
|
is defined).
|
|
|
|
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 \code{help_} methods), and also lists any
|
|
undocumented commands.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{onecmd}{str}
|
|
Interpret the argument as though it had been typed in in
|
|
response to the prompt.
|
|
\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}{precmd}
|
|
Hook method executed just before the input prompt is issued. This method is
|
|
a stub in \class{Cmd}; it exists to be overridden by subclasses.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{postcmd}
|
|
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.
|
|
\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 \code{help_} methods withoud corresponding
|
|
\code{do_} functions).
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}{undoc_header}
|
|
The header to issue if the help output has a section for undocumented
|
|
commands (that is, there are \code{do_} methods withoud corresponding
|
|
\code{help_} functions).
|
|
\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 "=".
|
|
\end{memberdesc}
|
|
|
|
|