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