Mercurial > python-cmd2
annotate docs/unfreefeatures.rst @ 411:9d5ff2ddfdea 0.6.2
doc update
| author | Catherine Devlin <catherine.devlin@gmail.com> |
|---|---|
| date | Tue, 09 Nov 2010 05:22:41 -0500 |
| parents | 52ab96d4f179 |
| children | f16f444a4d10 |
| 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 | |
| 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 | |
|
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). | |
| 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 |
|
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 | |
| 98 sunny''' | |
| 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() | |
| 109 | |
| 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"), | |
| 148 make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), | |
| 149 make_option('-r', '--repeat', type="int", help="output [n] times") | |
| 150 ]) | |
| 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 | |
| 165 (Cmd) say goodnight, gracie | |
| 166 goodnight, gracie | |
| 167 (Cmd) say -sp goodnight, gracie | |
| 168 OODNIGHT, GRACIEGAY | |
| 169 (Cmd) say -r 2 --shout goodnight, gracie | |
| 170 GOODNIGHT, GRACIE | |
| 171 GOODNIGHT, GRACIE | |
| 172 | |
| 173 .. _optparse: | |
| 174 | |
| 324 | 175 .. _outputters: |
| 176 | |
| 177 poutput, pfeedback, perror | |
| 178 ========================== | |
| 179 | |
| 180 Standard ``cmd`` applications produce their output with ``self.stdout.write('output')`` (or with ``print``, | |
| 181 but ``print`` decreases output flexibility). ``cmd2`` applications can use | |
| 182 ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')`` | |
| 183 instead. These methods have these advantages: | |
| 184 | |
| 185 - More concise | |
| 186 - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. | |
| 411 | 187 |
| 336 | 188 color |
| 189 ===== | |
| 190 | |
| 411 | 191 Text output can be colored by wrapping it in the ``colorize`` method. |
| 192 | |
| 193 .. automethod:: cmd2.Cmd.colorize | |
| 336 | 194 |
| 411 | 195 .. _quiet: |
| 196 | |
| 197 quiet | |
| 331 | 198 ===== |
| 199 | |
| 200 Controls whether ``self.pfeedback('message')`` output is suppressed; | |
| 201 useful for non-essential feedback that the user may not always want | |
| 202 to read. ``quiet`` is only relevant if | |
| 203 ``app.pfeedback`` is sometimes used. | |
| 204 | |
| 332 | 205 ``select`` |
| 206 ========== | |
| 207 | |
| 411 | 208 Presents numbered options to user, as bash ``select``. |
| 209 | |
| 332 | 210 ``app.select`` is called from within a method (not by the user directly; it is ``app.select``, not ``app.do_select``). |
| 211 | |
| 212 .. automethod:: cmd2.Cmd.select | |
| 213 | |
| 214 :: | |
| 215 | |
| 216 def do_eat(self, arg): | |
| 217 sauce = self.select('sweet salty', 'Sauce? ') | |
| 218 result = '{food} with {sauce} sauce, yum!' | |
| 219 result = result.format(food=arg, sauce=sauce) | |
| 220 self.stdout.write(result + '\n') | |
| 221 | |
| 222 :: | |
| 223 | |
| 224 (Cmd) eat wheaties | |
| 225 1. sweet | |
| 226 2. salty | |
| 227 Sauce? 2 | |
| 228 wheaties with salty sauce, yum! |