|
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
|
|
|
46 - Parsing commands with flags
|
|
|
47
|
|
|
48 To allow a command to parse flags:
|
|
|
49
|
|
|
50 1. Create a flagset: `flags = flagReader.FlagSet([flagReader.Flag('option')])`
|
|
|
51 2. Within the command's function, `(opts, arg) = flags.parse(arg)`
|
|
|
52 3. `opts` is a dictionary whose keys are the flags given, and whose values
|
|
|
53 are the arguments to those flags (if any).
|
|
|
54
|
|
|
55 - Catherine Devlin, catherinedevlin.blogspot.com
|
|
|
56
|
|
|
57 cmd2 can be installed with `easy_install cmd2`
|
|
|
58
|
|
|
59 Cheese Shop page: http://pypi.python.org/pypi/cmd2/0.1
|
|
|
60
|
|
|
61 Example cmd2 application (cmd2_example.py) ::
|
|
|
62
|
|
10
|
63 from cmd2 import Cmd
|
|
|
64 import optparse
|
|
6
|
65
|
|
|
66 class CmdLineApp(Cmd):
|
|
|
67 multilineCommands = ['orate']
|
|
|
68 Cmd.shortcuts.update({'&': 'speak'})
|
|
|
69 maxrepeats = 3
|
|
|
70 Cmd.settable.append('maxrepeats')
|
|
|
71 speakflags = flagReader.FlagSet([flagReader.Flag('piglatin'),
|
|
|
72 flagReader.Flag('shout'),
|
|
|
73 flagReader.Flag('repeat', nargs=1)
|
|
|
74 ])
|
|
10
|
75 speakOptionParser = optparse.OptionParser()
|
|
|
76 speakOptionParser.add_option('-p', '--piglatin', action="store_true", help="atinLay")
|
|
|
77 speakOptionParser.add_option('-s', '--shout', action="store_true", help="output in ALL CAPS")
|
|
|
78 speakOptionParser.add_option('-r', '--repeat', type="int", help="output [n] times")
|
|
6
|
79 def do_speak(self, arg):
|
|
|
80 """Repeats what you tell me to.
|
|
|
81
|
|
|
82 args: --piglatin, -p: translate to Pig Latin
|
|
|
83 --shout, -s: emulate internet newbie
|
|
|
84 --repeat (nTimes), -r: be redundant"""
|
|
10
|
85 (options, arg) = speakOptionParser.parse_args(arg.split())
|
|
6
|
86
|
|
10
|
87 if options.piglatin:
|
|
6
|
88 arg = '%s%say' % (arg[1:], arg[0])
|
|
10
|
89 if options.shout:
|
|
6
|
90 arg = arg.upper()
|
|
10
|
91 repetitions = options.repeat or 1
|
|
6
|
92 for i in range(min(repetitions, self.maxrepeats)):
|
|
|
93 self.stdout.write(arg)
|
|
|
94 self.stdout.write('\n')
|
|
|
95 # self.stdout.write is better than "print", because Cmd can be
|
|
|
96 # initialized with a non-standard output destination
|
|
|
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
|
|
|
99
|
|
|
100 app = CmdLineApp()
|
|
|
101 app.cmdloop()
|
|
|
102
|
|
|
103 Sample session using the above code ::
|
|
|
104
|
|
|
105 c:\cmd2>python cmd2_example.py
|
|
|
106 (Cmd) speak softly
|
|
|
107 softly
|
|
|
108 (Cmd) speak --piglatin softly
|
|
|
109 oftlysay
|
|
|
110 (Cmd) speak -psr 2 softly
|
|
|
111 OFTLYSAY
|
|
|
112 OFTLYSAY
|
|
|
113 (Cmd) speak --repeat 1000000 softly
|
|
|
114 softly
|
|
|
115 softly
|
|
|
116 softly
|
|
|
117 (Cmd) show maxrepeats
|
|
|
118 maxrepeats: 3
|
|
|
119 (Cmd) set maxrepeats 5
|
|
|
120 maxrepeats - was: 3
|
|
|
121 now: 5
|
|
|
122 (Cmd) speak --repeat 1000000 softly
|
|
|
123 softly
|
|
|
124 softly
|
|
|
125 softly
|
|
|
126 softly
|
|
|
127 softly
|
|
|
128 (Cmd) orate blah blah
|
|
|
129 > blah
|
|
|
130 > and furthermore
|
|
|
131 > blah
|
|
|
132 >
|
|
|
133 blah blah blah and furthermore blah
|
|
|
134 (Cmd) &greetings
|
|
|
135 greetings
|
|
|
136 (Cmd) history
|
|
|
137 -------------------------[1]
|
|
|
138 speak softly
|
|
|
139 -------------------------[2]
|
|
|
140 speak --piglatin softly
|
|
|
141 -------------------------[3]
|
|
|
142 speak -psr 2 softly
|
|
|
143 -------------------------[4]
|
|
|
144 speak --repeat 1000000 softly
|
|
|
145 -------------------------[5]
|
|
|
146 show maxrepeats
|
|
|
147 -------------------------[6]
|
|
|
148 set maxrepeats 5
|
|
|
149 -------------------------[7]
|
|
|
150 speak --repeat 1000000 softly
|
|
|
151 -------------------------[8]
|
|
|
152 orate blah blah
|
|
|
153 blah
|
|
|
154 and furthermore
|
|
|
155 blah
|
|
|
156
|
|
|
157 -------------------------[9]
|
|
|
158 &greetings
|
|
|
159 (Cmd) run
|
|
|
160 orate blah blah
|
|
|
161 blah
|
|
|
162 and furthermore
|
|
|
163 blah
|
|
|
164
|
|
|
165 blah blah blah and furthermore blah
|
|
|
166 (Cmd) run 3
|
|
|
167 speak -psr 2 softly
|
|
|
168 OFTLYSAY
|
|
|
169 OFTLYSAY
|
|
|
170 (Cmd) history maxrepeats
|
|
|
171 -------------------------[5]
|
|
|
172 set maxrepeats
|
|
|
173 -------------------------[6]
|
|
|
174 set maxrepeats 5
|
|
|
175 (Cmd)
|
