Mercurial > python-cmd2
annotate docs/unfreefeatures.rst @ 437:9e0fd9da25c6
Added tag 0.6.4 for changeset c4c35f002aef
| author | catherine.devlin@gmail.com |
|---|---|
| date | Thu, 25 Aug 2011 16:27:53 -0400 |
| parents | f16f444a4d10 |
| children |
| rev | line source |
|---|---|
| 315 | 1 ====================================== |
| 2 Features requiring application changes | |
| 3 ====================================== | |
| 4 | |
| 331 | 5 Multiline commands |
| 6 ================== | |
| 7 | |
| 8 Command input may span multiple lines for the | |
| 9 commands whose names are listed in the | |
| 10 parameter ``app.multilineCommands``. These | |
| 11 commands will be executed only | |
| 12 after the user has entered a *terminator*. | |
| 13 By default, the command terminators is | |
| 14 ``;``; replacing or appending to the list | |
| 15 ``app.terminators`` allows different | |
| 16 terminators. A blank line | |
| 17 is *always* considered a command terminator | |
| 18 (cannot be overridden). | |
| 19 | |
| 20 Parsed statements | |
| 315 | 21 ================= |
| 22 | |
| 331 | 23 ``cmd2`` passes ``arg`` to a ``do_`` method (or |
| 24 ``default`) as a ParsedString, a subclass of | |
| 25 string that includes an attribute ``parsed``. | |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
26 ``parsed`` is a ``pyparsing.ParseResults`` |
| 331 | 27 object produced by applying a pyparsing_ |
| 28 grammar applied to ``arg``. It may include: | |
| 29 | |
| 30 command | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
31 Name of the command called |
| 331 | 32 |
| 33 raw | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
34 Full input exactly as typed. |
| 331 | 35 |
| 36 terminator | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
37 Character used to end a multiline command |
| 331 | 38 |
| 39 suffix | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
40 Remnant of input after terminator |
| 331 | 41 |
| 42 :: | |
| 43 | |
| 44 def do_parsereport(self, arg): | |
| 45 self.stdout.write(arg.parsed.dump() + '\n') | |
| 46 | |
| 47 :: | |
| 48 | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
49 (Cmd) parsereport A B /* C */ D; E |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
50 ['parsereport', 'A B D', ';', 'E'] |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
51 - args: A B D |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
52 - command: parsereport |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
53 - raw: parsereport A B /* C */ D; E |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
54 - statement: ['parsereport', 'A B D', ';'] |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
55 - args: A B D |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
56 - command: parsereport |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
57 - terminator: ; |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
58 - suffix: E |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
59 - terminator: ; |
| 331 | 60 |
| 61 If ``parsed`` does not contain an attribute, | |
| 62 querying for it will return ``None``. (This | |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
63 is a characteristic of ``pyparsing.ParseResults``.) |
| 331 | 64 |
| 65 ParsedString was developed to support sqlpython_ | |
| 66 and reflects its needs. The parsing grammar and | |
| 67 process are painfully complex and should not be | |
| 68 considered stable; future ``cmd2`` releases may | |
| 69 change it somewhat (hopefully reducing complexity). | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
70 |
| 331 | 71 (Getting ``arg`` as a ``ParsedString`` is |
| 72 technically "free", in that it requires no application | |
| 73 changes from the cmd_ standard, but there will | |
| 74 be no result unless you change your application | |
| 75 to *use* ``arg.parsed``.) | |
| 324 | 76 |
|
388
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
77 .. _sqlpython: http://pypi.python.org/pypi/sqlpython/ |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
78 |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
79 .. _cmd: http://docs.python.org/library/cmd.html#module-cmd |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
80 |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
81 .. _pyparsing: http://pyparsing.wikispaces.com/ |
|
52ab96d4f179
fix some Sphinx warnings
anatoly techtonik <techtonik@gmail.com>
parents:
336
diff
changeset
|
82 |
| 315 | 83 Environment parameters |
| 84 ====================== | |
| 85 | |
| 316 | 86 Your application can define user-settable parameters |
| 324 | 87 which your code can reference. Create them as class attributes |
| 88 with their default values, and add them (with optional | |
| 89 documentation) to ``settable``. | |
| 90 | |
| 91 :: | |
| 316 | 92 |
| 324 | 93 from cmd2 import Cmd |
| 94 class App(Cmd): | |
| 95 degrees_c = 22 | |
| 96 sunny = False | |
| 97 settable = Cmd.settable + '''degrees_c temperature in Celsius | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
98 sunny''' |
| 324 | 99 def do_sunbathe(self, arg): |
| 100 if self.degrees_c < 20: | |
| 101 result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c) | |
| 102 elif not self.sunny: | |
| 103 result = 'Too dim.' | |
| 104 else: | |
| 105 result = 'UV is bad for your skin.' | |
| 106 self.stdout.write(result + '\n') | |
| 107 app = App() | |
| 108 app.cmdloop() | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
109 |
| 324 | 110 :: |
| 111 | |
| 112 (Cmd) set --long | |
| 113 degrees_c: 22 # temperature in Celsius | |
| 114 sunny: False # | |
| 115 (Cmd) sunbathe | |
| 116 Too dim. | |
| 117 (Cmd) set sunny yes | |
| 118 sunny - was: False | |
| 119 now: True | |
| 120 (Cmd) sunbathe | |
| 121 UV is bad for your skin. | |
| 122 (Cmd) set degrees_c 13 | |
| 123 degrees_c - was: 22 | |
| 124 now: 13 | |
| 125 (Cmd) sunbathe | |
| 126 It's 13 C - are you a penguin? | |
| 316 | 127 |
| 128 | |
| 315 | 129 Commands with flags |
| 130 =================== | |
| 324 | 131 |
| 331 | 132 All ``do_`` methods are responsible for interpreting |
| 133 the arguments passed to them. However, ``cmd2`` lets | |
| 134 a ``do_`` methods accept Unix-style *flags*. It uses optparse_ | |
| 135 to parse the flags, and they work the same way as for | |
| 136 that module. | |
| 137 | |
| 138 Flags are defined with the ``options`` decorator, | |
| 139 which is passed a list of optparse_-style options, | |
| 140 each created with ``make_option``. The method | |
| 141 should accept a second argument, ``opts``, in | |
| 142 addition to ``args``; the flags will be stripped | |
| 143 from ``args``. | |
| 144 | |
| 145 :: | |
| 146 | |
| 147 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
148 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
149 make_option('-r', '--repeat', type="int", help="output [n] times") |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
150 ]) |
| 331 | 151 def do_speak(self, arg, opts=None): |
| 152 """Repeats what you tell me to.""" | |
| 153 arg = ''.join(arg) | |
| 154 if opts.piglatin: | |
| 155 arg = '%s%say' % (arg[1:].rstrip(), arg[0]) | |
| 156 if opts.shout: | |
| 157 arg = arg.upper() | |
| 158 repetitions = opts.repeat or 1 | |
| 159 for i in range(min(repetitions, self.maxrepeats)): | |
| 160 self.stdout.write(arg) | |
| 161 self.stdout.write('\n') | |
| 162 | |
| 163 :: | |
| 164 | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
165 (Cmd) say goodnight, gracie |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
166 goodnight, gracie |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
167 (Cmd) say -sp goodnight, gracie |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
168 OODNIGHT, GRACIEGAY |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
169 (Cmd) say -r 2 --shout goodnight, gracie |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
170 GOODNIGHT, GRACIE |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
171 GOODNIGHT, GRACIE |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
172 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
173 ``options`` takes an optional additional argument, ``arg_desc``. |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
174 If present, ``arg_desc`` will appear in place of ``arg`` in |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
175 the option's online help. |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
176 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
177 :: |
| 331 | 178 |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
179 @options([make_option('-t', '--train', action='store_true', help='by train')], |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
180 arg_desc='(from city) (to city)') |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
181 def do_travel(self, arg, opts=None): |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
182 'Gets you from (from city) to (to city).' |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
183 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
184 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
185 :: |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
186 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
187 (Cmd) help travel |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
188 Gets you from (from city) to (to city). |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
189 Usage: travel [options] (from-city) (to-city) |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
190 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
191 Options: |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
192 -h, --help show this help message and exit |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
193 -t, --train by train |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
194 |
| 331 | 195 .. _optparse: |
| 196 | |
| 324 | 197 .. _outputters: |
| 198 | |
| 199 poutput, pfeedback, perror | |
| 200 ========================== | |
| 201 | |
| 202 Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``, | |
| 203 but ``print`` decreases output flexibility). ``cmd2`` applications can use | |
| 204 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')`` | |
| 205 instead. These methods have these advantages: | |
| 206 | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
207 - More concise |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
208 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
209 |
| 336 | 210 color |
| 211 ===== | |
| 212 | |
| 411 | 213 Text output can be colored by wrapping it in the ``colorize`` method. |
| 214 | |
| 215 .. automethod:: cmd2.Cmd.colorize | |
| 336 | 216 |
| 411 | 217 .. _quiet: |
| 218 | |
| 219 quiet | |
| 331 | 220 ===== |
| 221 | |
| 222 Controls whether ``self.pfeedback('message')`` output is suppressed; | |
| 223 useful for non-essential feedback that the user may not always want | |
| 224 to read. ``quiet`` is only relevant if | |
| 225 ``app.pfeedback`` is sometimes used. | |
| 226 | |
| 332 | 227 ``select`` |
| 228 ========== | |
| 229 | |
| 411 | 230 Presents numbered options to user, as bash ``select``. |
| 231 | |
| 332 | 232 ``app.select`` is called from within a method (not by the user directly; it is ``app.select``, not ``app.do_select``). |
| 233 | |
| 234 .. automethod:: cmd2.Cmd.select | |
| 235 | |
| 236 :: | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
237 |
| 332 | 238 def do_eat(self, arg): |
| 239 sauce = self.select('sweet salty', 'Sauce? ') | |
| 240 result = '{food} with {sauce} sauce, yum!' | |
| 241 result = result.format(food=arg, sauce=sauce) | |
| 242 self.stdout.write(result + '\n') | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
243 |
| 332 | 244 :: |
| 245 | |
|
413
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
246 (Cmd) eat wheaties |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
247 1. sweet |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
248 2. salty |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
249 Sauce? 2 |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
250 wheaties with salty sauce, yum! |
|
f16f444a4d10
added arg_desc to @options, thanks Renzo Crispiatico
Catherine Devlin <catherine.devlin@gmail.com>
parents:
411
diff
changeset
|
251 |