Mercurial > python-cmd2

comparison docs/unfreefeatures.rst @ 413:f16f444a4d10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
added arg_desc to @options, thanks Renzo Crispiatico
author Catherine Devlin <catherine.devlin@gmail.com>
date Fri, 12 Nov 2010 20:03:21 -0500
parents 9d5ff2ddfdea
children
comparison
equal deleted inserted replaced
412:5bd1d2b11548 413:f16f444a4d10
26 ``parsed`` is a ``pyparsing.ParseResults`` 26 ``parsed`` is a ``pyparsing.ParseResults``
27 object produced by applying a pyparsing_ 27 object produced by applying a pyparsing_
28 grammar applied to ``arg``. It may include: 28 grammar applied to ``arg``. It may include:
29 29
30 command 30 command
31 Name of the command called 31 Name of the command called
32 32
33 raw 33 raw
34 Full input exactly as typed. 34 Full input exactly as typed.
35 35
36 terminator 36 terminator
37 Character used to end a multiline command 37 Character used to end a multiline command
38 38
39 suffix 39 suffix
40 Remnant of input after terminator 40 Remnant of input after terminator
41 41
42 :: 42 ::
43 43
44 def do_parsereport(self, arg): 44 def do_parsereport(self, arg):
45 self.stdout.write(arg.parsed.dump() + '\n') 45 self.stdout.write(arg.parsed.dump() + '\n')
46 46
47 :: 47 ::
48 48
49 (Cmd) parsereport A B /* C */ D; E 49 (Cmd) parsereport A B /* C */ D; E
50 ['parsereport', 'A B D', ';', 'E'] 50 ['parsereport', 'A B D', ';', 'E']
51 - args: A B D 51 - args: A B D
52 - command: parsereport 52 - command: parsereport
53 - raw: parsereport A B /* C */ D; E 53 - raw: parsereport A B /* C */ D; E
54 - statement: ['parsereport', 'A B D', ';'] 54 - statement: ['parsereport', 'A B D', ';']
55 - args: A B D 55 - args: A B D
56 - command: parsereport 56 - command: parsereport
57 - terminator: ; 57 - terminator: ;
58 - suffix: E 58 - suffix: E
59 - terminator: ; 59 - terminator: ;
60 60
61 If ``parsed`` does not contain an attribute, 61 If ``parsed`` does not contain an attribute,
62 querying for it will return ``None``. (This 62 querying for it will return ``None``. (This
63 is a characteristic of ``pyparsing.ParseResults``.) 63 is a characteristic of ``pyparsing.ParseResults``.)
64 64
65 ParsedString was developed to support sqlpython_ 65 ParsedString was developed to support sqlpython_
66 and reflects its needs. The parsing grammar and 66 and reflects its needs. The parsing grammar and
67 process are painfully complex and should not be 67 process are painfully complex and should not be
68 considered stable; future ``cmd2`` releases may 68 considered stable; future ``cmd2`` releases may
69 change it somewhat (hopefully reducing complexity). 69 change it somewhat (hopefully reducing complexity).
70 70
71 (Getting ``arg`` as a ``ParsedString`` is 71 (Getting ``arg`` as a ``ParsedString`` is
72 technically "free", in that it requires no application 72 technically "free", in that it requires no application
73 changes from the cmd_ standard, but there will 73 changes from the cmd_ standard, but there will
74 be no result unless you change your application 74 be no result unless you change your application
75 to *use* ``arg.parsed``.) 75 to *use* ``arg.parsed``.)
93 from cmd2 import Cmd 93 from cmd2 import Cmd
94 class App(Cmd): 94 class App(Cmd):
95 degrees_c = 22 95 degrees_c = 22
96 sunny = False 96 sunny = False
97 settable = Cmd.settable + '''degrees_c temperature in Celsius 97 settable = Cmd.settable + '''degrees_c temperature in Celsius
98 sunny''' 98 sunny'''
99 def do_sunbathe(self, arg): 99 def do_sunbathe(self, arg):
100 if self.degrees_c < 20: 100 if self.degrees_c < 20:
101 result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c) 101 result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c)
102 elif not self.sunny: 102 elif not self.sunny:
103 result = 'Too dim.' 103 result = 'Too dim.'
104 else: 104 else:
105 result = 'UV is bad for your skin.' 105 result = 'UV is bad for your skin.'
106 self.stdout.write(result + '\n') 106 self.stdout.write(result + '\n')
107 app = App() 107 app = App()
108 app.cmdloop() 108 app.cmdloop()
109 109
110 :: 110 ::
111 111
112 (Cmd) set --long 112 (Cmd) set --long
113 degrees_c: 22 # temperature in Celsius 113 degrees_c: 22 # temperature in Celsius
114 sunny: False # 114 sunny: False #
143 from ``args``. 143 from ``args``.
144 144
145 :: 145 ::
146 146
147 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"), 147 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
148 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), 148 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
149 make_option('-r', '--repeat', type="int", help="output [n] times") 149 make_option('-r', '--repeat', type="int", help="output [n] times")
150 ]) 150 ])
151 def do_speak(self, arg, opts=None): 151 def do_speak(self, arg, opts=None):
152 """Repeats what you tell me to.""" 152 """Repeats what you tell me to."""
153 arg = ''.join(arg) 153 arg = ''.join(arg)
154 if opts.piglatin: 154 if opts.piglatin:
155 arg = '%s%say' % (arg[1:].rstrip(), arg[0]) 155 arg = '%s%say' % (arg[1:].rstrip(), arg[0])
160 self.stdout.write(arg) 160 self.stdout.write(arg)
161 self.stdout.write('\n') 161 self.stdout.write('\n')
162 162
163 :: 163 ::
164 164
165 (Cmd) say goodnight, gracie 165 (Cmd) say goodnight, gracie
166 goodnight, gracie 166 goodnight, gracie
167 (Cmd) say -sp goodnight, gracie 167 (Cmd) say -sp goodnight, gracie
168 OODNIGHT, GRACIEGAY 168 OODNIGHT, GRACIEGAY
169 (Cmd) say -r 2 --shout goodnight, gracie 169 (Cmd) say -r 2 --shout goodnight, gracie
170 GOODNIGHT, GRACIE 170 GOODNIGHT, GRACIE
171 GOODNIGHT, GRACIE 171 GOODNIGHT, GRACIE
172 172
173 ``options`` takes an optional additional argument, ``arg_desc``.
174 If present, ``arg_desc`` will appear in place of ``arg`` in
175 the option's online help.
176
177 ::
178
179 @options([make_option('-t', '--train', action='store_true', help='by train')],
180 arg_desc='(from city) (to city)')
181 def do_travel(self, arg, opts=None):
182 'Gets you from (from city) to (to city).'
183
184
185 ::
186
187 (Cmd) help travel
188 Gets you from (from city) to (to city).
189 Usage: travel [options] (from-city) (to-city)
190
191 Options:
192 -h, --help show this help message and exit
193 -t, --train by train
194
173 .. _optparse: 195 .. _optparse:
174 196
175 .. _outputters: 197 .. _outputters:
176 198
177 poutput, pfeedback, perror 199 poutput, pfeedback, perror
180 Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``, 202 Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``,
181 but ``print`` decreases output flexibility). ``cmd2`` applications can use 203 but ``print`` decreases output flexibility). ``cmd2`` applications can use
182 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')`` 204 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')``
183 instead. These methods have these advantages: 205 instead. These methods have these advantages:
184 206
185 - More concise 207 - More concise
186 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. 208 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
187 209
188 color 210 color
189 ===== 211 =====
190 212
191 Text output can be colored by wrapping it in the ``colorize`` method. 213 Text output can be colored by wrapping it in the ``colorize`` method.
192 214
210 ``app.select`` is called from within a method (not by the user directly; it is ``app.select``, not ``app.do_select``). 232 ``app.select`` is called from within a method (not by the user directly; it is ``app.select``, not ``app.do_select``).
211 233
212 .. automethod:: cmd2.Cmd.select 234 .. automethod:: cmd2.Cmd.select
213 235
214 :: 236 ::
215 237
216 def do_eat(self, arg): 238 def do_eat(self, arg):
217 sauce = self.select('sweet salty', 'Sauce? ') 239 sauce = self.select('sweet salty', 'Sauce? ')
218 result = '{food} with {sauce} sauce, yum!' 240 result = '{food} with {sauce} sauce, yum!'
219 result = result.format(food=arg, sauce=sauce) 241 result = result.format(food=arg, sauce=sauce)
220 self.stdout.write(result + '\n') 242 self.stdout.write(result + '\n')
221 243
222 :: 244 ::
223 245
224 (Cmd) eat wheaties 246 (Cmd) eat wheaties
225 1. sweet 247 1. sweet
226 2. salty 248 2. salty
227 Sauce? 2 249 Sauce? 2
228 wheaties with salty sauce, yum! 250 wheaties with salty sauce, yum!
251