Mercurial > python-cmd2

comparison README.txt @ 6:71067a445663

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added README
author catherine@localhost
date Wed, 14 May 2008 10:56:05 -0400
parents
children 47af95ad83c7
comparison
equal deleted inserted replaced
5:2d6280e022e4 6:71067a445663
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
63 from cmd2 import Cmd, flagReader
64
65 class CmdLineApp(Cmd):
66 multilineCommands = ['orate']
67 Cmd.shortcuts.update({'&': 'speak'})
68 maxrepeats = 3
69 Cmd.settable.append('maxrepeats')
70 speakflags = flagReader.FlagSet([flagReader.Flag('piglatin'),
71 flagReader.Flag('shout'),
72 flagReader.Flag('repeat', nargs=1)
73 ])
74 def do_speak(self, arg):
75 """Repeats what you tell me to.
76
77 args: --piglatin, -p: translate to Pig Latin
78 --shout, -s: emulate internet newbie
79 --repeat (nTimes), -r: be redundant"""
80 (options, arg) = self.speakflags.parse(arg)
81
82 if options.has_key('piglatin'):
83 arg = '%s%say' % (arg[1:], arg[0])
84 if options.has_key('shout'):
85 arg = arg.upper()
86 repetitions = options.get('repeat')
87 repetitions = int(repetitions[0]) if repetitions else 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 do_say = do_speak # now "say" is a synonym for "speak"
94 do_orate = do_speak # another synonym, but this one takes multi-line input
95
96 app = CmdLineApp()
97 app.cmdloop()
98
99 Sample session using the above code ::
100
101 c:\cmd2>python cmd2_example.py
102 (Cmd) speak softly
103 softly
104 (Cmd) speak --piglatin softly
105 oftlysay
106 (Cmd) speak -psr 2 softly
107 OFTLYSAY
108 OFTLYSAY
109 (Cmd) speak --repeat 1000000 softly
110 softly
111 softly
112 softly
113 (Cmd) show maxrepeats
114 maxrepeats: 3
115 (Cmd) set maxrepeats 5
116 maxrepeats - was: 3
117 now: 5
118 (Cmd) speak --repeat 1000000 softly
119 softly
120 softly
121 softly
122 softly
123 softly
124 (Cmd) orate blah blah
125 > blah
126 > and furthermore
127 > blah
128 >
129 blah blah blah and furthermore blah
130 (Cmd) &greetings
131 greetings
132 (Cmd) history
133 -------------------------[1]
134 speak softly
135 -------------------------[2]
136 speak --piglatin softly
137 -------------------------[3]
138 speak -psr 2 softly
139 -------------------------[4]
140 speak --repeat 1000000 softly
141 -------------------------[5]
142 show maxrepeats
143 -------------------------[6]
144 set maxrepeats 5
145 -------------------------[7]
146 speak --repeat 1000000 softly
147 -------------------------[8]
148 orate blah blah
149 blah
150 and furthermore
151 blah
152
153 -------------------------[9]
154 &greetings
155 (Cmd) run
156 orate blah blah
157 blah
158 and furthermore
159 blah
160
161 blah blah blah and furthermore blah
162 (Cmd) run 3
163 speak -psr 2 softly
164 OFTLYSAY
165 OFTLYSAY
166 (Cmd) history maxrepeats
167 -------------------------[5]
168 set maxrepeats
169 -------------------------[6]
170 set maxrepeats 5
171 (Cmd)