1
:mod:`cmd` --- Support for line-oriented command interpreters
2
=============================================================
5
:synopsis: Build line-oriented command interpreters.
6
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
8
**Source code:** :source:`Lib/cmd.py`
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
17
.. class:: Cmd(completekey='tab', stdin=None, stdout=None)
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.
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.
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
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
43
A :class:`Cmd` instance has the following methods:
46
.. method:: Cmd.cmdloop(intro=None)
48
Repeatedly issue a prompt, accept input, parse an initial prefix off the
49
received input, and dispatch to action methods, passing them the remainder of
52
The optional argument is a banner or intro string to be issued before the first
53
prompt (this overrides the :attr:`intro` class attribute).
55
If the :mod:`readline` module is loaded, input will automatically inherit
56
:program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
57
to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
58
moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
59
cursor to the left non-destructively, etc.).
61
An end-of-file on input is passed back as the string ``'EOF'``.
63
An interpreter instance will recognize a command name ``foo`` if and only if it
64
has a method :meth:`do_foo`. As a special case, a line beginning with the
65
character ``'?'`` is dispatched to the method :meth:`do_help`. As another
66
special case, a line beginning with the character ``'!'`` is dispatched to the
67
method :meth:`do_shell` (if such a method is defined).
69
This method will return when the :meth:`postcmd` method returns a true value.
70
The *stop* argument to :meth:`postcmd` is the return value from the command's
71
corresponding :meth:`do_\*` method.
73
If completion is enabled, completing commands will be done automatically, and
74
completing of commands args is done by calling :meth:`complete_foo` with
75
arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix
76
we are attempting to match: all returned matches must begin with it. *line* is
77
the current input line with leading whitespace removed, *begidx* and *endidx*
78
are the beginning and ending indexes of the prefix text, which could be used to
79
provide different completion depending upon which position the argument is in.
81
All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This
82
method, called with an argument ``'bar'``, invokes the corresponding method
83
:meth:`help_bar`, and if that is not present, prints the docstring of
84
:meth:`do_bar`, if available. With no argument, :meth:`do_help` lists all
85
available help topics (that is, all commands with corresponding
86
:meth:`help_\*` methods or commands that have docstrings), and also lists any
87
undocumented commands.
90
.. method:: Cmd.onecmd(str)
92
Interpret the argument as though it had been typed in response to the prompt.
93
This may be overridden, but should not normally need to be; see the
94
:meth:`precmd` and :meth:`postcmd` methods for useful execution hooks. The
95
return value is a flag indicating whether interpretation of commands by the
96
interpreter should stop. If there is a :meth:`do_\*` method for the command
97
*str*, the return value of that method is returned, otherwise the return value
98
from the :meth:`default` method is returned.
101
.. method:: Cmd.emptyline()
103
Method called when an empty line is entered in response to the prompt. If this
104
method is not overridden, it repeats the last nonempty command entered.
107
.. method:: Cmd.default(line)
109
Method called on an input line when the command prefix is not recognized. If
110
this method is not overridden, it prints an error message and returns.
113
.. method:: Cmd.completedefault(text, line, begidx, endidx)
115
Method called to complete an input line when no command-specific
116
:meth:`complete_\*` method is available. By default, it returns an empty list.
119
.. method:: Cmd.precmd(line)
121
Hook method executed just before the command line *line* is interpreted, but
122
after the input prompt is generated and issued. This method is a stub in
123
:class:`Cmd`; it exists to be overridden by subclasses. The return value is
124
used as the command which will be executed by the :meth:`onecmd` method; the
125
:meth:`precmd` implementation may re-write the command or simply return *line*
129
.. method:: Cmd.postcmd(stop, line)
131
Hook method executed just after a command dispatch is finished. This method is
132
a stub in :class:`Cmd`; it exists to be overridden by subclasses. *line* is the
133
command line which was executed, and *stop* is a flag which indicates whether
134
execution will be terminated after the call to :meth:`postcmd`; this will be the
135
return value of the :meth:`onecmd` method. The return value of this method will
136
be used as the new value for the internal flag which corresponds to *stop*;
137
returning false will cause interpretation to continue.
140
.. method:: Cmd.preloop()
142
Hook method executed once when :meth:`cmdloop` is called. This method is a stub
143
in :class:`Cmd`; it exists to be overridden by subclasses.
146
.. method:: Cmd.postloop()
148
Hook method executed once when :meth:`cmdloop` is about to return. This method
149
is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
151
Instances of :class:`Cmd` subclasses have some public instance variables:
154
.. attribute:: Cmd.prompt
156
The prompt issued to solicit input.
159
.. attribute:: Cmd.identchars
161
The string of characters accepted for the command prefix.
164
.. attribute:: Cmd.lastcmd
166
The last nonempty command prefix seen.
169
.. attribute:: Cmd.intro
171
A string to issue as an intro or banner. May be overridden by giving the
172
:meth:`cmdloop` method an argument.
175
.. attribute:: Cmd.doc_header
177
The header to issue if the help output has a section for documented commands.
180
.. attribute:: Cmd.misc_header
182
The header to issue if the help output has a section for miscellaneous help
183
topics (that is, there are :meth:`help_\*` methods without corresponding
184
:meth:`do_\*` methods).
187
.. attribute:: Cmd.undoc_header
189
The header to issue if the help output has a section for undocumented commands
190
(that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
194
.. attribute:: Cmd.ruler
196
The character used to draw separator lines under the help-message headers. If
197
empty, no ruler line is drawn. It defaults to ``'='``.
200
.. attribute:: Cmd.use_rawinput
202
A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`input` to
203
display a prompt and read the next command; if false, :meth:`sys.stdout.write`
204
and :meth:`sys.stdin.readline` are used. (This means that by importing
205
:mod:`readline`, on systems that support it, the interpreter will automatically
206
support :program:`Emacs`\ -like line editing and command-history keystrokes.)
214
.. sectionauthor:: Raymond Hettinger <python at rcn dot com>
216
The :mod:`cmd` module is mainly useful for building custom shells that let a
217
user work with a program interactively.
219
This section presents a simple example of how to build a shell around a few of
220
the commands in the :mod:`turtle` module.
222
Basic turtle commands such as :meth:`~turtle.forward` are added to a
223
:class:`Cmd` subclass with method named :meth:`do_forward`. The argument is
224
converted to a number and dispatched to the turtle module. The docstring is
225
used in the help utility provided by the shell.
227
The example also includes a basic record and playback facility implemented with
228
the :meth:`~Cmd.precmd` method which is responsible for converting the input to
229
lowercase and writing the commands to a file. The :meth:`do_playback` method
230
reads the file and adds the recorded commands to the :attr:`cmdqueue` for
236
class TurtleShell(cmd.Cmd):
237
intro = 'Welcome to the turtle shell. Type help or ? to list commands.\n'
241
# ----- basic turtle commands -----
242
def do_forward(self, arg):
243
'Move the turtle forward by the specified distance: FORWARD 10'
245
def do_right(self, arg):
246
'Turn turtle right by given number of degrees: RIGHT 20'
248
def do_left(self, arg):
249
'Turn turtle left by given number of degrees: LEFT 90'
251
def do_goto(self, arg):
252
'Move turtle to an absolute position with changing orientation. GOTO 100 200'
254
def do_home(self, arg):
255
'Return turtle to the home postion: HOME'
257
def do_circle(self, arg):
258
'Draw circle with given radius an options extent and steps: CIRCLE 50'
260
def do_position(self, arg):
261
'Print the current turle position: POSITION'
262
print('Current position is %d %d\n' % position())
263
def do_heading(self, arg):
264
'Print the current turle heading in degrees: HEADING'
265
print('Current heading is %d\n' % (heading(),))
266
def do_color(self, arg):
267
'Set the color: COLOR BLUE'
269
def do_undo(self, arg):
270
'Undo (repeatedly) the last turtle action(s): UNDO'
271
def do_reset(self, arg):
272
'Clear the screen and return turtle to center: RESET'
274
def do_bye(self, arg):
275
'Stop recording, close the turtle window, and exit: BYE'
276
print('Thank you for using Turtle')
281
# ----- record and playback -----
282
def do_record(self, arg):
283
'Save future commands to filename: RECORD rose.cmd'
284
self.file = open(arg, 'w')
285
def do_playback(self, arg):
286
'Playback commands from a file: PLAYBACK rose.cmd'
289
self.cmdqueue.extend(f.read().splitlines())
290
def precmd(self, line):
292
if self.file and 'playback' not in line:
293
print(line, file=self.file)
301
'Convert a series of zero or more numbers to an argument tuple'
302
return tuple(map(int, arg.split()))
304
if __name__ == '__main__':
305
TurtleShell().cmdloop()
308
Here is a sample session with the turtle shell showing the help functions, using
309
blank lines to repeat commands, and the simple record and playback facility::
311
Welcome to the turtle shell. Type help or ? to list commands.
315
Documented commands (type help <topic>):
316
========================================
317
bye color goto home playback record right
318
circle forward heading left position reset undo
320
(turtle) help forward
321
Move the turtle forward by the specified distance: FORWARD 10
322
(turtle) record spiral.cmd
324
Current position is 0 0
344
Current heading is 180
359
(turtle) playback spiral.cmd
360
Current position is 0 0
364
Current heading is 180
367
Thank you for using Turtle
added
removed
Doc/library/cmd.rst
