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
|
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
Timing
~~~~~~
Setting ``App.timing`` to ``True`` outputs timing data after every application
command is executed. |settable|
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.
Debug
~~~~~
Setting ``App.debug`` to ``True`` will produce detailed error stacks whenever
the application generates an error. |settable|
.. |settable| replace:: The user can ``set`` this parameter
during application execution.
(See :ref:`parameters`)
.. _parameters:
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
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
----------------------
|
