diff options
Diffstat (limited to 'docs/features')
| -rw-r--r-- | docs/features/argument_processing.rst | 129 | ||||
| -rw-r--r-- | docs/features/help.rst | 16 | ||||
| -rw-r--r-- | docs/features/history.rst | 229 | ||||
| -rw-r--r-- | docs/features/hooks.rst | 82 | ||||
| -rw-r--r-- | docs/features/initialization.rst | 3 | ||||
| -rw-r--r-- | docs/features/multiline_commands.rst | 21 | ||||
| -rw-r--r-- | docs/features/os.rst | 3 | ||||
| -rw-r--r-- | docs/features/prompt.rst | 35 | ||||
| -rw-r--r-- | docs/features/scripting.rst | 12 | ||||
| -rw-r--r-- | docs/features/transcripts.rst | 51 |
10 files changed, 420 insertions, 161 deletions
diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst index 20ab7879..5efc83ef 100644 --- a/docs/features/argument_processing.rst +++ b/docs/features/argument_processing.rst @@ -3,21 +3,29 @@ Argument Processing =================== -``cmd2`` makes it easy to add sophisticated argument processing to your commands using the ``argparse`` python module. -``cmd2`` handles the following for you: +``cmd2`` makes it easy to add sophisticated argument processing to your +commands using the ``argparse`` python module. ``cmd2`` handles the following +for you: 1. Parsing input and quoted strings like the Unix shell -2. Parse the resulting argument list using an instance of ``argparse.ArgumentParser`` that you provide -3. Passes the resulting ``argparse.Namespace`` object to your command function. The ``Namespace`` includes the - ``Statement`` object that was created when parsing the command line. It is stored in the ``__statement__`` - attribute of the ``Namespace``. + +2. Parse the resulting argument list using an instance of + ``argparse.ArgumentParser`` that you provide + +3. Passes the resulting ``argparse.Namespace`` object to your command function. + The ``Namespace`` includes the ``Statement`` object that was created when + parsing the command line. It is stored in the ``__statement__`` attribute of + the ``Namespace``. 4. Adds the usage message from the argument parser to your command. -5. Checks if the ``-h/--help`` option is present, and if so, display the help message for the command +5. Checks if the ``-h/--help`` option is present, and if so, display the help + message for the command -These features are all provided by the ``@with_argparser`` decorator which is importable from ``cmd2``. +These features are all provided by the ``@with_argparser`` decorator which is +importable from ``cmd2``. -See the either the argprint_ or decorator_ example to learn more about how to use the various ``cmd2`` argument -processing decorators in your ``cmd2`` applications. +See the either the argprint_ or decorator_ example to learn more about how to +use the various ``cmd2`` argument processing decorators in your ``cmd2`` +applications. .. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py .. _decorator: https://github.com/python-cmd2/cmd2/blob/master/examples/decorator_example.py @@ -26,7 +34,8 @@ processing decorators in your ``cmd2`` applications. Decorators provided by cmd2 for argument processing --------------------------------------------------- -``cmd2`` provides the following decorators for assisting with parsing arguments passed to commands: +``cmd2`` provides the following decorators for assisting with parsing arguments +passed to commands: .. automethod:: cmd2.cmd2.with_argument_list :noindex: @@ -35,9 +44,10 @@ Decorators provided by cmd2 for argument processing .. automethod:: cmd2.cmd2.with_argparser_and_unknown_args :noindex: -All of these decorators accept an optional **preserve_quotes** argument which defaults to ``False``. -Setting this argument to ``True`` is useful for cases where you are passing the arguments to another -command which might have its own argument parsing. +All of these decorators accept an optional **preserve_quotes** argument which +defaults to ``False``. Setting this argument to ``True`` is useful for cases +where you are passing the arguments to another command which might have its own +argument parsing. Using the argument parser decorator @@ -45,10 +55,10 @@ Using the argument parser decorator For each command in the ``cmd2`` subclass which requires argument parsing, create a unique instance of ``argparse.ArgumentParser()`` which can parse the -input appropriately for the command. Then decorate the command method with -the ``@with_argparser`` decorator, passing the argument parser as the -first parameter to the decorator. This changes the second argument to the command method, which will contain the results -of ``ArgumentParser.parse_args()``. +input appropriately for the command. Then decorate the command method with the +``@with_argparser`` decorator, passing the argument parser as the first +parameter to the decorator. This changes the second argument to the command +method, which will contain the results of ``ArgumentParser.parse_args()``. Here's what it looks like:: @@ -75,20 +85,20 @@ Here's what it looks like:: .. warning:: - It is important that each command which uses the ``@with_argparser`` decorator be passed a unique instance of a - parser. This limitation is due to bugs in CPython prior to Python 3.7 which make it impossible to make a deep copy - of an instance of a ``argparse.ArgumentParser``. + It is important that each command which uses the ``@with_argparser`` + decorator be passed a unique instance of a parser. This limitation is due + to bugs in CPython prior to Python 3.7 which make it impossible to make a + deep copy of an instance of a ``argparse.ArgumentParser``. - See the table_display_ example for a work-around that demonstrates how to create a function which returns a unique - instance of the parser you want. + See the table_display_ example for a work-around that demonstrates how to + create a function which returns a unique instance of the parser you want. .. note:: - The ``@with_argparser`` decorator sets the ``prog`` variable in - the argument parser based on the name of the method it is decorating. - This will override anything you specify in ``prog`` variable when - creating the argument parser. + The ``@with_argparser`` decorator sets the ``prog`` variable in the argument + parser based on the name of the method it is decorating. This will override + anything you specify in ``prog`` variable when creating the argument parser. .. _table_display: https://github.com/python-cmd2/cmd2/blob/master/examples/table_display.py @@ -96,9 +106,10 @@ Here's what it looks like:: Help Messages ------------- -By default, cmd2 uses the docstring of the command method when a user asks -for help on the command. When you use the ``@with_argparser`` -decorator, the docstring for the ``do_*`` method is used to set the description for the ``argparse.ArgumentParser``. +By default, cmd2 uses the docstring of the command method when a user asks for +help on the command. When you use the ``@with_argparser`` decorator, the +docstring for the ``do_*`` method is used to set the description for the +``argparse.ArgumentParser``. With this code:: @@ -116,7 +127,7 @@ With this code:: the ``help tag`` command displays: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -130,8 +141,8 @@ the ``help tag`` command displays: -h, --help show this help message and exit -If you would prefer you can set the ``description`` while instantiating the ``argparse.ArgumentParser`` and leave the -docstring on your method empty:: +If you would prefer you can set the ``description`` while instantiating the +``argparse.ArgumentParser`` and leave the docstring on your method empty:: import argparse from cmd2 import with_argparser @@ -146,7 +157,7 @@ docstring on your method empty:: Now when the user enters ``help tag`` they see: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -176,7 +187,7 @@ To add additional text to the end of the generated help message, use the ``epilo Which yields: -.. code-block:: none +.. code-block:: text usage: tag [-h] tag content [content ...] @@ -193,9 +204,11 @@ Which yields: .. warning:: - If a command **foo** is decorated with one of cmd2's argparse decorators, then **help_foo** will not - be invoked when ``help foo`` is called. The argparse_ module provides a rich API which can be used to - tweak every aspect of the displayed help and we encourage ``cmd2`` developers to utilize that. + If a command **foo** is decorated with one of cmd2's argparse decorators, + then **help_foo** will not be invoked when ``help foo`` is called. The + argparse_ module provides a rich API which can be used to tweak every + aspect of the displayed help and we encourage ``cmd2`` developers to + utilize that. .. _argparse: https://docs.python.org/3/library/argparse.html @@ -250,11 +263,12 @@ argument list instead of a string:: pass -Using the argument parser decorator and also receiving a list of unknown positional arguments ---------------------------------------------------------------------------------------------- +Unknown positional arguments +---------------------------- -If you want all unknown arguments to be passed to your command as a list of strings, then -decorate the command method with the ``@with_argparser_and_unknown_args`` decorator. +If you want all unknown arguments to be passed to your command as a list of +strings, then decorate the command method with the +``@with_argparser_and_unknown_args`` decorator. Here's what it looks like:: @@ -279,14 +293,17 @@ Here's what it looks like:: ... -Using custom argparse.Namespace with argument parser decorators ---------------------------------------------------------------- +Using custom argparse.Namespace +------------------------------- -In some cases, it may be necessary to write custom ``argparse`` code that is dependent on state data of your -application. To support this ability while still allowing use of the decorators, both ``@with_argparser`` and -``@with_argparser_and_unknown_args`` have an optional argument called ``ns_provider``. +In some cases, it may be necessary to write custom ``argparse`` code that is +dependent on state data of your application. To support this ability while +still allowing use of the decorators, both ``@with_argparser`` and +``@with_argparser_and_unknown_args`` have an optional argument called +``ns_provider``. -``ns_provider`` is a Callable that accepts a ``cmd2.Cmd`` object as an argument and returns an ``argparse.Namespace``:: +``ns_provider`` is a Callable that accepts a ``cmd2.Cmd`` object as an argument +and returns an ``argparse.Namespace``:: Callable[[cmd2.Cmd], argparse.Namespace] @@ -302,19 +319,23 @@ To use this function with the argparse decorators, do the following:: @with_argparser(my_parser, ns_provider=settings_ns_provider) -The Namespace is passed by the decorators to the ``argparse`` parsing functions which gives your custom code access -to the state data it needs for its parsing logic. +The Namespace is passed by the decorators to the ``argparse`` parsing functions +which gives your custom code access to the state data it needs for its parsing +logic. Sub-commands ------------ Sub-commands are supported for commands using either the ``@with_argparser`` or -``@with_argparser_and_unknown_args`` decorator. The syntax for supporting them is based on argparse sub-parsers. +``@with_argparser_and_unknown_args`` decorator. The syntax for supporting them +is based on argparse sub-parsers. -You may add multiple layers of sub-commands for your command. Cmd2 will automatically traverse and tab-complete -sub-commands for all commands using argparse. +You may add multiple layers of sub-commands for your command. Cmd2 will +automatically traverse and tab-complete sub-commands for all commands using +argparse. -See the subcommands_ and tab_autocompletion_ example to learn more about how to use sub-commands in your ``cmd2`` application. +See the subcommands_ and tab_autocompletion_ example to learn more about how to +use sub-commands in your ``cmd2`` application. .. _subcommands: https://github.com/python-cmd2/cmd2/blob/master/examples/subcommands.py .. _tab_autocompletion: https://github.com/python-cmd2/cmd2/blob/master/examples/tab_autocompletion.py diff --git a/docs/features/help.rst b/docs/features/help.rst index 37280bf0..755d40f9 100644 --- a/docs/features/help.rst +++ b/docs/features/help.rst @@ -17,8 +17,8 @@ By default, the ``help`` command displays:: 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``:: +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>): @@ -44,9 +44,11 @@ Here's the output from the example ``help_categories.py``:: 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`. +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:: @@ -85,8 +87,8 @@ Using the ``categorize()`` function: 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:: +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>): diff --git a/docs/features/history.rst b/docs/features/history.rst index 9fd881d4..a2c9e2d7 100644 --- a/docs/features/history.rst +++ b/docs/features/history.rst @@ -6,10 +6,235 @@ For Developers - Describe how cmd2 tracks history - how persistent history works -- differences in history and bash shell history (we only store valid commands in history) +- differences in history and bash shell history (we only store valid commands + in history) - reference the public code structures we use to store history +``cmd2`` adds the option of making this history persistent via optional +arguments to ``cmd2.Cmd.__init__()``: + +.. automethod:: cmd2.cmd2.Cmd.__init__ + + For Users --------- -- describe the uses of the built in history command +You can use the up and down arrow keys to move through the history of +previously entered commands. + +If the ``readline`` module is installed, you can press ``Control-p`` to move to +the previously entered command, and ``Control-n`` to move to the next command. +You can also search through the command history using ``Control-r``. + +Eric Johnson hosts a nice `readline cheat sheet +<http://readline.kablamo.org/emacs.html>`_, or you can dig into the `GNU +Readline User Manual +<https://tiswww.case.edu/php/chet/readline/rluserman.html>`_ for all the +details, including instructions for customizing the key bindings. + +``cmd2`` makes a third type of history access available with the ``history`` +command. Each time the user enters a command, ``cmd2`` saves the input. The +``history`` command lets you do interesting things with that saved input. The +examples to follow all assume that you have entered the following commands:: + + (Cmd) alias create one !echo one + Alias 'one' created + (Cmd) alias create two !echo two + Alias 'two' created + (Cmd) alias create three !echo three + Alias 'three' created + (Cmd) alias create four !echo four + Alias 'four' created + +In it's simplest form, the ``history`` command displays previously entered +commands. With no additional arguments, it displays all previously entered +commands:: + + (Cmd) history + 1 alias create one !echo one + 2 alias create two !echo two + 3 alias create three !echo three + 4 alias create four !echo four + +If you give a positive integer as an argument, then it only displays the +specified command:: + + (Cmd) history 4 + 4 alias create four !echo four + +If you give a negative integer *N* as an argument, then it display the *Nth* +last command. For example, if you give ``-1`` it will display the last command +you entered. If you give ``-2`` it will display the next to last command you +entered, and so forth:: + + (Cmd) history -2 + 3 alias create three !echo three + +You can use a similar mechanism to display a range of commands. Simply give two +command numbers separated by ``..`` or ``:``, and you will see all commands +between, and including, those two numbers:: + + (Cmd) history 1:3 + 1 alias create one !echo one + 2 alias create two !echo two + 3 alias create three !echo three + +If you omit the first number, it will start at the beginning. If you omit the +last number, it will continue to the end:: + + (Cmd) history :2 + 1 alias create one !echo one + 2 alias create two !echo two + (Cmd) history 2: + 2 alias create two !echo two + 3 alias create three !echo three + 4 alias create four !echo four + +If you want to display the last three commands entered:: + + (Cmd) history -- -3: + 2 alias create two !echo two + 3 alias create three !echo three + 4 alias create four !echo four + +Notice the double dashes. These are required because the history command uses +``argparse`` to parse the command line arguments. As described in the `argparse +documentation <https://docs.python.org/3/library/argparse.html>`_ , ``-3:`` is +an option, not an argument: + + If you have positional arguments that must begin with - and don’t look + like negative numbers, you can insert the pseudo-argument '--' which tells + parse_args() that everything after that is a positional argument: + +There is no zeroth command, so don't ask for it. If you are a python +programmer, you've probably noticed this looks a lot like the slice syntax for +lists and arrays. It is, with the exception that the first history command is +1, where the first element in a python array is 0. + +Besides selecting previous commands by number, you can also search for them. +You can use a simple string search:: + + (Cmd) history two + 2 alias create two !echo two + +Or a regular expression search by enclosing your regex in slashes:: + + (Cmd) history '/te\ +th/' + 3 alias create three !echo three + +If your regular expression contains any characters that ``argparse`` finds +interesting, like dash or plus, you also need to enclose your regular +expression in quotation marks. + +This all sounds great, but doesn't it seem like a bit of overkill to have all +these ways to select commands if all we can do is display them? Turns out, +displaying history commands is just the beginning. The history command can +perform many other actions: + +- running previously entered commands +- saving previously entered commands to a text file +- opening previously entered commands in your favorite text editor +- running previously entered commands, saving the commands and their output + to a text file +- clearing the history of entered commands + +Each of these actions is invoked using a command line option. The ``-r`` or +``--run`` option runs one or more previously entered commands. To run command +number 1:: + + (Cmd) history --run 1 + +To rerun the last two commands (there's that double dash again to make argparse +stop looking for options):: + + (Cmd) history -r -- -2: + +Say you want to re-run some previously entered commands, but you would really +like to make a few changes to them before doing so. When you use the ``-e`` or +``--edit`` option, ``history`` will write the selected commands out to a text +file, and open that file with a text editor. You make whatever changes, +additions, or deletions, you want. When you leave the text editor, all the +commands in the file are executed. To edit and then re-run commands 2-4 you +would:: + + (Cmd) history --edit 2:4 + +If you want to save the commands to a text file, but not edit and re-run them, +use the ``-o`` or ``--output-file`` option. This is a great way to create +:ref:`scripts`, which can be executed using the ``run_script`` command. To +save the first 5 commands entered in this session to a text file:: + + (Cmd) history :5 -o history.txt + +The ``history`` command can also save both the commands and their output to a +text file. This is called a transcript. See +:ref:`features/transcripts:Transcripts` for more information on how transcripts +work, and what you can use them for. To create a transcript use the ``-t`` or +``--transcription`` option:: + + (Cmd) history 2:3 --transcript transcript.txt + +The ``--transcript`` option implies ``--run``: the commands must be re-run in +order to capture their output to the transcript file. + +The last action the history command can perform is to clear the command history +using ``-c`` or ``--clear``:: + + (Cmd) history -c + +In addition to these five actions, the ``history`` command also has some +options to control how the output is formatted. With no arguments, the +``history`` command displays the command number before each command. This is +great when displaying history to the screen because it gives you an easy +reference to identify previously entered commands. However, when creating a +script or a transcript, the command numbers would prevent the script from +loading properly. The ``-s`` or ``--script`` option instructs the ``history`` +command to suppress the line numbers. This option is automatically set by the +``--output-file``, ``--transcript``, and ``--edit`` options. If you want to +output the history commands with line numbers to a file, you can do it with +output redirection:: + + (Cmd) history 1:4 > history.txt + +You might use ``-s`` or ``--script`` on it's own if you want to display history +commands to the screen without line numbers, so you can copy them to the +clipboard:: + + (Cmd) history -s 1:3 + +``cmd2`` supports both aliases and macros, which allow you to substitute a +short, more convenient input string with a longer replacement string. Say we +create an alias like this, and then use it:: + + (Cmd) alias create ls shell ls -aF + Alias 'ls' created + (Cmd) ls -d h* + history.txt htmlcov/ + +By default, the ``history`` command shows exactly what we typed:: + + (Cmd) history + 1 alias create ls shell ls -aF + 2 ls -d h* + +There are two ways to modify that display so you can see what aliases and +macros were expanded to. The first is to use ``-x`` or ``--expanded``. These +options show the expanded command instead of the entered command:: + + (Cmd) history -x + 1 alias create ls shell ls -aF + 2 shell ls -aF -d h* + +If you want to see both the entered command and the expanded command, use the +``-v`` or ``--verbose`` option:: + + (Cmd) history -v + 1 alias create ls shell ls -aF + 2 ls -d h* + 2x shell ls -aF -d h* + +If the entered command had no expansion, it is displayed as usual. However, if +there is some change as the result of expanding macros and aliases, then the +entered command is displayed with the number, and the expanded command is +displayed with the number followed by an ``x``. + diff --git a/docs/features/hooks.rst b/docs/features/hooks.rst index 01d12425..17f2884e 100644 --- a/docs/features/hooks.rst +++ b/docs/features/hooks.rst @@ -53,9 +53,9 @@ value is ignored. Application Lifecycle Attributes -------------------------------- -There are numerous attributes of and arguments to ``cmd2.Cmd`` which have -a significant effect on the application behavior upon entering or during the -main loop. A partial list of some of the more important ones is presented here: +There are numerous attributes of and arguments to ``cmd2.Cmd`` which have a +significant effect on the application behavior upon entering or during the main +loop. A partial list of some of the more important ones is presented here: - **intro**: *str* - if provided this serves as the intro banner printed once at start of application, after ``preloop`` runs @@ -86,7 +86,8 @@ the application exits: #. Add statement to history #. Call `do_command` method #. Call methods registered with `register_postcmd_hook()` -#. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` +#. Call `postcmd(stop, statement)` - for backwards compatibility with + ``cmd.Cmd`` #. Stop timer and display the elapsed time #. Stop redirecting output if it was redirected #. Call methods registered with `register_cmdfinalization_hook()` @@ -140,10 +141,10 @@ To define and register a postparsing hook, do the following:: # is available as params.statement return params -``register_postparsing_hook()`` checks the method signature of the passed callable, -and raises a ``TypeError`` if it has the wrong number of parameters. It will -also raise a ``TypeError`` if the passed parameter and return value are not annotated -as ``PostparsingData``. +``register_postparsing_hook()`` checks the method signature of the passed +callable, and raises a ``TypeError`` if it has the wrong number of parameters. +It will also raise a ``TypeError`` if the passed parameter and return value are +not annotated as ``PostparsingData``. The hook method will be passed one parameter, a ``PostparsingData`` object which we will refer to as ``params``. ``params`` contains two attributes. @@ -158,17 +159,17 @@ method may modify the attributes of the object to influece the behavior of the application. If ``params.stop`` is set to true, a fatal failure is triggered prior to execution of the command, and the application exits. -To modify the user input, you create a new ``Statement`` object and return it in -``params.statement``. Don't try and directly modify the contents of a -``Statement`` object, there be dragons. Instead, use the various attributes in a -``Statement`` object to construct a new string, and then parse that string to +To modify the user input, you create a new ``Statement`` object and return it +in ``params.statement``. Don't try and directly modify the contents of a +``Statement`` object, there be dragons. Instead, use the various attributes in +a ``Statement`` object to construct a new string, and then parse that string to create a new ``Statement`` object. -``cmd2.Cmd()`` uses an instance of ``cmd2.StatementParser`` to parse user input. -This instance has been configured with the proper command terminators, multiline -commands, and other parsing related settings. This instance is available as the -``self.statement_parser`` attribute. Here's a simple example which shows the -proper technique:: +``cmd2.Cmd()`` uses an instance of ``cmd2.StatementParser`` to parse user +input. This instance has been configured with the proper command terminators, +multiline commands, and other parsing related settings. This instance is +available as the ``self.statement_parser`` attribute. Here's a simple example +which shows the proper technique:: def myhookmethod(self, params: cmd2.plugin.PostparsingData) -> cmd2.plugin.PostparsingData: if not '|' in params.statement.raw: @@ -215,11 +216,12 @@ different properties (see above). If you do so, assign your new ``Statement`` object to ``data.statement``. The precommand hook must return a ``PrecommandData`` object. You don't have to -create this object from scratch, you can just return the one passed into the hook. +create this object from scratch, you can just return the one passed into the +hook. After all registered precommand hooks have been called, -``self.precmd(statement)`` will be called. To retain full backward compatibility -with ``cmd.Cmd``, this method is passed a ``Statement``, not a +``self.precmd(statement)`` will be called. To retain full backward +compatibility with ``cmd.Cmd``, this method is passed a ``Statement``, not a ``PrecommandData`` object. @@ -228,8 +230,8 @@ Postcommand Hooks Once the command method has returned (i.e. the ``do_command(self, statement) method`` has been called and returns, all postcommand hooks are called. If -output was redirected by the user, it is still redirected, and the command timer -is still running. +output was redirected by the user, it is still redirected, and the command +timer is still running. Here's how to define and register a postcommand hook:: @@ -241,25 +243,25 @@ Here's how to define and register a postcommand hook:: def myhookmethod(self, data: cmd2.plugin.PostcommandData) -> cmd2.plugin.PostcommandData: return data -Your hook will be passed a ``PostcommandData`` object, which has a ``statement`` -attribute that describes the command which was executed. If your postcommand -hook method gets called, you are guaranteed that the command method was called, -and that it didn't raise an exception. +Your hook will be passed a ``PostcommandData`` object, which has a +``statement`` attribute that describes the command which was executed. If your +postcommand hook method gets called, you are guaranteed that the command method +was called, and that it didn't raise an exception. If any postcommand hook raises an exception, the exception will be displayed to the user, and no further postcommand hook methods will be called. Command finalization hooks, if any, will be called. After all registered postcommand hooks have been called, -``self.postcmd(statement)`` will be called to retain full backward compatibility -with ``cmd.Cmd``. +``self.postcmd(statement)`` will be called to retain full backward +compatibility with ``cmd.Cmd``. If any postcommand hook (registered or ``self.postcmd()``) returns a ``PostcommandData`` object with the stop attribute set to ``True``, subsequent postcommand hooks will still be called, as will the command finalization hooks, but once those hooks have all been called, the application will terminate. -Likewise, if ``self.postcmd()`` returns ``True``, the command finalization hooks -will be called before the application terminates. +Likewise, if ``self.postcmd()`` returns ``True``, the command finalization +hooks will be called before the application terminates. Any postcommand hook can change the value of the ``stop`` parameter before returning it, and the modified value will be passed to the next postcommand @@ -273,8 +275,8 @@ compelling reason to do otherwise. Command Finalization Hooks -------------------------- -Command finalization hooks are called even if one of the other types of hooks or -the command method raise an exception. Here's how to create and register a +Command finalization hooks are called even if one of the other types of hooks +or the command method raise an exception. Here's how to create and register a command finalization hook:: class App(cmd2.Cmd): @@ -291,16 +293,16 @@ statement has been parsed, so you can't always rely on having a statement. If any prior postparsing or precommand hook has requested the application to terminate, the value of the ``stop`` parameter passed to the first command -finalization hook will be ``True``. Any command finalization hook can change the -value of the ``stop`` parameter before returning it, and the modified value will -be passed to the next command finalization hook. The value returned by the final -command finalization hook will determine whether the application terminates or -not. +finalization hook will be ``True``. Any command finalization hook can change +the value of the ``stop`` parameter before returning it, and the modified value +will be passed to the next command finalization hook. The value returned by the +final command finalization hook will determine whether the application +terminates or not. This approach to command finalization hooks can be powerful, but it can also -cause problems. If your hook blindly returns ``False``, a prior hook's requst to -exit the application will not be honored. It's best to return the value you were -passed unless you have a compelling reason to do otherwise. +cause problems. If your hook blindly returns ``False``, a prior hook's requst +to exit the application will not be honored. It's best to return the value you +were passed unless you have a compelling reason to do otherwise. If any command finalization hook raises an exception, no more command finalization hooks will be called. If the last hook to return a value returned diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index b13d5bc8..f167a55a 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -1,4 +1,5 @@ Initialization ============== -Show how to properly initialize a ``cmd2`` app, showing parameters, sequencing, etc. +Show how to properly initialize a ``cmd2`` app, showing parameters, sequencing, +etc. diff --git a/docs/features/multiline_commands.rst b/docs/features/multiline_commands.rst index 85a92bb2..d6502058 100644 --- a/docs/features/multiline_commands.rst +++ b/docs/features/multiline_commands.rst @@ -1,17 +1,12 @@ 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). +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. +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 index f771fee2..780e99f2 100644 --- a/docs/features/os.rst +++ b/docs/features/os.rst @@ -6,5 +6,6 @@ Integrating with the OS - editors - paging - exit codes -- Automation and calling cmd2 from other CLI/CLU tools via commands at invocation and quit +- Automation and calling cmd2 from other CLI/CLU tools via commands at + invocation and quit diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst index bda0ec4e..40c50d2b 100644 --- a/docs/features/prompt.rst +++ b/docs/features/prompt.rst @@ -5,30 +5,37 @@ Prompt 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. + +``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. + 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. + 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. +``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. +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 index c6869774..73566cde 100644 --- a/docs/features/scripting.rst +++ b/docs/features/scripting.rst @@ -6,13 +6,15 @@ 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. +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. +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 + (Cmd) this # is not a comment diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst index e4ff79a5..18daeb78 100644 --- a/docs/features/transcripts.rst +++ b/docs/features/transcripts.rst @@ -13,8 +13,8 @@ from commands that produce dynamic or variable output. Creating From History --------------------- -A transcript can automatically generated based upon commands previously executed -in the *history* using ``history -t``:: +A transcript can automatically generated based upon commands previously +executed in the *history* using ``history -t``:: (Cmd) help ... @@ -28,15 +28,16 @@ This is by far the easiest way to generate a transcript. .. warning:: Make sure you use the **poutput()** method in your ``cmd2`` application for - generating command output. This method of the ``cmd2.Cmd`` class ensure that - output is properly redirected when redirecting to a file, piping to a shell - command, and when generating a transcript. + generating command output. This method of the ``cmd2.Cmd`` class ensure + that output is properly redirected when redirecting to a file, piping to a + shell command, and when generating a transcript. Creating From A Script File --------------------------- -A transcript can also be automatically generated from a script file using ``run_script -t``:: +A transcript can also be automatically generated from a script file using +``run_script -t``:: (Cmd) run_script scripts/script.txt -t transcript.txt 2 commands and their outputs saved to transcript file 'transcript.txt' @@ -98,12 +99,12 @@ will be ignored. Regular Expressions ------------------- -If we used the above transcript as-is, it would likely fail. As you can see, the -``mumble`` command doesn't always return the same thing: it inserts random words -into the input. +If we used the above transcript as-is, it would likely fail. As you can see, +the ``mumble`` command doesn't always return the same thing: it inserts random +words into the input. -Regular expressions can be included in the response portion of a transcript, and -are surrounded by slashes:: +Regular expressions can be included in the response portion of a transcript, +and are surrounded by slashes:: (Cmd) mumble maybe we could go to lunch /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/ @@ -111,9 +112,10 @@ are surrounded by slashes:: /.*\bmaybe\b.*\bcould\b.*\blunch\b.*/ Without creating a tutorial on regular expressions, this one matches anything -that has the words ``maybe``, ``could``, and ``lunch`` in that order. It doesn't -ensure that ``we`` or ``go`` or ``to`` appear in the output, but it does work if -mumble happens to add words to the beginning or the end of the output. +that has the words ``maybe``, ``could``, and ``lunch`` in that order. It +doesn't ensure that ``we`` or ``go`` or ``to`` appear in the output, but it +does work if mumble happens to add words to the beginning or the end of the +output. Since the output could be multiple lines long, ``cmd2`` uses multiline regular expression matching, and also uses the ``DOTALL`` flag. These two flags subtly @@ -122,7 +124,8 @@ change the behavior of commonly used special characters like ``.``, ``^`` and documentation <https://docs.python.org/3/library/re.html>`_. If your output has slashes in it, you will need to escape those slashes so the -stuff between them is not interpred as a regular expression. In this transcript:: +stuff between them is not interpred as a regular expression. In this +transcript:: (Cmd) say cd /usr/local/lib/python3.6/site-packages /usr/local/lib/python3.6/site-packages @@ -147,15 +150,15 @@ the path instead of specifying it verbatim, or we can escape the slashes:: prompt: (Cmd)/ / Some terminal emulators strip trailing space when you copy text from them. - This could make the actual data generated by your app different than the text - you pasted into the transcript, and it might not be readily obvious why the - transcript is not passing. Consider using :ref:`output_redirection` to the - clipboard or to a file to ensure you accurately capture the output of your - command. - - If you aren't using regular expressions, make sure the newlines at the end of - your transcript exactly match the output of your commands. A common cause of - a failing transcript is an extra or missing newline. + This could make the actual data generated by your app different than the + text you pasted into the transcript, and it might not be readily obvious why + the transcript is not passing. Consider using :ref:`output_redirection` to + the clipboard or to a file to ensure you accurately capture the output of + your command. + + If you aren't using regular expressions, make sure the newlines at the end + of your transcript exactly match the output of your commands. A common cause + of a failing transcript is an extra or missing newline. If you are using regular expressions, be aware that depending on how you write your regex, the newlines after the regex may or may not matter. ``\Z`` |