From 332c49e024daa2b4395d09979ca139a9521d3a2a Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 20 Jan 2022 10:45:29 +0100 Subject: [PATCH 01/16] Two typo fixes. --- src/prompts/sort.rs | 2 +- src/theme.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/prompts/sort.rs b/src/prompts/sort.rs index 03152bf4..2782172c 100644 --- a/src/prompts/sort.rs +++ b/src/prompts/sort.rs @@ -57,7 +57,7 @@ impl Sort<'_> { /// Sets an optional max length for a page /// - /// Max length is disabled by None + /// Max length is disabled by `None` pub fn max_length(&mut self, val: usize) -> &mut Self { // Paging subtracts two from the capacity, paging does this to // make an offset for the page indicator. So to make sure that diff --git a/src/theme.rs b/src/theme.rs index 43ea7a01..bfdde318 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -619,7 +619,7 @@ impl Theme for ColorfulTheme { } } -/// Helper struct to conveniently render a theme ot a term. +/// Helper struct to conveniently render a theme to a term. pub(crate) struct TermThemeRenderer<'a> { term: &'a Term, theme: &'a dyn Theme, From 9c9ed0ee153808d61af89550ba45ec4e0d6f5563 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Mon, 14 Feb 2022 17:36:13 +0100 Subject: [PATCH 02/16] doc: use imperative tense more in render.rs. --- src/theme.rs | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/theme.rs b/src/theme.rs index bfdde318..a8b5e0b4 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -5,19 +5,19 @@ use console::{style, Style, StyledObject, Term}; /// Implements a theme for dialoguer. pub trait Theme { - /// Formats a prompt. + /// Format a prompt. #[inline] fn format_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { write!(f, "{}:", prompt) } - /// Formats out an error. + /// Format out an error. #[inline] fn format_error(&self, f: &mut dyn fmt::Write, err: &str) -> fmt::Result { write!(f, "error: {}", err) } - /// Formats a confirm prompt. + /// Format a confirmation prompt. fn format_confirm_prompt( &self, f: &mut dyn fmt::Write, @@ -35,7 +35,7 @@ pub trait Theme { Ok(()) } - /// Formats a confirm prompt after selection. + /// Format a confirmation prompt after selection. fn format_confirm_prompt_selection( &self, f: &mut dyn fmt::Write, @@ -58,7 +58,7 @@ pub trait Theme { } } - /// Formats an input prompt. + /// Format an input prompt. fn format_input_prompt( &self, f: &mut dyn fmt::Write, @@ -72,7 +72,7 @@ pub trait Theme { } } - /// Formats an input prompt after selection. + /// Format an input prompt after selection. #[inline] fn format_input_prompt_selection( &self, @@ -83,14 +83,14 @@ pub trait Theme { write!(f, "{}: {}", prompt, sel) } - /// Formats a password prompt. + /// Format a password prompt. #[inline] #[cfg(feature = "password")] fn format_password_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_input_prompt(f, prompt, None) } - /// Formats a password prompt after selection. + /// Format a password prompt after selection. #[inline] #[cfg(feature = "password")] fn format_password_prompt_selection( @@ -101,13 +101,13 @@ pub trait Theme { self.format_input_prompt_selection(f, prompt, "[hidden]") } - /// Formats a select prompt. + /// Format a select prompt. #[inline] fn format_select_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_prompt(f, prompt) } - /// Formats a select prompt after selection. + /// Format a select prompt after selection. #[inline] fn format_select_prompt_selection( &self, @@ -118,19 +118,19 @@ pub trait Theme { self.format_input_prompt_selection(f, prompt, sel) } - /// Formats a multi select prompt. + /// Format a multi select prompt. #[inline] fn format_multi_select_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_prompt(f, prompt) } - /// Formats a sort prompt. + /// Format a sort prompt. #[inline] fn format_sort_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_prompt(f, prompt) } - /// Formats a multi_select prompt after selection. + /// Format a multi_select prompt after selection. fn format_multi_select_prompt_selection( &self, f: &mut dyn fmt::Write, @@ -144,7 +144,7 @@ pub trait Theme { Ok(()) } - /// Formats a sort prompt after selection. + /// Format a sort prompt after selection. #[inline] fn format_sort_prompt_selection( &self, @@ -155,7 +155,7 @@ pub trait Theme { self.format_multi_select_prompt_selection(f, prompt, selections) } - /// Formats a select prompt item. + /// Format a select prompt item. fn format_select_prompt_item( &self, f: &mut dyn fmt::Write, @@ -186,7 +186,7 @@ pub trait Theme { ) } - /// Formats a sort prompt item. + /// Format a sort prompt item. fn format_sort_prompt_item( &self, f: &mut dyn fmt::Write, @@ -206,7 +206,7 @@ pub trait Theme { ) } - /// Formats a fuzzy select prompt. + /// Format a fuzzy select prompt. #[cfg(feature = "fuzzy-select")] fn format_fuzzy_select_prompt( &self, From 86ebe759fb9864a77037ce53a5567ce75f2d5220 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Mon, 14 Feb 2022 17:40:28 +0100 Subject: [PATCH 03/16] doc: Use imperative tense in select.rs. In addition, consistently speak of a 'selection prompt'. --- src/prompts/select.rs | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/prompts/select.rs b/src/prompts/select.rs index 5e4335fc..89beb5b7 100644 --- a/src/prompts/select.rs +++ b/src/prompts/select.rs @@ -5,7 +5,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme}; use console::{Key, Term}; -/// Renders a select prompt. +/// Render a selection prompt. /// /// User can select from one or more options. /// Interaction returns index of an item selected in the order they appear in `item` invocation or `items` slice. @@ -51,14 +51,14 @@ impl Default for Select<'static> { } impl Select<'static> { - /// Creates a select prompt builder with default theme. + /// Create a selection prompt builder with default theme. pub fn new() -> Self { Self::with_theme(&SimpleTheme) } } impl Select<'_> { - /// Indicates whether select menu should be erased from the screen after interaction. + /// Indicate whether the selection menu should be erased from the screen after interaction. /// /// The default is to clear the menu. pub fn clear(&mut self, val: bool) -> &mut Self { @@ -66,7 +66,7 @@ impl Select<'_> { self } - /// Sets initial selected element when select menu is rendered + /// Set the initial selected element when the selection menu is rendered. /// /// Element is indicated by the index at which it appears in `item` method invocation or `items` slice. pub fn default(&mut self, val: usize) -> &mut Self { @@ -106,7 +106,7 @@ impl Select<'_> { self } - /// Adds multiple items to the selector. + /// Add multiple items to the selector. /// /// ## Examples /// ```rust,no_run @@ -130,7 +130,7 @@ impl Select<'_> { self } - /// Sets the select prompt. + /// Set the selection prompt. /// /// By default, when a prompt is set the system also prints out a confirmation after /// the selection. You can opt-out of this with [`report`](#method.report). @@ -155,7 +155,7 @@ impl Select<'_> { self } - /// Indicates whether to report the selected value after interaction. + /// Indicate whether to report the selected value after interaction. /// /// The default is to report the selection. pub fn report(&mut self, val: bool) -> &mut Self { @@ -163,7 +163,7 @@ impl Select<'_> { self } - /// Enables user interaction and returns the result. + /// Enable user interaction and return the result. /// /// The user can select the items with the 'Space' bar or 'Enter' and the index of selected item will be returned. /// The dialog is rendered on stderr. @@ -174,7 +174,7 @@ impl Select<'_> { self.interact_on(&Term::stderr()) } - /// Enables user interaction and returns the result. + /// Enable user interaction and return the result. /// /// The user can select the items with the 'Space' bar or 'Enter' and the index of selected item will be returned. /// The dialog is rendered on stderr. @@ -350,7 +350,7 @@ impl Select<'_> { } impl<'a> Select<'a> { - /// Creates a select prompt builder with a specific theme. + /// Create a selection prompt builder with a specific theme. /// /// ## Examples /// ```rust,no_run From 7426264d19768615d09577289afa0ba809142d06 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Mon, 14 Feb 2022 17:42:31 +0100 Subject: [PATCH 04/16] doc: Reword some doc comments in select.rs. The comment on max_length was simply outdated. --- src/prompts/select.rs | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/prompts/select.rs b/src/prompts/select.rs index 89beb5b7..a6ab88e9 100644 --- a/src/prompts/select.rs +++ b/src/prompts/select.rs @@ -68,19 +68,17 @@ impl Select<'_> { /// Set the initial selected element when the selection menu is rendered. /// - /// Element is indicated by the index at which it appears in `item` method invocation or `items` slice. + /// The default element is indicated by the index at which it appears in the `item` method invocation or the `items` slice. pub fn default(&mut self, val: usize) -> &mut Self { self.default = val; self } - /// Sets an optional max length for a page. - /// - /// Max length is disabled by None + /// Set an optional max length for a page. pub fn max_length(&mut self, val: usize) -> &mut Self { // Paging subtracts two from the capacity, paging does this to // make an offset for the page indicator. So to make sure that - // we can show the intended amount of items we need to add two + // we can show the intended amount of items, we need to add two // to our value. self.max_length = Some(val + 2); self @@ -168,7 +166,7 @@ impl Select<'_> { /// The user can select the items with the 'Space' bar or 'Enter' and the index of selected item will be returned. /// The dialog is rendered on stderr. /// Result contains `index` if user selected one of items using 'Enter'. - /// This unlike [`interact_opt`](Self::interact_opt) does not allow to quit with 'Esc' or 'q'. + /// Unlike [`interact_opt`](Self::interact_opt), this does not allow to quit with 'Esc' or 'q'. #[inline] pub fn interact(&self) -> io::Result { self.interact_on(&Term::stderr()) From c2cc7c51b91c0734aa503f99646e66d57f71aa47 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Mon, 14 Feb 2022 19:09:52 +0100 Subject: [PATCH 05/16] doc: minor and grammar improvements in theme.rs. --- src/theme.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/theme.rs b/src/theme.rs index a8b5e0b4..7e45bf09 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -101,13 +101,13 @@ pub trait Theme { self.format_input_prompt_selection(f, prompt, "[hidden]") } - /// Format a select prompt. + /// Format a selection prompt. #[inline] fn format_select_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_prompt(f, prompt) } - /// Format a select prompt after selection. + /// Format a selection prompt after an item was selected. #[inline] fn format_select_prompt_selection( &self, @@ -118,7 +118,7 @@ pub trait Theme { self.format_input_prompt_selection(f, prompt, sel) } - /// Format a multi select prompt. + /// Format a multi-selection prompt. #[inline] fn format_multi_select_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { self.format_prompt(f, prompt) @@ -130,7 +130,7 @@ pub trait Theme { self.format_prompt(f, prompt) } - /// Format a multi_select prompt after selection. + /// Format a multi-selection prompt after an item was selected. fn format_multi_select_prompt_selection( &self, f: &mut dyn fmt::Write, @@ -144,7 +144,7 @@ pub trait Theme { Ok(()) } - /// Format a sort prompt after selection. + /// Format a sort prompt after an item was selected. #[inline] fn format_sort_prompt_selection( &self, @@ -155,7 +155,7 @@ pub trait Theme { self.format_multi_select_prompt_selection(f, prompt, selections) } - /// Format a select prompt item. + /// Format a single selection prompt item. fn format_select_prompt_item( &self, f: &mut dyn fmt::Write, @@ -165,7 +165,7 @@ pub trait Theme { write!(f, "{} {}", if active { ">" } else { " " }, text) } - /// Formats a multi select prompt item. + /// Format a single multi-selection prompt item. fn format_multi_select_prompt_item( &self, f: &mut dyn fmt::Write, @@ -206,7 +206,7 @@ pub trait Theme { ) } - /// Format a fuzzy select prompt. + /// Format a fuzzy selection prompt. #[cfg(feature = "fuzzy-select")] fn format_fuzzy_select_prompt( &self, @@ -848,7 +848,7 @@ impl<'a> TermThemeRenderer<'a> { pub fn clear_preserve_prompt(&mut self, size_vec: &[usize]) -> io::Result<()> { let mut new_height = self.height; - //Check each item size, increment on finding an overflow + // Check each item size, increment on finding an overflow for size in size_vec { if *size > self.term.size().1 as usize { new_height += 1; From 0d28b43d0b83174416f698ea192e15c3a03b271b Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Mon, 14 Feb 2022 19:17:38 +0100 Subject: [PATCH 06/16] Document some members in select.rs. I'm not sure about the grammar or format of the comments, but open to changing it. --- src/prompts/select.rs | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/prompts/select.rs b/src/prompts/select.rs index a6ab88e9..322b640c 100644 --- a/src/prompts/select.rs +++ b/src/prompts/select.rs @@ -35,12 +35,19 @@ use console::{Key, Term}; /// } /// ``` pub struct Select<'a> { + /// The initial selected element when the selection menu is rendered, + /// indicated by its index in [`items`](#field::items). default: usize, + /// Items the user can select. items: Vec, + /// Message of the selection prompt. prompt: Option, + /// whether to report the selected value after interaction report: bool, + /// whether the selection menu should be erased from the screen after interaction clear: bool, theme: &'a dyn Theme, + /// Maximal number of items on page (`None` if unbounded). max_length: Option, } From 684a08a8e9f3c518262bf2dade74ba0ae204de3b Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:25:42 +0200 Subject: [PATCH 07/16] doc: use imperative tense more in confirm.rs. --- src/prompts/confirm.rs | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/src/prompts/confirm.rs b/src/prompts/confirm.rs index 328f792f..b66cf575 100644 --- a/src/prompts/confirm.rs +++ b/src/prompts/confirm.rs @@ -4,7 +4,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme}; use console::{Key, Term}; -/// Renders a confirm prompt. +/// Render a confirmation prompt. /// /// ## Example usage /// @@ -35,20 +35,20 @@ impl Default for Confirm<'static> { } impl Confirm<'static> { - /// Creates a confirm prompt. + /// Create a confirmation prompt. pub fn new() -> Self { Self::with_theme(&SimpleTheme) } } impl Confirm<'_> { - /// Sets the confirm prompt. + /// Set the confirmation prompt message. pub fn with_prompt>(&mut self, prompt: S) -> &mut Self { self.prompt = prompt.into(); self } - /// Indicates whether or not to report the chosen selection after interaction. + /// Indicate whether or not to report the chosen selection after interaction. /// /// The default is to report the chosen selection. pub fn report(&mut self, val: bool) -> &mut Self { @@ -76,7 +76,7 @@ impl Confirm<'_> { self } - /// Sets a default. + /// Set a default choice for the prompt. /// /// Out of the box the prompt does not have a default and will continue /// to display until the user inputs something and hits enter. If a default is set the user @@ -86,7 +86,7 @@ impl Confirm<'_> { self } - /// Disables or enables the default value display. + /// Disable or enable the default value display. /// /// The default is to append the default value to the prompt to tell the user. pub fn show_default(&mut self, val: bool) -> &mut Self { @@ -94,7 +94,7 @@ impl Confirm<'_> { self } - /// Enables user interaction and returns the result. + /// Enable user interaction and return the result. /// /// The dialog is rendered on stderr. /// @@ -105,7 +105,7 @@ impl Confirm<'_> { self.interact_on(&Term::stderr()) } - /// Enables user interaction and returns the result. + /// Enable user interaction and return the result. /// /// The dialog is rendered on stderr. /// @@ -116,7 +116,7 @@ impl Confirm<'_> { self.interact_on_opt(&Term::stderr()) } - /// Like [interact](#method.interact) but allows a specific terminal to be set. + /// Like [interact](#method.interact) but allow a specific terminal to be set. /// /// ## Examples /// @@ -178,7 +178,7 @@ impl Confirm<'_> { let rv; if self.wait_for_newline { - // Waits for user input and for the user to hit the Enter key + // Wait for user input and for the user to hit the Enter key // before validation. let mut value = default_if_show; @@ -215,8 +215,8 @@ impl Confirm<'_> { render.confirm_prompt(&self.prompt, value)?; } } else { - // Default behavior: matches continuously on every keystroke, - // and does not wait for user to hit the Enter key. + // Default behavior: match continuously on every keystroke, + // and do not wait for the user to hit the Enter key. loop { let input = term.read_key()?; let value = match input { @@ -246,7 +246,7 @@ impl Confirm<'_> { } impl<'a> Confirm<'a> { - /// Creates a confirm prompt with a specific theme. + /// Create a confirm prompt with a specific theme. /// /// ## Examples /// ```rust,no_run From cdbab5587ad5a0174da4088d87aa7f184053f01a Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:27:57 +0200 Subject: [PATCH 08/16] doc: copy-edit some doc comments in confirm.rs. The comment of default() was misleading: if a default value is set, the user can still change the selected answer. They merely have the *additional* option of confirming the default choice. --- src/prompts/confirm.rs | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/src/prompts/confirm.rs b/src/prompts/confirm.rs index b66cf575..a9bb1f2a 100644 --- a/src/prompts/confirm.rs +++ b/src/prompts/confirm.rs @@ -78,9 +78,9 @@ impl Confirm<'_> { /// Set a default choice for the prompt. /// - /// Out of the box the prompt does not have a default and will continue - /// to display until the user inputs something and hits enter. If a default is set the user - /// can instead accept the default with enter. + /// Out of the box, the prompt does not have a default choice and will continue + /// to display until the user inputs something and hits enter. If a default is set, + /// the user can also accept the default with enter. pub fn default(&mut self, val: bool) -> &mut Self { self.default = Some(val); self @@ -98,8 +98,10 @@ impl Confirm<'_> { /// /// The dialog is rendered on stderr. /// - /// Result contains `bool` if user answered "yes" or "no" or `default` (configured in [`default`](Self::default) if pushes enter. - /// This unlike [`interact_opt`](Self::interact_opt) does not allow to quit with 'Esc' or 'q'. + /// Result contains `bool` if the user answered "yes" or "no" or `default` + /// (configured in [`default`](Self::default)) if they pushed enter. + /// Unlike [`interact_opt`](Self::interact_opt), this does not allow + /// to quit the dialog with 'Esc' or 'q'. #[inline] pub fn interact(&self) -> io::Result { self.interact_on(&Term::stderr()) @@ -109,8 +111,9 @@ impl Confirm<'_> { /// /// The dialog is rendered on stderr. /// - /// Result contains `Some(bool)` if user answered "yes" or "no" or `Some(default)` (configured in [`default`](Self::default)) if pushes enter, - /// or `None` if user cancelled with 'Esc' or 'q'. + /// Result contains `Some(bool)` if the user answered "yes" or "no" or `Some(default)` + /// (configured in [`default`](Self::default)) if they pushed enter, + /// or `None` if the user cancelled the prompt with 'Esc' or 'q'. #[inline] pub fn interact_opt(&self) -> io::Result> { self.interact_on_opt(&Term::stderr()) From 13a215323c974caf67bbf0d5d2e2b123cecf7efc Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:33:34 +0200 Subject: [PATCH 09/16] doc: Document members of the Confirm struct. --- src/prompts/confirm.rs | 5 +++++ src/theme.rs | 3 +++ 2 files changed, 8 insertions(+) diff --git a/src/prompts/confirm.rs b/src/prompts/confirm.rs index a9bb1f2a..f182b741 100644 --- a/src/prompts/confirm.rs +++ b/src/prompts/confirm.rs @@ -20,10 +20,15 @@ use console::{Key, Term}; /// # Ok(()) } fn main() { test().unwrap(); } /// ``` pub struct Confirm<'a> { + /// Message of the confirmation prompt. prompt: String, + /// Whether to report the user's choice after selection. report: bool, + /// default option for the prompt (if any) default: Option, + /// if true, show the default value to the user, see [`show_default`](#method::show_default) show_default: bool, + /// when to react to user input, see [`wait_for_newline`](#methhod::wait_for_newline) wait_for_newline: bool, theme: &'a dyn Theme, } diff --git a/src/theme.rs b/src/theme.rs index 7e45bf09..fc1fc2bc 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -18,6 +18,9 @@ pub trait Theme { } /// Format a confirmation prompt. + /// + /// `prompt` is the message of the confirmation prompt, + /// `default` is the default choice for the prompt (if any). fn format_confirm_prompt( &self, f: &mut dyn fmt::Write, From 1875fe535c300fe927f8d1f1e8dace1a5a034725 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:34:03 +0200 Subject: [PATCH 10/16] doc: Use imperative tense more in theme.rs. --- src/theme.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/theme.rs b/src/theme.rs index fc1fc2bc..185c9dc7 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -313,7 +313,7 @@ impl Default for ColorfulTheme { } impl Theme for ColorfulTheme { - /// Formats a prompt. + /// Format a prompt. fn format_prompt(&self, f: &mut dyn fmt::Write, prompt: &str) -> fmt::Result { if !prompt.is_empty() { write!( @@ -327,7 +327,7 @@ impl Theme for ColorfulTheme { write!(f, "{}", &self.prompt_suffix) } - /// Formats an error + /// Format an error. fn format_error(&self, f: &mut dyn fmt::Write, err: &str) -> fmt::Result { write!( f, @@ -337,7 +337,7 @@ impl Theme for ColorfulTheme { ) } - /// Formats an input prompt. + /// Format an input prompt. fn format_input_prompt( &self, f: &mut dyn fmt::Write, @@ -364,7 +364,7 @@ impl Theme for ColorfulTheme { } } - /// Formats a confirm prompt. + /// Format a confirmation prompt. fn format_confirm_prompt( &self, f: &mut dyn fmt::Write, @@ -404,7 +404,7 @@ impl Theme for ColorfulTheme { } } - /// Formats a confirm prompt after selection. + /// Format a confirmation prompt after selection. fn format_confirm_prompt_selection( &self, f: &mut dyn fmt::Write, From 537fd916c31e47fe503ba5ab476e8dfe9d0bcf5a Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:37:01 +0200 Subject: [PATCH 11/16] doc: use imperative tense in password.rs. --- src/prompts/password.rs | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/prompts/password.rs b/src/prompts/password.rs index c419d645..3edf5994 100644 --- a/src/prompts/password.rs +++ b/src/prompts/password.rs @@ -5,7 +5,7 @@ use crate::theme::{SimpleTheme, TermThemeRenderer, Theme}; use console::Term; use zeroize::Zeroizing; -/// Renders a password input prompt. +/// Render a password input prompt. /// /// ## Example usage /// @@ -34,20 +34,20 @@ impl Default for Password<'static> { } impl Password<'static> { - /// Creates a password input prompt. + /// Create a password input prompt. pub fn new() -> Password<'static> { Self::with_theme(&SimpleTheme) } } impl Password<'_> { - /// Sets the password input prompt. + /// Set the password input prompt. pub fn with_prompt>(&mut self, prompt: S) -> &mut Self { self.prompt = prompt.into(); self } - /// Indicates whether to report confirmation after interaction. + /// Indicate whether to report confirmation after interaction. /// /// The default is to report. pub fn report(&mut self, val: bool) -> &mut Self { @@ -73,7 +73,7 @@ impl Password<'_> { self } - /// Enables user interaction and returns the result. + /// Enable user interaction and return the result. /// /// If the user confirms the result is `true`, `false` otherwise. /// The dialog is rendered on stderr. @@ -81,7 +81,7 @@ impl Password<'_> { self.interact_on(&Term::stderr()) } - /// Like `interact` but allows a specific terminal to be set. + /// Like [`interact`](#method::interact), but allow a specific terminal to be set. pub fn interact_on(&self, term: &Term) -> io::Result { let mut render = TermThemeRenderer::new(term, self.theme); render.set_prompts_reset_height(false); @@ -131,7 +131,7 @@ impl Password<'_> { } impl<'a> Password<'a> { - /// Creates a password input prompt with a specific theme. + /// Create a password input prompt with a specific theme. pub fn with_theme(theme: &'a dyn Theme) -> Self { Self { prompt: "".into(), From 623acf853090492d68a4589bf7402535553fe0b0 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 16:57:46 +0200 Subject: [PATCH 12/16] doc: document members of password.rs. --- src/prompts/password.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/prompts/password.rs b/src/prompts/password.rs index 3edf5994..317c75a5 100644 --- a/src/prompts/password.rs +++ b/src/prompts/password.rs @@ -20,10 +20,14 @@ use zeroize::Zeroizing; /// # Ok(()) } fn main() { test().unwrap(); } /// ``` pub struct Password<'a> { + /// Message of the confirmation prompt. prompt: String, + /// Whether to print a confirmation message after selecting a password. report: bool, theme: &'a dyn Theme, + /// Whether an empty password is allowed. allow_empty_password: bool, + // Confirmation prompt for passwords: see [`with_confirmation`](#method::with_confirmation). confirmation_prompt: Option<(String, String)>, } @@ -47,7 +51,7 @@ impl Password<'_> { self } - /// Indicate whether to report confirmation after interaction. + /// Indicate whether to report a confirmation after interaction. /// /// The default is to report. pub fn report(&mut self, val: bool) -> &mut Self { @@ -55,7 +59,11 @@ impl Password<'_> { self } - /// Enables confirmation prompting. + /// Enable prompting for confirmation of the password: + /// if set, the user must type the same password again to confirm their choice. + /// + /// `prompt` is the prompt message for the confirmation prompt, + /// `mismatch_err` the error message printed upon mismatching passwords. pub fn with_confirmation(&mut self, prompt: A, mismatch_err: B) -> &mut Self where A: Into, @@ -65,9 +73,9 @@ impl Password<'_> { self } - /// Allows/Disables empty password. + /// Allow/disallow entering an empty password. /// - /// By default this setting is set to false (i.e. password is not empty). + /// By default this setting is set to false (i.e. empty passwords are not allowed). pub fn allow_empty_password(&mut self, allow_empty_password: bool) -> &mut Self { self.allow_empty_password = allow_empty_password; self From 782705620de66547477de093082249bec1de9f37 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Thu, 5 May 2022 17:10:30 +0200 Subject: [PATCH 13/16] doc: document four functions in theme.rs. --- src/theme.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/theme.rs b/src/theme.rs index 185c9dc7..c4776971 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -652,10 +652,14 @@ impl<'a> TermThemeRenderer<'a> { self.term } + /// Enlarge the theme by one line: allow displaying one more line of input. pub fn add_line(&mut self) { self.height += 1; } + /// Write a formatted string to this terminal. The string can be span multiple lines. + /// + /// `F` is a closure prescribing the text to write into the current instance. fn write_formatted_str< F: FnOnce(&mut TermThemeRenderer, &mut dyn fmt::Write) -> fmt::Result, >( @@ -668,6 +672,7 @@ impl<'a> TermThemeRenderer<'a> { self.term.write_str(&buf) } + /// Like [`write_formatted_string`](#method::write_formatted_string), but add a linebreak afterwards. fn write_formatted_line< F: FnOnce(&mut TermThemeRenderer, &mut dyn fmt::Write) -> fmt::Result, >( @@ -680,6 +685,9 @@ impl<'a> TermThemeRenderer<'a> { self.term.write_line(&buf) } + /// Write a formatted prompt string to this terminal. + /// + /// `F` is a closure prescribing the text to write into the current instance. fn write_formatted_prompt< F: FnOnce(&mut TermThemeRenderer, &mut dyn fmt::Write) -> fmt::Result, >( From 497de3826627255dc9b1fdc6b154de8e7516b4d5 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Fri, 6 May 2022 00:51:57 +0200 Subject: [PATCH 14/16] refactor: use prompts_reset_heights=true in password prompt. Setting it to false doesn't make a difference in practice. The distinction between self.height and self.prompt_height only matters when calling TermThemeRenderer::clear_preserve_prompt(): that method preserves prompts and only clears input below the most recent prompt. However, the password prompt only calls TermThemeRenderer::clear(), which treats height and prompt_height in the same way. The function set_prompts_reset_height is now unused, hence is removed. --- src/prompts/password.rs | 2 -- src/theme.rs | 5 ----- 2 files changed, 7 deletions(-) diff --git a/src/prompts/password.rs b/src/prompts/password.rs index 317c75a5..cbf94a17 100644 --- a/src/prompts/password.rs +++ b/src/prompts/password.rs @@ -92,8 +92,6 @@ impl Password<'_> { /// Like [`interact`](#method::interact), but allow a specific terminal to be set. pub fn interact_on(&self, term: &Term) -> io::Result { let mut render = TermThemeRenderer::new(term, self.theme); - render.set_prompts_reset_height(false); - loop { let password = Zeroizing::new(self.prompt_password(&mut render, &self.prompt)?); diff --git a/src/theme.rs b/src/theme.rs index c4776971..00ceb407 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -642,11 +642,6 @@ impl<'a> TermThemeRenderer<'a> { } } - #[cfg(feature = "password")] - pub fn set_prompts_reset_height(&mut self, val: bool) { - self.prompts_reset_height = val; - } - #[cfg(feature = "password")] pub fn term(&self) -> &Term { self.term From f1dfaa1c1ec1800a18d15a83809da9e9acaaa553 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Fri, 6 May 2022 00:53:13 +0200 Subject: [PATCH 15/16] refactor: remove prompts_reset_height: it's always true now. --- src/theme.rs | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/theme.rs b/src/theme.rs index 00ceb407..6d4285fe 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -628,7 +628,6 @@ pub(crate) struct TermThemeRenderer<'a> { theme: &'a dyn Theme, height: usize, prompt_height: usize, - prompts_reset_height: bool, } impl<'a> TermThemeRenderer<'a> { @@ -638,7 +637,6 @@ impl<'a> TermThemeRenderer<'a> { theme, height: 0, prompt_height: 0, - prompts_reset_height: true, } } @@ -690,10 +688,8 @@ impl<'a> TermThemeRenderer<'a> { f: F, ) -> io::Result<()> { self.write_formatted_line(f)?; - if self.prompts_reset_height { - self.prompt_height = self.height; - self.height = 0; - } + self.prompt_height = self.height; + self.height = 0; Ok(()) } From cb1ae52d49ef02e0128ad30415a0e5a647e53636 Mon Sep 17 00:00:00 2001 From: Mike Grunweg Date: Fri, 6 May 2022 12:22:30 +0200 Subject: [PATCH 16/16] doc: document meaning of height and prompt_height in TermThemeRenderer. --- src/theme.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/theme.rs b/src/theme.rs index 6d4285fe..1aeede2f 100644 --- a/src/theme.rs +++ b/src/theme.rs @@ -626,7 +626,11 @@ impl Theme for ColorfulTheme { pub(crate) struct TermThemeRenderer<'a> { term: &'a Term, theme: &'a dyn Theme, + /// Height (number of lines, ignoring lines overflowing the terminal) + /// of output after the last prompt: not counting the current line. height: usize, + /// Height (number of output lines, ignoring overflowing items) + /// of the last completed prompt and everything above it. prompt_height: usize, }