Debian Codegraph @

Doc/library/cmd.rst

raw
1 :mod:`!cmd` --- Support for line-oriented command interpreters
2 ==============================================================
3
4 .. module:: cmd
5 :synopsis: Build line-oriented command interpreters.
6
7 .. sectionauthor:: Eric S. Raymond <[email protected]>
8
9 **Source code:** :source:`Lib/cmd.py`
10
11 --------------
12
13 The :class:`Cmd` class provides a simple framework for writing line-oriented
14 command interpreters. These are often useful for test harnesses, administrative
15 tools, and prototypes that will later be wrapped in a more sophisticated
16 interface.
17
18 .. class:: Cmd(completekey='tab', stdin=None, stdout=None)
19
20 A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
21 framework. There is no good reason to instantiate :class:`Cmd` itself; rather,
22 it's useful as a superclass of an interpreter class you define yourself in order
23 to inherit :class:`Cmd`'s methods and encapsulate action methods.
24
25 The optional argument *completekey* is the :mod:`readline` name of a completion
26 key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
27 :mod:`readline` is available, command completion is done automatically.
28
29 The default, ``'tab'``, is treated specially, so that it refers to the
30 :kbd:`Tab` key on every :data:`readline.backend`.
31 Specifically, if :data:`readline.backend` is ``editline``,
32 ``Cmd`` will use ``'^I'`` instead of ``'tab'``.
33 Note that other values are not treated this way, and might only work
34 with a specific backend.
35
36 The optional arguments *stdin* and *stdout* specify the input and output file
37 objects that the Cmd instance or subclass instance will use for input and
38 output. If not specified, they will default to :data:`sys.stdin` and
39 :data:`sys.stdout`.
40
41 If you want a given *stdin* to be used, make sure to set the instance's
42 :attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be
43 ignored.
44
45 .. versionchanged:: 3.13
46 ``completekey='tab'`` is replaced by ``'^I'`` for ``editline``.
47
48
49 .. _cmd-objects:
50
51 Cmd Objects
52 -----------
53
54 A :class:`Cmd` instance has the following methods:
55
56
57 .. method:: Cmd.cmdloop(intro=None)
58
59 Repeatedly issue a prompt, accept input, parse an initial prefix off the
60 received input, and dispatch to action methods, passing them the remainder of
61 the line as argument.
62
63 The optional argument is a banner or intro string to be issued before the first
64 prompt (this overrides the :attr:`intro` class attribute).
65
66 If the :mod:`readline` module is loaded, input will automatically inherit
67 :program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
68 to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
69 moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
70 cursor to the left non-destructively, etc.).
71
72 An end-of-file on input is passed back as the string ``'EOF'``.
73
74 .. index::
75 single: ? (question mark); in a command interpreter
76 single: ! (exclamation); in a command interpreter
77
78 An interpreter instance will recognize a command name ``foo`` if and only if it
79 has a method :meth:`!do_foo`. As a special case, a line beginning with the
80 character ``'?'`` is dispatched to the method :meth:`do_help`. As another
81 special case, a line beginning with the character ``'!'`` is dispatched to the
82 method :meth:`!do_shell` (if such a method is defined).
83
84 This method will return when the :meth:`postcmd` method returns a true value.
85 The *stop* argument to :meth:`postcmd` is the return value from the command's
86 corresponding :meth:`!do_\*` method.
87
88 If completion is enabled, completing commands will be done automatically, and
89 completing of commands args is done by calling :meth:`!complete_foo` with
90 arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix
91 we are attempting to match: all returned matches must begin with it. *line* is
92 the current input line with leading whitespace removed, *begidx* and *endidx*
93 are the beginning and ending indexes of the prefix text, which could be used to
94 provide different completion depending upon which position the argument is in.
95
96
97 .. method:: Cmd.do_help(arg)
98
99 All subclasses of :class:`Cmd` inherit a predefined :meth:`!do_help`. This
100 method, called with an argument ``'bar'``, invokes the corresponding method
101 :meth:`!help_bar`, and if that is not present, prints the docstring of
102 :meth:`!do_bar`, if available. With no argument, :meth:`!do_help` lists all
103 available help topics (that is, all commands with corresponding
104 :meth:`!help_\*` methods or commands that have docstrings), and also lists any
105 undocumented commands.
106
107
108 .. method:: Cmd.onecmd(str)
109
110 Interpret the argument as though it had been typed in response to the prompt.
111 This may be overridden, but should not normally need to be; see the
112 :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The
113 return value is a flag indicating whether interpretation of commands by the
114 interpreter should stop. If there is a :meth:`!do_\*` method for the command
115 *str*, the return value of that method is returned, otherwise the return value
116 from the :meth:`default` method is returned.
117
118
119 .. method:: Cmd.emptyline()
120
121 Method called when an empty line is entered in response to the prompt. If this
122 method is not overridden, it repeats the last nonempty command entered.
123
124
125 .. method:: Cmd.default(line)
126
127 Method called on an input line when the command prefix is not recognized. If
128 this method is not overridden, it prints an error message and returns.
129
130
131 .. method:: Cmd.completedefault(text, line, begidx, endidx)
132
133 Method called to complete an input line when no command-specific
134 :meth:`!complete_\*` method is available. By default, it returns an empty list.
135
136
137 .. method:: Cmd.columnize(list, displaywidth=80)
138
139 Method called to display a list of strings as a compact set of columns.
140 Each column is only as wide as necessary.
141 Columns are separated by two spaces for readability.
142
143
144 .. method:: Cmd.precmd(line)
145
146 Hook method executed just before the command line *line* is interpreted, but
147 after the input prompt is generated and issued. This method is a stub in
148 :class:`Cmd`; it exists to be overridden by subclasses. The return value is
149 used as the command which will be executed by the :meth:`onecmd` method; the
150 :meth:`precmd` implementation may re-write the command or simply return *line*
151 unchanged.
152
153
154 .. method:: Cmd.postcmd(stop, line)
155
156 Hook method executed just after a command dispatch is finished. This method is
157 a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* is the
158 command line which was executed, and *stop* is a flag which indicates whether
159 execution will be terminated after the call to :meth:`postcmd`; this will be the
160 return value of the :meth:`onecmd` method. The return value of this method will
161 be used as the new value for the internal flag which corresponds to *stop*;
162 returning false will cause interpretation to continue.
163
164
165 .. method:: Cmd.preloop()
166
167 Hook method executed once when :meth:`cmdloop` is called. This method is a stub
168 in :class:`Cmd`; it exists to be overridden by subclasses.
169
170
171 .. method:: Cmd.postloop()
172
173 Hook method executed once when :meth:`cmdloop` is about to return. This method
174 is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
175
176
177 Instances of :class:`Cmd` subclasses have some public instance variables:
178
179 .. attribute:: Cmd.prompt
180
181 The prompt issued to solicit input.
182
183
184 .. attribute:: Cmd.identchars
185
186 The string of characters accepted for the command prefix.
187
188
189 .. attribute:: Cmd.lastcmd
190
191 The last nonempty command prefix seen.
192
193
194 .. attribute:: Cmd.cmdqueue
195
196 A list of queued input lines. The cmdqueue list is checked in
197 :meth:`cmdloop` when new input is needed; if it is nonempty, its elements
198 will be processed in order, as if entered at the prompt.
199
200
201 .. attribute:: Cmd.intro
202
203 A string to issue as an intro or banner. May be overridden by giving the
204 :meth:`cmdloop` method an argument.
205
206
207 .. attribute:: Cmd.doc_header
208
209 The header to issue if the help output has a section for documented commands.
210
211
212 .. attribute:: Cmd.misc_header
213
214 The header to issue if the help output has a section for miscellaneous help
215 topics (that is, there are :meth:`!help_\*` methods without corresponding
216 :meth:`!do_\*` methods).
217
218
219 .. attribute:: Cmd.undoc_header
220
221 The header to issue if the help output has a section for undocumented commands
222 (that is, there are :meth:`!do_\*` methods without corresponding :meth:`!help_\*`
223 methods).
224
225
226 .. attribute:: Cmd.ruler
227
228 The character used to draw separator lines under the help-message headers. If
229 empty, no ruler line is drawn. It defaults to ``'='``.
230
231
232 .. attribute:: Cmd.use_rawinput
233
234 A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to
235 display a prompt and read the next command; if false, :data:`sys.stdout.write() <sys.stdout>`
236 and :data:`sys.stdin.readline() <sys.stdin>` are used. (This means that by importing
237 :mod:`readline`, on systems that support it, the interpreter will automatically
238 support :program:`Emacs`\ -like line editing and command-history keystrokes.)
239
240
241 .. _cmd-example:
242
243 Cmd Example
244 -----------
245
246 .. sectionauthor:: Raymond Hettinger <python at rcn dot com>
247
248 The :mod:`!cmd` module is mainly useful for building custom shells that let a
249 user work with a program interactively.
250
251 This section presents a simple example of how to build a shell around a few of
252 the commands in the :mod:`turtle` module.
253
254 Basic turtle commands such as :meth:`~turtle.forward` are added to a
255 :class:`Cmd` subclass with method named :meth:`!do_forward`. The argument is
256 converted to a number and dispatched to the turtle module. The docstring is
257 used in the help utility provided by the shell.
258
259 The example also includes a basic record and playback facility implemented with
260 the :meth:`~Cmd.precmd` method which is responsible for converting the input to
261 lowercase and writing the commands to a file. The :meth:`!do_playback` method
262 reads the file and adds the recorded commands to the :attr:`~Cmd.cmdqueue` for
263 immediate playback::
264
265 import cmd, sys
266 from turtle import *
267
268 class TurtleShell(cmd.Cmd):
269 intro = 'Welcome to the turtle shell. Type help or ? to list commands.\n'
270 prompt = '(turtle) '
271 file = None
272
273 # ----- basic turtle commands -----
274 def do_forward(self, arg):
275 'Move the turtle forward by the specified distance: FORWARD 10'
276 forward(*parse(arg))
277 def do_right(self, arg):
278 'Turn turtle right by given number of degrees: RIGHT 20'
279 right(*parse(arg))
280 def do_left(self, arg):
281 'Turn turtle left by given number of degrees: LEFT 90'
282 left(*parse(arg))
283 def do_goto(self, arg):
284 'Move turtle to an absolute position with changing orientation. GOTO 100 200'
285 goto(*parse(arg))
286 def do_home(self, arg):
287 'Return turtle to the home position: HOME'
288 home()
289 def do_circle(self, arg):
290 'Draw circle with given radius an options extent and steps: CIRCLE 50'
291 circle(*parse(arg))
292 def do_position(self, arg):
293 'Print the current turtle position: POSITION'
294 print('Current position is %d %d\n' % position())
295 def do_heading(self, arg):
296 'Print the current turtle heading in degrees: HEADING'
297 print('Current heading is %d\n' % (heading(),))
298 def do_color(self, arg):
299 'Set the color: COLOR BLUE'
300 color(arg.lower())
301 def do_undo(self, arg):
302 'Undo (repeatedly) the last turtle action(s): UNDO'
303 def do_reset(self, arg):
304 'Clear the screen and return turtle to center: RESET'
305 reset()
306 def do_bye(self, arg):
307 'Stop recording, close the turtle window, and exit: BYE'
308 print('Thank you for using Turtle')
309 self.close()
310 bye()
311 return True
312
313 # ----- record and playback -----
314 def do_record(self, arg):
315 'Save future commands to filename: RECORD rose.cmd'
316 self.file = open(arg, 'w')
317 def do_playback(self, arg):
318 'Playback commands from a file: PLAYBACK rose.cmd'
319 self.close()
320 with open(arg) as f:
321 self.cmdqueue.extend(f.read().splitlines())
322 def precmd(self, line):
323 line = line.lower()
324 if self.file and 'playback' not in line:
325 print(line, file=self.file)
326 return line
327 def close(self):
328 if self.file:
329 self.file.close()
330 self.file = None
331
332 def parse(arg):
333 'Convert a series of zero or more numbers to an argument tuple'
334 return tuple(map(int, arg.split()))
335
336 if __name__ == '__main__':
337 TurtleShell().cmdloop()
338
339
340 Here is a sample session with the turtle shell showing the help functions, using
341 blank lines to repeat commands, and the simple record and playback facility:
342
343 .. code-block:: none
344
345 Welcome to the turtle shell. Type help or ? to list commands.
346
347 (turtle) ?
348
349 Documented commands (type help <topic>):
350 ========================================
351 bye color goto home playback record right
352 circle forward heading left position reset undo
353
354 (turtle) help forward
355 Move the turtle forward by the specified distance: FORWARD 10
356 (turtle) record spiral.cmd
357 (turtle) position
358 Current position is 0 0
359
360 (turtle) heading
361 Current heading is 0
362
363 (turtle) reset
364 (turtle) circle 20
365 (turtle) right 30
366 (turtle) circle 40
367 (turtle) right 30
368 (turtle) circle 60
369 (turtle) right 30
370 (turtle) circle 80
371 (turtle) right 30
372 (turtle) circle 100
373 (turtle) right 30
374 (turtle) circle 120
375 (turtle) right 30
376 (turtle) circle 120
377 (turtle) heading
378 Current heading is 180
379
380 (turtle) forward 100
381 (turtle)
382 (turtle) right 90
383 (turtle) forward 100
384 (turtle)
385 (turtle) right 90
386 (turtle) forward 400
387 (turtle) right 90
388 (turtle) forward 500
389 (turtle) right 90
390 (turtle) forward 400
391 (turtle) right 90
392 (turtle) forward 300
393 (turtle) playback spiral.cmd
394 Current position is 0 0
395
396 Current heading is 0
397
398 Current heading is 180
399
400 (turtle) bye
401 Thank you for using Turtle