Mercurial > python-cmd2
annotate docs/settingchanges.rst @ 333:45e70737791f
unit tests fixed
| author | cat@eee |
|---|---|
| date | Fri, 12 Feb 2010 22:57:41 -0500 |
| parents | 6306edc46a6e |
| children | 92a15405ed8a |
| rev | line source |
|---|---|
| 315 | 1 ========================================= |
| 2 Features requiring only parameter changes | |
| 3 ========================================= | |
| 4 | |
| 324 | 5 Several aspects of a ``cmd2`` application's behavior |
| 6 can be controlled simply by setting attributes of ``App``. | |
| 7 | |
| 328 | 8 (To define your own user-settable parameters, see :ref:`parameters`) |
| 315 | 9 |
| 10 Case-insensitivity | |
| 11 ================== | |
| 12 | |
| 324 | 13 By default, all ``cmd2`` command names are case-insensitive; |
| 14 ``sing the blues`` and ``SiNg the blues`` are equivalent. To change this, | |
| 15 set ``App.case_insensitive`` to False. | |
| 16 | |
| 17 Whether or not you set ``case_insensitive``, *please do not* define | |
| 18 command method names with any uppercase letters. ``cmd2`` will probably | |
| 19 do something evil if you do. | |
| 20 | |
| 21 Multiline commands | |
| 22 ================== | |
| 23 | |
| 24 Like cmd_, ``cmd2`` assumes that a line break ends any command. | |
| 25 However, ``App.multilineCommands`` is a list of commands that are assumed to span | |
| 26 multiple lines. For these commands | |
| 27 | |
| 28 ``cmd2.Cmd.multilineCommands`` defaults to [], so you may set your own list | |
| 29 of multiline command names (without ``do_``):: | |
| 30 | |
| 31 class App(Cmd): | |
| 32 multilineCommands = ['lenghtycommand'] | |
| 33 def do_lengthycommand(self, args): | |
|
325
4172feeddf76
want to incorporate run() for tests - not yet working
catherine@dellzilla
parents:
324
diff
changeset
|
34 # ... |
| 324 | 35 |
| 331 | 36 |
| 324 | 37 Shortcuts |
| 38 ========= | |
| 39 | |
| 40 Special-character shortcuts for common commands can make life more convenient for your | |
| 41 users. Shortcuts are used without a space separating them from their arguments, | |
| 42 like ``!ls``. By default, the following shortcuts are defined: | |
| 43 | |
| 44 ``?`` | |
| 45 help | |
| 46 | |
| 47 ``!`` | |
| 48 shell: run as OS-level command | |
| 49 | |
| 50 ``@`` | |
| 51 load script file | |
| 52 | |
| 53 ``@@`` | |
| 54 load script file; filename is relative to current script location | |
| 55 | |
| 56 To define more shortcuts, update the dict ``App.shortcuts`` with the | |
| 57 {'shortcut': 'command_name'} (omit ``do_``):: | |
| 58 | |
| 59 class App(Cmd2): | |
| 60 Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'}) | |
| 61 | |
| 331 | 62 Default to shell |
| 63 ================ | |
| 64 | |
| 65 Every ``cmd2`` application can execute operating-system | |
| 66 level (shell) commands with ``shell`` or a ``!`` | |
| 67 shortcut:: | |
| 68 | |
| 69 (Cmd) shell which python | |
| 70 /usr/bin/python | |
| 71 (Cmd) !which python | |
| 72 /usr/bin/python | |
| 73 | |
| 74 However, if the parameter ``default_to_shell`` is | |
| 75 ``True``, then *every* command will be attempted on | |
| 76 the operating system. Only if that attempt fails | |
| 77 (i.e., produces a nonzero return value) will the | |
| 78 application's own ``default`` method be called. | |
| 79 | |
| 80 :: | |
| 81 | |
| 82 (Cmd) which python | |
| 83 /usr/bin/python | |
| 84 (Cmd) my dog has fleas | |
| 85 sh: my: not found | |
| 86 *** Unknown syntax: my dog has fleas | |
| 87 | |
| 324 | 88 Timing |
| 89 ====== | |
| 90 | |
| 91 Setting ``App.timing`` to ``True`` outputs timing data after | |
| 92 every application command is executed. |settable| | |
| 93 | |
| 94 Debug | |
| 95 ===== | |
| 96 | |
| 97 Setting ``App.debug`` to ``True`` will produce detailed error stacks | |
| 98 whenever the application generates an error. |settable| | |
| 99 | |
| 100 .. |settable| replace:: The user can ``set`` this parameter | |
| 101 during application execution. | |
| 102 (See :ref:`parameters`) | |
| 103 | |
| 104 Settability | |
| 105 =========== | |
| 106 | |
| 107 If you wish the user to be able to set one of these | |
| 108 application-controlling attributes while the application | |
| 109 is running, add its name to ``App.settable``. See | |
| 110 :ref:`parameters`. | |
| 111 | |
| 331 | 112 Other user-settable parameters |
| 113 ============================== | |
| 114 | |
| 115 A list of all user-settable parameters, with brief | |
| 116 comments, is viewable from within a running application | |
| 117 with:: | |
| 118 | |
| 119 (Cmd) set --long | |
| 120 |