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