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