annotate docs/settingchanges.rst @ 325:4172feeddf76

want to incorporate run() for tests - not yet working
author catherine@dellzilla
date Thu, 11 Feb 2010 17:03:45 -0500
parents 21584174d865
children 7b2bca3951a7
rev   line source
315
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
1 =========================================
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
2 Features requiring only parameter changes
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
3 =========================================
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
4
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
5 Several aspects of a ``cmd2`` application's behavior
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
6 can be controlled simply by setting attributes of ``App``.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
7
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
8 (To define your own user-settable parameters, see :ref:`parameters`
315
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
9
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
10 Case-insensitivity
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
11 ==================
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
12
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
13 By default, all ``cmd2`` command names are case-insensitive;
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
14 ``sing the blues`` and ``SiNg the blues`` are equivalent. To change this,
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
15 set ``App.case_insensitive`` to False.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
16
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
17 Whether or not you set ``case_insensitive``, *please do not* define
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
18 command method names with any uppercase letters. ``cmd2`` will probably
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
19 do something evil if you do.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
20
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
21 Multiline commands
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
22 ==================
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
23
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
24 Like cmd_, ``cmd2`` assumes that a line break ends any command.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
25 However, ``App.multilineCommands`` is a list of commands that are assumed to span
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
26 multiple lines. For these commands
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
27
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
28 ``cmd2.Cmd.multilineCommands`` defaults to [], so you may set your own list
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
29 of multiline command names (without ``do_``)::
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
30
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
31 class App(Cmd):
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
32 multilineCommands = ['lenghtycommand']
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
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
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
35
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
36 Shortcuts
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
37 =========
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
38
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
39 Special-character shortcuts for common commands can make life more convenient for your
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
40 users. Shortcuts are used without a space separating them from their arguments,
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
41 like ``!ls``. By default, the following shortcuts are defined:
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
42
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
43 ``?``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
44 help
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
45
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
46 ``!``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
47 shell: run as OS-level command
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
48
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
49 ``@``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
50 load script file
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
51
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
52 ``@@``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
53 load script file; filename is relative to current script location
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
54
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
55 To define more shortcuts, update the dict ``App.shortcuts`` with the
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
56 {'shortcut': 'command_name'} (omit ``do_``)::
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
57
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
58 class App(Cmd2):
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
59 Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
60
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
61 Timing
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
62 ======
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
63
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
64 Setting ``App.timing`` to ``True`` outputs timing data after
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
65 every application command is executed. |settable|
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
66
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
67 Debug
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
68 =====
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
69
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
70 Setting ``App.debug`` to ``True`` will produce detailed error stacks
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
71 whenever the application generates an error. |settable|
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
72
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
73 .. |settable| replace:: The user can ``set`` this parameter
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
74 during application execution.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
75 (See :ref:`parameters`)
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
76
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
77 .. _quiet:
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
78
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
79 Quiet
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
80 =====
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
81
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
82 Controls whether ``self.pfeedback('message')`` output is suppressed;
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
83 useful for non-essential feedback that the user may not always want
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
84 to read. Only relevant if :ref:`outputters` are used.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
85
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
86 Settability
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
87 ===========
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
88
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
89 If you wish the user to be able to set one of these
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
90 application-controlling attributes while the application
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
91 is running, add its name to ``App.settable``. See
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
92 :ref:`parameters`.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
93
315
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
94 Abbreviated commands
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
95 ====================