45
by Dave Kuhlman
Updated docs |
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@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 |