From 40722f10ace3107dcb4709008239ac8233ada30f Mon Sep 17 00:00:00 2001 From: Todd Leonhardt Date: Tue, 4 Feb 2020 23:01:30 -0500 Subject: Added cmd2.utils.Settable to the cmd2 namespace and updated examples and docs --- docs/features/initialization.rst | 7 +++++-- docs/features/plugins.rst | 4 ++-- docs/features/settings.rst | 4 ++-- 3 files changed, 9 insertions(+), 6 deletions(-) (limited to 'docs/features') diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 46b4ecd2..d48290fa 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -20,7 +20,7 @@ capabilities which you may wish to utilize while initializing the app:: """ import cmd2 from cmd2 import style - + from cmd2.ansi import FG_COLORS class BasicApp(cmd2.Cmd): CUSTOM_CATEGORY = 'My Custom Commands' @@ -48,7 +48,10 @@ capabilities which you may wish to utilize while initializing the app:: self.foreground_color = 'cyan' # Make echo_fg settable at runtime - self.settable['foreground_color'] = 'Foreground color to use with echo command' + self.add_settable(cmd2.Settable('foreground_color', + str, + 'Foreground color to use with echo command', + choices=FG_COLORS)) @cmd2.with_category(CUSTOM_CATEGORY) def do_intro(self, _): diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst index caa46b8c..00c0a9f0 100644 --- a/docs/features/plugins.rst +++ b/docs/features/plugins.rst @@ -82,10 +82,10 @@ example:: super().__init__(*args, **kwargs) # code placed here runs after cmd2.Cmd initializes self.mysetting = 'somevalue' - self.settable.update({'mysetting': 'short help message for mysetting'}) + self.add_settable(cmd2.Settable('mysetting', str, 'short help message for mysetting')) You can also hide settings from the user by removing them from -``self.settable``. +``self.settables``. Decorators ~~~~~~~~~~ diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 55b6a10d..6a8996e1 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -150,7 +150,7 @@ changes a setting, and will receive both the old value and the new value. 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 @@ -165,4 +165,4 @@ the :ref:`features/settings:debug` setting. To do so, remove it from the def __init__(self): super().__init__() - self.settable.pop('debug') + self.settables.pop('debug') -- cgit v1.2.1 From f3285c801791b46acb4a3ddd0ef372316f314151 Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Wed, 5 Feb 2020 17:06:15 -0500 Subject: Updated help text --- docs/features/builtin_commands.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/features') diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst index 025149b3..83d3176d 100644 --- a/docs/features/builtin_commands.rst +++ b/docs/features/builtin_commands.rst @@ -93,10 +93,10 @@ within a running application: (Cmd) set --long allow_style: Terminal # Allow ANSI text style sequences in output (valid values: Terminal, Always, Never) - debug: False # Show full error stack on error + debug: False # Show full traceback on exception echo: False # Echo command issued into output - editor: vim # Program used by ``edit`` - feedback_to_output: False # include nonessentials in `|`, `>` results + editor: vim # Program used by 'edit' + feedback_to_output: False # include nonessentials in '|', '>' results max_completion_items: 50 # Maximum number of CompletionItems to display during tab completion quiet: False # Don't print nonessential feedback timing: False # Report execution times -- cgit v1.2.1 From f254f4a9acd5e946892e86315e8313b3181dbb6e Mon Sep 17 00:00:00 2001 From: Kevin Van Brunt Date: Wed, 5 Feb 2020 20:55:07 -0500 Subject: Updated documentation --- docs/features/settings.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/features') diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 6a8996e1..23c7686d 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -165,4 +165,4 @@ the :ref:`features/settings:debug` setting. To do so, remove it from the def __init__(self): super().__init__() - self.settables.pop('debug') + self.remove_settable('debug') -- cgit v1.2.1 From 7476c27e95b6a9c1ee1c93893d678012c019cf7c Mon Sep 17 00:00:00 2001 From: kotfu Date: Wed, 5 Feb 2020 20:56:29 -0700 Subject: Documentation updates --- docs/features/settings.rst | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) (limited to 'docs/features') diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 23c7686d..40b9bc35 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.cmd2.Cmd` and must also appear in the -:attr:`cmd2.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 @@ -116,15 +116,21 @@ 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 +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`. + +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 +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 @@ -153,13 +159,14 @@ 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 +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.cmd2.Cmd.settable` dictionary after you initialize your object:: +: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): -- cgit v1.2.1