2 :mod:`cmd` --- Support for line-oriented command interpreters
3 =============================================================
6 :synopsis: Build line-oriented command interpreters.
7 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
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
16 .. class:: Cmd([completekey[, stdin[, stdout]]])
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.
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.
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
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
36 .. versionchanged:: 2.3
37 The *stdin* and *stdout* parameters were added.
45 A :class:`Cmd` instance has the following methods:
48 .. method:: Cmd.cmdloop([intro])
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
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).
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.).
63 An end-of-file on input is passed back as the string ``'EOF'``.
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).
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.
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.
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.
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:`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.)