diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/freefeatures.rst | 10 | ||||
| -rw-r--r-- | docs/hooks.rst | 51 | ||||
| -rw-r--r-- | docs/integrating.rst | 29 | ||||
| -rw-r--r-- | docs/settingchanges.rst | 57 | ||||
| -rw-r--r-- | docs/unfreefeatures.rst | 70 |
5 files changed, 138 insertions, 79 deletions
diff --git a/docs/freefeatures.rst b/docs/freefeatures.rst index a03a1d08..0a95a829 100644 --- a/docs/freefeatures.rst +++ b/docs/freefeatures.rst @@ -174,13 +174,9 @@ More Python examples: Type "help", "copyright", "credits" or "license" for more information. (CmdLineApp) - Invoke python command, shell, or script - - py <command>: Executes a Python command. - py: Enters interactive Python mode. - End with ``Ctrl-D`` (Unix) / ``Ctrl-Z`` (Windows), ``quit()``, '`exit()``. - Non-python commands can be issued with ``app("your command")``. - Run python code from external script files with ``run("script.py")`` + End with `Ctrl-D` (Unix) / `Ctrl-Z` (Windows), `quit()`, `exit()`. + Non-python commands can be issued with: app("your command") + Run python code from external script files with: run("script.py") >>> import os >>> os.uname() diff --git a/docs/hooks.rst b/docs/hooks.rst index 2a5d7b5f..1696d365 100644 --- a/docs/hooks.rst +++ b/docs/hooks.rst @@ -76,24 +76,21 @@ Command Processing Loop When you call `.cmdloop()`, the following sequence of events are repeated until the application exits: -1. Output the prompt -2. Accept user input -3. Call `preparse()` - for backwards compatibility with prior releases of cmd2, now deprecated -4. Parse user input into `Statement` object -5. Call methods registered with `register_postparsing_hook()` -6. Call `postparsing_precmd()` - for backwards compatibility with prior releases of cmd2, now deprecated -7. Redirect output, if user asked for it and it's allowed -8. Start timer -9. Call methods registered with `register_precmd_hook()` -10. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` -11. Add statement to history -12. Call `do_command` method -13. Call methods registered with `register_postcmd_hook()` -14. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` -15. Stop timer and display the elapsed time -16. Stop redirecting output if it was redirected -17. Call methods registered with `register_cmdfinalization_hook()` -18. Call `postparsing_postcmd()` - for backwards compatibility - deprecated +#. Output the prompt +#. Accept user input +#. Parse user input into `Statement` object +#. Call methods registered with `register_postparsing_hook()` +#. Redirect output, if user asked for it and it's allowed +#. Start timer +#. Call methods registered with `register_precmd_hook()` +#. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` +#. 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`` +#. Stop timer and display the elapsed time +#. Stop redirecting output if it was redirected +#. Call methods registered with `register_cmdfinalization_hook()` By registering hook methods, steps 4, 8, 12, and 16 allow you to run code during, and control the flow of the command processing loop. Be aware that @@ -305,21 +302,3 @@ 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 ``True``, then the exception will be rendered, and the application will terminate. - -Deprecated Command Processing Hooks ------------------------------------ - -Inside the main loop, every time the user hits <Enter> the line is processed by the ``onecmd_plus_hooks`` method. - -.. automethod:: cmd2.cmd2.Cmd.onecmd_plus_hooks - -As the ``onecmd_plus_hooks`` name implies, there are a number of *hook* methods that can be defined in order to inject -application-specific behavior at various points during the processing of a line of text entered by the user. ``cmd2`` -increases the 2 hooks provided by ``cmd`` (**precmd** and **postcmd**) to 6 for greater flexibility. Here are -the various hook methods, presented in chronological order starting with the ones called earliest in the process. - -.. automethod:: cmd2.cmd2.Cmd.preparse - -.. automethod:: cmd2.cmd2.Cmd.postparsing_precmd - -.. automethod:: cmd2.cmd2.Cmd.postparsing_postcmd diff --git a/docs/integrating.rst b/docs/integrating.rst index 8f605e06..a8377fdb 100644 --- a/docs/integrating.rst +++ b/docs/integrating.rst @@ -135,22 +135,19 @@ script file. The **onecmd_plus_hooks()** method will do the following to execute a single ``cmd2`` command in a normal fashion: -1. Call `preparse()` - for backwards compatibility with prior releases of cmd2, now deprecated -2. Parse user input into `Statement` object -3. Call methods registered with `register_postparsing_hook()` -4. Call `postparsing_precmd()` - for backwards compatibility with prior releases of cmd2, now deprecated -5. Redirect output, if user asked for it and it's allowed -6. Start timer -7. Call methods registered with `register_precmd_hook()` -8. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` -9. Add statement to history -10. Call `do_command` method -11. Call methods registered with `register_postcmd_hook()` -12. Call `postcmd(stop, statement)` - for backwards compatibility with ``cmd.Cmd`` -13. Stop timer and display the elapsed time -14. Stop redirecting output if it was redirected -15. Call methods registered with `register_cmdfinalization_hook()` -16. Call `postparsing_postcmd()` - for backwards compatibility - deprecated +#. Parse user input into `Statement` object +#. Call methods registered with `register_postparsing_hook()` +#. Redirect output, if user asked for it and it's allowed +#. Start timer +#. Call methods registered with `register_precmd_hook()` +#. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` +#. 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`` +#. Stop timer and display the elapsed time +#. Stop redirecting output if it was redirected +#. Call methods registered with `register_cmdfinalization_hook()` Running in this fashion enables the ability to integrate with an external event loop. However, how to integrate with any specific event loop is beyond the diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst index 02955273..25a671ab 100644 --- a/docs/settingchanges.rst +++ b/docs/settingchanges.rst @@ -50,17 +50,54 @@ To define more shortcuts, update the dict ``App.shortcuts`` with the Aliases ======= -In addition to shortcuts, ``cmd2`` provides a full alias feature via the ``alias`` command which is similar to the -``alias`` command in Bash. +In addition to shortcuts, ``cmd2`` provides a full alias feature via the ``alias`` command. Aliases work in a similar +fashion to aliases in the Bash shell. -The syntax to create an alias is ``alias <name> <value>``. ``value`` can contain spaces and does not need -to be quoted. Ex: ``alias ls !ls -lF`` +The syntax to create an alias is: ``alias create name command [args]``. -If ``alias`` is run without arguments, then a list of all aliases will be printed to stdout and are in the proper -``alias`` command syntax, meaning they can easily be reused. + Ex: ``alias create ls !ls -lF`` -The ``unalias`` is used to clear aliases. Using the ``-a`` flag will clear all aliases. Otherwise provide a list of -aliases to clear. Ex: ``unalias ls cd pwd`` will clear the aliases called ls, cd, and pwd. +For more details run: ``help alias create`` + +Use ``alias list`` to see all or some of your aliases. The output of this command displays your aliases using the same command that +was used to create them. Therefore you can place this output in a ``cmd2`` startup script to recreate your aliases each time +you start the application + + Ex: ``alias list`` + +For more details run: ``help alias list`` + +Use ``alias delete`` to remove aliases + +For more details run: ``help alias delete`` + +Macros +====== + +``cmd2`` provides a feature that is similar to aliases called macros. The major difference between macros and aliases +is that macros are intended to take arguments when called. These can be useful if you need to run a complex command +frequently with different arguments that appear in various parts of the command. + +Arguments are expressed when creating a macro using {#} notation where {1} means the first argument. + +The following creates a macro called my_macro that expects two arguments: + + macro create my_macro make_dinner -meat {1} -veggie {2} + +When the macro is called, the provided arguments are resolved and the assembled +command is run. For example: + + my_macro beef broccoli ---> make_dinner -meat beef -veggie broccoli + +For more details run: ``help macro create`` + +The macro command has ``list`` and ``delete`` subcommands that function identically to the alias subcommands of the +same name. Like aliases, macros can be created via a ``cmd2`` startup script to preserve them across application +sessions. + +For more details on listing macros run: ``help macro list`` + +For more details on deleting macros run: ``help macro delete`` Default to shell @@ -137,7 +174,7 @@ comments, is viewable from within a running application with:: (Cmd) set --long - colors: True # Colorized output (*nix only) + colors: Terminal # Allow colorized output continuation_prompt: > # On 2nd+ line of input debug: False # Show full error stack on error echo: False # Echo command issued into output @@ -150,5 +187,5 @@ with:: Any of these user-settable parameters can be set while running your app with the ``set`` command like so:: - set colors False + set colors Never diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst index cd27745d..364addc6 100644 --- a/docs/unfreefeatures.rst +++ b/docs/unfreefeatures.rst @@ -139,23 +139,43 @@ instead. These methods have these advantages: .. automethod:: cmd2.cmd2.Cmd.ppaged -color -===== +Colored Output +============== -Text output can be colored by wrapping it in the ``colorize`` method. +The output methods in the previous section all honor the ``colors`` setting, +which has three possible values: + +Never + poutput() and pfeedback() strip all ANSI escape sequences + which instruct the terminal to colorize output + +Terminal + (the default value) poutput() and pfeedback() 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, preferably using some python color library + like `plumbum.colors`, `colorama`, `blessings`, or `termcolor`. + +Always + poutput() and pfeedback() never strip ANSI escape sequences, regardless of + the output destination + + +The previously recommended ``colorize`` method is now deprecated. -.. automethod:: cmd2.cmd2.Cmd.colorize .. _quiet: +Suppressing non-essential output +================================ -quiet -===== +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. -Controls whether ``self.pfeedback('message')`` output is suppressed; -useful for non-essential feedback that the user may not always want -to read. ``quiet`` is only relevant if -``app.pfeedback`` is sometimes used. +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 @@ -189,3 +209,33 @@ Exit code to shell The ``self.exit_code`` attribute of your ``cmd2`` application controls what exit code is sent to the shell when your application exits from ``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 |