1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
Settings
========
Settings provide a mechanism for a user to control the behavior of a ``cmd2``
based application. A setting is stored in an instance attribute on your
subclass of :class:`cmd2.cmd2.Cmd` and must also appear in the
:attr:`cmd2.cmd2.Cmd.settable` dictionary. Developers may set default values
for these settings and users can modify them at runtime using the
:ref:`features/builtin_commands:set` command. Developers can
:ref:`features/settings:Create New Settings` and can also
:ref:`features/settings:Hide Builtin Settings` from the user.
Builtin Settings
-----------------
``cmd2`` has a number of builtin settings. These settings control the behavior
of certain application features and :ref:`features/builtin_commands:Builtin
Commands`. Users can use the :ref:`features/builtin_commands:set` command to
show all settings and to modify the value of any setting.
allow_style
~~~~~~~~~~~
Output generated by ``cmd2`` programs may contain ANSI escape seqences which
instruct the terminal to apply colors or text styling (i.e. bold) to the
output. The ``allow_style`` setting controls the behavior of these escape
sequences in output generated with any of the following methods:
- :meth:`.cmd2.Cmd.poutput`
- :meth:`.cmd2.Cmd.perror`
- :meth:`.cmd2.Cmd.pwarning`
- :meth:`.cmd2.Cmd.pexcept`
- :meth:`.cmd2.Cmd.pfeedback`
- :meth:`.cmd2.Cmd.ppaged`
This setting can be one of three values:
- ``Never`` - all ANSI escape sequences which instruct the terminal to style
output are stripped from the output.
- ``Terminal`` - (the default value) pass through ANSI escape sequences when
the output is being sent to the terminal, but if the output is redirected to
a pipe or a file the escape sequences are stripped.
- ``Always`` - ANSI escape sequences are always passed through to the output
continuation_prompt
~~~~~~~~~~~~~~~~~~~
When a user types a :ref:`Multiline Command
<features/multiline_commands:Multiline Commands>` it may span more than one
line of input. The prompt for the first line of input is specified by the
:ref:`features/settings:prompt` setting. The prompt for subsequent lines of
input is defined by this setting.
debug
~~~~~
The default value of this setting is ``False``, which causes the
:meth:`~.cmd2.Cmd.pexcept` method to only display the message from an
exception. However, if the debug setting is ``True``, then the entire stack
trace will be printed.
echo
~~~~
If ``True``, each command the user issues will be repeated to the screen before
it is executed. This is particularly useful when running scripts. This behavior
does not occur when a running command at the prompt.
editor
~~~~~~
Similar to the ``EDITOR`` shell variable, this setting contains the name of the
program which should be run by the :ref:`features/builtin_commands:edit`
command.
feedback_to_output
~~~~~~~~~~~~~~~~~~
Controls whether feedback generated with the :meth:`~cmd2.cmd2.Cmd.pfeedback`
method is sent to ``sys.stdout`` or ``sys.stderr``. If ``False`` the output
will be sent to ``sys.stderr``
If ``True`` the output is sent to ``stdout`` (which is often the screen but may
be :ref:`redirected <features/redirection:Output Redirection and Pipes>`). The
feedback output will be mixed in with and indistinguishable from output
generated with :meth:`~cmd2.cmd2.Cmd.poutput`.
locals_in_py
~~~~~~~~~~~~
Allow access to your application in one of the
:ref:`features/embedded_python_shells:Embedded Python Shells` via ``self``.
max_completion_items
~~~~~~~~~~~~~~~~~~~~
Maximum number of CompletionItems to display during tab completion. A CompletionItem
is a special kind of tab-completion hint which displays both a value and description
and uses one line for each hint. Tab complete the ``set`` command for an example.
If the number of tab-completion hints exceeds ``max_completion_items``, then they will
be displayed in the typical columnized format and will not include the description text
of the CompletionItem.
prompt
~~~~~~
This setting contains the string which should be printed as a prompt for user
input.
quiet
~~~~~
If ``True``, output generated by calling :meth:`~.cmd2.Cmd.pfeedback` is
suppressed. If ``False``, the :ref:`features/settings:feedback_to_output`
setting controls where the output is sent.
timing
~~~~~~
If ``True``, the elapsed time is reported for each command executed.
Create New Settings
-------------------
Your application can define user-settable parameters which your code can
reference. First create a class attribute with the default value. Then update
the ``settable`` dictionary with your setting name and a short description
before you initialize the superclass. Here's an example, from
``examples/environment.py``:
.. literalinclude:: ../../examples/environment.py
If you want to be notified when a setting changes (as we do above), then define
a method ``_onchange_{setting}()``. This method will be called after the user
changes a setting, and will receive both the old value and the new value.
.. code-block:: text
(Cmd) set --long | grep sunny
sunny: False # Is it sunny outside?
(Cmd) set --long | grep degrees
degrees_c: 22 # Temperature in Celsius
(Cmd) sunbathe
Too dim.
(Cmd) set degrees_c 41
degrees_c - was: 22
now: 41
(Cmd) set sunny
sunny: True
(Cmd) sunbathe
UV is bad for your skin.
(Cmd) set degrees_c 13
degrees_c - was: 41
now: 13
(Cmd) sunbathe
It's 13 C - are you a penguin?
Hide Builtin Settings
----------------------
You may want to prevent a user from modifying a builtin setting. A setting
must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it
to be available to the :ref:`features/builtin_commands:set` command.
Let's say your program does not have any
:ref:`features/multiline_commands:Multiline Commands`. You might want to hide
the :ref:`features/settings:continuation_prompt` setting from your users since
it is only applicable to multiline commands. To do so, remove it from the
:attr:`cmd2.cmd2.Cmd.settable` dictionary after you initialize your object::
class MyApp(cmd2.Cmd):
def __init__(self):
super().__init__()
self.settable.pop('continuation_prompt')
|
