diff options
Diffstat (limited to 'docs/features')
| -rw-r--r-- | docs/features/builtin_commands.rst | 3 | ||||
| -rw-r--r-- | docs/features/embedded_python_shells.rst | 6 | ||||
| -rw-r--r-- | docs/features/initialization.rst | 8 | ||||
| -rw-r--r-- | docs/features/multiline_commands.rst | 10 | ||||
| -rw-r--r-- | docs/features/prompt.rst | 7 | ||||
| -rw-r--r-- | docs/features/settings.rst | 35 | ||||
| -rw-r--r-- | docs/features/transcripts.rst | 4 |
7 files changed, 30 insertions, 43 deletions
diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst index 540cfbb1..025149b3 100644 --- a/docs/features/builtin_commands.rst +++ b/docs/features/builtin_commands.rst @@ -93,14 +93,11 @@ within a running application: (Cmd) set --long allow_style: Terminal # Allow ANSI text style sequences in output (valid values: Terminal, Always, Never) - continuation_prompt: > # On 2nd+ line of input debug: False # Show full error stack on error echo: False # Echo command issued into output editor: vim # Program used by ``edit`` feedback_to_output: False # include nonessentials in `|`, `>` results - locals_in_py: False # Allow access to your application in py via self max_completion_items: 50 # Maximum number of CompletionItems to display during tab completion - prompt: (Cmd) # The prompt issued to solicit input quiet: False # Don't print nonessential feedback timing: False # Report execution times diff --git a/docs/features/embedded_python_shells.rst b/docs/features/embedded_python_shells.rst index 9d721c2c..0af2f737 100644 --- a/docs/features/embedded_python_shells.rst +++ b/docs/features/embedded_python_shells.rst @@ -8,11 +8,9 @@ arguments, it enters an interactive Python session. The session can call your cmd2 application while maintaining isolation. You may optionally enable full access to to your application by setting -``locals_in_py`` to ``True``. Enabling this flag adds ``self`` to the python +``self_in_py`` to ``True``. Enabling this flag adds ``self`` to the python session, which is a reference to your Cmd2 application. This can be useful for -debugging your application. To prevent users from enabling this ability -manually you'll need to remove ``locals_in_py`` from the ``settable`` -dictionary. +debugging your application. The ``app`` object (or your custom name) provides access to application commands through raw commands. For example, any application command call be diff --git a/docs/features/initialization.rst b/docs/features/initialization.rst index 39e36428..c5df5af8 100644 --- a/docs/features/initialization.rst +++ b/docs/features/initialization.rst @@ -39,7 +39,7 @@ capabilities which you may wish to utilize while initializing the app:: self.continuation_prompt = '... ' # Allow access to your application in py and ipy via self - self.locals_in_py = True + self.self_in_py = True # Set the default category name self.default_category = 'cmd2 Built-in Commands' @@ -110,7 +110,7 @@ override: DisabledCommand objects. - **echo**: if ``True``, each command the user issues will be repeated to the screen before it is executed. This is particularly useful when running - scripts. This behavior does not occur when a running command at the prompt. + scripts. This behavior does not occur when running a command at the prompt. (Default: ``False``) - **editor**: text editor program to use with *edit* command (e.g. ``vim``) - **exclude_from_history**: commands to exclude from the *history* command @@ -125,7 +125,7 @@ override: of results in a Python script or interactive console. Built-in commands don't make use of this. It is purely there for user-defined commands and convenience. -- **locals_in_py**: if ``True`` allow access to your application in *py* +- **self_in_py**: if ``True`` allow access to your application in *py* command via ``self`` (Default: ``False``) - **macros**: dictionary of macro names and their values - **max_completion_items**: max number of CompletionItems to display during @@ -139,7 +139,7 @@ override: ``app``) - **py_locals**: dictionary that defines specific variables/functions available in Python shells and scripts (provides more fine-grained control than making - everything available with **locals_in_py**) + everything available with **self_in_py**) - **quiet**: if ``True`` then completely suppress nonessential output (Default: ``False``) - **quit_on_sigint**: if ``True`` quit the main loop on interrupt instead of diff --git a/docs/features/multiline_commands.rst b/docs/features/multiline_commands.rst index d6502058..769e0a64 100644 --- a/docs/features/multiline_commands.rst +++ b/docs/features/multiline_commands.rst @@ -10,3 +10,13 @@ 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. + +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 +:ref:`features/prompt:Customizing the Prompt`. The prompt for subsequent lines +of input is defined by the ``cmd2.Cmd.continuation_prompt`` attribute. diff --git a/docs/features/prompt.rst b/docs/features/prompt.rst index 40c50d2b..244ffb31 100644 --- a/docs/features/prompt.rst +++ b/docs/features/prompt.rst @@ -3,6 +3,13 @@ Prompt ``cmd2`` can issue a prompt before soliciting user input. +Customizing the Prompt +---------------------- + +This prompt can be configured by setting the `cmd2.Cmd.prompt` instance +attribute. This contains the string which should be printed as a prompt +for user input. + Asynchronous Feedback --------------------- diff --git a/docs/features/settings.rst b/docs/features/settings.rst index b8f75934..55b6a10d 100644 --- a/docs/features/settings.rst +++ b/docs/features/settings.rst @@ -47,16 +47,6 @@ This setting can be one of three values: - ``Always`` - ANSI escape sequences are always passed through to the output -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 -:ref:`features/settings:prompt` setting. The prompt for subsequent lines of -input is defined by this setting. - - debug ~~~~~ @@ -71,7 +61,7 @@ echo If ``True``, each command the user issues will be repeated to the screen before it is executed. This is particularly useful when running scripts. -This behavior does not occur when a running command at the prompt. +This behavior does not occur when running a command at the prompt. editor @@ -95,13 +85,6 @@ feedback output will be mixed in with and indistinguishable from output generated with :meth:`~cmd2.cmd2.Cmd.poutput`. -locals_in_py -~~~~~~~~~~~~ - -Allow access to your application in one of the -:ref:`features/embedded_python_shells:Embedded Python Shells` via ``self``. - - max_completion_items ~~~~~~~~~~~~~~~~~~~~ @@ -115,13 +98,6 @@ they will be displayed in the typical columnized format and will not include the description text of the CompletionItem. -prompt -~~~~~~ - -This setting contains the string which should be printed as a prompt for user -input. - - quiet ~~~~~ @@ -180,14 +156,13 @@ You may want to prevent a user from modifying a builtin setting. A setting must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it to be available to the :ref:`features/builtin_commands:set` command. -Let's say your program does not have any -:ref:`features/multiline_commands:Multiline Commands`. You might want to hide -the :ref:`features/settings:continuation_prompt` setting from your users since -it is only applicable to multiline commands. To do so, remove it from the +Let's say that you never want end users of your program to be able to enable +full debug tracebacks to print out if an error occurs. You might want to hide +the :ref:`features/settings:debug` setting. To do so, remove it from the :attr:`cmd2.cmd2.Cmd.settable` dictionary after you initialize your object:: class MyApp(cmd2.Cmd): def __init__(self): super().__init__() - self.settable.pop('continuation_prompt') + self.settable.pop('debug') diff --git a/docs/features/transcripts.rst b/docs/features/transcripts.rst index 9f524e0a..1af2a74f 100644 --- a/docs/features/transcripts.rst +++ b/docs/features/transcripts.rst @@ -146,8 +146,8 @@ the path instead of specifying it verbatim, or we can escape the slashes:: invisible, you can add a regular expression to match them, so that you can see where they are when you look at the transcript:: - (Cmd) set prompt - prompt: (Cmd)/ / + (Cmd) set editor + editor: vim/ / 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 |