|
1 |
|
2 :mod:`cmd` --- Support for line-oriented command interpreters |
|
3 ============================================================= |
|
4 |
|
5 .. module:: cmd |
|
6 :synopsis: Build line-oriented command interpreters. |
|
7 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com> |
|
8 |
|
9 |
|
10 The :class:`Cmd` class provides a simple framework for writing line-oriented |
|
11 command interpreters. These are often useful for test harnesses, administrative |
|
12 tools, and prototypes that will later be wrapped in a more sophisticated |
|
13 interface. |
|
14 |
|
15 |
|
16 .. class:: Cmd([completekey[, stdin[, stdout]]]) |
|
17 |
|
18 A :class:`Cmd` instance or subclass instance is a line-oriented interpreter |
|
19 framework. There is no good reason to instantiate :class:`Cmd` itself; rather, |
|
20 it's useful as a superclass of an interpreter class you define yourself in order |
|
21 to inherit :class:`Cmd`'s methods and encapsulate action methods. |
|
22 |
|
23 The optional argument *completekey* is the :mod:`readline` name of a completion |
|
24 key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and |
|
25 :mod:`readline` is available, command completion is done automatically. |
|
26 |
|
27 The optional arguments *stdin* and *stdout* specify the input and output file |
|
28 objects that the Cmd instance or subclass instance will use for input and |
|
29 output. If not specified, they will default to :data:`sys.stdin` and |
|
30 :data:`sys.stdout`. |
|
31 |
|
32 If you want a given *stdin* to be used, make sure to set the instance's |
|
33 :attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be |
|
34 ignored. |
|
35 |
|
36 .. versionchanged:: 2.3 |
|
37 The *stdin* and *stdout* parameters were added. |
|
38 |
|
39 |
|
40 .. _cmd-objects: |
|
41 |
|
42 Cmd Objects |
|
43 ----------- |
|
44 |
|
45 A :class:`Cmd` instance has the following methods: |
|
46 |
|
47 |
|
48 .. method:: Cmd.cmdloop([intro]) |
|
49 |
|
50 Repeatedly issue a prompt, accept input, parse an initial prefix off the |
|
51 received input, and dispatch to action methods, passing them the remainder of |
|
52 the line as argument. |
|
53 |
|
54 The optional argument is a banner or intro string to be issued before the first |
|
55 prompt (this overrides the :attr:`intro` class member). |
|
56 |
|
57 If the :mod:`readline` module is loaded, input will automatically inherit |
|
58 :program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back |
|
59 to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F` |
|
60 moves the cursor to the right non-destructively, :kbd:`Control-B` moves the |
|
61 cursor to the left non-destructively, etc.). |
|
62 |
|
63 An end-of-file on input is passed back as the string ``'EOF'``. |
|
64 |
|
65 An interpreter instance will recognize a command name ``foo`` if and only if it |
|
66 has a method :meth:`do_foo`. As a special case, a line beginning with the |
|
67 character ``'?'`` is dispatched to the method :meth:`do_help`. As another |
|
68 special case, a line beginning with the character ``'!'`` is dispatched to the |
|
69 method :meth:`do_shell` (if such a method is defined). |
|
70 |
|
71 This method will return when the :meth:`postcmd` method returns a true value. |
|
72 The *stop* argument to :meth:`postcmd` is the return value from the command's |
|
73 corresponding :meth:`do_\*` method. |
|
74 |
|
75 If completion is enabled, completing commands will be done automatically, and |
|
76 completing of commands args is done by calling :meth:`complete_foo` with |
|
77 arguments *text*, *line*, *begidx*, and *endidx*. *text* is the string prefix |
|
78 we are attempting to match: all returned matches must begin with it. *line* is |
|
79 the current input line with leading whitespace removed, *begidx* and *endidx* |
|
80 are the beginning and ending indexes of the prefix text, which could be used to |
|
81 provide different completion depending upon which position the argument is in. |
|
82 |
|
83 All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`. This |
|
84 method, called with an argument ``'bar'``, invokes the corresponding method |
|
85 :meth:`help_bar`. With no argument, :meth:`do_help` lists all available help |
|
86 topics (that is, all commands with corresponding :meth:`help_\*` methods), and |
|
87 also lists any undocumented commands. |
|
88 |
|
89 |
|
90 .. method:: Cmd.onecmd(str) |
|
91 |
|
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. |
|
99 |
|
100 |
|
101 .. method:: Cmd.emptyline() |
|
102 |
|
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. |
|
105 |
|
106 |
|
107 .. method:: Cmd.default(line) |
|
108 |
|
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. |
|
111 |
|
112 |
|
113 .. method:: Cmd.completedefault(text, line, begidx, endidx) |
|
114 |
|
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. |
|
117 |
|
118 |
|
119 .. method:: Cmd.precmd(line) |
|
120 |
|
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* |
|
126 unchanged. |
|
127 |
|
128 |
|
129 .. method:: Cmd.postcmd(stop, line) |
|
130 |
|
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. |
|
138 |
|
139 |
|
140 .. method:: Cmd.preloop() |
|
141 |
|
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. |
|
144 |
|
145 |
|
146 .. method:: Cmd.postloop() |
|
147 |
|
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. |
|
150 |
|
151 Instances of :class:`Cmd` subclasses have some public instance variables: |
|
152 |
|
153 |
|
154 .. attribute:: Cmd.prompt |
|
155 |
|
156 The prompt issued to solicit input. |
|
157 |
|
158 |
|
159 .. attribute:: Cmd.identchars |
|
160 |
|
161 The string of characters accepted for the command prefix. |
|
162 |
|
163 |
|
164 .. attribute:: Cmd.lastcmd |
|
165 |
|
166 The last nonempty command prefix seen. |
|
167 |
|
168 |
|
169 .. attribute:: Cmd.intro |
|
170 |
|
171 A string to issue as an intro or banner. May be overridden by giving the |
|
172 :meth:`cmdloop` method an argument. |
|
173 |
|
174 |
|
175 .. attribute:: Cmd.doc_header |
|
176 |
|
177 The header to issue if the help output has a section for documented commands. |
|
178 |
|
179 |
|
180 .. attribute:: Cmd.misc_header |
|
181 |
|
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). |
|
185 |
|
186 |
|
187 .. attribute:: Cmd.undoc_header |
|
188 |
|
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_\*` |
|
191 methods). |
|
192 |
|
193 |
|
194 .. attribute:: Cmd.ruler |
|
195 |
|
196 The character used to draw separator lines under the help-message headers. If |
|
197 empty, no ruler line is drawn. It defaults to ``'='``. |
|
198 |
|
199 |
|
200 .. attribute:: Cmd.use_rawinput |
|
201 |
|
202 A flag, defaulting to true. If true, :meth:`cmdloop` uses :func:`raw_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.) |
|
207 |