From f94466f207366531253ff92c04d2f6f698f0c038 Mon Sep 17 00:00:00 2001 From: kotfu Date: Tue, 16 Jul 2019 21:25:16 -0600 Subject: Integrate the unfreefeatures legacy documentation --- docs/features/commands.rst | 43 +++++++ docs/features/generating_output.rst | 60 ++++++++++ docs/features/misc.rst | 70 +++++++++++ docs/features/os.rst | 75 ++++++++++++ docs/features/settings.rst | 33 ++++++ docs/index.rst | 2 - docs/integrating.rst | 75 ------------ docs/unfreefeatures.rst | 231 ------------------------------------ 8 files changed, 281 insertions(+), 308 deletions(-) delete mode 100644 docs/unfreefeatures.rst diff --git a/docs/features/commands.rst b/docs/features/commands.rst index 3eec2373..6a8fedee 100644 --- a/docs/features/commands.rst +++ b/docs/features/commands.rst @@ -1,4 +1,47 @@ Commands ======== +.. _cmd: https://docs.python.org/3/library/cmd.html + How to create a command with a ``do_command`` method, + +Parsed statements +----------------- + +``cmd2`` passes ``arg`` to a ``do_`` method (or ``default``) as a Statement, a +subclass of string that includes many attributes of the parsed input: + +command + Name of the command called + +args + The arguments to the command with output redirection + or piping to shell commands removed + +command_and_args + A string of just the command and the arguments, with + output redirection or piping to shell commands removed + +argv + A list of arguments a-la ``sys.argv``, including + the command as ``argv[0]`` and the subsequent + arguments as additional items in the list. + Quotes around arguments will be stripped as will + any output redirection or piping portions of the command + +raw + Full input exactly as typed. + +terminator + Character used to end a multiline command + + + +If ``Statement`` does not contain an attribute, querying for it will return +``None``. + +(Getting ``arg`` as a ``Statement`` is technically "free", in that it requires +no application changes from the cmd_ standard, but there will be no result +unless you change your application to *use* any of the additional attributes.) + + diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst index 5813322b..c03f8778 100644 --- a/docs/features/generating_output.rst +++ b/docs/features/generating_output.rst @@ -9,6 +9,39 @@ how to generate output - exceptions - color support +Standard ``cmd`` applications produce their output with +``self.stdout.write('output')`` (or with ``print``, but ``print`` decreases +output flexibility). ``cmd2`` applications can use ``self.poutput('output')``, +``self.pfeedback('message')``, ``self.perror('errmsg')``, and +``self.ppaged('text')`` instead. These methods have these advantages: + +- Handle output redirection to file and/or pipe appropriately +- More concise + - ``.pfeedback()`` destination is controlled by ``quiet`` parameter. +- Option to display long output using a pager via ``ppaged()`` + +.. automethod:: cmd2.cmd2.Cmd.poutput + :noindex: +.. automethod:: cmd2.cmd2.Cmd.perror + :noindex: +.. automethod:: cmd2.cmd2.Cmd.pfeedback + :noindex: +.. automethod:: cmd2.cmd2.Cmd.ppaged + :noindex: + + +Suppressing non-essential output +-------------------------------- + +The ``quiet`` setting controls whether ``self.pfeedback()`` actually produces +any output. If ``quiet`` is ``False``, then the output will be produced. If +``quiet`` is ``True``, no output will be produced. + +This makes ``self.pfeedback()`` useful for non-essential output like status +messages. Users can control whether they would like to see these messages by +changing the value of the ``quiet`` setting. + + Output Redirection ------------------ @@ -43,3 +76,30 @@ If you need to include any of these redirection characters in your command, you can enclose them in quotation marks, ``mycommand 'with > in the argument'``. +Colored Output +-------------- + +The output methods in the previous section all honor the ``allow_ansi`` +setting, which has three possible values: + +Never + poutput(), pfeedback(), and ppaged() strip all ANSI escape sequences + which instruct the terminal to colorize output + +Terminal + (the default value) poutput(), pfeedback(), and ppaged() do not strip any + ANSI escape sequences when the output is a terminal, but if the output is a + pipe or a file the escape sequences are stripped. If you want colorized + output you must add ANSI escape sequences using either cmd2's internal ansi + module or another color library such as `plumbum.colors`, `colorama`, or + `colored`. + +Always + poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences, + regardless of the output destination + +Colored and otherwise styled output can be generated using the `ansi.style()` +function: + +.. automethod:: cmd2.ansi.style + diff --git a/docs/features/misc.rst b/docs/features/misc.rst index b556d44e..0ddc03e1 100644 --- a/docs/features/misc.rst +++ b/docs/features/misc.rst @@ -77,3 +77,73 @@ like so:: This text file should contain a :ref:`Command Script `. See the AliasStartup_ example for a demonstration. + + +select +------ + +Presents numbered options to user, as bash ``select``. + +``app.select`` is called from within a method (not by the user directly; it is +``app.select``, not ``app.do_select``). + +.. automethod:: cmd2.cmd2.Cmd.select + :noindex: + +:: + + def do_eat(self, arg): + sauce = self.select('sweet salty', 'Sauce? ') + result = '{food} with {sauce} sauce, yum!' + result = result.format(food=arg, sauce=sauce) + self.stdout.write(result + '\n') + +:: + + (Cmd) eat wheaties + 1. sweet + 2. salty + Sauce? 2 + wheaties with salty sauce, yum! + + +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 + + +Exit code +--------- + +The ``self.exit_code`` attribute of your ``cmd2`` application controls what +exit code is returned from ``cmdloop()`` when it completes. It is your job to +make sure that this exit code gets sent to the shell when your application +exits by calling ``sys.exit(app.cmdloop())``. diff --git a/docs/features/os.rst b/docs/features/os.rst index 780e99f2..40a7cbf4 100644 --- a/docs/features/os.rst +++ b/docs/features/os.rst @@ -9,3 +9,78 @@ Integrating with the OS - Automation and calling cmd2 from other CLI/CLU tools via commands at invocation and quit + +Invoking With Arguments +----------------------- + +Typically you would invoke a ``cmd2`` program by typing:: + + $ python mycmd2program.py + +or:: + + $ mycmd2program.py + +Either of these methods will launch your program and enter the ``cmd2`` command +loop, which allows the user to enter commands, which are then executed by your +program. + +You may want to execute commands in your program without prompting the user for +any input. There are several ways you might accomplish this task. The easiest +one is to pipe commands and their arguments into your program via standard +input. You don't need to do anything to your program in order to use this +technique. Here's a demonstration using the ``examples/example.py`` included in +the source code of ``cmd2``:: + + $ echo "speak -p some words" | python examples/example.py + omesay ordsway + +Using this same approach you could create a text file containing the commands +you would like to run, one command per line in the file. Say your file was +called ``somecmds.txt``. To run the commands in the text file using your +``cmd2`` program (from a Windows command prompt):: + + c:\cmd2> type somecmds.txt | python.exe examples/example.py + omesay ordsway + +By default, ``cmd2`` programs also look for commands pass as arguments from the +operating system shell, and execute those commands before entering the command +loop:: + + $ python examples/example.py help + + Documented commands (type help ): + ======================================== + alias help macro orate quit run_script set shortcuts + edit history mumble py run_pyscript say shell speak + + (Cmd) + +You may need more control over command line arguments passed from the operating +system shell. For example, you might have a command inside your ``cmd2`` +program which itself accepts arguments, and maybe even option strings. Say you +wanted to run the ``speak`` command from the operating system shell, but have +it say it in pig latin:: + + $ python example/example.py speak -p hello there + python example.py speak -p hello there + usage: speak [-h] [-p] [-s] [-r REPEAT] words [words ...] + speak: error: the following arguments are required: words + *** Unknown syntax: -p + *** Unknown syntax: hello + *** Unknown syntax: there + (Cmd) + +Uh-oh, that's not what we wanted. ``cmd2`` treated ``-p``, ``hello``, and +``there`` as commands, which don't exist in that program, thus the syntax +errors. + +There is an easy way around this, which is demonstrated in +``examples/cmd_as_argument.py``. By setting ``allow_cli_args=False`` you can so +your own argument parsing of the command line:: + + $ python examples/cmd_as_argument.py speak -p hello there + ellohay heretay + +Check the source code of this example, especially the ``main()`` function, to +see the technique. diff --git a/docs/features/settings.rst b/docs/features/settings.rst index 696b085f..27730572 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -4,3 +4,36 @@ Settings - current settings and what they do - how a developer can add their own - how to hide built in settings from a user + +Your application can define user-settable parameters which your code can +reference. First create a class attribute with the default value. Then update +the ``settable`` dictionary with your setting name and a short description +before you initialize the superclass. Here's an example, from +``examples/environment.py``: + +.. literalinclude:: ../../examples/environment.py + +If you want to be notified when a setting changes (as we do above), then define +a method ``_onchange_{setting}()``. This method will be called after the user +changes a setting, and will receive both the old value and the new value. + +.. code-block:: text + + (Cmd) set --long | grep sunny + sunny: False # Is it sunny outside? + (Cmd) set --long | grep degrees + degrees_c: 22 # Temperature in Celsius + (Cmd) sunbathe + Too dim. + (Cmd) set degrees_c 41 + degrees_c - was: 22 + now: 41 + (Cmd) set sunny + sunny: True + (Cmd) sunbathe + UV is bad for your skin. + (Cmd) set degrees_c 13 + degrees_c - was: 41 + now: 13 + (Cmd) sunbathe + It's 13 C - are you a penguin? diff --git a/docs/index.rst b/docs/index.rst index 3ff4e379..2c432a16 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -97,7 +97,6 @@ Files from old documentation to be integrated into new structure * :doc:`integrating` * :doc:`settingchanges` -* :doc:`unfreefeatures` .. toctree:: :maxdepth: 2 @@ -106,4 +105,3 @@ Files from old documentation to be integrated into new structure integrating settingchanges - unfreefeatures diff --git a/docs/integrating.rst b/docs/integrating.rst index 9b0cf737..b903c3a1 100644 --- a/docs/integrating.rst +++ b/docs/integrating.rst @@ -4,81 +4,6 @@ Integrating cmd2 with external tools ==================================== -Integrating cmd2 with the shell -------------------------------- - -Typically you would invoke a ``cmd2`` program by typing:: - - $ python mycmd2program.py - -or:: - - $ mycmd2program.py - -Either of these methods will launch your program and enter the ``cmd2`` command -loop, which allows the user to enter commands, which are then executed by your -program. - -You may want to execute commands in your program without prompting the user for -any input. There are several ways you might accomplish this task. The easiest -one is to pipe commands and their arguments into your program via standard -input. You don't need to do anything to your program in order to use this -technique. Here's a demonstration using the ``examples/example.py`` included in -the source code of ``cmd2``:: - - $ echo "speak -p some words" | python examples/example.py - omesay ordsway - -Using this same approach you could create a text file containing the commands -you would like to run, one command per line in the file. Say your file was -called ``somecmds.txt``. To run the commands in the text file using your -``cmd2`` program (from a Windows command prompt):: - - c:\cmd2> type somecmds.txt | python.exe examples/example.py - omesay ordsway - -By default, ``cmd2`` programs also look for commands pass as arguments from the -operating system shell, and execute those commands before entering the command -loop:: - - $ python examples/example.py help - - Documented commands (type help ): - ======================================== - alias help macro orate quit run_script set shortcuts - edit history mumble py run_pyscript say shell speak - - (Cmd) - -You may need more control over command line arguments passed from the operating -system shell. For example, you might have a command inside your ``cmd2`` -program which itself accepts arguments, and maybe even option strings. Say you -wanted to run the ``speak`` command from the operating system shell, but have -it say it in pig latin:: - - $ python example/example.py speak -p hello there - python example.py speak -p hello there - usage: speak [-h] [-p] [-s] [-r REPEAT] words [words ...] - speak: error: the following arguments are required: words - *** Unknown syntax: -p - *** Unknown syntax: hello - *** Unknown syntax: there - (Cmd) - -Uh-oh, that's not what we wanted. ``cmd2`` treated ``-p``, ``hello``, and -``there`` as commands, which don't exist in that program, thus the syntax -errors. - -There is an easy way around this, which is demonstrated in -``examples/cmd_as_argument.py``. By setting ``allow_cli_args=False`` you can so -your own argument parsing of the command line:: - - $ python examples/cmd_as_argument.py speak -p hello there - ellohay heretay - -Check the source code of this example, especially the ``main()`` function, to -see the technique. - Integrating cmd2 with event loops --------------------------------- diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst deleted file mode 100644 index 19c4e547..00000000 --- a/docs/unfreefeatures.rst +++ /dev/null @@ -1,231 +0,0 @@ -Features requiring application changes -====================================== - - -Parsed statements ------------------ - -``cmd2`` passes ``arg`` to a ``do_`` method (or ``default``) as a Statement, a -subclass of string that includes many attributes of the parsed input: - -command - Name of the command called - -args - The arguments to the command with output redirection - or piping to shell commands removed - -command_and_args - A string of just the command and the arguments, with - output redirection or piping to shell commands removed - -argv - A list of arguments a-la ``sys.argv``, including - the command as ``argv[0]`` and the subsequent - arguments as additional items in the list. - Quotes around arguments will be stripped as will - any output redirection or piping portions of the command - -raw - Full input exactly as typed. - -terminator - Character used to end a multiline command - - - -If ``Statement`` does not contain an attribute, querying for it will return -``None``. - -(Getting ``arg`` as a ``Statement`` is technically "free", in that it requires -no application changes from the cmd_ standard, but there will be no result -unless you change your application to *use* any of the additional attributes.) - -.. _cmd: https://docs.python.org/3/library/cmd.html - - -Environment parameters ----------------------- - -Your application can define user-settable parameters which your code can -reference. First create a class attribute with the default value. Then update -the ``settable`` dictionary with your setting name and a short description -before you initialize the superclass. Here's an example, from -``examples/environment.py``: - -.. literalinclude:: ../examples/environment.py - -If you want to be notified when a setting changes (as we do above), then define -a method ``_onchange_{setting}()``. This method will be called after the user -changes a setting, and will receive both the old value and the new value. - -.. code-block:: text - - (Cmd) set --long | grep sunny - sunny: False # Is it sunny outside? - (Cmd) set --long | grep degrees - degrees_c: 22 # Temperature in Celsius - (Cmd) sunbathe - Too dim. - (Cmd) set degrees_c 41 - degrees_c - was: 22 - now: 41 - (Cmd) set sunny - sunny: True - (Cmd) sunbathe - UV is bad for your skin. - (Cmd) set degrees_c 13 - degrees_c - was: 41 - now: 13 - (Cmd) sunbathe - It's 13 C - are you a penguin? - - -Commands with flags -=================== - -All ``do_`` methods are responsible for interpreting the arguments passed to -them. However, ``cmd2`` lets a ``do_`` methods accept Unix-style *flags*. It -uses argparse_ to parse the flags, and they work the same way as for that -module. - -``cmd2`` defines a few decorators which change the behavior of how arguments -get parsed for and passed to a ``do_`` method. See the section -:ref:`decorators` for more information. - -.. _argparse: https://docs.python.org/3/library/argparse.html - -poutput, pfeedback, perror, ppaged -================================== - -Standard ``cmd`` applications produce their output with -``self.stdout.write('output')`` (or with ``print``, but ``print`` decreases -output flexibility). ``cmd2`` applications can use ``self.poutput('output')``, -``self.pfeedback('message')``, ``self.perror('errmsg')``, and -``self.ppaged('text')`` instead. These methods have these advantages: - -- Handle output redirection to file and/or pipe appropriately -- More concise - - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. -- Option to display long output using a pager via ``ppaged()`` - -.. automethod:: cmd2.cmd2.Cmd.poutput - :noindex: -.. automethod:: cmd2.cmd2.Cmd.perror - :noindex: -.. automethod:: cmd2.cmd2.Cmd.pfeedback - :noindex: -.. automethod:: cmd2.cmd2.Cmd.ppaged - :noindex: - - -Colored Output -============== - -The output methods in the previous section all honor the ``allow_ansi`` -setting, which has three possible values: - -Never - poutput(), pfeedback(), and ppaged() strip all ANSI escape sequences - which instruct the terminal to colorize output - -Terminal - (the default value) poutput(), pfeedback(), and ppaged() do not strip any - ANSI escape sequences when the output is a terminal, but if the output is a - pipe or a file the escape sequences are stripped. If you want colorized - output you must add ANSI escape sequences using either cmd2's internal ansi - module or another color library such as `plumbum.colors`, `colorama`, or - `colored`. - -Always - poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences, - regardless of the output destination - -Colored and otherwise styled output can be generated using the `ansi.style()` -function: - -.. automethod:: cmd2.ansi.style - - -.. _quiet: - -Suppressing non-essential output -================================ - -The ``quiet`` setting controls whether ``self.pfeedback()`` actually produces -any output. If ``quiet`` is ``False``, then the output will be produced. If -``quiet`` is ``True``, no output will be produced. - -This makes ``self.pfeedback()`` useful for non-essential output like status -messages. Users can control whether they would like to see these messages by -changing the value of the ``quiet`` setting. - - -select -====== - -Presents numbered options to user, as bash ``select``. - -``app.select`` is called from within a method (not by the user directly; it is -``app.select``, not ``app.do_select``). - -.. automethod:: cmd2.cmd2.Cmd.select - :noindex: - -:: - - def do_eat(self, arg): - sauce = self.select('sweet salty', 'Sauce? ') - result = '{food} with {sauce} sauce, yum!' - result = result.format(food=arg, sauce=sauce) - self.stdout.write(result + '\n') - -:: - - (Cmd) eat wheaties - 1. sweet - 2. salty - Sauce? 2 - wheaties with salty sauce, yum! - - -Exit code to shell -================== - -The ``self.exit_code`` attribute of your ``cmd2`` application controls what -exit code is returned from ``cmdloop()`` when it completes. It is your job to -make sure that this exit code gets sent to the shell when your application -exits by calling ``sys.exit(app.cmdloop())``. - - -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 -- cgit v1.2.1