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<'a>,
}
Expand description
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>
.
- By default, a successfully submitted answer is displayed to the user simply as
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<'a>
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§
source§impl<'a> Editor<'a>
impl<'a> Editor<'a>
sourcepub const DEFAULT_FORMATTER: StringFormatter<'a> = _
pub const DEFAULT_FORMATTER: StringFormatter<'a> = _
Default formatter, set to DEFAULT_STRING_FORMATTER
sourcepub const DEFAULT_VALIDATORS: Vec<Box<dyn StringValidator>> = _
pub const DEFAULT_VALIDATORS: Vec<Box<dyn StringValidator>> = _
Default validators added to the Editor prompt, none.
sourcepub const DEFAULT_HELP_MESSAGE: Option<&'a str> = None
pub const DEFAULT_HELP_MESSAGE: Option<&'a str> = None
Default help message.
sourcepub fn new(message: &'a str) -> Self
pub fn new(message: &'a str) -> Self
Creates a Editor with the provided message and default options.
Examples found in repository?
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
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(())
}
sourcepub fn with_help_message(self, message: &'a str) -> Self
pub fn with_help_message(self, message: &'a str) -> Self
Sets the help message of the prompt.
sourcepub fn with_predefined_text(self, text: &'a str) -> Self
pub fn with_predefined_text(self, text: &'a str) -> Self
Sets the predefined text to be written into the temporary file.
sourcepub fn with_file_extension(self, file_extension: &'a str) -> Self
pub fn with_file_extension(self, file_extension: &'a str) -> Self
Sets the file extension of the temporary file.
sourcepub fn with_editor_command(self, editor_command: &'a OsStr) -> Self
pub fn with_editor_command(self, editor_command: &'a OsStr) -> Self
Sets the command to open the editor.
sourcepub fn with_args(self, args: &'a [&'a OsStr]) -> Self
pub fn with_args(self, args: &'a [&'a OsStr]) -> Self
Sets the args for the command to open the editor.
sourcepub fn with_formatter(self, formatter: StringFormatter<'a>) -> Self
pub fn with_formatter(self, formatter: StringFormatter<'a>) -> Self
Sets the formatter.
Examples found in repository?
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
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(())
}
sourcepub fn with_validator<V>(self, validator: V) -> Selfwhere
V: StringValidator + 'static,
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.
sourcepub fn with_validators(self, validators: &[Box<dyn StringValidator>]) -> Self
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.
sourcepub fn with_render_config(self, render_config: RenderConfig<'a>) -> Self
pub fn with_render_config(self, render_config: RenderConfig<'a>) -> 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?
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
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(())
}
sourcepub fn prompt_skippable(self) -> InquireResult<Option<String>>
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
.
sourcepub fn prompt(self) -> InquireResult<String>
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?
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
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(())
}