Doc/lib/libcmd.tex

% Documentation by ESR
\section{Standard Module \module{cmd}}
\stmodindex{cmd}
\label{module-cmd}

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}{}
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.
\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 \module{readline} module is loaded, input will automatically
inherit \program{bash}-like history-list editing (e.g. \kbd{Ctrl-P}
scrolls back to the last command, \kbd{Ctrl-N} forward to the next
one, \kbd{Ctrl-F} moves the cursor to the right non-destructively,
\kbd{Ctrl-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 containing only the character \character{?} is dispatched to
the method \method{do_help()}.  As another special case, a line
containing only the character \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 \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 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 \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}