annotate docs/freefeatures.rst @ 438:a5f3d5a89d6c tip

pyparsing 2.0.0 only if on Python3
author Catherine Devlin <catherine.devlin@gmail.com>
date Tue, 19 Feb 2013 04:33:12 -0500
parents bfbe4241bd6b
children
rev   line source
314
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
1 ===================================
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
2 Features requiring no modifications
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
3 ===================================
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
4
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
5 These features are provided "for free" to a cmd_-based application
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
6 simply by replacing ``import cmd`` with ``import cmd2 as cmd``.
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
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
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
10 Script files
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
11 ============
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
12
331
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
13 Text files can serve as scripts for your ``cmd2``-based
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
14 application, with the ``load``, ``save``, and ``edit``
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
15 commands.
315
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
16
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
17 .. automethod:: cmd2.Cmd.do_load
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
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
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
21 .. automethod:: cmd2.Cmd.do_edit
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
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
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
49 Commands at invocation
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
50 ======================
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
51
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
52 You can send commands to your app as you invoke it by
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
53 including them as extra arguments to the program.
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
54 ``cmd2`` interprets each argument as a separate
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
55 command, so you should enclose each command in
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
56 quotation marks if it is more than a one-word command.
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
57
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
58 ::
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
59
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
60 cat@eee:~/proj/cmd2/example$ python example.py "say hello" "say Gracie" quit
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
61 hello
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
62 Gracie
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
63 cat@eee:~/proj/cmd2/example$
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
64
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
65
315
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
66 Output redirection
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
67 ==================
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
68
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
69 As in a Unix shell, output of a command can be redirected:
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
70
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
71 - sent to a file with ``>``, as in ``mycommand args > filename.txt``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
72 - piped (``|``) as input to operating-system commands, as in
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
73 ``mycommand args | wc``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
74 - sent to the paste buffer, ready for the next Copy operation, by
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
75 ending with a bare ``>``, as in ``mycommand args >``.. Redirecting
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
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
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
78
435
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
79 If your application depends on mathematical syntax, ``>`` may be a bad
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
80 choice for redirecting output - it will prevent you from using the
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
81 greater-than sign in your actual user commands. You can override your
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
82 app's value of ``self.redirector`` to use a different string for output redirection::
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
83
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
84 class MyApp(cmd2.Cmd):
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
85 redirector = '->'
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
86
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
87 ::
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
88
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
89 (Cmd) say line1 -> out.txt
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
90 (Cmd) say line2 ->-> out.txt
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
91 (Cmd) !cat out.txt
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
92 line1
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
93 line2
bfbe4241bd6b custom double-redirector fixed
catherine.devlin@gmail.com
parents: 396
diff changeset
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
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
97
315
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
98 Python
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
99 ======
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
100
328
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
101 The ``py`` command will run its arguments as a Python
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
102 command. Entered without arguments, it enters an
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
103 interactive Python session. That session can call
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
104 "back" to your application with ``cmd("")``. Through
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
105 ``self``, it also has access to your application
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
106 instance itself. (If that thought terrifies you,
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
107 you can set the ``locals_in_py`` parameter to ``False``.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
108 See see :ref:`parameters`)
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
109
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
110 ::
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
111
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
112 (Cmd) py print("-".join("spelling"))
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
113 s-p-e-l-l-i-n-g
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
114 (Cmd) py
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
115 Python 2.6.4 (r264:75706, Dec 7 2009, 18:45:15)
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
116 [GCC 4.4.1] on linux2
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
117 Type "help", "copyright", "credits" or "license" for more information.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
118 (CmdLineApp)
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
119
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
120 py <command>: Executes a Python command.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
121 py: Enters interactive Python mode.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
122 End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, 'exit()`.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
123 Non-python commands can be issued with `cmd("your command")`.
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
124
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
125 >>> import os
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
126 >>> os.uname()
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
127 ('Linux', 'eee', '2.6.31-19-generic', '#56-Ubuntu SMP Thu Jan 28 01:26:53 UTC 2010', 'i686')
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
128 >>> cmd("say --piglatin {os}".format(os=os.uname()[0]))
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
129 inuxLay
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
130 >>> self.prompt
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
131 '(Cmd) '
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
132 >>> self.prompt = 'Python was here > '
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
133 >>> quit()
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
134 Python was here >
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
135
314
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
136 Searchable command history
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
137 ==========================
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
138
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
139 All cmd_-based applications have access to previous commands with
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
140 the up- and down- cursor keys.
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
141
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
142 All cmd_-based applications on systems with the ``readline`` module
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
143 also provide `bash-like history list editing`_.
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
144
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
145 .. _`bash-like history list editing`: http://www.talug.org/events/20030709/cmdline_history.html
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
146
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
147 ``cmd2`` makes a third type of history access available, consisting of these commands:
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
148
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
149 .. automethod:: cmd2.Cmd.do_history
0687bb650118 begin new docs
catherine@dellzilla
parents:
diff changeset
150
329
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
151 .. automethod:: cmd2.Cmd.do_list
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
152
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
153 .. automethod:: cmd2.Cmd.do_run
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
154
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
155 Quitting the application
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
156 ========================
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
157
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
158 ``cmd2`` pre-defines a ``quit`` command for you (with
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
159 synonyms ``exit`` and simply ``q``).
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
160 It's trivial, but it's one less thing for you to remember.
c69ad8418d39 free function docs
cat@eee
parents: 328
diff changeset
161
331
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
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
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
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
6306edc46a6e more docs
cat@eee
parents: 329
diff changeset
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
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
175 Misc. pre-defined commands
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
176 ==========================
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
177
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
178 Several generically useful commands are defined
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
179 with automatically included ``do_`` methods.
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
180
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
181 .. automethod:: cmd2.Cmd.do_quit
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
182
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
183 .. automethod:: cmd2.Cmd.do_pause
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
184
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
185 .. automethod:: cmd2.Cmd.do_shell
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
186
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
187 ( ``!`` is a shortcut for ``shell``; thus ``!ls``
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
188 is equivalent to ``shell ls``.)
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
189
49bea7cab179 doc refreshing refresh.bash
cat@eee
parents: 331
diff changeset
190
315
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
191 Transcript-based testing
a08c50b7d3d3 doc skeleton
cat@eee
parents: 314
diff changeset
192 ========================
345
6fe1e75e3a67 transcript test wasn't running pre and post cmd hooks
catherine@Drou
parents: 332
diff changeset
193
346
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
194 If the entire transcript (input and output) of a successful session of
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
195 a ``cmd2``-based app is copied from the screen and pasted into a text
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
196 file, ``transcript.txt``, then a transcript test can be run against it::
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
197
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
198 python app.py --test transcript.txt
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
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
49dd1ce6cfd6 quitting after invocation commands
catherine@Drou
parents: 345
diff changeset
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