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