Mercurial > python-cmd2

comparison docs/unfreefeatures.rst @ 331:6306edc46a6e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
more docs
author cat@eee
date Fri, 12 Feb 2010 21:41:17 -0500
parents 21584174d865
children 49bea7cab179
comparison
equal deleted inserted replaced
330:3aca8af5971f 331:6306edc46a6e
1 ====================================== 1 ======================================
2 Features requiring application changes 2 Features requiring application changes
3 ====================================== 3 ======================================
4 4
5 Command shortcuts 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
6 ================= 21 =================
7 22
8 .. _parameters: 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``.)
9 76
10 Environment parameters 77 Environment parameters
11 ====================== 78 ======================
12 79
13 Your application can define user-settable parameters 80 Your application can define user-settable parameters
54 121
55 122
56 Commands with flags 123 Commands with flags
57 =================== 124 ===================
58 125
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
59 .. _outputters: 169 .. _outputters:
60 170
61 poutput, pfeedback, perror 171 poutput, pfeedback, perror
62 ========================== 172 ==========================
63 173
67 instead. These methods have these advantages: 177 instead. These methods have these advantages:
68 178
69 - More concise 179 - More concise
70 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. 180 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
71 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