diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/cmd.rst | 16 | ||||
| -rw-r--r-- | docs/features/multiline_commands.rst | 4 | ||||
| -rw-r--r-- | docs/features/prompt.rst | 51 |
3 files changed, 51 insertions, 20 deletions
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst index e20e8eff..213a14ec 100644 --- a/docs/api/cmd.rst +++ b/docs/api/cmd.rst @@ -6,14 +6,26 @@ cmd2.Cmd .. automethod:: __init__ + .. attribute:: continuation_prompt + + Use as prompt for multiline commands on the 2nd+ line of input. + Default: ``>``. + + .. attribute:: default_error + + The error message displayed when a non-existent command is run. + Default: ``{} is not a recognized command, alias, or macro`` + .. attribute:: help_error The error message displayed to the user when they request help for a command with no help defined. + Default: ``No help on {}`` - .. attribute:: default_error + .. attribute:: prompt - The error message displayed when a non-existent command is run. + The prompt issued to solicit input. + Default: ``(Cmd)``. .. attribute:: settable diff --git a/docs/features/multiline_commands.rst b/docs/features/multiline_commands.rst index 96063867..6e0a4539 100644 --- a/docs/features/multiline_commands.rst +++ b/docs/features/multiline_commands.rst @@ -17,9 +17,9 @@ Continuation prompt When a user types a :ref:`Multiline Command <features/multiline_commands:Multiline Commands>` it may span more than one line of input. The prompt for the first line of input is specified by the -``cmd2.Cmd.prompt`` instance attribute - see +:attr:`cmd2.Cmd.prompt` instance attribute - see :ref:`features/prompt:Customizing the Prompt`. The prompt for subsequent lines -of input is defined by the ``cmd2.Cmd.continuation_prompt`` attribute. +of input is defined by the :attr:`cmd2.Cmd.continuation_prompt` attribute. Use cases --------- diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst index 244ffb31..49f8d1be 100644 --- a/docs/features/prompt.rst +++ b/docs/features/prompt.rst @@ -1,14 +1,40 @@ Prompt ====== -``cmd2`` can issue a prompt before soliciting user input. +``cmd2`` issues a configurable prompt before soliciting user input. Customizing the Prompt ---------------------- -This prompt can be configured by setting the `cmd2.Cmd.prompt` instance +This prompt can be configured by setting the :attr:`cmd2.Cmd.prompt` instance attribute. This contains the string which should be printed as a prompt -for user input. +for user input. See the Pirate_ example for the simple use case of statically +setting the prompt. + +.. _Pirate: https://github.com/python-cmd2/cmd2/blob/master/examples/pirate.py#L33 + +Continuation Prompt +------------------- + +When a user types a +:ref:`Multiline Command <features/multiline_commands:Multiline Commands>` +it may span more than one line of input. The prompt for the first line of input +is specified by the :attr:`cmd2.Cmd.prompt` instance attribute. The prompt for +subsequent lines of input is defined by the +:attr:`cmd2.Cmd.continuation_prompt` attribute.See the Initialization_ example +for a demonstration of customizing the continuation prompt. + +.. _Initialization: https://github.com/python-cmd2/cmd2/blob/master/examples/initialization.py#L33 + +Updating the prompt +------------------- + +If you wish to update the prompt between commands, you can do so using one of +the :ref:`Application Lifecycle Hooks <features/hooks:Hooks>` such as a +:ref:`Postcommand hook <features/hooks:Postcommand Hooks>`. See +PythonScripting_ for an example of dynamically updating the prompt. + +.. _PythonScripting: https://github.com/python-cmd2/cmd2/blob/master/examples/python_scripting.py#L34-L48 Asynchronous Feedback --------------------- @@ -20,26 +46,19 @@ 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. +.. automethod:: cmd2.Cmd.async_alert + :noindex: -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. +.. automethod:: cmd2.Cmd.async_update_prompt + :noindex: ``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 - +.. automethod:: cmd2.Cmd.set_window_title + :noindex: The easiest way to understand these functions is to see the AsyncPrinting_ example for a demonstration. |