Mercurial > python-cmd2
annotate docs/freefeatures.rst @ 437:9e0fd9da25c6
Added tag 0.6.4 for changeset c4c35f002aef
| author | catherine.devlin@gmail.com |
|---|---|
| date | Thu, 25 Aug 2011 16:27:53 -0400 |
| parents | bfbe4241bd6b |
| children |
| rev | line source |
|---|---|
| 314 | 1 =================================== |
| 2 Features requiring no modifications | |
| 3 =================================== | |
| 4 | |
| 5 These features are provided "for free" to a cmd_-based application | |
| 6 simply by replacing ``import cmd`` with ``import cmd2 as cmd``. | |
| 7 | |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
8 .. _cmd: http://docs.python.org/library/cmd.html#module-cmd |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
9 |
| 315 | 10 Script files |
| 11 ============ | |
| 12 | |
| 331 | 13 Text files can serve as scripts for your ``cmd2``-based |
| 14 application, with the ``load``, ``save``, and ``edit`` | |
| 15 commands. | |
| 315 | 16 |
| 17 .. automethod:: cmd2.Cmd.do_load | |
| 18 | |
|
325
4172feeddf76
want to incorporate run() for tests - not yet working
catherine@dellzilla
parents:
324
diff
changeset
|
19 .. automethod:: cmd2.Cmd.do_save |
|
4172feeddf76
want to incorporate run() for tests - not yet working
catherine@dellzilla
parents:
324
diff
changeset
|
20 |
| 331 | 21 .. automethod:: cmd2.Cmd.do_edit |
| 22 | |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
23 Comments |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
24 ======== |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
25 |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
26 Comments are omitted from the argument list |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
27 before it is passed to a ``do_`` method. By |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
28 default, both Python-style and C-style comments |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
29 are recognized; you may change this by overriding |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
30 ``app.commentGrammars`` with a different pyparsing_ |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
31 grammar. |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
32 |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
33 Comments can be useful in :ref:`scripts`. Used |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
34 in an interactive session, they may indicate |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
35 mental imbalance. |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
36 |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
37 :: |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
38 |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
39 def do_speak(self, arg): |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
40 self.stdout.write(arg + '\n') |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
41 |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
42 :: |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
43 |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
44 (Cmd) speak it was /* not */ delicious! # Yuck! |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
45 it was delicious! |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
46 |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
47 .. _pyparsing: http://pyparsing.wikispaces.com/ |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
48 |
| 346 | 49 Commands at invocation |
| 50 ====================== | |
| 51 | |
| 52 You can send commands to your app as you invoke it by | |
| 53 including them as extra arguments to the program. | |
| 54 ``cmd2`` interprets each argument as a separate | |
| 55 command, so you should enclose each command in | |
| 56 quotation marks if it is more than a one-word command. | |
| 57 | |
| 58 :: | |
| 59 | |
| 60 cat@eee:~/proj/cmd2/example$ python example.py "say hello" "say Gracie" quit | |
| 61 hello | |
| 62 Gracie | |
| 63 cat@eee:~/proj/cmd2/example$ | |
| 64 | |
| 65 | |
| 315 | 66 Output redirection |
| 67 ================== | |
| 68 | |
| 324 | 69 As in a Unix shell, output of a command can be redirected: |
| 70 | |
| 71 - sent to a file with ``>``, as in ``mycommand args > filename.txt`` | |
| 72 - piped (``|``) as input to operating-system commands, as in | |
| 73 ``mycommand args | wc`` | |
| 74 - sent to the paste buffer, ready for the next Copy operation, by | |
| 75 ending with a bare ``>``, as in ``mycommand args >``.. Redirecting | |
| 76 to paste buffer requires software to be installed on the operating | |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
77 system, pywin32_ on Windows or xclip_ on \*nix. |
| 324 | 78 |
| 435 | 79 If your application depends on mathematical syntax, ``>`` may be a bad |
| 80 choice for redirecting output - it will prevent you from using the | |
| 81 greater-than sign in your actual user commands. You can override your | |
| 82 app's value of ``self.redirector`` to use a different string for output redirection:: | |
| 83 | |
| 84 class MyApp(cmd2.Cmd): | |
| 85 redirector = '->' | |
| 86 | |
| 87 :: | |
| 88 | |
| 89 (Cmd) say line1 -> out.txt | |
| 90 (Cmd) say line2 ->-> out.txt | |
| 91 (Cmd) !cat out.txt | |
| 92 line1 | |
| 93 line2 | |
| 94 | |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
95 .. _pywin32: http://sourceforge.net/projects/pywin32/ |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
346
diff
changeset
|
96 .. _xclip: http://www.cyberciti.biz/faq/xclip-linux-insert-files-command-output-intoclipboard/ |
| 324 | 97 |
| 315 | 98 Python |
| 99 ====== | |
| 100 | |
| 328 | 101 The ``py`` command will run its arguments as a Python |
| 102 command. Entered without arguments, it enters an | |
| 103 interactive Python session. That session can call | |
| 104 "back" to your application with ``cmd("")``. Through | |
| 105 ``self``, it also has access to your application | |
| 106 instance itself. (If that thought terrifies you, | |
| 107 you can set the ``locals_in_py`` parameter to ``False``. | |
| 108 See see :ref:`parameters`) | |
| 109 | |
| 110 :: | |
| 111 | |
| 112 (Cmd) py print("-".join("spelling")) | |
| 113 s-p-e-l-l-i-n-g | |
| 114 (Cmd) py | |
| 115 Python 2.6.4 (r264:75706, Dec 7 2009, 18:45:15) | |
| 116 [GCC 4.4.1] on linux2 | |
| 117 Type "help", "copyright", "credits" or "license" for more information. | |
| 118 (CmdLineApp) | |
| 119 | |
| 120 py <command>: Executes a Python command. | |
| 121 py: Enters interactive Python mode. | |
| 122 End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, 'exit()`. | |
| 123 Non-python commands can be issued with `cmd("your command")`. | |
| 124 | |
| 125 >>> import os | |
| 126 >>> os.uname() | |
| 127 ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686') | |
| 128 >>> cmd("say --piglatin {os}".format(os=os.uname()[0])) | |
| 129 inuxLay | |
| 130 >>> self.prompt | |
| 131 '(Cmd) ' | |
| 132 >>> self.prompt = 'Python was here > ' | |
| 133 >>> quit() | |
| 134 Python was here > | |
| 135 | |
| 314 | 136 Searchable command history |
| 137 ========================== | |
| 138 | |
| 139 All cmd_-based applications have access to previous commands with | |
| 140 the up- and down- cursor keys. | |
| 141 | |
| 142 All cmd_-based applications on systems with the ``readline`` module | |
| 143 also provide `bash-like history list editing`_. | |
| 144 | |
| 145 .. _`bash-like history list editing`: http://www.talug.org/events/20030709/cmdline_history.html | |
| 146 | |
| 147 ``cmd2`` makes a third type of history access available, consisting of these commands: | |
| 148 | |
| 149 .. automethod:: cmd2.Cmd.do_history | |
| 150 | |
| 329 | 151 .. automethod:: cmd2.Cmd.do_list |
| 152 | |
| 153 .. automethod:: cmd2.Cmd.do_run | |
| 154 | |
| 155 Quitting the application | |
| 156 ======================== | |
| 157 | |
| 158 ``cmd2`` pre-defines a ``quit`` command for you (with | |
| 159 synonyms ``exit`` and simply ``q``). | |
| 160 It's trivial, but it's one less thing for you to remember. | |
| 161 | |
| 331 | 162 |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
163 Abbreviated commands |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
164 ==================== |
| 331 | 165 |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
166 ``cmd2`` apps will accept shortened command names |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
167 so long as there is no ambiguity. Thus, if |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
168 ``do_divide`` is defined, then ``divid``, ``div``, |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
169 or even ``d`` will suffice, so long as there are |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
170 no other commands defined beginning with *divid*, |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
171 *div*, or *d*. |
| 331 | 172 |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
173 This behavior can be turned off with ``app.abbrev`` (see :ref:`parameters`) |
|
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
174 |
| 332 | 175 Misc. pre-defined commands |
| 176 ========================== | |
| 177 | |
| 178 Several generically useful commands are defined | |
| 179 with automatically included ``do_`` methods. | |
| 180 | |
| 181 .. automethod:: cmd2.Cmd.do_quit | |
| 182 | |
| 183 .. automethod:: cmd2.Cmd.do_pause | |
| 184 | |
| 185 .. automethod:: cmd2.Cmd.do_shell | |
| 186 | |
| 187 ( ``!`` is a shortcut for ``shell``; thus ``!ls`` | |
| 188 is equivalent to ``shell ls``.) | |
| 189 | |
| 190 | |
| 315 | 191 Transcript-based testing |
| 192 ======================== | |
|
345
6fe1e75e3a67
transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents:
332
diff
changeset
|
193 |
| 346 | 194 If the entire transcript (input and output) of a successful session of |
| 195 a ``cmd2``-based app is copied from the screen and pasted into a text | |
| 196 file, ``transcript.txt``, then a transcript test can be run against it:: | |
| 197 | |
| 198 python app.py --test transcript.txt | |
| 199 | |
|
396
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
200 Any non-whitespace deviations between the output prescribed in ``transcript.txt`` and |
| 346 | 201 the actual output from a fresh run of the application will be reported |
|
396
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
202 as a unit test failure. (Whitespace is ignored during the comparison.) |
|
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
203 |
|
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
204 Regular expressions can be embedded in the transcript inside paired ``/`` |
|
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
205 slashes. These regular expressions should not include any whitespace |
|
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
206 expressions. |
|
e60e2c15f026
ignore whitespace during comparisons
Catherine Devlin <catherine.devlin@gmail.com>
parents:
388
diff
changeset
|
207 |