diff options
| -rw-r--r-- | docs/examples/index.rst | 1 | ||||
| -rw-r--r-- | docs/examples/remove_builtin_commands.rst | 41 | ||||
| -rw-r--r-- | docs/features/commands.rst | 21 | ||||
| -rw-r--r-- | docs/features/disable_commands.rst | 101 | ||||
| -rw-r--r-- | docs/features/help.rst | 4 |
5 files changed, 116 insertions, 52 deletions
diff --git a/docs/examples/index.rst b/docs/examples/index.rst index f895059f..94a3e06f 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -5,5 +5,4 @@ Examples :maxdepth: 1 first_app - remove_builtin_commands alternate_event_loops diff --git a/docs/examples/remove_builtin_commands.rst b/docs/examples/remove_builtin_commands.rst deleted file mode 100644 index c3e73b0c..00000000 --- a/docs/examples/remove_builtin_commands.rst +++ /dev/null @@ -1,41 +0,0 @@ -Remove Built-in Commands -========================= - -``cmd2`` comes with a bunch of built-in commands. These commands add lots of -useful functionality, but you might not want them in your application. You can -either hide these commands, or remove them completely. - - -Hiding Commands ---------------- - -When a command is hidden, it is still available to run, but it won't show in -the help menu. To hide a command:: - - class HideBuiltinCommand(cmd2.Cmd): - """Hide a built-in command.""" - - def __init__(self): - super().__init__() - - # To prevent commands from displaying in the help menu - # add them to the hidden_commands list - self.hidden_commands.append('py') - - -Removing Commands ------------------ - -You can remove a command from your application is defined in ``cmd2.Cmd`` or -inherited from a :ref:`plugin <features/plugins:Plugins>`. Delete the -command method in your initialization code:: - - class RemoveBuiltinCommand(cmd2.Cmd): - """Remove an undesired built-in command.""" - - 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 diff --git a/docs/features/commands.rst b/docs/features/commands.rst index ab53e990..196944b5 100644 --- a/docs/features/commands.rst +++ b/docs/features/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 diff --git a/docs/features/disable_commands.rst b/docs/features/disable_commands.rst index b0f7f11b..78d214bb 100644 --- a/docs/features/disable_commands.rst +++ b/docs/features/disable_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') diff --git a/docs/features/help.rst b/docs/features/help.rst index 755d40f9..03e0867b 100644 --- a/docs/features/help.rst +++ b/docs/features/help.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:: |