Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame^] | 1 | % Documentation by ESR |
| 2 | \section{Standard Module \module{cmd}} |
| 3 | \stmodindex{cmd} |
| 4 | \label{module-cmd} |
| 5 | |
| 6 | The \code{Cmd} class provides a simple framework for writing |
| 7 | line-oriented command interpreters. These are often useful for |
| 8 | test harnesses, administrative tools, and prototypes that will |
| 9 | later be wrapped in a more sophisticated interface. |
| 10 | |
| 11 | \begin{classdesc}{Cmd}{} |
| 12 | A \class{Cmd} instance or subclass instance is a line-oriented |
| 13 | interpreter framework. There is no good reason to instantiate Cmd |
| 14 | itself; rather, it's useful as a superclass of an interpreter class |
| 15 | you define yourself in order to inherit Cmd's methods and encapsulate |
| 16 | action functions. |
| 17 | \end{classdesc} |
| 18 | |
| 19 | \subsection{Cmd Objects} |
| 20 | \label{Cmd-objects} |
| 21 | |
| 22 | A \class{Cmd} instance has the following methods: |
| 23 | |
| 24 | \begin{methoddesc}{cmdloop}{intro} |
| 25 | Repeatedly issue a prompt, accept input, parse an initial prefix off |
| 26 | the received input, and dispatch to action methods, passing them the |
| 27 | remainder of the line as argument. |
| 28 | |
| 29 | The optional argument is a banner or intro string to be issued before the |
| 30 | first prompt (this overrides the \member{intro} class member). |
| 31 | |
| 32 | If the \module{readline} module is loaded, input will automatically |
| 33 | inherit Emacs-like history-list editing (e.g. Ctrl-P scrolls back to |
| 34 | the last command, Ctrl-N forward to the next one, Ctrl-F moves the |
| 35 | cursor to the right non-destructively, Ctrl-B moves the cursor to the |
| 36 | left non-destructively, etc.). |
| 37 | |
| 38 | An end-of-file on input is passed back as the string "EOF". |
| 39 | |
| 40 | An interpreter instance will recognize a command name \code{foo} if |
| 41 | and only if it has a method named \method{do_foo}. As a special case, |
| 42 | a line containing only the character `?' is dispatched to the method |
| 43 | \method{do_help}. As another special case, a line containing only the |
| 44 | character `!' is dispatched to the method \method{do_shell} (if such a method |
| 45 | is defined). |
| 46 | |
| 47 | All subclasses of \class{Cmd} inherit a predefined \method{do_help}. |
| 48 | This method, called with an argument \code{bar}, invokes the |
| 49 | corresponding method \method{help_bar}. With no argument, |
| 50 | \method{do_help} lists all available help topics (that is, all |
| 51 | commands with corresponding \code{help_} methods), and also lists any |
| 52 | undocumented commands. |
| 53 | \end{methoddesc} |
| 54 | |
| 55 | \begin{methoddesc}{onecmd}{str} |
| 56 | Interpret the argument as though it had been typed in in |
| 57 | response to the prompt. |
| 58 | \end{methoddesc} |
| 59 | |
| 60 | \begin{methoddesc}{emptyline}{} |
| 61 | Method called when an empty line is entered in response to the prompt. |
| 62 | If this method is not overridden, it repeats the last nonempty command |
| 63 | entered. |
| 64 | \end{methoddesc} |
| 65 | |
| 66 | \begin{methoddesc}{default}{line} |
| 67 | Method called on an input line when the command prefix is not |
| 68 | recognized. If this method is not overridden, it prints an |
| 69 | error message and returns. |
| 70 | \end{methoddesc} |
| 71 | |
| 72 | \begin{methoddesc}{precmd} |
| 73 | Hook method executed just before the input prompt is issued. This method is |
| 74 | a stub in \class{Cmd}; it exists to be overridden by subclasses. |
| 75 | \end{methoddesc} |
| 76 | |
| 77 | \begin{methoddesc}{postcmd} |
| 78 | Hook method executed just after a command dispatch is finished. This |
| 79 | method is a stub in \class{Cmd}; it exists to be overridden by |
| 80 | subclasses. |
| 81 | \end{methoddesc} |
| 82 | |
| 83 | \begin{methoddesc}{preloop} |
| 84 | Hook method executed once when \method{cmdloop()} is called. This method is |
| 85 | a stub in \class{Cmd}; it exists to be overridden by subclasses. |
| 86 | \end{methoddesc} |
| 87 | |
| 88 | \begin{methoddesc}{postloop} |
| 89 | Hook method executed once when \method{cmdloop()} is about to return. This |
| 90 | method is a stub in \class{Cmd}; it exists to be overridden by |
| 91 | subclasses. |
| 92 | \end{methoddesc} |
| 93 | |
| 94 | Instances of \class{Cmd} subclasses have some public instance variables: |
| 95 | |
| 96 | \begin{memberdesc}{prompt} |
| 97 | The prompt issued to solicit input. |
| 98 | \end{memberdesc} |
| 99 | |
| 100 | \begin{memberdesc}{identchars} |
| 101 | The string of characters accepted for the command prefix. |
| 102 | \end{memberdesc} |
| 103 | |
| 104 | \begin{memberdesc}{lastcmd} |
| 105 | The last nonempty command prefix seen. |
| 106 | \end{memberdesc} |
| 107 | |
| 108 | \begin{memberdesc}{intro} |
| 109 | A string to issue as an intro or banner. May be overridden by giving |
| 110 | the \method{cmdloop()} method an argument. |
| 111 | \end{memberdesc} |
| 112 | |
| 113 | \begin{memberdesc}{doc_header} |
| 114 | The header to issue if the help output has a section for documented commands. |
| 115 | \end{memberdesc} |
| 116 | |
| 117 | \begin{memberdesc}{misc_header} |
| 118 | The header to issue if the help output has a section for miscellaneous |
| 119 | help topics (that is, there are \code{help_} methods withoud corresponding |
| 120 | \code{do_} functions). |
| 121 | \end{memberdesc} |
| 122 | |
| 123 | \begin{memberdesc}{undoc_header} |
| 124 | The header to issue if the help output has a section for undocumented |
| 125 | commands (that is, there are \code{do_} methods withoud corresponding |
| 126 | \code{help_} functions). |
| 127 | \end{memberdesc} |
| 128 | |
| 129 | \begin{memberdesc}{ruler} |
| 130 | The character used to draw separator lines under the help-message |
| 131 | headers. If empty, no ruler line is drawn. It defaults to "=". |
| 132 | \end{memberdesc} |
| 133 | |
| 134 | |