Struct inquire::Editor

pub struct Editor<'a> {
    pub message: &'a str,
    pub editor_command: &'a OsStr,
    pub editor_command_args: &'a [&'a OsStr],
    pub file_extension: &'a str,
    pub predefined_text: Option<&'a str>,
    pub help_message: Option<&'a str>,
    pub formatter: StringFormatter<'a>,
    pub validators: Vec<Box<dyn StringValidator>>,
    pub render_config: RenderConfig,
}

This prompt is meant for cases where you need the user to write some text that might not fit in a single line, such as long descriptions or commit messages.

This prompt is gated via the editor because it depends on the tempfile crate.

This prompt’s behavior is to ask the user to either open the editor - by pressing the e key - or submit the current text - by pressing the enter key. The user can freely open and close the editor as they wish, until they either cancel or submit.

The editor opened is set by default to nano on Unix environments and notepad on Windows environments. Additionally, if there’s an editor set in either the EDITOR or VISUAL environment variables, it is used instead.

If the user presses esc while the editor is not open, it will be interpreted as the user canceling (or skipping) the operation, in which case the prompt call will return Err(InquireError::OperationCanceled).

If the user presses enter without ever modyfing the temporary file, it will be treated as an empty submission. If this is unwanted behavior, you can control the user input by using validators.

Finally, this prompt allows a great range of customizable options as all others:

• Prompt message: Main message when prompting the user for input, "What is your name?" in the example above.
• Help message: Message displayed at the line below the prompt.
• Editor command and its args: If you want to override the selected editor, you can pass over the command and additional args.
• File extension: Custom extension for the temporary file, useful as a proxy for proper syntax highlighting for example.
• Predefined text: Pre-defined text to be written to the temporary file before the user is allowed to edit it.
• 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.
  • By default, a successfully submitted answer is displayed to the user simply as <received>.

Fields

message: &'a str

Message to be presented to the user.

editor_command: &'a OsStr

Command to open the editor.

editor_command_args: &'a [&'a OsStr]

Args to pass to the editor.

file_extension: &'a str

Extension of the file opened in the text editor, useful for syntax highlighting.

The dot prefix should be included in the string, e.g. “.rs”.

predefined_text: Option<&'a str>

Predefined text to be present on the text file on the text editor.

help_message: Option<&'a str>

Help message to be presented to the user.

formatter: StringFormatter<'a>

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

validators: Vec<Box<dyn StringValidator>>

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.

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> Editor<'a>

pub const DEFAULT_FORMATTER: StringFormatter<'a> = _

Default formatter, set to DEFAULT_STRING_FORMATTER

pub const DEFAULT_VALIDATORS: Vec<Box<dyn StringValidator>> = _

Default validators added to the Editor prompt, none.

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

Default help message.

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

Creates a Editor with the provided message and default options.

Examples found in repository

examples/editor.rs (line 10)

fn main() -> InquireResult<()> {
    let _title = Text::new("Title:").prompt()?;

    let _description = Editor::new("Description:")
        .with_formatter(&|submission| {
            let char_count = submission.chars().count();
            if char_count == 0 {
                String::from("<skipped>")
            } else if char_count <= 20 {
                submission.into()
            } else {
                let mut substr: String = submission.chars().take(17).collect();
                substr.push_str("...");
                substr
            }
        })
        .with_render_config(description_render_config())
        .prompt()?;

    Ok(())
}

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

Sets the help message of the prompt.

pub fn with_predefined_text(self, text: &'a str) -> Self

Sets the predefined text to be written into the temporary file.

pub fn with_file_extension(self, file_extension: &'a str) -> Self

Sets the file extension of the temporary file.

pub fn with_editor_command(self, editor_command: &'a OsStr) -> Self

Sets the command to open the editor.

pub fn with_args(self, args: &'a [&'a OsStr]) -> Self

Sets the args for the command to open the editor.

pub fn with_formatter(self, formatter: StringFormatter<'a>) -> Self

Sets the formatter.

Examples found in repository

examples/editor.rs (lines 11-22)

fn main() -> InquireResult<()> {
    let _title = Text::new("Title:").prompt()?;

    let _description = Editor::new("Description:")
        .with_formatter(&|submission| {
            let char_count = submission.chars().count();
            if char_count == 0 {
                String::from("<skipped>")
            } else if char_count <= 20 {
                submission.into()
            } else {
                let mut substr: String = submission.chars().take(17).collect();
                substr.push_str("...");
                substr
            }
        })
        .with_render_config(description_render_config())
        .prompt()?;

    Ok(())
}

pub fn with_validator<V>(self, validator: V) -> Selfwhere
    V: StringValidator + 'static,

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: &[Box<dyn StringValidator>]) -> Self

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) -> Self

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.

Examples found in repository

examples/editor.rs (line 23)

fn main() -> InquireResult<()> {
    let _title = Text::new("Title:").prompt()?;

    let _description = Editor::new("Description:")
        .with_formatter(&|submission| {
            let char_count = submission.chars().count();
            if char_count == 0 {
                String::from("<skipped>")
            } else if char_count <= 20 {
                submission.into()
            } else {
                let mut substr: String = submission.chars().take(17).collect();
                substr.push_str("...");
                substr
            }
        })
        .with_render_config(description_render_config())
        .prompt()?;

    Ok(())
}

pub fn prompt_skippable(self) -> InquireResult<Option<String>>

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) -> InquireResult<String>

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

Examples found in repository

examples/editor.rs (line 24)

fn main() -> InquireResult<()> {
    let _title = Text::new("Title:").prompt()?;

    let _description = Editor::new("Description:")
        .with_formatter(&|submission| {
            let char_count = submission.chars().count();
            if char_count == 0 {
                String::from("<skipped>")
            } else if char_count <= 20 {
                submission.into()
            } else {
                let mut substr: String = submission.chars().take(17).collect();
                substr.push_str("...");
                substr
            }
        })
        .with_render_config(description_render_config())
        .prompt()?;

    Ok(())
}

Trait Implementations

impl<'a> Clone for Editor<'a>

fn clone(&self) -> Editor<'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 Editor<'a>

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

Converts to this type from the input type.