Doc/library/cmd.rst

   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 Instances of :class:`Cmd` subclasses have some public instance variables:
 155
 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.intro
 173
 174    A string to issue as an intro or banner.  May be overridden by giving the
 175    :meth:`cmdloop` method an argument.
 176
 177
 178 .. attribute:: Cmd.doc_header
 179
 180    The header to issue if the help output has a section for documented commands.
 181
 182
 183 .. attribute:: Cmd.misc_header
 184
 185    The header to issue if the help output has a section for miscellaneous  help
 186    topics (that is, there are :meth:`help_\*` methods without corresponding
 187    :meth:`do_\*` methods).
 188
 189
 190 .. attribute:: Cmd.undoc_header
 191
 192    The header to issue if the help output has a section for undocumented  commands
 193    (that is, there are :meth:`do_\*` methods without corresponding :meth:`help_\*`
 194    methods).
 195
 196
 197 .. attribute:: Cmd.ruler
 198
 199    The character used to draw separator lines under the help-message headers.  If
 200    empty, no ruler line is drawn.  It defaults to ``'='``.
 201
 202
 203 .. attribute:: Cmd.use_rawinput
 204
 205    A flag, defaulting to true.  If true, :meth:`cmdloop` uses :func:`raw_input` to
 206    display a prompt and read the next command; if false, :meth:`sys.stdout.write`
 207    and :meth:`sys.stdin.readline` are used. (This means that by importing
 208    :mod:`readline`, on systems that support it, the interpreter will automatically
 209    support :program:`Emacs`\ -like line editing  and command-history keystrokes.)
 210