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 ` 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 `). 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')