annotate docs/unfreefeatures.rst @ 355:5972ae04515e

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