Struct cargo_lambda_interactive::Text

pub struct Text<'a> {
    pub message: &'a str,
    pub initial_value: Option<&'a str>,
    pub default: Option<&'a str>,
    pub placeholder: Option<&'a str>,
    pub help_message: Option<&'a str>,
    pub formatter: &'a (dyn Fn(&str) + 'a),
    pub validators: Vec<&'a (dyn Fn(&str) + 'a), Global>,
    pub page_size: usize,
    pub suggester: Option<&'a (dyn Fn(&str) + 'a)>,
    pub render_config: RenderConfig,
}

Standard text prompt that returns the user string input.

This is the standard the standard kind of prompt you would expect from a library like this one. It displays a message to the user, prompting them to type something back. The user’s input is then stored in a String and returned to the prompt caller.

Configuration options

• Prompt message: Main message when prompting the user for input, "What is your name?" in the example below.
• Help message: Message displayed at the line below the prompt.
• Default value: Default value returned when the user submits an empty response.
• Initial value: Initial value of the prompt’s text input, in case you want to display the prompt with something already filled in.
• Placeholder: Short hint that describes the expected value of the input.
• Validators: Custom validators to the user’s input, displaying an error message if the input does not pass the requirements.
• Formatter: Custom formatter in case you need to pre-process the user input before showing it as the final answer.
• Suggester: Custom function that returns a list of input suggestions based on the current text input. See more on “Autocomplete” below.

Default behaviors

Default behaviors for each one of Text configuration options:

• The input formatter just echoes back the given input.
• No validators are called, accepting any sort of input including empty ones.
• No default values or help messages.
• No auto-completion features set-up.
• Prompt messages are always required when instantiating via new().

Autocomplete

With Text inputs, it is also possible to set-up an auto-completion system to provide a better UX when necessary.

You can set-up a custom Suggester function, which receives the current input as the only argument and should return a vector of strings, the suggested values.

The user is then able to select one of them by moving up and down the list, possibly further modifying a selected suggestion.

Example

use inquire::Text;

let name = Text::new("What is your name?").prompt();

match name {
    Ok(name) => println!("Hello {}", name),
    Err(_) => println!("An error happened when asking for your name, try again later."),
}

Fields

message: &'a str

Message to be presented to the user.

initial_value: Option<&'a str>

Initial value of the prompt’s text input.

If you want to set a default value for the prompt, returned when the user’s submission is empty, see [default].

default: Option<&'a str>

Default value, returned when the user input is empty.

placeholder: Option<&'a str>

Short hint that describes the expected value of the input.

help_message: Option<&'a str>

Help message to be presented to the user.

formatter: &'a (dyn Fn(&str) + 'a)

Function that formats the user input and presents it to the user as the final rendering of the prompt.

validators: Vec<&'a (dyn Fn(&str) + 'a), Global>

Collection of validators to apply to the user input.

Validators are executed in the order they are stored, stopping at and displaying to the user only the first validation error that might appear.

The possible error is displayed to the user one line above the prompt.

page_size: usize

Page size of the suggestions displayed to the user, when applicable.

suggester: Option<&'a (dyn Fn(&str) + 'a)>

Function that provides a list of suggestions to the user based on the current input.

render_config: RenderConfig

RenderConfig to apply to the rendered interface.

Note: The default render config considers if the NO_COLOR environment variable is set to decide whether to render the colored config or the empty one.

When overriding the config in a prompt, NO_COLOR is no longer considered and your config is treated as the only source of truth. If you want to customize colors and still suport NO_COLOR, you will have to do this on your end.

Implementations

impl<'a> Text<'a>

pub const DEFAULT_FORMATTER: &'a (dyn Fn(&str) + 'a) = DEFAULT_STRING_FORMATTER

Default formatter, set to DEFAULT_STRING_FORMATTER

pub const DEFAULT_PAGE_SIZE: usize = 7usize

Default page size, equal to the global default page size [config::DEFAULT_PAGE_SIZE]

pub const DEFAULT_VALIDATORS: Vec<&'a (dyn Fn(&str) + 'a), Global> = ::alloc::vec::Vec::new()

Default validators added to the Text prompt, none.

pub const DEFAULT_HELP_MESSAGE: Option<&'a str> = None

Default help message.

pub fn new(message: &'a str) -> Text<'a>

Creates a Text with the provided message and default options.

pub fn with_help_message(self, message: &'a str) -> Text<'a>

Sets the help message of the prompt.

pub fn with_initial_value(self, message: &'a str) -> Text<'a>

Sets the initial value of the prompt’s text input.

If you want to set a default value for the prompt, returned when the user’s submission is empty, see [with_default].

pub fn with_default(self, message: &'a str) -> Text<'a>

Sets the default input.

pub fn with_placeholder(self, placeholder: &'a str) -> Text<'a>

Sets the placeholder.

pub fn with_suggester(self, suggester: &'a (dyn Fn(&str) + 'a)) -> Text<'a>

Sets the suggester.

pub fn with_formatter(self, formatter: &'a (dyn Fn(&str) + 'a)) -> Text<'a>

Sets the formatter.

pub fn with_page_size(self, page_size: usize) -> Text<'a>

Sets the page size

pub fn with_validator(self, validator: &'a (dyn Fn(&str) + 'a)) -> Text<'a>

Adds a validator to the collection of validators. You might want to use this feature in case you need to require certain features from the user’s answer, such as defining a limit of characters.

Validators are executed in the order they are stored, stopping at and displaying to the user only the first validation error that might appear.

The possible error is displayed to the user one line above the prompt.

pub fn with_validators(self, validators: &[&'a (dyn Fn(&str) + 'a)]) -> Text<'a>

Adds the validators to the collection of validators in the order they are given. You might want to use this feature in case you need to require certain features from the user’s answer, such as defining a limit of characters.

Validators are executed in the order they are stored, stopping at and displaying to the user only the first validation error that might appear.

The possible error is displayed to the user one line above the prompt.

pub fn with_render_config(self, render_config: RenderConfig) -> Text<'a>

Sets the provided color theme to this prompt.

Note: The default render config considers if the NO_COLOR environment variable is set to decide whether to render the colored config or the empty one.

When overriding the config in a prompt, NO_COLOR is no longer considered and your config is treated as the only source of truth. If you want to customize colors and still suport NO_COLOR, you will have to do this on your end.

pub fn prompt_skippable(self) -> Result<Option<String>, InquireError>

Parses the provided behavioral and rendering options and prompts the CLI user for input according to the defined rules.

This method is intended for flows where the user skipping/cancelling the prompt - by pressing ESC - is considered normal behavior. In this case, it does not return Err(InquireError::OperationCanceled), but Ok(None).

Meanwhile, if the user does submit an answer, the method wraps the return type with Some.

pub fn prompt(self) -> Result<String, InquireError>

Parses the provided behavioral and rendering options and prompts the CLI user for input according to the defined rules.

Trait Implementations

impl<'a> Clone for Text<'a>

fn clone(&self) -> Text<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> From<&'a str> for Text<'a>

fn from(val: &'a str) -> Text<'a>

Converts to this type from the input type.