Document hiding and disabling commands

For #765

Author: kotfu

docs/examples/index.rst

@@ -5,5 +5,4 @@ Examples
    :maxdepth: 1
 
    first_app
-   remove_builtin_commands
    alternate_event_loops

docs/examples/remove_builtin_commands.rst

@@ -140,8 +140,12 @@ Exit Codes
 ``cmd2`` has basic infrastructure to support sh/ksh/csh/bash type exit codes.
 The ``cmd2.Cmd`` object sets an ``exit_code`` attribute to zero when it is
 instantiated. The value of this attribute is returned from the ``cmdloop()``
-call, so if you want to get an exit code back to the operating system shell,
-you can do so like this::
+call. Therefore, if you don't do anything with this attribute in your code,
+``cmdloop()`` will (almost) always return zero. There are a few built-in
+``cmd2`` commands which set ``exit_code`` to ``-1`` if an error occers.
+
+You can use this capability to easily return your own values to the operating
+system shell::
 
     #!/usr/bin/env python
     """A simple cmd2 application."""
@@ -183,9 +187,12 @@ name and message. If `debug` is `true`, ``cmd2`` will display a traceback, and
 then display the exception name and message.
 
 
-Remove Built-in Commands
-------------------------
+Disabling or Hiding Commands
+----------------------------
+
+See :ref:`features/disable_commands:Disabling Commands` for details of how
+to:
 
-See the :ref:`examples/remove_builtin_commands:Remove Built-in Commands`
-example for information on hiding or removing commands included in ``cmd2``
-which you might not want in your application.
+- removing commands included in ``cmd2``
+- hiding commands from the help menu
+- disabling and re-enabling commands at runtime

docs/features/commands.rst

@@ -1,4 +1,103 @@
 Disabling Commands
 ==================
 
-How to disable and re-enable commands, by individual command and by category
+``cmd2`` allows a developer to:
+
+- remove commands included in ``cmd2``
+- prevent commands from appearing in the help menu (hiding commands)
+- disable and re-enable commands at runtime
+
+
+Remove A Command
+----------------
+
+When a command has been removed, the command method has been deleted from the
+object. The command doesn't show up in help, and it can't be executed. This
+approach is appropriate if you never want a built-in command to be part of your
+application. Delete the command method in your initialization code::
+
+    class RemoveBuiltinCommand(cmd2.Cmd):
+        """An app which removes a built-in command from cmd2"""
+
+        def __init__(self):
+            super().__init__()
+            # To remove built-in commands entirely, delete
+            # the "do_*" function from the cmd2.Cmd class
+            del cmd2.Cmd.do_edit
+
+
+Hide A Command
+--------------
+
+When a command is hidden, it won't show up in the help menu, but if
+the user knows it's there and types the command, it will be executed.
+You hide a command by adding it to the ``hidden_commands`` list::
+
+    class HiddenCommands(cmd2.Cmd):
+        ""An app which demonstrates how to hide a command"""
+        def __init__(self):
+            super().__init__()
+            self.hidden_commands.append('py')
+
+As shown above, you would typically do this as part of initializing your
+application. If you decide you want to unhide a command later in the execution
+of your application, you can by doing::
+
+    self.hidden_commands = [cmd for cmd in self.hidden_commands if cmd != 'py']
+
+You might be thinking that the list comprehension is overkill and you'd rather
+do something like::
+
+    self.hidden_commands.remove('py')
+
+You may be right, but ``remove()`` will raise a ``ValueError`` if ``py``
+isn't in the list, and it will only remove the first one if it's in the list
+multiple times.
+
+
+Disable A Command
+-----------------
+
+One way to disable a command is to add code to the command method which
+determines whether the command should be executed or not. If the command should
+not be executed, your code can print an appropriate error message and return.
+
+``cmd2`` also provides another way to accomplish the same thing. Here's a
+simple app which disables the ``open`` command if the door is locked::
+
+    class DisabledCommands(cmd2.Cmd):
+        """An application which disables and enables commands"""
+
+        def do_lock(self, line):
+            self.disable_command('open', "you can't open the door because it is locked")
+            self.poutput('the door is locked')
+
+        def do_unlock(self, line):
+            self.enable_command('open')
+            self.poutput('the door is unlocked')
+
+        def do_open(self, line):
+            """open the door"""
+            self.poutput('opening the door')
+
+This method has the added benefit of removing disabled commands from the help
+menu. But, this method only works if you know in advance that the command
+should be disabled, and if the conditions for re-enabling it are likewise known
+in advance.
+
+
+Disable A Category of Commands
+------------------------------
+
+You can group or categorize commands as shown in
+:ref:`features/help:Categorizing Commands`. If you do so, you can disable and
+enable all the commands in a category with a single method call. Say you have
+created a category of commands called "Server Information". You can disable
+all commands in that category::
+
+    not_connected_msg = 'You must be connected to use this command'
+    self.disable_category('Server Information', not_connected_msg)
+
+Similarly, you can re-enable all the commands in a category::
+
+    self.enable_category('Server Information')

docs/features/disable_commands.rst

@@ -7,8 +7,8 @@ Use ``help_method()`` to custom roll your own help messages.
 
 See :ref:`features/argument_processing:Help Messages`
 
-Grouping Commands
------------------
+Categorizing Commands
+---------------------
 
 By default, the ``help`` command displays::