| \section{\module{cmd} --- |
| Build line-oriented command interpreters.} |
| \declaremodule{standard}{cmd} |
| \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} |
| |
| \modulesynopsis{Build line-oriented command interpreters; this is used |
| by module \module{pdb}.} |
| |
| |
| 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 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). |
| |
| 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} |
| |
| |