ref: 0366f11300521165ff22423514a5d829a1f34912
dir: /sys/src/cmd/python/Doc/lib/libcmd.tex/
\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 \constant{None} and \refmodule{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 \refmodule{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). This method will return when the \method{postcmd()} method returns a true value. The \var{stop} argument to \method{postcmd()} is the return value from the command's corresponding \method{do_*()} method. 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. If there is a \method{do_*()} method for the command \var{str}, the return value 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 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 \refmodule{readline}, on systems that support it, the interpreter will automatically support \program{Emacs}-like line editing and command-history keystrokes.) \end{memberdesc}