\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 writingline-oriented command interpreters.  These are often useful fortest harnesses, administrative tools, and prototypes that willlater 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-orientedinterpreter framework.  There is no good reason to instantiate\class{Cmd} itself; rather, it's useful as a superclass of aninterpreter 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} nameof a completion key; it defaults to \kbd{Tab}. If \var{completekey} isnot \constant{None} and \refmodule{readline} is available, command completionis 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, theywill 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 offthe received input, and dispatch to action methods, passing them theremainder of the line as argument. The optional argument is a banner or intro string to be issued before thefirst prompt (this overrides the \member{intro} class member). If the \refmodule{readline} module is loaded, input will automaticallyinherit \program{bash}-like history-list editing (e.g. \kbd{Control-P}scrolls back to the last command, \kbd{Control-N} forward to the nextone, \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} ifand only if it has a method \method{do_foo()}.  As a special case,a line beginning with the character \character{?} is dispatched tothe method \method{do_help()}.  As another special case, a linebeginning with the character \character{!} is dispatched to themethod \method{do_shell()} (if such a method is defined). This method will return when the \method{postcmd()} method returns atrue value.  The \var{stop} argument to \method{postcmd()} is thereturn value from the command's corresponding \method{do_*()} method. If completion is enabled, completing commands will be doneautomatically, 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 weare 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 indexesof the prefix text, which could be used to provide differentcompletion 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 thecorresponding method \method{help_bar()}.  With no argument,\method{do_help()} lists all available help topics (that is, allcommands with corresponding \method{help_*()} methods), and also listsany undocumented commands.\end{methoddesc} \begin{methoddesc}{onecmd}{str}Interpret the argument as though it had been typed in response to theprompt.  This may be overridden, but should not normally need to be;see the \method{precmd()} and \method{postcmd()} methods for usefulexecution hooks.  The return value is a flag indicating whetherinterpretation of commands by the interpreter should stop.  If thereis a \method{do_*()} method for the command \var{str}, the returnvalue 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 commandentered.  \end{methoddesc} \begin{methoddesc}{default}{line}Method called on an input line when the command prefix is notrecognized. If this method is not overridden, it prints anerror 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 anempty list.\end{methoddesc} \begin{methoddesc}{precmd}{line}Hook method executed just before the command line \var{line} isinterpreted, but after the input prompt is generated and issued.  Thismethod is a stub in \class{Cmd}; it exists to be overridden bysubclasses.  The return value is used as the command which will beexecuted 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.  Thismethod is a stub in \class{Cmd}; it exists to be overridden bysubclasses.  \var{line} is the command line which was executed, and\var{stop} is a flag which indicates whether execution will beterminated after the call to \method{postcmd()}; this will be thereturn value of the \method{onecmd()} method.  The return value ofthis method will be used as the new value for the internal flag whichcorresponds to \var{stop}; returning false will cause interpretationto continue.\end{methoddesc} \begin{methoddesc}{preloop}{}Hook method executed once when \method{cmdloop()} is called.  Thismethod is a stub in \class{Cmd}; it exists to be overridden bysubclasses.\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 bysubclasses.\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 givingthe \method{cmdloop()} method an argument.\end{memberdesc} \begin{memberdesc}{doc_header}The header to issue if the help output has a section for documentedcommands.\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 withoutcorresponding \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 withoutcorresponding \method{help_*()} methods).\end{memberdesc} \begin{memberdesc}{ruler}The character used to draw separator lines under the help-messageheaders.  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 byimporting \refmodule{readline}, on systems that support it, theinterpreter will automatically support \program{Emacs}-like line editing and command-history keystrokes.)\end{memberdesc}