|
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``.
|
|
|
26 ``parsed`` is a ``pyparsing.ParseResults``_
|
|
|
27 object produced by applying a pyparsing_
|
|
|
28 grammar applied to ``arg``. It may include:
|
|
|
29
|
|
|
30 command
|
|
|
31 Name of the command called
|
|
|
32
|
|
|
33 raw
|
|
|
34 Full input exactly as typed.
|
|
|
35
|
|
|
36 terminator
|
|
|
37 Character used to end a multiline command
|
|
|
38
|
|
|
39 suffix
|
|
|
40 Remnant of input after terminator
|
|
|
41
|
|
|
42 ::
|
|
|
43
|
|
|
44 def do_parsereport(self, arg):
|
|
|
45 self.stdout.write(arg.parsed.dump() + '\n')
|
|
|
46
|
|
|
47 ::
|
|
|
48
|
|
|
49 (Cmd) parsereport A B /* C */ D; E
|
|
|
50 ['parsereport', 'A B D', ';', 'E']
|
|
|
51 - args: A B D
|
|
|
52 - command: parsereport
|
|
|
53 - raw: parsereport A B /* C */ D; E
|
|
|
54 - statement: ['parsereport', 'A B D', ';']
|
|
|
55 - args: A B D
|
|
|
56 - command: parsereport
|
|
|
57 - terminator: ;
|
|
|
58 - suffix: E
|
|
|
59 - terminator: ;
|
|
|
60
|
|
|
61 If ``parsed`` does not contain an attribute,
|
|
|
62 querying for it will return ``None``. (This
|
|
|
63 is a characteristic of ``pyparsing.ParseResults``_.)
|
|
|
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).
|
|
|
70
|
|
|
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
|
|
315
|
77 Environment parameters
|
|
|
78 ======================
|
|
|
79
|
|
316
|
80 Your application can define user-settable parameters
|
|
324
|
81 which your code can reference. Create them as class attributes
|
|
|
82 with their default values, and add them (with optional
|
|
|
83 documentation) to ``settable``.
|
|
|
84
|
|
|
85 ::
|
|
316
|
86
|
|
324
|
87 from cmd2 import Cmd
|
|
|
88 class App(Cmd):
|
|
|
89 degrees_c = 22
|
|
|
90 sunny = False
|
|
|
91 settable = Cmd.settable + '''degrees_c temperature in Celsius
|
|
|
92 sunny'''
|
|
|
93 def do_sunbathe(self, arg):
|
|
|
94 if self.degrees_c < 20:
|
|
|
95 result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c)
|
|
|
96 elif not self.sunny:
|
|
|
97 result = 'Too dim.'
|
|
|
98 else:
|
|
|
99 result = 'UV is bad for your skin.'
|
|
|
100 self.stdout.write(result + '\n')
|
|
|
101 app = App()
|
|
|
102 app.cmdloop()
|
|
|
103
|
|
|
104 ::
|
|
|
105
|
|
|
106 (Cmd) set --long
|
|
|
107 degrees_c: 22 # temperature in Celsius
|
|
|
108 sunny: False #
|
|
|
109 (Cmd) sunbathe
|
|
|
110 Too dim.
|
|
|
111 (Cmd) set sunny yes
|
|
|
112 sunny - was: False
|
|
|
113 now: True
|
|
|
114 (Cmd) sunbathe
|
|
|
115 UV is bad for your skin.
|
|
|
116 (Cmd) set degrees_c 13
|
|
|
117 degrees_c - was: 22
|
|
|
118 now: 13
|
|
|
119 (Cmd) sunbathe
|
|
|
120 It's 13 C - are you a penguin?
|
|
316
|
121
|
|
|
122
|
|
315
|
123 Commands with flags
|
|
|
124 ===================
|
|
324
|
125
|
|
331
|
126 All ``do_`` methods are responsible for interpreting
|
|
|
127 the arguments passed to them. However, ``cmd2`` lets
|
|
|
128 a ``do_`` methods accept Unix-style *flags*. It uses optparse_
|
|
|
129 to parse the flags, and they work the same way as for
|
|
|
130 that module.
|
|
|
131
|
|
|
132 Flags are defined with the ``options`` decorator,
|
|
|
133 which is passed a list of optparse_-style options,
|
|
|
134 each created with ``make_option``. The method
|
|
|
135 should accept a second argument, ``opts``, in
|
|
|
136 addition to ``args``; the flags will be stripped
|
|
|
137 from ``args``.
|
|
|
138
|
|
|
139 ::
|
|
|
140
|
|
|
141 @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
|
|
|
142 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
|
|
|
143 make_option('-r', '--repeat', type="int", help="output [n] times")
|
|
|
144 ])
|
|
|
145 def do_speak(self, arg, opts=None):
|
|
|
146 """Repeats what you tell me to."""
|
|
|
147 arg = ''.join(arg)
|
|
|
148 if opts.piglatin:
|
|
|
149 arg = '%s%say' % (arg[1:].rstrip(), arg[0])
|
|
|
150 if opts.shout:
|
|
|
151 arg = arg.upper()
|
|
|
152 repetitions = opts.repeat or 1
|
|
|
153 for i in range(min(repetitions, self.maxrepeats)):
|
|
|
154 self.stdout.write(arg)
|
|
|
155 self.stdout.write('\n')
|
|
|
156
|
|
|
157 ::
|
|
|
158
|
|
|
159 (Cmd) say goodnight, gracie
|
|
|
160 goodnight, gracie
|
|
|
161 (Cmd) say -sp goodnight, gracie
|
|
|
162 OODNIGHT, GRACIEGAY
|
|
|
163 (Cmd) say -r 2 --shout goodnight, gracie
|
|
|
164 GOODNIGHT, GRACIE
|
|
|
165 GOODNIGHT, GRACIE
|
|
|
166
|
|
|
167 .. _optparse:
|
|
|
168
|
|
324
|
169 .. _outputters:
|
|
|
170
|
|
|
171 poutput, pfeedback, perror
|
|
|
172 ==========================
|
|
|
173
|
|
|
174 Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``,
|
|
|
175 but ``print`` decreases output flexibility). ``cmd2`` applications can use
|
|
|
176 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')``
|
|
|
177 instead. These methods have these advantages:
|
|
|
178
|
|
|
179 - More concise
|
|
|
180 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
|
|
331
|
181
|
|
|
182 .. _quiet:
|
|
|
183
|
|
|
184 Quiet
|
|
|
185 =====
|
|
|
186
|
|
|
187 Controls whether ``self.pfeedback('message')`` output is suppressed;
|
|
|
188 useful for non-essential feedback that the user may not always want
|
|
|
189 to read. ``quiet`` is only relevant if
|
|
|
190 ``app.pfeedback`` is sometimes used.
|
|
|
191
|
