Mercurial > python-cmd2
annotate README.txt @ 36:f472921d6189
fixing split arg, AND cleaning up accidental merge mess
author | catherine@localhost |
---|---|
date | Mon, 19 May 2008 13:56:00 -0400 |
parents | 1899088dd95d |
children | a791d615545c |
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 | |
9 - Special-character shortcut commands (beyond cmd's "@" and "!") | |
10 - Settable environment parameters | |
11 - Parsing commands with flags | |
12 | |
13 Instructions for implementing each feature follow. | |
14 | |
15 - Searchable command history | |
16 | |
17 All commands will automatically be tracked in the session's history, unless the command is listed in Cmd's excludeFromHistory attribute. | |
18 The history is accessed through the `history`, `list`, and `run` commands | |
19 (and their abbreviations: `hi`, `li`, `l`, `r`). | |
20 If you wish to exclude some of your custom commands from the history, append their names | |
21 to the list at Cmd.ExcludeFromHistory. | |
22 | |
23 - Load commands from file, save to file, edit commands in file | |
24 | |
25 Type `help load`, `help save`, `help edit` for details. | |
26 | |
27 - Multi-line commands | |
28 | |
29 Any command accepts multi-line input when its name is listed in `Cmd.multilineCommands`. | |
30 The program will keep expecting input until a line ends with any of the characters | |
31 in `Cmd.terminators` . The default terminators are `;` and `/n` (empty newline). | |
32 | |
33 - Case-insensitive commands | |
34 | |
35 All commands are case-insensitive, unless `Cmd.caseInsensitive` is set to `False`. | |
36 | |
37 - Special-character shortcut commands (beyond cmd's "@" and "!") | |
38 | |
39 To create a single-character shortcut for a command, update `Cmd.shortcuts`. | |
40 | |
41 - Settable environment parameters | |
42 | |
43 To allow a user to change an environment parameter during program execution, | |
44 append the parameter's name to `Cmd.settable`. | |
45 | |
13 | 46 - Parsing commands with `optparse` options (flags) |
6 | 47 |
13 | 48 :: |
49 | |
17 | 50 @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
|
51 def do_myfunc(self, arg, opts): |
18
b7489d3f838e
more readme correction, now in function def
catherine@localhost
parents:
17
diff
changeset
|
52 if opts.myoption: |
b7489d3f838e
more readme correction, now in function def
catherine@localhost
parents:
17
diff
changeset
|
53 ... |
13 | 54 |
55 See Python standard library's `optparse` documentation: http://docs.python.org/lib/optparse-defining-options.html | |
56 | |
18
b7489d3f838e
more readme correction, now in function def
catherine@localhost
parents:
17
diff
changeset
|
57 - Catherine Devlin, http://catherinedevlin.blogspot.com |
6 | 58 |
59 cmd2 can be installed with `easy_install cmd2` | |
60 | |
16 | 61 Cheese Shop page: http://pypi.python.org/pypi/cmd2 |
6 | 62 |
63 Example cmd2 application (cmd2_example.py) :: | |
64 | |
13 | 65 from cmd2 import Cmd, make_option, options |
66 | |
6 | 67 class CmdLineApp(Cmd): |
68 multilineCommands = ['orate'] | |
69 Cmd.shortcuts.update({'&': 'speak'}) | |
70 maxrepeats = 3 | |
13 | 71 Cmd.settable.append('maxrepeats') |
72 | |
73 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), | |
74 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), | |
75 make_option('-r', '--repeat', type="int", help="output [n] times") | |
76 ]) | |
77 def do_speak(self, arg, opts=None): | |
78 """Repeats what you tell me to.""" | |
79 arg = ' '.join(arg) | |
80 if opts.piglatin: | |
6 | 81 arg = '%s%say' % (arg[1:], arg[0]) |
13 | 82 if opts.shout: |
6 | 83 arg = arg.upper() |
13 | 84 repetitions = opts.repeat or 1 |
6 | 85 for i in range(min(repetitions, self.maxrepeats)): |
86 self.stdout.write(arg) | |
87 self.stdout.write('\n') | |
88 # self.stdout.write is better than "print", because Cmd can be | |
89 # initialized with a non-standard output destination | |
13 | 90 |
6 | 91 do_say = do_speak # now "say" is a synonym for "speak" |
92 do_orate = do_speak # another synonym, but this one takes multi-line input | |
13 | 93 |
6 | 94 app = CmdLineApp() |
95 app.cmdloop() | |
96 | |
97 Sample session using the above code :: | |
98 | |
99 c:\cmd2>python cmd2_example.py | |
100 (Cmd) speak softly | |
101 softly | |
102 (Cmd) speak --piglatin softly | |
103 oftlysay | |
104 (Cmd) speak -psr 2 softly | |
105 OFTLYSAY | |
106 OFTLYSAY | |
107 (Cmd) speak --repeat 1000000 softly | |
108 softly | |
109 softly | |
110 softly | |
111 (Cmd) show maxrepeats | |
112 maxrepeats: 3 | |
113 (Cmd) set maxrepeats 5 | |
114 maxrepeats - was: 3 | |
115 now: 5 | |
116 (Cmd) speak --repeat 1000000 softly | |
117 softly | |
118 softly | |
119 softly | |
120 softly | |
121 softly | |
122 (Cmd) orate blah blah | |
123 > blah | |
124 > and furthermore | |
125 > blah | |
126 > | |
127 blah blah blah and furthermore blah | |
128 (Cmd) &greetings | |
129 greetings | |
130 (Cmd) history | |
131 -------------------------[1] | |
132 speak softly | |
133 -------------------------[2] | |
134 speak --piglatin softly | |
135 -------------------------[3] | |
136 speak -psr 2 softly | |
137 -------------------------[4] | |
138 speak --repeat 1000000 softly | |
139 -------------------------[5] | |
140 show maxrepeats | |
141 -------------------------[6] | |
142 set maxrepeats 5 | |
143 -------------------------[7] | |
144 speak --repeat 1000000 softly | |
145 -------------------------[8] | |
146 orate blah blah | |
147 blah | |
148 and furthermore | |
149 blah | |
150 | |
151 -------------------------[9] | |
152 &greetings | |
153 (Cmd) run | |
154 orate blah blah | |
155 blah | |
156 and furthermore | |
157 blah | |
158 | |
159 blah blah blah and furthermore blah | |
160 (Cmd) run 3 | |
161 speak -psr 2 softly | |
162 OFTLYSAY | |
163 OFTLYSAY | |
164 (Cmd) history maxrepeats | |
165 -------------------------[5] | |
166 set maxrepeats | |
167 -------------------------[6] | |
168 set maxrepeats 5 | |
169 (Cmd) |