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
|
Settings
========
- current settings and what they do
- how a developer can add their own
- how to hide built in settings from a user
Built In Settings
-----------------
``cmd2`` has a number of built in settings, which a developer can set a default
value, and which users can modify to change the behavior of the application.
A list of all user-settable parameters, with brief comments, is viewable from
within a running application::
(Cmd) set --long
allow_ansi: Terminal # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
continuation_prompt: > # On 2nd+ line of input
debug: False # Show full error stack on error
echo: False # Echo command issued into output
editor: vim # Program used by ``edit``
feedback_to_output: False # include nonessentials in `|`, `>` results
locals_in_py: False # Allow access to your application in py via self
max_completion_items: 50 # Maximum number of CompletionItems to display during tab completion
prompt: (Cmd) # The prompt issued to solicit input
quiet: False # Don't print nonessential feedback
timing: False # Report execution times
Any of these user-settable parameters can be set while running your app with
the ``set`` command like so::
(Cmd) set allow_ansi Never
allow_ansi
~~~~~~~~~~
The ``allow_ansi`` setting controls the behavior of ANSI escape sequences
in output generated with any of the following methods:
- ``poutput()``
- ``perror()``
- ``pwarning()``
- ``pfeedback()``
- ``ppaged()``
This setting can be one of three values:
- ``Never`` - all ANSI escape sequences which instruct the terminal to colorize
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, regardless
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.
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`.
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
~~~~~~
Setting ``App.timing`` to ``True`` outputs timing data after every application
command is executed. |settable|
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 Built-in Settings
----------------------
|
