annotate README.txt @ 93:f54e3e842f21

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