← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/cmd.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/cmd.rst
 
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