annotate docs/settingchanges.rst @ 359:5b95dacca46e

remove ex2
author catherine@Drou
date Thu, 18 Feb 2010 01:15:39 -0500
parents 92a15405ed8a
children
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``.
338
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
7 A parameter can also be changed at runtime by the user *if*
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
8 its name is included in the dictionary ``app.settable``.
328
7b2bca3951a7 locals_in_py
cat@eee
parents: 325
diff changeset
9 (To define your own user-settable parameters, see :ref:`parameters`)
315
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
10
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
11 Case-insensitivity
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
12 ==================
a08c50b7d3d3 doc skeleton
cat@eee
parents:
diff changeset
13
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
14 By default, all ``cmd2`` command names are case-insensitive;
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
15 ``sing the blues`` and ``SiNg the blues`` are equivalent. To change this,
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
16 set ``App.case_insensitive`` to False.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
17
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
18 Whether or not you set ``case_insensitive``, *please do not* define
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
19 command method names with any uppercase letters. ``cmd2`` will probably
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
20 do something evil if you do.
331
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
21
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
22 Shortcuts
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
23 =========
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
24
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
25 Special-character shortcuts for common commands can make life more convenient for your
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
26 users. Shortcuts are used without a space separating them from their arguments,
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
27 like ``!ls``. By default, the following shortcuts are defined:
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
28
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
29 ``?``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
30 help
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
31
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
32 ``!``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
33 shell: run as OS-level command
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
34
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
35 ``@``
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
36 load script file
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 load script file; filename is relative to current script location
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
40
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
41 To define more shortcuts, update the dict ``App.shortcuts`` with the
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
42 {'shortcut': 'command_name'} (omit ``do_``)::
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
43
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
44 class App(Cmd2):
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
45 Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
46
331
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
47 Default to shell
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
48 ================
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
49
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
50 Every ``cmd2`` application can execute operating-system
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
51 level (shell) commands with ``shell`` or a ``!``
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
52 shortcut::
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
53
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
54 (Cmd) shell which python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
55 /usr/bin/python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
56 (Cmd) !which python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
57 /usr/bin/python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
58
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
59 However, if the parameter ``default_to_shell`` is
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
60 ``True``, then *every* command will be attempted on
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
61 the operating system. Only if that attempt fails
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
62 (i.e., produces a nonzero return value) will the
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
63 application's own ``default`` method be called.
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
64
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
65 ::
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
66
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
67 (Cmd) which python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
68 /usr/bin/python
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
69 (Cmd) my dog has fleas
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
70 sh: my: not found
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
71 *** Unknown syntax: my dog has fleas
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
72
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
73 Timing
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
74 ======
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
75
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
76 Setting ``App.timing`` to ``True`` outputs timing data after
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
77 every application command is executed. |settable|
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
78
338
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
79 Echo
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
80 ====
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
81
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
82 If ``True``, each command the user issues will be repeated
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
83 to the screen before it is executed. This is particularly
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
84 useful when running scripts.
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
85
324
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
86 Debug
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 Setting ``App.debug`` to ``True`` will produce detailed error stacks
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
90 whenever the application generates an error. |settable|
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
91
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
92 .. |settable| replace:: The user can ``set`` this parameter
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
93 during application execution.
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
94 (See :ref:`parameters`)
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
95
21584174d865 make SHOW TABLES work
catherine@dellzilla
parents: 315
diff changeset
96
331
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
97 Other user-settable parameters
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
98 ==============================
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
99
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
100 A list of all user-settable parameters, with brief
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
101 comments, is viewable from within a running application
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
102 with::
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
103
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
104 (Cmd) set --long
338
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
105 abbrev: True # Accept abbreviated commands
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
106 case_insensitive: True # upper- and lower-case both OK
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
107 colors: True # Colorized output (*nix only)
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
108 continuation_prompt: > # On 2nd+ line of input
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
109 debug: False # Show full error stack on error
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
110 default_file_name: command.txt # for ``save``, ``load``, etc.
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
111 echo: False # Echo command issued into output
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
112 editor: gedit # Program used by ``edit``
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
113 feedback_to_output: False # include nonessentials in `|`, `>` results
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
114 prompt: (Cmd) #
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
115 quiet: False # Don't print nonessential feedback
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
116 timing: False # Report execution times
92a15405ed8a example changing print to 2.6'
catherine@Drou
parents: 331
diff changeset
117
331
6306edc46a6e more docs
cat@eee
parents: 328
diff changeset
118