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.Cmd` and must also appear in the :attr:`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 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 running a 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.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.Cmd.poutput`. 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. 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. In your initialization code: 1. Create an instance attribute with a default value. 2. Create a :class:`.Settable` object which describes your setting. 3. Pass the :class:`.Settable` object to :meth:`cmd2.Cmd.add_settable`. 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 be sure to supply a method to the ``onchange_cb`` parameter of the `.cmd2.utils.Settable`. 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 | grep sunny sunny False Is it sunny outside? (Cmd) set | 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.Cmd.settable` dictionary in order for it to be available to the :ref:`features/builtin_commands:set` command. Let's say that you never want end users of your program to be able to enable full debug tracebacks to print out if an error occurs. You might want to hide the :ref:`features/settings:debug` setting. To do so, remove it from the :attr:`cmd2.Cmd.settable` dictionary after you initialize your object. The :meth:`cmd2.Cmd.remove_settable` convenience method makes this easy:: class MyApp(cmd2.Cmd): def __init__(self): super().__init__() self.remove_settable('debug')