Doc/lib/libcmd.tex

   1 \section{\module{cmd} ---
   2          Support for line-oriented command interpreters}
   3
   4 \declaremodule{standard}{cmd}
   5 \sectionauthor{Eric S. Raymond}{esr@snark.thyrsus.com}
   6 \modulesynopsis{Build line-oriented command interpreters.}
   7
   8
   9 The \class{Cmd} class provides a simple framework for writing
  10 line-oriented command interpreters.  These are often useful for
  11 test harnesses, administrative tools, and prototypes that will
  12 later be wrapped in a more sophisticated interface.
  13
  14 \begin{classdesc}{Cmd}{\optional{completekey}}
  15 A \class{Cmd} instance or subclass instance is a line-oriented
  16 interpreter framework.  There is no good reason to instantiate
  17 \class{Cmd} itself; rather, it's useful as a superclass of an
  18 interpreter class you define yourself in order to inherit
  19 \class{Cmd}'s methods and encapsulate action methods.
  20
  21 The optional argument is the \refmodule{readline} name of a completion
  22 key; it defaults to \kbd{Tab}. If \var{completekey} is not \code{None}
  23 and \module{readline} is available, command completion is done
  24 automatically.
  25 \end{classdesc}
  26
  27 \subsection{Cmd Objects}
  28 \label{Cmd-objects}
  29
  30 A \class{Cmd} instance has the following methods:
  31
  32 \begin{methoddesc}{cmdloop}{\optional{intro}}
  33 Repeatedly issue a prompt, accept input, parse an initial prefix off
  34 the received input, and dispatch to action methods, passing them the
  35 remainder of the line as argument.
  36
  37 The optional argument is a banner or intro string to be issued before the
  38 first prompt (this overrides the \member{intro} class member).
  39
  40 If the \module{readline} module is loaded, input will automatically
  41 inherit \program{bash}-like history-list editing (e.g. \kbd{Control-P}
  42 scrolls back to the last command, \kbd{Control-N} forward to the next
  43 one, \kbd{Control-F} moves the cursor to the right non-destructively,
  44 \kbd{Control-B} moves the cursor to the left non-destructively, etc.).
  45
  46 An end-of-file on input is passed back as the string \code{'EOF'}.
  47
  48 An interpreter instance will recognize a command name \samp{foo} if
  49 and only if it has a method \method{do_foo()}.  As a special case,
  50 a line beginning with the character \character{?} is dispatched to
  51 the method \method{do_help()}.  As another special case, a line
  52 beginning with the character \character{!} is dispatched to the
  53 method \method{do_shell()} (if such a method is defined).
  54
  55 If completion is enabled, completing commands will be done
  56 automatically, and completing of commands args is done by calling
  57 \method{complete_foo()} with arguments \var{text}, \var{line},
  58 \var{begidx}, and \var{endidx}.  \var{text} is the string prefix we
  59 are attempting to match: all returned matches must begin with it.
  60 \var{line} is the current input line with leading whitespace removed,
  61 \var{begidx} and \var{endidx} are the beginning and ending indexes
  62 of the prefix text, which could be used to provide different
  63 completion depending upon which position the argument is in.
  64
  65 All subclasses of \class{Cmd} inherit a predefined \method{do_help()}.
  66 This method, called with an argument \code{'bar'}, invokes the
  67 corresponding method \method{help_bar()}.  With no argument,
  68 \method{do_help()} lists all available help topics (that is, all
  69 commands with corresponding \method{help_*()} methods), and also lists
  70 any undocumented commands.
  71 \end{methoddesc}
  72
  73 \begin{methoddesc}{onecmd}{str}
  74 Interpret the argument as though it had been typed in response to the
  75 prompt.  This may be overridden, but should not normally need to be;
  76 see the \method{precmd()} and \method{postcmd()} methods for useful
  77 execution hooks.  The return value is a flag indicating whether
  78 interpretation of commands by the interpreter should stop.
  79 \end{methoddesc}
  80
  81 \begin{methoddesc}{emptyline}{}
  82 Method called when an empty line is entered in response to the prompt.
  83 If this method is not overridden, it repeats the last nonempty command
  84 entered.
  85 \end{methoddesc}
  86
  87 \begin{methoddesc}{default}{line}
  88 Method called on an input line when the command prefix is not
  89 recognized. If this method is not overridden, it prints an
  90 error message and returns.
  91 \end{methoddesc}
  92
  93 \begin{methoddesc}{completedefault}{text, line, begidx, endidx}
  94 Method called to complete an input line when no command-specific
  95 \method{complete_*()} method is available.  By default, it returns an
  96 empty list.
  97 \end{methoddesc}
  98
  99 \begin{methoddesc}{precmd}{line}
 100 Hook method executed just before the command line \var{line} is
 101 interpreted, but after the input prompt is generated and issued.  This
 102 method is a stub in \class{Cmd}; it exists to be overridden by
 103 subclasses.  The return value is used as the command which will be
 104 executed by the \method{onecmd()} method; the \method{precmd()}
 105 implementation may re-write the command or simply return \var{line}
 106 unchanged.
 107 \end{methoddesc}
 108
 109 \begin{methoddesc}{postcmd}{stop, line}
 110 Hook method executed just after a command dispatch is finished.  This
 111 method is a stub in \class{Cmd}; it exists to be overridden by
 112 subclasses.  \var{line} is the command line which was executed, and
 113 \var{stop} is a flag which indicates whether execution will be
 114 terminated after the call to \method{postcmd()}; this will be the
 115 return value of the \method{onecmd()} method.  The return value of
 116 this method will be used as the new value for the internal flag which
 117 corresponds to \var{stop}; returning false will cause interpretation
 118 to continue.
 119 \end{methoddesc}
 120
 121 \begin{methoddesc}{preloop}{}
 122 Hook method executed once when \method{cmdloop()} is called.  This
 123 method is a stub in \class{Cmd}; it exists to be overridden by
 124 subclasses.
 125 \end{methoddesc}
 126
 127 \begin{methoddesc}{postloop}{}
 128 Hook method executed once when \method{cmdloop()} is about to return.
 129 This method is a stub in \class{Cmd}; it exists to be overridden by
 130 subclasses.
 131 \end{methoddesc}
 132
 133 Instances of \class{Cmd} subclasses have some public instance variables:
 134
 135 \begin{memberdesc}{prompt}
 136 The prompt issued to solicit input.
 137 \end{memberdesc}
 138
 139 \begin{memberdesc}{identchars}
 140 The string of characters accepted for the command prefix.
 141 \end{memberdesc}
 142
 143 \begin{memberdesc}{lastcmd}
 144 The last nonempty command prefix seen.
 145 \end{memberdesc}
 146
 147 \begin{memberdesc}{intro}
 148 A string to issue as an intro or banner.  May be overridden by giving
 149 the \method{cmdloop()} method an argument.
 150 \end{memberdesc}
 151
 152 \begin{memberdesc}{doc_header}
 153 The header to issue if the help output has a section for documented
 154 commands.
 155 \end{memberdesc}
 156
 157 \begin{memberdesc}{misc_header}
 158 The header to issue if the help output has a section for miscellaneous
 159 help topics (that is, there are \method{help_*()} methods without
 160 corresponding \method{do_*()} methods).
 161 \end{memberdesc}
 162
 163 \begin{memberdesc}{undoc_header}
 164 The header to issue if the help output has a section for undocumented
 165 commands (that is, there are \method{do_*()} methods without
 166 corresponding \method{help_*()} methods).
 167 \end{memberdesc}
 168
 169 \begin{memberdesc}{ruler}
 170 The character used to draw separator lines under the help-message
 171 headers.  If empty, no ruler line is drawn.  It defaults to
 172 \character{=}.
 173 \end{memberdesc}
 174
 175 \begin{memberdesc}{use_rawinput}
 176 A flag, defaulting to true.  If true, \method{cmdloop()} uses
 177 \function{raw_input()} to display a prompt and read the next command;
 178 if false, \method{sys.stdout.write()} and
 179 \method{sys.stdin.readline()} are used. (This means that by
 180 importing \module{readline}, on systems that support it, the
 181 interpreter will automatically support Emacs-like line editing
 182 and command-history keystrokes.)
 183 \end{memberdesc}