diff options
| -rw-r--r-- | docs/features/clipboard.rst | 3 | ||||
| -rw-r--r-- | docs/features/completion.rst | 4 | ||||
| -rw-r--r-- | docs/features/disable_commands.rst | 4 | ||||
| -rw-r--r-- | docs/features/embedded_python_shells.rst | 4 | ||||
| -rw-r--r-- | docs/features/generating_output.rst | 8 | ||||
| -rw-r--r-- | docs/features/help.rst | 131 | ||||
| -rw-r--r-- | docs/features/history.rst | 8 | ||||
| -rw-r--r-- | docs/features/multiline.rst | 17 | ||||
| -rw-r--r-- | docs/features/os.rst | 10 | ||||
| -rw-r--r-- | docs/features/plugins.rst | 3 | ||||
| -rw-r--r-- | docs/features/prompt.rst | 35 | ||||
| -rw-r--r-- | docs/features/scripting.rst | 18 | ||||
| -rw-r--r-- | docs/features/settings.rst | 6 | ||||
| -rw-r--r-- | docs/features/shortcuts_aliases_macros.rst | 3 | ||||
| -rw-r--r-- | docs/features/startup_commands.rst | 2 | ||||
| -rw-r--r-- | docs/freefeatures.rst | 14 | ||||
| -rw-r--r-- | docs/index.rst | 13 | ||||
| -rw-r--r-- | docs/unfreefeatures.rst | 178 |
18 files changed, 266 insertions, 195 deletions
diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst new file mode 100644 index 00000000..0c69a279 --- /dev/null +++ b/docs/features/clipboard.rst @@ -0,0 +1,3 @@ +Clipboard Integration +===================== + diff --git a/docs/features/completion.rst b/docs/features/completion.rst new file mode 100644 index 00000000..c89b24cc --- /dev/null +++ b/docs/features/completion.rst @@ -0,0 +1,4 @@ +Completion +========== + +How tab completion works and how to implement it in your own project diff --git a/docs/features/disable_commands.rst b/docs/features/disable_commands.rst new file mode 100644 index 00000000..b0f7f11b --- /dev/null +++ b/docs/features/disable_commands.rst @@ -0,0 +1,4 @@ +Disabling Commands +================== + +How to disable and re-enable commands, by individual command and by category diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst new file mode 100644 index 00000000..ace68877 --- /dev/null +++ b/docs/features/embedded_python_shells.rst @@ -0,0 +1,4 @@ +Embedded Python Shells +====================== + +Describe ``py`` and optional ``ipy`` commands diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst index a4a928cf..1dab6f64 100644 --- a/docs/features/generating_output.rst +++ b/docs/features/generating_output.rst @@ -3,8 +3,10 @@ Generating Output how to generate output -poutput +- poutput +- perror +- paging +- exceptions +- color support -perror -paging diff --git a/docs/features/help.rst b/docs/features/help.rst index e5cc0451..37280bf0 100644 --- a/docs/features/help.rst +++ b/docs/features/help.rst @@ -6,3 +6,134 @@ use the categorize() function to create help categories Use ``help_method()`` to custom roll your own help messages. See :ref:`features/argument_processing:Help Messages` + +Grouping Commands +----------------- + +By default, the ``help`` command displays:: + + Documented commands (type help <topic>): + ======================================== + alias help ipy py run_pyscript set shortcuts + edit history macro quit run_script shell + +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 + + Command Management + ================== + disable_commands enable_commands + + Connecting + ========== + connect which + + Server Information + ================== + resources serverinfo sslconnectorciphers status thread_dump vminfo + + Other + ===== + alias edit history py run_pyscript set shortcuts + config help macro quit run_script shell 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] + py Invoke python command, shell, or script + quit Exits this application + run_pyscript Runs a python script file inside the console + run_script Runs commands in script file that is encoded as either ASCII or UTF-8 text + 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 + diff --git a/docs/features/history.rst b/docs/features/history.rst new file mode 100644 index 00000000..cbd3f3e6 --- /dev/null +++ b/docs/features/history.rst @@ -0,0 +1,8 @@ +Command History +=============== + +- Describe how cmd2 tracks history +- describe the uses of the built in history command +- how persistent history works +- differences in history and bash shell history (we only store valid commands in history) +- reference the public code structures we use to store history diff --git a/docs/features/multiline.rst b/docs/features/multiline.rst new file mode 100644 index 00000000..85a92bb2 --- /dev/null +++ b/docs/features/multiline.rst @@ -0,0 +1,17 @@ +Multiline Commands +================== + +Command input may span multiple lines for the +commands whose names are listed in the +``multiline_commands`` argument to ``cmd2.Cmd.__init__()``. These +commands will be executed only +after the user has entered a *terminator*. +By default, the command terminator is +``;``; specifying the ``terminators`` optional argument to ``cmd2.Cmd.__init__()`` allows different +terminators. A blank line +is *always* considered a command terminator +(cannot be overridden). + +In multiline commands, output redirection characters +like ``>`` and ``|`` are part of the command +arguments unless they appear after the terminator. diff --git a/docs/features/os.rst b/docs/features/os.rst new file mode 100644 index 00000000..f771fee2 --- /dev/null +++ b/docs/features/os.rst @@ -0,0 +1,10 @@ +Integrating with the OS +======================= + +- how to redirect output +- executing OS commands from within ``cmd2`` +- editors +- paging +- exit codes +- Automation and calling cmd2 from other CLI/CLU tools via commands at invocation and quit + diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst new file mode 100644 index 00000000..253666e7 --- /dev/null +++ b/docs/features/plugins.rst @@ -0,0 +1,3 @@ +Plugins +======= + diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst new file mode 100644 index 00000000..bda0ec4e --- /dev/null +++ b/docs/features/prompt.rst @@ -0,0 +1,35 @@ +Prompt +====== + +``cmd2`` can issue a prompt before soliciting user input. + +Asynchronous Feedback +--------------------- +``cmd2`` provides two functions to provide asynchronous feedback to the user without interfering with +the command line. This means the feedback is provided to the user when they are still entering text at +the prompt. To use this functionality, the application must be running in a terminal that supports +VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these. + +async_alert() + Used to display an important message to the user while they are at the prompt in between commands. + To the user it appears as if an alert message is printed above the prompt and their current input + text and cursor location is left alone. + +async_update_prompt() + Updates the prompt while the user is still typing at it. This is good for alerting the user to system + changes dynamically in between commands. For instance you could alter the color of the prompt to indicate + a system status or increase a counter to report an event. + +``cmd2`` also provides a function to change the title of the terminal window. This feature requires the +application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and +greater all support these. + +set_window_title() + Sets the terminal 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 + + diff --git a/docs/features/scripting.rst b/docs/features/scripting.rst new file mode 100644 index 00000000..c6869774 --- /dev/null +++ b/docs/features/scripting.rst @@ -0,0 +1,18 @@ +Scripting +========= + +Document use cases and commands for ``run_script`` and ``run_pyscript`` + +Comments +-------- + +Any command line input where the first non-whitespace character is a `#` will be treated as a comment. +This means any `#` character appearing later in the command will be treated as a literal. The same +applies to a `#` in the middle of a multiline command, even if it is the first character on a line. + +Comments can be useful in :ref:`scripts`, but would be pointless within an interactive session. + +:: + + (Cmd) # this is a comment + (Cmd) this # is not a comment
\ No newline at end of file diff --git a/docs/features/settings.rst b/docs/features/settings.rst new file mode 100644 index 00000000..696b085f --- /dev/null +++ b/docs/features/settings.rst @@ -0,0 +1,6 @@ +Settings +======== + +- current settings and what they do +- how a developer can add their own +- how to hide built in settings from a user diff --git a/docs/features/shortcuts_aliases_macros.rst b/docs/features/shortcuts_aliases_macros.rst new file mode 100644 index 00000000..39b2c9c2 --- /dev/null +++ b/docs/features/shortcuts_aliases_macros.rst @@ -0,0 +1,3 @@ +Shortcuts, Aliases, and Macros +============================== + diff --git a/docs/features/startup_commands.rst b/docs/features/startup_commands.rst new file mode 100644 index 00000000..1efcc014 --- /dev/null +++ b/docs/features/startup_commands.rst @@ -0,0 +1,2 @@ +Startup Commands +================ diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index e7a4c35b..fda3ee15 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -26,20 +26,6 @@ Simply include one command per line, typed exactly as you would inside a ``cmd2` .. automethod:: cmd2.cmd2.Cmd.do_edit -Comments -======== - -Any command line input where the first non-whitespace character is a `#` will be treated as a comment. -This means any `#` character appearing later in the command will be treated as a literal. The same -applies to a `#` in the middle of a multiline command, even if it is the first character on a line. - -Comments can be useful in :ref:`scripts`, but would be pointless within an interactive session. - -:: - - (Cmd) # this is a comment - (Cmd) this # is not a comment - Startup Initialization Script ============================= You can execute commands from a startup initialization script by passing a file path to the ``startup_script`` diff --git a/docs/index.rst b/docs/index.rst index 515209e8..df9a1513 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -70,9 +70,22 @@ Features features/generating_output features/argument_processing + features/prompt features/help + features/history + features/startup_commands + features/shortcuts_aliases_macros + features/settings + features/completion + features/os + features/multiline + features/disable_commands + features/clipboard features/transcript features/hooks + features/plugins + features/scripting + features/embedded_python_shells Examples diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index 02e1b981..62348bb7 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -2,23 +2,6 @@ Features requiring application changes ====================================== -Multiline commands -================== - -Command input may span multiple lines for the -commands whose names are listed in the -``multiline_commands`` argument to ``cmd2.Cmd.__init__()``. These -commands will be executed only -after the user has entered a *terminator*. -By default, the command terminator is -``;``; specifying the ``terminators`` optional argument to ``cmd2.Cmd.__init__()`` allows different -terminators. A blank line -is *always* considered a command terminator -(cannot be overridden). - -In multiline commands, output redirection characters -like ``>`` and ``|`` are part of the command -arguments unless they appear after the terminator. Parsed statements @@ -211,167 +194,6 @@ what exit code is returned from ``cmdloop()`` when it completes. It is your job this exit code gets sent to the shell when your application exits by calling ``sys.exit(app.cmdloop())``. -Asynchronous Feedback -===================== -``cmd2`` provides two functions to provide asynchronous feedback to the user without interfering with -the command line. This means the feedback is provided to the user when they are still entering text at -the prompt. To use this functionality, the application must be running in a terminal that supports -VT100 control characters and readline. Linux, Mac, and Windows 10 and greater all support these. - -async_alert() - Used to display an important message to the user while they are at the prompt in between commands. - To the user it appears as if an alert message is printed above the prompt and their current input - text and cursor location is left alone. - -async_update_prompt() - Updates the prompt while the user is still typing at it. This is good for alerting the user to system - changes dynamically in between commands. For instance you could alter the color of the prompt to indicate - a system status or increase a counter to report an event. - -``cmd2`` also provides a function to change the title of the terminal window. This feature requires the -application be running in a terminal that supports VT100 control characters. Linux, Mac, and Windows 10 and -greater all support these. - -set_window_title() - Sets the terminal 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 help ipy py run_pyscript set shortcuts - edit history macro quit run_script shell - -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 - - Command Management - ================== - disable_commands enable_commands - - Connecting - ========== - connect which - - Server Information - ================== - resources serverinfo sslconnectorciphers status thread_dump vminfo - - Other - ===== - alias edit history py run_pyscript set shortcuts - config help macro quit run_script shell 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] - py Invoke python command, shell, or script - quit Exits this application - run_pyscript Runs a python script file inside the console - run_script Runs commands in script file that is encoded as either ASCII or UTF-8 text - 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 ================== |