diff options
Diffstat (limited to 'docs/features/settings.rst')
| -rw-r--r-- | docs/features/settings.rst | 33 |
1 files changed, 16 insertions, 17 deletions
diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 40b9bc35..5a4a9c0f 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -3,8 +3,8 @@ 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 +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 @@ -28,12 +28,12 @@ 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` +- :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: @@ -51,7 +51,7 @@ debug ~~~~~ The default value of this setting is ``False``, which causes the -:meth:`~.cmd2.Cmd.pexcept` method to only display the message from an +: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. @@ -75,14 +75,14 @@ command. feedback_to_output ~~~~~~~~~~~~~~~~~~ -Controls whether feedback generated with the :meth:`~cmd2.cmd2.Cmd.pfeedback` +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 <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`. +generated with :meth:`~cmd2.Cmd.poutput`. max_completion_items @@ -101,7 +101,7 @@ the description text of the CompletionItem. quiet ~~~~~ -If ``True``, output generated by calling :meth:`~.cmd2.Cmd.pfeedback` is +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. @@ -120,8 +120,7 @@ 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.cmd2.Cmd.add_settable`. +3. Pass the :class:`.Settable` object to :meth:`cmd2.Cmd.add_settable`. Here's an example, from ``examples/environment.py``: @@ -159,14 +158,14 @@ 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 +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:: +: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): |