Prompt¶
cmd2
issues a configurable 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. See the Pirate example for the simple use case of statically
setting the prompt.
Continuation Prompt¶
When a user types a
Multiline Command
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. The prompt for
subsequent lines of input is defined by the
cmd2.Cmd.continuation_prompt
attribute.See the Initialization example
for a demonstration of customizing the continuation prompt.
Updating the prompt¶
If you wish to update the prompt between commands, you can do so using one of the Application Lifecycle Hooks such as a Postcommand hook. See PythonScripting for an example of dynamically updating the 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.
-
Cmd.
async_alert
(alert_msg: str, new_prompt: Optional[str] = None) → None Display an important message to the user while they are at a command line prompt. 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.
Raises a RuntimeError if called while another thread holds terminal_lock.
- IMPORTANT: This function will not print an alert unless it can acquire self.terminal_lock to ensure
- a prompt is onscreen. Therefore it is best to acquire the lock before calling this function to guarantee the alert prints and to avoid raising a RuntimeError.
Parameters: - alert_msg – the message to display to the user
- new_prompt – If you also want to change the prompt that is displayed, then include it here. See async_update_prompt() docstring for guidance on updating a prompt.
-
Cmd.
async_update_prompt
(new_prompt: str) → None Update the command line 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. If you do alter the actual text of the prompt, it is best to keep the prompt the same width as what’s on screen. Otherwise the user’s input text will be shifted and the update will not be seamless.
Raises a RuntimeError if called while another thread holds terminal_lock.
- IMPORTANT: This function will not update the prompt unless it can acquire self.terminal_lock to ensure
a prompt is onscreen. Therefore it is best to acquire the lock before calling this function to guarantee the prompt changes and to avoid raising a RuntimeError.
If user is at a continuation prompt while entering a multiline command, the onscreen prompt will not change. However self.prompt will still be updated and display immediately after the multiline line command completes.
Parameters: new_prompt – what to change the prompt to
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.
-
Cmd.
set_window_title
(title: str) → None Set the terminal window title.
Raises a RuntimeError if called while another thread holds terminal_lock.
- IMPORTANT: This function will not set the title unless it can acquire self.terminal_lock to avoid writing
- to stderr while a command is running. Therefore it is best to acquire the lock before calling this function to guarantee the title changes and to avoid raising a RuntimeError.
Parameters: title – the new window title
The easiest way to understand these functions is to see the AsyncPrinting example for a demonstration.