Mercurial > python-cmd2
annotate README.txt @ 337:2ce34ad4e520
begin Pycon talk
author | catherine@Drou |
---|---|
date | Tue, 16 Feb 2010 11:02:56 -0500 |
parents | 403e1c3ffc4a |
children |
rev | line source |
---|---|
116
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
1 ---- |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
2 cmd2 |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
3 ---- |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
4 |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
5 :Author: Catherine Devlin, http://catherinedevlin.blogspot.com |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
6 |
6 | 7 `cmd2` is a tool for writing command-line interactive applications. It is based on the Python Standard Library's `cmd` module, and can be used anyplace `cmd` is used simply by importing `cmd2` instead. |
8 | |
9 `cmd2` provides the following features, in addition to those already existing in `cmd`: | |
10 | |
11 - Searchable command history | |
12 - Load commands from file, save to file, edit commands in file | |
13 - Multi-line commands | |
14 - Case-insensitive commands | |
54 | 15 - Special-character shortcut commands (beyond cmd's `@` and `!`) |
6 | 16 - Settable environment parameters |
17 - Parsing commands with flags | |
54 | 18 - Redirection to file with `>`, `>>`; input from file with `<` |
19 - Bare '>', '>>' with no filename send output to paste buffer | |
20 - Pipe output to shell commands with `|` | |
116
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
21 - Simple transcript-based application testing |
6 | 22 |
23 Instructions for implementing each feature follow. | |
24 | |
25 - Searchable command history | |
26 | |
27 All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's excludeFromHistory attribute. | |
28 The history is accessed through the `history`, `list`, and `run` commands | |
29 (and their abbreviations: `hi`, `li`, `l`, `r`). | |
30 If you wish to exclude some of your custom commands from the history, append their names | |
31 to the list at Cmd.ExcludeFromHistory. | |
32 | |
33 - Load commands from file, save to file, edit commands in file | |
34 | |
35 Type `help load`, `help save`, `help edit` for details. | |
36 | |
37 - Multi-line commands | |
38 | |
39 Any command accepts multi-line input when its name is listed in `Cmd.multilineCommands`. | |
40 The program will keep expecting input until a line ends with any of the characters | |
41 in `Cmd.terminators` . The default terminators are `;` and `/n` (empty newline). | |
42 | |
43 - Case-insensitive commands | |
44 | |
45 All commands are case-insensitive, unless `Cmd.caseInsensitive` is set to `False`. | |
46 | |
47 - Special-character shortcut commands (beyond cmd's "@" and "!") | |
48 | |
49 To create a single-character shortcut for a command, update `Cmd.shortcuts`. | |
50 | |
51 - Settable environment parameters | |
52 | |
53 To allow a user to change an environment parameter during program execution, | |
54 append the parameter's name to `Cmd.settable`. | |
55 | |
13 | 56 - Parsing commands with `optparse` options (flags) |
6 | 57 |
13 | 58 :: |
59 | |
17 | 60 @options([make_option('-m', '--myoption', action="store_true", help="all about my option")]) |
19
1899088dd95d
more readme correction, now in function def
catherine@localhost
parents:
18
diff
changeset
|
61 def do_myfunc(self, arg, opts): |
18
b7489d3f838e
more readme correction, now in function def
catherine@localhost
parents:
17
diff
changeset
|
62 if opts.myoption: |
b7489d3f838e
more readme correction, now in function def
catherine@localhost
parents:
17
diff
changeset
|
63 ... |
13 | 64 |
65 See Python standard library's `optparse` documentation: http://docs.python.org/lib/optparse-defining-options.html | |
66 | |
6 | 67 cmd2 can be installed with `easy_install cmd2` |
68 | |
16 | 69 Cheese Shop page: http://pypi.python.org/pypi/cmd2 |
6 | 70 |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
71 Example cmd2 application (example/example.py) :: |
6 | 72 |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
73 '''A sample application for cmd2.''' |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
74 |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
75 from cmd2 import Cmd, make_option, options, Cmd2TestCase |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
76 import unittest, optparse, sys |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
77 |
6 | 78 class CmdLineApp(Cmd): |
79 multilineCommands = ['orate'] | |
80 Cmd.shortcuts.update({'&': 'speak'}) | |
81 maxrepeats = 3 | |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
82 Cmd.settable.append('maxrepeats') |
13 | 83 |
84 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), | |
85 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), | |
86 make_option('-r', '--repeat', type="int", help="output [n] times") | |
87 ]) | |
88 def do_speak(self, arg, opts=None): | |
89 """Repeats what you tell me to.""" | |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
90 arg = ''.join(arg) |
13 | 91 if opts.piglatin: |
6 | 92 arg = '%s%say' % (arg[1:], arg[0]) |
13 | 93 if opts.shout: |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
94 arg = arg.upper() |
13 | 95 repetitions = opts.repeat or 1 |
6 | 96 for i in range(min(repetitions, self.maxrepeats)): |
97 self.stdout.write(arg) | |
98 self.stdout.write('\n') | |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
99 # self.stdout.write is better than "print", because Cmd can be |
6 | 100 # initialized with a non-standard output destination |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
101 |
6 | 102 do_say = do_speak # now "say" is a synonym for "speak" |
103 do_orate = do_speak # another synonym, but this one takes multi-line input | |
13 | 104 |
112
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
105 class TestMyAppCase(Cmd2TestCase): |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
106 CmdApp = CmdLineApp |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
107 transcriptFileName = 'exampleSession.txt' |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
108 |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
109 parser = optparse.OptionParser() |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
110 parser.add_option('-t', '--test', dest='unittests', action='store_true', default=False, help='Run unit test suite') |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
111 (callopts, callargs) = parser.parse_args() |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
112 if callopts.unittests: |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
113 sys.argv = [sys.argv[0]] # the --test argument upsets unittest.main() |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
114 unittest.main() |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
115 else: |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
116 app = CmdLineApp() |
e3b8eaadea56
going to collapse down out of overdone package structure
catherine@Elli.myhome.westell.com
parents:
110
diff
changeset
|
117 app.cmdloop() |
6 | 118 |
115 | 119 The following is a sample session running example.py. |
116
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
120 Thanks to `TestMyAppCase(Cmd2TestCase)`, it also serves as a test |
115 | 121 suite for example.py when saved as `exampleSession.txt`. |
122 Running `python example.py -t` will run all the commands in the | |
116
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
123 transcript against `example.py`, verifying that the output produced |
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
124 matches the transcript. |
115 | 125 |
116
06f5eba2f588
perfect, except testing multiline output
catherine@Elli.myhome.westell.com
parents:
115
diff
changeset
|
126 example/exampleSession.txt:: |
6 | 127 |
115 | 128 (Cmd) help |
129 | |
130 Documented commands (type help <topic>): | |
131 ======================================== | |
183
403e1c3ffc4a
changed order for blankline parsing
catherine@Elli.myhome.westell.com
parents:
119
diff
changeset
|
132 _load edit history li load pause run say shell show |
403e1c3ffc4a
changed order for blankline parsing
catherine@Elli.myhome.westell.com
parents:
119
diff
changeset
|
133 ed hi l list orate r save set shortcuts speak |
115 | 134 |
135 Undocumented commands: | |
136 ====================== | |
137 EOF cmdenvironment eof exit help q quit | |
183
403e1c3ffc4a
changed order for blankline parsing
catherine@Elli.myhome.westell.com
parents:
119
diff
changeset
|
138 |
115 | 139 (Cmd) help say |
140 Repeats what you tell me to. | |
141 Usage: speak [options] arg | |
142 | |
143 Options: | |
144 -h, --help show this help message and exit | |
145 -p, --piglatin atinLay | |
146 -s, --shout N00B EMULATION MODE | |
147 -r REPEAT, --repeat=REPEAT | |
148 output [n] times | |
149 | |
150 (Cmd) say goodnight, Gracie | |
151 goodnight, Gracie | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
152 (Cmd) say -ps --repeat=5 goodnight, Gracie |
115 | 153 OODNIGHT, GRACIEGAY |
154 OODNIGHT, GRACIEGAY | |
155 OODNIGHT, GRACIEGAY | |
156 (Cmd) set | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
157 prompt: (Cmd) |
115 | 158 editor: gedit |
159 echo: False | |
6 | 160 maxrepeats: 3 |
161 (Cmd) set maxrepeats 5 | |
162 maxrepeats - was: 3 | |
163 now: 5 | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
164 (Cmd) say -ps --repeat=5 goodnight, Gracie |
115 | 165 OODNIGHT, GRACIEGAY |
166 OODNIGHT, GRACIEGAY | |
167 OODNIGHT, GRACIEGAY | |
168 OODNIGHT, GRACIEGAY | |
169 OODNIGHT, GRACIEGAY | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
170 (Cmd) hi |
6 | 171 -------------------------[1] |
115 | 172 help |
6 | 173 -------------------------[2] |
115 | 174 help say |
6 | 175 -------------------------[3] |
115 | 176 say goodnight, Gracie |
6 | 177 -------------------------[4] |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
178 say -ps --repeat=5 goodnight, Gracie |
6 | 179 -------------------------[5] |
115 | 180 set |
6 | 181 -------------------------[6] |
182 set maxrepeats 5 | |
183 -------------------------[7] | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
184 say -ps --repeat=5 goodnight, Gracie |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
185 (Cmd) run 4 |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
186 say -ps --repeat=5 goodnight, Gracie |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
187 OODNIGHT, GRACIEGAY |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
188 OODNIGHT, GRACIEGAY |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
189 OODNIGHT, GRACIEGAY |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
190 OODNIGHT, GRACIEGAY |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
191 OODNIGHT, GRACIEGAY |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
192 (Cmd) orate Four score and |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
193 > seven releases ago |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
194 > our BDFL |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
195 > blah blah blah |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
196 > |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
197 > |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
198 Four score and seven releases ago our BDFL blah blah blah |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
199 (Cmd) & look, a shortcut! |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
200 look, a shortcut! |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
201 (Cmd) say put this in a file > myfile.txt |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
202 (Cmd) say < myfile.txt |
115 | 203 put this in a file |
204 (Cmd) set prompt "---> " | |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
205 prompt - was: (Cmd) |
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
206 now: ---> |
115 | 207 ---> say goodbye |
119
fe47c5b269cc
altering README to match exampleSession.txt
catherine@dellzilla
parents:
116
diff
changeset
|
208 goodbye |