diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/argument_processing.rst | 132 | ||||
| -rw-r--r-- | docs/unfreefeatures.rst | 162 |
2 files changed, 162 insertions, 132 deletions
diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst index 4c77fa80..bad683bf 100644 --- a/docs/argument_processing.rst +++ b/docs/argument_processing.rst @@ -195,138 +195,6 @@ Which yields: .. _argparse: https://docs.python.org/3/library/argparse.html -Grouping Commands -================= - -By default, the ``help`` command displays:: - - Documented commands (type help <topic>): - ======================================== - alias findleakers pyscript sessions status vminfo - config help quit set stop which - connect history redeploy shell thread_dump - deploy list resources shortcuts unalias - edit load restart sslconnectorciphers undeploy - expire py serverinfo start version - -If you have a large number of commands, you can optionally group your commands into categories. -Here's the output from the example ``help_categories.py``:: - - Documented commands (type help <topic>): - - Application Management - ====================== - deploy findleakers redeploy sessions stop - expire list restart start undeploy - - Connecting - ========== - connect which - - Server Information - ================== - resources serverinfo sslconnectorciphers status thread_dump vminfo - - Other - ===== - alias edit history py quit shell unalias - config help load pyscript set shortcuts version - - -There are 2 methods of specifying command categories, using the ``@with_category`` decorator or with the -``categorize()`` function. Once a single command category is detected, the help output switches to a categorized -mode of display. All commands with an explicit category defined default to the category `Other`. - -Using the ``@with_category`` decorator:: - - @with_category(CMD_CAT_CONNECTING) - def do_which(self, _): - """Which command""" - self.poutput('Which') - -Using the ``categorize()`` function: - - You can call with a single function:: - - def do_connect(self, _): - """Connect command""" - self.poutput('Connect') - - # Tag the above command functions under the category Connecting - categorize(do_connect, CMD_CAT_CONNECTING) - - Or with an Iterable container of functions:: - - def do_undeploy(self, _): - """Undeploy command""" - self.poutput('Undeploy') - - def do_stop(self, _): - """Stop command""" - self.poutput('Stop') - - def do_findleakers(self, _): - """Find Leakers command""" - self.poutput('Find Leakers') - - # Tag the above command functions under the category Application Management - categorize((do_undeploy, - do_stop, - do_findleakers), CMD_CAT_APP_MGMT) - -The ``help`` command also has a verbose option (``help -v`` or ``help --verbose``) that combines -the help categories with per-command Help Messages:: - - Documented commands (type help <topic>): - - Application Management - ================================================================================ - deploy Deploy command - expire Expire command - findleakers Find Leakers command - list List command - redeploy Redeploy command - restart usage: restart [-h] {now,later,sometime,whenever} - sessions Sessions command - start Start command - stop Stop command - undeploy Undeploy command - - Connecting - ================================================================================ - connect Connect command - which Which command - - Server Information - ================================================================================ - resources Resources command - serverinfo Server Info command - sslconnectorciphers SSL Connector Ciphers command is an example of a command that contains - multiple lines of help information for the user. Each line of help in a - contiguous set of lines will be printed and aligned in the verbose output - provided with 'help --verbose' - status Status command - thread_dump Thread Dump command - vminfo VM Info command - - Other - ================================================================================ - alias Define or display aliases - config Config command - edit Edit a file in a text editor - help List available commands with "help" or detailed help with "help cmd" - history usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg] - load Runs commands in script file that is encoded as either ASCII or UTF-8 text - py Invoke python command, shell, or script - pyscript Runs a python script file inside the console - quit Exits this application - set usage: set [-h] [-a] [-l] [settable [settable ...]] - shell Execute a command as if at the OS prompt - shortcuts Lists shortcuts available - unalias Unsets aliases - version Version command - - Receiving an argument list ========================== diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 2cdc17ba..97953215 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -237,3 +237,165 @@ set_window_title() The easiest way to understand these functions is to see the AsyncPrinting_ example for a demonstration. .. _AsyncPrinting: https://github.com/python-cmd2/cmd2/blob/master/examples/async_printing.py + + +Grouping Commands +================= + +By default, the ``help`` command displays:: + + Documented commands (type help <topic>): + ======================================== + alias findleakers pyscript sessions status vminfo + config help quit set stop which + connect history redeploy shell thread_dump + deploy list resources shortcuts unalias + edit load restart sslconnectorciphers undeploy + expire py serverinfo start version + +If you have a large number of commands, you can optionally group your commands into categories. +Here's the output from the example ``help_categories.py``:: + + Documented commands (type help <topic>): + + Application Management + ====================== + deploy findleakers redeploy sessions stop + expire list restart start undeploy + + Connecting + ========== + connect which + + Server Information + ================== + resources serverinfo sslconnectorciphers status thread_dump vminfo + + Other + ===== + alias edit history py quit shell unalias + config help load pyscript set shortcuts version + + +There are 2 methods of specifying command categories, using the ``@with_category`` decorator or with the +``categorize()`` function. Once a single command category is detected, the help output switches to a categorized +mode of display. All commands with an explicit category defined default to the category `Other`. + +Using the ``@with_category`` decorator:: + + @with_category(CMD_CAT_CONNECTING) + def do_which(self, _): + """Which command""" + self.poutput('Which') + +Using the ``categorize()`` function: + + You can call with a single function:: + + def do_connect(self, _): + """Connect command""" + self.poutput('Connect') + + # Tag the above command functions under the category Connecting + categorize(do_connect, CMD_CAT_CONNECTING) + + Or with an Iterable container of functions:: + + def do_undeploy(self, _): + """Undeploy command""" + self.poutput('Undeploy') + + def do_stop(self, _): + """Stop command""" + self.poutput('Stop') + + def do_findleakers(self, _): + """Find Leakers command""" + self.poutput('Find Leakers') + + # Tag the above command functions under the category Application Management + categorize((do_undeploy, + do_stop, + do_findleakers), CMD_CAT_APP_MGMT) + +The ``help`` command also has a verbose option (``help -v`` or ``help --verbose``) that combines +the help categories with per-command Help Messages:: + + Documented commands (type help <topic>): + + Application Management + ================================================================================ + deploy Deploy command + expire Expire command + findleakers Find Leakers command + list List command + redeploy Redeploy command + restart usage: restart [-h] {now,later,sometime,whenever} + sessions Sessions command + start Start command + stop Stop command + undeploy Undeploy command + + Connecting + ================================================================================ + connect Connect command + which Which command + + Server Information + ================================================================================ + resources Resources command + serverinfo Server Info command + sslconnectorciphers SSL Connector Ciphers command is an example of a command that contains + multiple lines of help information for the user. Each line of help in a + contiguous set of lines will be printed and aligned in the verbose output + provided with 'help --verbose' + status Status command + thread_dump Thread Dump command + vminfo VM Info command + + Other + ================================================================================ + alias Define or display aliases + config Config command + edit Edit a file in a text editor + help List available commands with "help" or detailed help with "help cmd" + history usage: history [-h] [-r | -e | -s | -o FILE | -t TRANSCRIPT] [arg] + load Runs commands in script file that is encoded as either ASCII or UTF-8 text + py Invoke python command, shell, or script + pyscript Runs a python script file inside the console + quit Exits this application + set usage: set [-h] [-a] [-l] [settable [settable ...]] + shell Execute a command as if at the OS prompt + shortcuts Lists shortcuts available + unalias Unsets aliases + version Version command + + +Disabling Commands +================== + +``cmd2`` supports disabling commands during runtime. This is useful if certain commands should only be available +when the application is in a specific state. When a command is disabled, it will not show up in the help menu or +tab complete. If a user tries to run the command, a command-specific message supplied by the developer will be +printed. The following functions support this feature. + +enable_command() + Enable an individual command + +enable_category() + Enable an entire category of commands + +disable_command() + Disable an individual command and set the message that will print when this command is run or help is called + on it while disabled + +disable_category() + Disable an entire category of commands and set the message that will print when anything in this category is + run or help is called on it while disabled + +See the definitions of these functions for descriptions of their arguments. + +See the ``do_enable_commands()`` and ``do_disable_commands()`` functions in the HelpCategories_ example for +a demonstration. + +.. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py |