Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{cmd} --- |
Fred Drake | f8ca7d8 | 2000-10-10 17:03:45 +0000 | [diff] [blame] | 2 | Support for line-oriented command interpreters} |
| 3 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{cmd} |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 5 | \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com} |
Fred Drake | f8ca7d8 | 2000-10-10 17:03:45 +0000 | [diff] [blame] | 6 | \modulesynopsis{Build line-oriented command interpreters.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 7 | |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 8 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 9 | The \class{Cmd} class provides a simple framework for writing |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 10 | line-oriented command interpreters. These are often useful for |
| 11 | test harnesses, administrative tools, and prototypes that will |
| 12 | later be wrapped in a more sophisticated interface. |
| 13 | |
Fred Drake | 7f8d17a | 2003-12-31 05:01:23 +0000 | [diff] [blame] | 14 | \begin{classdesc}{Cmd}{\optional{completekey\optional{, |
| 15 | stdin\optional{, stdout}}}} |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 16 | A \class{Cmd} instance or subclass instance is a line-oriented |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 17 | interpreter framework. There is no good reason to instantiate |
| 18 | \class{Cmd} itself; rather, it's useful as a superclass of an |
| 19 | interpreter class you define yourself in order to inherit |
| 20 | \class{Cmd}'s methods and encapsulate action methods. |
Martin v. Löwis | 66b6e19 | 2001-07-28 14:44:03 +0000 | [diff] [blame] | 21 | |
Anthony Baxter | 983b008 | 2003-02-06 01:45:11 +0000 | [diff] [blame] | 22 | The optional argument \var{completekey} is the \refmodule{readline} name |
| 23 | of a completion key; it defaults to \kbd{Tab}. If \var{completekey} is |
Fred Drake | 7f8d17a | 2003-12-31 05:01:23 +0000 | [diff] [blame] | 24 | not \constant{None} and \refmodule{readline} is available, command completion |
Anthony Baxter | 983b008 | 2003-02-06 01:45:11 +0000 | [diff] [blame] | 25 | is done automatically. |
| 26 | |
| 27 | The optional arguments \var{stdin} and \var{stdout} specify the |
| 28 | input and output file objects that the Cmd instance or subclass |
| 29 | instance will use for input and output. If not specified, they |
| 30 | will default to \var{sys.stdin} and \var{sys.stdout}. |
| 31 | |
Neal Norwitz | 292f56c | 2003-02-06 05:02:39 +0000 | [diff] [blame] | 32 | \versionchanged[The \var{stdin} and \var{stdout} parameters were added.]{2.3} |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 33 | \end{classdesc} |
| 34 | |
| 35 | \subsection{Cmd Objects} |
| 36 | \label{Cmd-objects} |
| 37 | |
| 38 | A \class{Cmd} instance has the following methods: |
| 39 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 40 | \begin{methoddesc}{cmdloop}{\optional{intro}} |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 41 | Repeatedly issue a prompt, accept input, parse an initial prefix off |
| 42 | the received input, and dispatch to action methods, passing them the |
| 43 | remainder of the line as argument. |
| 44 | |
| 45 | The optional argument is a banner or intro string to be issued before the |
| 46 | first prompt (this overrides the \member{intro} class member). |
| 47 | |
Fred Drake | 7f8d17a | 2003-12-31 05:01:23 +0000 | [diff] [blame] | 48 | If the \refmodule{readline} module is loaded, input will automatically |
Fred Drake | 682d5f3 | 2001-07-12 02:09:51 +0000 | [diff] [blame] | 49 | inherit \program{bash}-like history-list editing (e.g. \kbd{Control-P} |
| 50 | scrolls back to the last command, \kbd{Control-N} forward to the next |
| 51 | one, \kbd{Control-F} moves the cursor to the right non-destructively, |
| 52 | \kbd{Control-B} moves the cursor to the left non-destructively, etc.). |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 53 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 54 | An end-of-file on input is passed back as the string \code{'EOF'}. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 55 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 56 | An interpreter instance will recognize a command name \samp{foo} if |
| 57 | and only if it has a method \method{do_foo()}. As a special case, |
Eric S. Raymond | 7ae3a5e | 2000-07-12 02:56:15 +0000 | [diff] [blame] | 58 | a line beginning with the character \character{?} is dispatched to |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 59 | the method \method{do_help()}. As another special case, a line |
Eric S. Raymond | 7ae3a5e | 2000-07-12 02:56:15 +0000 | [diff] [blame] | 60 | beginning with the character \character{!} is dispatched to the |
Fred Drake | 43211ec | 2001-07-29 03:41:23 +0000 | [diff] [blame] | 61 | method \method{do_shell()} (if such a method is defined). |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 62 | |
Martin v. Löwis | 66b6e19 | 2001-07-28 14:44:03 +0000 | [diff] [blame] | 63 | If completion is enabled, completing commands will be done |
| 64 | automatically, and completing of commands args is done by calling |
Fred Drake | 43211ec | 2001-07-29 03:41:23 +0000 | [diff] [blame] | 65 | \method{complete_foo()} with arguments \var{text}, \var{line}, |
| 66 | \var{begidx}, and \var{endidx}. \var{text} is the string prefix we |
| 67 | are attempting to match: all returned matches must begin with it. |
| 68 | \var{line} is the current input line with leading whitespace removed, |
| 69 | \var{begidx} and \var{endidx} are the beginning and ending indexes |
| 70 | of the prefix text, which could be used to provide different |
| 71 | completion depending upon which position the argument is in. |
Martin v. Löwis | 66b6e19 | 2001-07-28 14:44:03 +0000 | [diff] [blame] | 72 | |
Fred Drake | 43211ec | 2001-07-29 03:41:23 +0000 | [diff] [blame] | 73 | All subclasses of \class{Cmd} inherit a predefined \method{do_help()}. |
| 74 | This method, called with an argument \code{'bar'}, invokes the |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 75 | corresponding method \method{help_bar()}. With no argument, |
| 76 | \method{do_help()} lists all available help topics (that is, all |
| 77 | commands with corresponding \method{help_*()} methods), and also lists |
| 78 | any undocumented commands. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 79 | \end{methoddesc} |
| 80 | |
| 81 | \begin{methoddesc}{onecmd}{str} |
Fred Drake | 7c9a53d | 2001-12-27 05:10:18 +0000 | [diff] [blame] | 82 | Interpret the argument as though it had been typed in response to the |
| 83 | prompt. This may be overridden, but should not normally need to be; |
| 84 | see the \method{precmd()} and \method{postcmd()} methods for useful |
| 85 | execution hooks. The return value is a flag indicating whether |
| 86 | interpretation of commands by the interpreter should stop. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 87 | \end{methoddesc} |
| 88 | |
| 89 | \begin{methoddesc}{emptyline}{} |
| 90 | Method called when an empty line is entered in response to the prompt. |
| 91 | If this method is not overridden, it repeats the last nonempty command |
| 92 | entered. |
| 93 | \end{methoddesc} |
| 94 | |
| 95 | \begin{methoddesc}{default}{line} |
| 96 | Method called on an input line when the command prefix is not |
| 97 | recognized. If this method is not overridden, it prints an |
| 98 | error message and returns. |
| 99 | \end{methoddesc} |
| 100 | |
Martin v. Löwis | 66b6e19 | 2001-07-28 14:44:03 +0000 | [diff] [blame] | 101 | \begin{methoddesc}{completedefault}{text, line, begidx, endidx} |
| 102 | Method called to complete an input line when no command-specific |
Fred Drake | 43211ec | 2001-07-29 03:41:23 +0000 | [diff] [blame] | 103 | \method{complete_*()} method is available. By default, it returns an |
Martin v. Löwis | 66b6e19 | 2001-07-28 14:44:03 +0000 | [diff] [blame] | 104 | empty list. |
| 105 | \end{methoddesc} |
| 106 | |
Fred Drake | 7c9a53d | 2001-12-27 05:10:18 +0000 | [diff] [blame] | 107 | \begin{methoddesc}{precmd}{line} |
| 108 | Hook method executed just before the command line \var{line} is |
| 109 | interpreted, but after the input prompt is generated and issued. This |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 110 | method is a stub in \class{Cmd}; it exists to be overridden by |
Fred Drake | 7c9a53d | 2001-12-27 05:10:18 +0000 | [diff] [blame] | 111 | subclasses. The return value is used as the command which will be |
| 112 | executed by the \method{onecmd()} method; the \method{precmd()} |
| 113 | implementation may re-write the command or simply return \var{line} |
| 114 | unchanged. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 115 | \end{methoddesc} |
| 116 | |
Fred Drake | 7c9a53d | 2001-12-27 05:10:18 +0000 | [diff] [blame] | 117 | \begin{methoddesc}{postcmd}{stop, line} |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 118 | Hook method executed just after a command dispatch is finished. This |
| 119 | method is a stub in \class{Cmd}; it exists to be overridden by |
Fred Drake | 7c9a53d | 2001-12-27 05:10:18 +0000 | [diff] [blame] | 120 | subclasses. \var{line} is the command line which was executed, and |
| 121 | \var{stop} is a flag which indicates whether execution will be |
| 122 | terminated after the call to \method{postcmd()}; this will be the |
| 123 | return value of the \method{onecmd()} method. The return value of |
| 124 | this method will be used as the new value for the internal flag which |
| 125 | corresponds to \var{stop}; returning false will cause interpretation |
| 126 | to continue. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 127 | \end{methoddesc} |
| 128 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 129 | \begin{methoddesc}{preloop}{} |
| 130 | Hook method executed once when \method{cmdloop()} is called. This |
| 131 | method is a stub in \class{Cmd}; it exists to be overridden by |
| 132 | subclasses. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 133 | \end{methoddesc} |
| 134 | |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 135 | \begin{methoddesc}{postloop}{} |
| 136 | Hook method executed once when \method{cmdloop()} is about to return. |
| 137 | This method is a stub in \class{Cmd}; it exists to be overridden by |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 138 | subclasses. |
| 139 | \end{methoddesc} |
| 140 | |
| 141 | Instances of \class{Cmd} subclasses have some public instance variables: |
| 142 | |
| 143 | \begin{memberdesc}{prompt} |
| 144 | The prompt issued to solicit input. |
| 145 | \end{memberdesc} |
| 146 | |
| 147 | \begin{memberdesc}{identchars} |
| 148 | The string of characters accepted for the command prefix. |
| 149 | \end{memberdesc} |
| 150 | |
| 151 | \begin{memberdesc}{lastcmd} |
| 152 | The last nonempty command prefix seen. |
| 153 | \end{memberdesc} |
| 154 | |
| 155 | \begin{memberdesc}{intro} |
| 156 | A string to issue as an intro or banner. May be overridden by giving |
| 157 | the \method{cmdloop()} method an argument. |
| 158 | \end{memberdesc} |
| 159 | |
| 160 | \begin{memberdesc}{doc_header} |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 161 | The header to issue if the help output has a section for documented |
| 162 | commands. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 163 | \end{memberdesc} |
| 164 | |
| 165 | \begin{memberdesc}{misc_header} |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 166 | The header to issue if the help output has a section for miscellaneous |
| 167 | help topics (that is, there are \method{help_*()} methods without |
| 168 | corresponding \method{do_*()} methods). |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 169 | \end{memberdesc} |
| 170 | |
| 171 | \begin{memberdesc}{undoc_header} |
| 172 | The header to issue if the help output has a section for undocumented |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 173 | commands (that is, there are \method{do_*()} methods without |
| 174 | corresponding \method{help_*()} methods). |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 175 | \end{memberdesc} |
| 176 | |
| 177 | \begin{memberdesc}{ruler} |
| 178 | The character used to draw separator lines under the help-message |
Fred Drake | 579d366 | 1998-07-02 19:35:12 +0000 | [diff] [blame] | 179 | headers. If empty, no ruler line is drawn. It defaults to |
| 180 | \character{=}. |
Guido van Rossum | 8668e8e | 1998-06-28 17:55:53 +0000 | [diff] [blame] | 181 | \end{memberdesc} |
| 182 | |
Guido van Rossum | c8da0f9 | 2001-03-24 19:17:35 +0000 | [diff] [blame] | 183 | \begin{memberdesc}{use_rawinput} |
| 184 | A flag, defaulting to true. If true, \method{cmdloop()} uses |
| 185 | \function{raw_input()} to display a prompt and read the next command; |
Fred Drake | 43211ec | 2001-07-29 03:41:23 +0000 | [diff] [blame] | 186 | if false, \method{sys.stdout.write()} and |
| 187 | \method{sys.stdin.readline()} are used. (This means that by |
Fred Drake | 7f8d17a | 2003-12-31 05:01:23 +0000 | [diff] [blame] | 188 | importing \refmodule{readline}, on systems that support it, the |
| 189 | interpreter will automatically support \program{Emacs}-like line editing |
Eric S. Raymond | ff00fda | 2001-06-23 14:42:43 +0000 | [diff] [blame] | 190 | and command-history keystrokes.) |
Guido van Rossum | c8da0f9 | 2001-03-24 19:17:35 +0000 | [diff] [blame] | 191 | \end{memberdesc} |