Mercurial > python-cmd2

comparison cmd2/README.txt @ 100:3de2a3eb765a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
oops, renesting directory
author catherine@dellzilla
date Mon, 29 Sep 2008 12:48:29 -0400
parents README.txt@a791d615545c
children
comparison
equal deleted inserted replaced
99:00898931969b 100:3de2a3eb765a
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 - 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 `|`
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
49 - Parsing commands with `optparse` options (flags)
50
51 ::
52
53 @options([make_option('-m', '--myoption', action="store_true", help="all about my option")])
54 def do_myfunc(self, arg, opts):
55 if opts.myoption:
56 ...
57
58 See Python standard library's `optparse` documentation: http://docs.python.org/lib/optparse-defining-options.html
59
60 - Catherine Devlin, http://catherinedevlin.blogspot.com
61
62 cmd2 can be installed with `easy_install cmd2`
63
64 Cheese Shop page: http://pypi.python.org/pypi/cmd2
65
66 Example cmd2 application (cmd2_example.py) ::
67
68 from cmd2 import Cmd, make_option, options
69
70 class CmdLineApp(Cmd):
71 multilineCommands = ['orate']
72 Cmd.shortcuts.update({'&': 'speak'})
73 maxrepeats = 3
74 Cmd.settable.append('maxrepeats')
75
76 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
77 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
78 make_option('-r', '--repeat', type="int", help="output [n] times")
79 ])
80 def do_speak(self, arg, opts=None):
81 """Repeats what you tell me to."""
82 arg = ' '.join(arg)
83 if opts.piglatin:
84 arg = '%s%say' % (arg[1:], arg[0])
85 if opts.shout:
86 arg = arg.upper()
87 repetitions = opts.repeat or 1
88 for i in range(min(repetitions, self.maxrepeats)):
89 self.stdout.write(arg)
90 self.stdout.write('\n')
91 # self.stdout.write is better than "print", because Cmd can be
92 # initialized with a non-standard output destination
93
94 do_say = do_speak # now "say" is a synonym for "speak"
95 do_orate = do_speak # another synonym, but this one takes multi-line input
96
97 app = CmdLineApp()
98 app.cmdloop()
99
100 Sample session using the above code ::
101
102 c:\cmd2>python cmd2_example.py
103 (Cmd) speak softly
104 softly
105 (Cmd) speak --piglatin softly
106 oftlysay
107 (Cmd) speak -psr 2 softly
108 OFTLYSAY
109 OFTLYSAY
110 (Cmd) speak --repeat 1000000 softly
111 softly
112 softly
113 softly
114 (Cmd) show maxrepeats
115 maxrepeats: 3
116 (Cmd) set maxrepeats 5
117 maxrepeats - was: 3
118 now: 5
119 (Cmd) speak --repeat 1000000 softly
120 softly
121 softly
122 softly
123 softly
124 softly
125 (Cmd) orate blah blah
126 > blah
127 > and furthermore
128 > blah
129 >
130 blah blah blah and furthermore blah
131 (Cmd) &greetings
132 greetings
133 (Cmd) history
134 -------------------------[1]
135 speak softly
136 -------------------------[2]
137 speak --piglatin softly
138 -------------------------[3]
139 speak -psr 2 softly
140 -------------------------[4]
141 speak --repeat 1000000 softly
142 -------------------------[5]
143 show maxrepeats
144 -------------------------[6]
145 set maxrepeats 5
146 -------------------------[7]
147 speak --repeat 1000000 softly
148 -------------------------[8]
149 orate blah blah
150 blah
151 and furthermore
152 blah
153
154 -------------------------[9]
155 &greetings
156 (Cmd) run
157 orate blah blah
158 blah
159 and furthermore
160 blah
161
162 blah blah blah and furthermore blah
163 (Cmd) run 3
164 speak -psr 2 softly
165 OFTLYSAY
166 OFTLYSAY
167 (Cmd) history maxrepeats
168 -------------------------[5]
169 set maxrepeats
170 -------------------------[6]
171 set maxrepeats 5
172 (Cmd) speak a dead parrot > pet.txt
173 (Cmd) speak < pet.txt
174 a dead parrot
175 (Cmd) speak only resting | wc
176 1 2 13
177 (Cmd)