diff options
Diffstat (limited to 'Doc/lib/libcmd.tex')
| -rw-r--r-- | Doc/lib/libcmd.tex | 198 |
1 files changed, 0 insertions, 198 deletions
diff --git a/Doc/lib/libcmd.tex b/Doc/lib/libcmd.tex deleted file mode 100644 index 810f19c..0000000 --- a/Doc/lib/libcmd.tex +++ /dev/null @@ -1,198 +0,0 @@ -\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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{prompt} -The prompt issued to solicit input. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{identchars} -The string of characters accepted for the command prefix. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{lastcmd} -The last nonempty command prefix seen. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{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}[Cmd]{doc_header} -The header to issue if the help output has a section for documented -commands. -\end{memberdesc} - -\begin{memberdesc}[Cmd]{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}[Cmd]{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}[Cmd]{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}[Cmd]{use_rawinput} -A flag, defaulting to true. If true, \method{cmdloop()} uses -\function{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} |