Added cmd2.utils.Settable to the cmd2 namespace and updated examples and docs

16 files changed, 45 insertions, 21 deletions

diff --git a/README.md b/README.md
index 7bec9734..19bd259b 100755
--- a/README.md
+++ b/README.md
@@ -229,7 +229,6 @@ import argparse
 import random
 import sys
 import cmd2
-from cmd2.utils import Settable
 
 class CmdLineApp(cmd2.Cmd):
     """ Example cmd2 application. """
@@ -249,7 +248,7 @@ class CmdLineApp(cmd2.Cmd):
         super().__init__(use_ipython=False, multiline_commands=['orate'], shortcuts=shortcuts)
         
         # Make maxrepeats settable at runtime
-        self.add_settable(Settable('maxrepeats', int, 'max repetitions for speak command'))
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
     speak_parser = argparse.ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
diff --git a/cmd2/__init__.py b/cmd2/__init__.py
index 8fc5e9f2..cc5a0963 100644
--- a/cmd2/__init__.py
+++ b/cmd2/__init__.py
@@ -27,3 +27,4 @@ from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS
 from .decorators import categorize, with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
 from .parsing import Statement
 from .py_bridge import CommandResult
+from .utils import Settable
diff --git a/docs/examples/first_app.rst b/docs/examples/first_app.rst
index 19d573b4..310c8d0c 100644
--- a/docs/examples/first_app.rst
+++ b/docs/examples/first_app.rst
@@ -67,7 +67,7 @@ initializer to our class::
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
 In that initializer, the first thing to do is to make sure we initialize
 ``cmd2``. That's what the ``super().__init__()`` line does. Then we create an
@@ -203,7 +203,7 @@ method so it looks like this::
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
 Shortcuts are passed to the ``cmd2`` initializer, and if you want the built-in
 shortcuts of ``cmd2`` you have to pass them. These shortcuts are defined as a
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')
diff --git a/examples/cmd_as_argument.py b/examples/cmd_as_argument.py
index 08643a50..b65bcbcb 100755
--- a/examples/cmd_as_argument.py
+++ b/examples/cmd_as_argument.py
@@ -36,7 +36,7 @@ class CmdLineApp(cmd2.Cmd):
         self.self_in_py = True
         self.maxrepeats = 3
         # Make maxrepeats settable at runtime
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
     speak_parser = argparse.ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
diff --git a/examples/colors.py b/examples/colors.py
index bbb3b2ad..33b17e53 100755
--- a/examples/colors.py
+++ b/examples/colors.py
@@ -39,7 +39,7 @@ class CmdLineApp(cmd2.Cmd):
 
         self.maxrepeats = 3
         # Make maxrepeats settable at runtime
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
         # Should ANSI color output be allowed
         self.allow_style = ansi.STYLE_TERMINAL
diff --git a/examples/decorator_example.py b/examples/decorator_example.py
index 4f68653e..0f5374ce 100755
--- a/examples/decorator_example.py
+++ b/examples/decorator_example.py
@@ -27,7 +27,7 @@ class CmdLineApp(cmd2.Cmd):
 
         self.maxrepeats = 3
         # Make maxrepeats settable at runtime
-        self.settable['maxrepeats'] = 'Max number of `--repeat`s allowed'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
         # Example of args set from the command-line (but they aren't being used here)
         self._ip = ip_addr
diff --git a/examples/environment.py b/examples/environment.py
index 9e611f08..fb90838c 100755
--- a/examples/environment.py
+++ b/examples/environment.py
@@ -8,16 +8,16 @@ import cmd2
 
 class EnvironmentApp(cmd2.Cmd):
     """ Example cmd2 application. """
-
     degrees_c = 22
     sunny = False
 
     def __init__(self):
         super().__init__()
-        self.settable.update({'degrees_c': 'Temperature in Celsius'})
-        self.settable.update({'sunny': 'Is it sunny outside?'})
+        self.add_settable(cmd2.Settable('degrees_c', int, 'Temperature in Celsius'))
+        self.add_settable(cmd2.Settable('sunny', bool, 'Is it sunny outside?'))
 
     def do_sunbathe(self, arg):
+        """Attempt to sunbathe."""
         if self.degrees_c < 20:
             result = "It's {} C - are you a penguin?".format(self.degrees_c)
         elif not self.sunny:
diff --git a/examples/example.py b/examples/example.py
index b8f8202c..0272a6e5 100755
--- a/examples/example.py
+++ b/examples/example.py
@@ -32,7 +32,7 @@ class CmdLineApp(cmd2.Cmd):
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
     speak_parser = argparse.ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
diff --git a/examples/first_app.py b/examples/first_app.py
index b5bd07e9..d8272e86 100755
--- a/examples/first_app.py
+++ b/examples/first_app.py
@@ -27,7 +27,7 @@ class FirstApp(cmd2.Cmd):
 
         # Make maxrepeats settable at runtime
         self.maxrepeats = 3
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
     speak_parser = argparse.ArgumentParser()
     speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
diff --git a/examples/initialization.py b/examples/initialization.py
index 32aa852f..c13ed137 100755
--- a/examples/initialization.py
+++ b/examples/initialization.py
@@ -14,6 +14,7 @@
 """
 import cmd2
 from cmd2 import style
+from cmd2.ansi import FG_COLORS
 
 
 class BasicApp(cmd2.Cmd):
@@ -42,7 +43,8 @@ class BasicApp(cmd2.Cmd):
         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/examples/pirate.py b/examples/pirate.py
index eda3994e..acbab17c 100755
--- a/examples/pirate.py
+++ b/examples/pirate.py
@@ -25,7 +25,7 @@ class Pirate(cmd2.Cmd):
         self.songcolor = 'blue'
 
         # Make songcolor settable at runtime
-        self.settable['songcolor'] = 'Color to ``sing`` in (black/red/green/yellow/blue/magenta/cyan/white)'
+        self.add_settable(cmd2.Settable('songcolor', str, 'Color to ``sing``', choices=cmd2.ansi.FG_COLORS))
 
         # prompts and defaults
         self.gold = 0
diff --git a/examples/plumbum_colors.py b/examples/plumbum_colors.py
index fe692805..94815f50 100755
--- a/examples/plumbum_colors.py
+++ b/examples/plumbum_colors.py
@@ -75,7 +75,7 @@ class CmdLineApp(cmd2.Cmd):
 
         self.maxrepeats = 3
         # Make maxrepeats settable at runtime
-        self.settable['maxrepeats'] = 'max repetitions for speak command'
+        self.add_settable(cmd2.Settable('maxrepeats', int, 'max repetitions for speak command'))
 
         # Should ANSI color output be allowed
         self.allow_style = ansi.STYLE_TERMINAL
diff --git a/examples/remove_settable.py b/examples/remove_settable.py
new file mode 100755
index 00000000..13a75e11
--- /dev/null
+++ b/examples/remove_settable.py
@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+# coding=utf-8
+"""
+A sample application for cmd2 demonstrating how to remove one of the built-in runtime settable parameters.
+"""
+import cmd2
+
+
+class MyApp(cmd2.Cmd):
+
+    def __init__(self):
+        super().__init__()
+        self.settables.pop('debug')
+
+
+if __name__ == '__main__':
+    import sys
+    c = MyApp()
+    sys.exit(c.cmdloop())