| \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 \code{None} and \module{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 \module{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). |
| |
| 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. |
| \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 \module{readline}, on systems that support it, the |
| interpreter will automatically support Emacs-like line editing |
| and command-history keystrokes.) |
| \end{memberdesc} |