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 .. seealso::
  16
  17    Latest version of the `cmd module Python source code
  18    <http://svn.python.org/view/python/branches/release27-maint/Lib/cmd.py?view=markup>`_
  19
  20 .. class:: Cmd([completekey[, stdin[, stdout]]])
  21
  22    A :class:`Cmd` instance or subclass instance is a line-oriented interpreter
  23    framework.  There is no good reason to instantiate :class:`Cmd` itself; rather,
  24    it's useful as a superclass of an interpreter class you define yourself in order
  25    to inherit :class:`Cmd`'s methods and encapsulate action methods.
  26
  27    The optional argument *completekey* is the :mod:`readline` name of a completion
  28    key; it defaults to :kbd:`Tab`. If *completekey* is not :const:`None` and
  29    :mod:`readline` is available, command completion is done automatically.
  30
  31    The optional arguments *stdin* and *stdout* specify the  input and output file
  32    objects that the Cmd instance or subclass  instance will use for input and
  33    output. If not specified, they will default to :data:`sys.stdin` and
  34    :data:`sys.stdout`.
  35
  36    If you want a given *stdin* to be used, make sure to set the instance's
  37    :attr:`use_rawinput` attribute to ``False``, otherwise *stdin* will be
  38    ignored.
  39
  40    .. versionchanged:: 2.3
  41       The *stdin* and *stdout* parameters were added.
  42
  43
  44 .. _cmd-objects:
  45
  46 Cmd Objects
  47 -----------
  48
  49 A :class:`Cmd` instance has the following methods:
  50
  51
  52 .. method:: Cmd.cmdloop([intro])
  53
  54    Repeatedly issue a prompt, accept input, parse an initial prefix off the
  55    received input, and dispatch to action methods, passing them the remainder of
  56    the line as argument.
  57
  58    The optional argument is a banner or intro string to be issued before the first
  59    prompt (this overrides the :attr:`intro` class member).
  60
  61    If the :mod:`readline` module is loaded, input will automatically inherit
  62    :program:`bash`\ -like history-list editing (e.g. :kbd:`Control-P` scrolls back
  63    to the last command, :kbd:`Control-N` forward to the next one, :kbd:`Control-F`
  64    moves the cursor to the right non-destructively, :kbd:`Control-B` moves the
  65    cursor to the left non-destructively, etc.).
  66
  67    An end-of-file on input is passed back as the string ``'EOF'``.
  68
  69    An interpreter instance will recognize a command name ``foo`` if and only if it
  70    has a method :meth:`do_foo`.  As a special case, a line beginning with the
  71    character ``'?'`` is dispatched to the method :meth:`do_help`.  As another
  72    special case, a line beginning with the character ``'!'`` is dispatched to the
  73    method :meth:`do_shell` (if such a method is defined).
  74
  75    This method will return when the :meth:`postcmd` method returns a true value.
  76    The *stop* argument to :meth:`postcmd` is the return value from the command's
  77    corresponding :meth:`do_\*` method.
  78
  79    If completion is enabled, completing commands will be done automatically, and
  80    completing of commands args is done by calling :meth:`complete_foo` with
  81    arguments *text*, *line*, *begidx*, and *endidx*.  *text* is the string prefix
  82    we are attempting to match: all returned matches must begin with it. *line* is
  83    the current input line with leading whitespace removed, *begidx* and *endidx*
  84    are the beginning and ending indexes of the prefix text, which could be used to
  85    provide different completion depending upon which position the argument is in.
  86
  87    All subclasses of :class:`Cmd` inherit a predefined :meth:`do_help`.  This
  88    method, called with an argument ``'bar'``, invokes the corresponding method
  89    :meth:`help_bar`, and if that is not present, prints the docstring of
  90    :meth:`do_bar`, if available.  With no argument, :meth:`do_help` lists all
  91    available help topics (that is, all commands with corresponding
  92    :meth:`help_\*` methods or commands that have docstrings), and also lists any
  93    undocumented commands.
  94
  95
  96 .. method:: Cmd.onecmd(str)
  97
  98    Interpret the argument as though it had been typed in response to the prompt.
  99    This may be overridden, but should not normally need to be; see the
 100    :meth:`precmd` and :meth:`postcmd` methods for useful execution hooks.  The
 101    return value is a flag indicating whether interpretation of commands by the
 102    interpreter should stop.  If there is a :meth:`do_\*` method for the command
 103    *str*, the return value of that method is returned, otherwise the return value
 104    from the :meth:`default` method is returned.
 105
 106
 107 .. method:: Cmd.emptyline()
 108
 109    Method called when an empty line is entered in response to the prompt. If this
 110    method is not overridden, it repeats the last nonempty command entered.
 111
 112
 113 .. method:: Cmd.default(line)
 114
 115    Method called on an input line when the command prefix is not recognized. If
 116    this method is not overridden, it prints an error message and returns.
 117
 118
 119 .. method:: Cmd.completedefault(text, line, begidx, endidx)
 120
 121    Method called to complete an input line when no command-specific
 122    :meth:`complete_\*` method is available.  By default, it returns an empty list.
 123
 124
 125 .. method:: Cmd.precmd(line)
 126
 127    Hook method executed just before the command line *line* is interpreted, but
 128    after the input prompt is generated and issued.  This method is a stub in
 129    :class:`Cmd`; it exists to be overridden by subclasses.  The return value is
 130    used as the command which will be executed by the :meth:`onecmd` method; the
 131    :meth:`precmd` implementation may re-write the command or simply return *line*
 132    unchanged.
 133
 134
 135 .. method:: Cmd.postcmd(stop, line)
 136
 137    Hook method executed just after a command dispatch is finished.  This method is
 138    a stub in :class:`Cmd`; it exists to be overridden by subclasses.  *line* is the
 139    command line which was executed, and *stop* is a flag which indicates whether
 140    execution will be terminated after the call to :meth:`postcmd`; this will be the
 141    return value of the :meth:`onecmd` method.  The return value of this method will
 142    be used as the new value for the internal flag which corresponds to *stop*;
 143    returning false will cause interpretation to continue.
 144
 145
 146 .. method:: Cmd.preloop()
 147
 148    Hook method executed once when :meth:`cmdloop` is called.  This method is a stub
 149    in :class:`Cmd`; it exists to be overridden by subclasses.
 150
 151
 152 .. method:: Cmd.postloop()
 153
 154    Hook method executed once when :meth:`cmdloop` is about to return. This method
 155    is a stub in :class:`Cmd`; it exists to be overridden by subclasses.
 156
 157 Instances of :class:`Cmd` subclasses have some public instance variables:
 158
 159
 160 .. attribute:: Cmd.prompt
 161
 162    The prompt issued to solicit input.
 163
 164
 165 .. attribute:: Cmd.identchars
 166
 167    The string of characters accepted for the command prefix.
 168
 169
 170 .. attribute:: Cmd.lastcmd
 171
 172    The last nonempty command prefix seen.
 173
 174
 175 .. attribute:: Cmd.intro
 176
 177    A string to issue as an intro or banner.  May be overridden by giving the
 178    :meth:`cmdloop` method an argument.
 179
 180
 181 .. attribute:: Cmd.doc_header
 182
 183    The header to issue if the help output has a section for documented commands.
 184
 185
 186 .. attribute:: Cmd.misc_header
 187
 188    The header to issue if the help output has a section for miscellaneous  help
 189    topics (that is, there are :meth:`help_\*` methods without corresponding
 190    :meth:`do_\*` methods).
 191
 192
 193 .. attribute:: Cmd.undoc_header
 194
 195    The header to issue if the help output has a section for undocumented  commands
 196    (that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
 197    methods).
 198
 199
 200 .. attribute:: Cmd.ruler
 201
 202    The character used to draw separator lines under the help-message headers.  If
 203    empty, no ruler line is drawn.  It defaults to ``'='``.
 204
 205
 206 .. attribute:: Cmd.use_rawinput
 207
 208    A flag, defaulting to true.  If true, :meth:`cmdloop` uses :func:`raw_input` to
 209    display a prompt and read the next command; if false, :meth:`sys.stdout.write`
 210    and :meth:`sys.stdin.readline` are used. (This means that by importing
 211    :mod:`readline`, on systems that support it, the interpreter will automatically
 212    support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
 213