Struct Question

Source

pub struct Question<R, W>where
    R: Read,
    W: Write,
{ /* private fields */ }

Expand description

An Answer builder. Once a question has been formulated either ask or confirm may be used to get an answer.

§Examples

The ask function will execute exactly the configuration of the question. This will ask the user if they would like to continue until they provide a valid yes or no response.

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .ask();

The following confirm function is exactly equivalent.

Question::new("Do you want to continue?").confirm();

Implementations§

Source §

impl Question<Stdin, Stdout>

Source

pub fn new(question: &str) -> Question<Stdin, Stdout>

Create a new Question.

§Examples

Question::new("What is your favorite color?").ask();

Examples found in repository ?

examples/yes_or_no.rs (line 5)

4fn main() {
5    let answer = Question::new("Continue?").confirm();
6    let correct = Answer::YES;
7    assert_eq!(answer, correct);
8}

More examples

Hide additional examples

examples/custom_yes_no.rs (line 5)

4fn main() {
5    let answer = Question::new("Continue?")
6        .accept("y")
7        .accept("n")
8        .until_acceptable()
9        .ask();
10    let correct = Some(Answer::RESPONSE(String::from("y")));
11    assert_eq!(answer, correct);
12}

examples/yes_no_with_defaults.rs (line 5)

4fn main() {
5    let answer = Question::new("Continue?")
6        .default(Answer::YES)
7        .show_defaults()
8        .confirm();
9
10    if answer == Answer::YES {
11        println!("Onward then!");
12    } else {
13        println!("Aborting...");
14    }
15}

examples/ultimate_question.rs (line 8)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let answer = Question::new(question).ask().unwrap();
9    let correct = Answer::RESPONSE(String::from("42"));
10    assert_eq!(answer, correct);
11}

examples/defaults.rs (line 9)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let default = Answer::RESPONSE(String::from("42"));
9    let answer = Question::new(question)
10        .default(default.clone())
11        .show_defaults()
12        .ask()
13        .unwrap();
14    let correct = default;
15    assert_eq!(answer, correct);
16}

Source §

impl<R, W> Question<R, W>
where R: Read, W: Write,

Source

pub fn accept(&mut self, accepted: &str) -> &mut Question<R, W>

Add a single acceptable response to the list.

§Examples

The following will ask the user if they would like to continue until either “y” or “n” is entered.

Question::new("Do you want to continue?")
    .accept("y")
    .accept("n")
    .until_acceptable()
    .ask();

Examples found in repository ?

examples/custom_yes_no.rs (line 6)

4fn main() {
5    let answer = Question::new("Continue?")
6        .accept("y")
7        .accept("n")
8        .until_acceptable()
9        .ask();
10    let correct = Some(Answer::RESPONSE(String::from("y")));
11    assert_eq!(answer, correct);
12}

Source

pub fn acceptable(&mut self, accepted: Vec<&str>) -> &mut Question<R, W>

Add a collection of acceptable responses to the list.

§Examples

The following will ask the user if they would like to continue until either “y” or “n” is entered.

Question::new("Do you want to continue?")
    .acceptable(vec!["y", "n"])
    .until_acceptable()
    .ask();

Source

pub fn yes_no(&mut self) -> &mut Question<R, W>

Shorthand the most common case of a yes/no question.

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, or “no”, is entered.

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .ask();

Source

pub fn tries(&mut self, tries: u64) -> &mut Question<R, W>

Set a maximum number of attempts to try and get an acceptable answer from the user.

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, or “no”, is entered, or until they have entered 3 invalid responses.

Question::new("Do you want to continue?")
    .yes_no()
    .tries(3)
    .ask();

Source

pub fn until_acceptable(&mut self) -> &mut Question<R, W>

Never stop asking until the user provides an acceptable answer.

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, or “no”, is entered.

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .ask();

Examples found in repository ?

examples/custom_yes_no.rs (line 8)

4fn main() {
5    let answer = Question::new("Continue?")
6        .accept("y")
7        .accept("n")
8        .until_acceptable()
9        .ask();
10    let correct = Some(Answer::RESPONSE(String::from("y")));
11    assert_eq!(answer, correct);
12}

Source

pub fn show_defaults(&mut self) -> &mut Question<R, W>

Show the default response to the user that will be submitted if they enter an empty string "\n".

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, or “no”, is entered. Since no default was set the prompt will be displayed with (y/n) after it, and if the user enters an empty string no answer will be returned and they will be re-prompted.

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .show_defaults()
    .ask();

If either Answer::YES or Answer::NO have been set as default then the prompt will be shown with that entry capitalized, either (Y/n) or (y/N).

Examples found in repository ?

examples/yes_no_with_defaults.rs (line 7)

4fn main() {
5    let answer = Question::new("Continue?")
6        .default(Answer::YES)
7        .show_defaults()
8        .confirm();
9
10    if answer == Answer::YES {
11        println!("Onward then!");
12    } else {
13        println!("Aborting...");
14    }
15}

More examples

Hide additional examples

examples/defaults.rs (line 11)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let default = Answer::RESPONSE(String::from("42"));
9    let answer = Question::new(question)
10        .default(default.clone())
11        .show_defaults()
12        .ask()
13        .unwrap();
14    let correct = default;
15    assert_eq!(answer, correct);
16}

Source

pub fn default(&mut self, answer: Answer) -> &mut Question<R, W>

Provide a default answer.

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, “no”, or “” an empty string is entered. If an empty string is entered Answer::YES will be returned.

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .default(Answer::YES)
    .show_defaults()
    .ask();

Examples found in repository ?

examples/yes_no_with_defaults.rs (line 6)

4fn main() {
5    let answer = Question::new("Continue?")
6        .default(Answer::YES)
7        .show_defaults()
8        .confirm();
9
10    if answer == Answer::YES {
11        println!("Onward then!");
12    } else {
13        println!("Aborting...");
14    }
15}

More examples

Hide additional examples

examples/defaults.rs (line 10)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let default = Answer::RESPONSE(String::from("42"));
9    let answer = Question::new(question)
10        .default(default.clone())
11        .show_defaults()
12        .ask()
13        .unwrap();
14    let correct = default;
15    assert_eq!(answer, correct);
16}

Source

pub fn clarification(&mut self, c: &str) -> &mut Question<R, W>

Provide a clarification to be shown if the user does not enter an acceptable answer on the first try.

§Examples

The following will ask the user if they would like to continue until either “y”, “n”, “yes”, “no”, or “” an empty string is entered. If an empty string is entered Answer::YES will be returned. If the user does not enter a valid response on the first attempt, the clarification will be added to the prompt.

Please enter either ‘yes’ or ‘no’ Do you want to continue? (Y/n)

Question::new("Do you want to continue?")
    .yes_no()
    .until_acceptable()
    .default(Answer::YES)
    .show_defaults()
    .clarification("Please enter either 'yes' or 'no'\n")
    .ask();

Source

pub fn ask(&mut self) -> Option<Answer>

Ask the user a question exactly as it has been built.

§Examples

The following will return whatever the user enters as an Answer::RESPONSE(String).

Question::new("What is your favorite color?").ask();

Examples found in repository ?

examples/custom_yes_no.rs (line 9)

4fn main() {
5    let answer = Question::new("Continue?")
6        .accept("y")
7        .accept("n")
8        .until_acceptable()
9        .ask();
10    let correct = Some(Answer::RESPONSE(String::from("y")));
11    assert_eq!(answer, correct);
12}

More examples

Hide additional examples

examples/ultimate_question.rs (line 8)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let answer = Question::new(question).ask().unwrap();
9    let correct = Answer::RESPONSE(String::from("42"));
10    assert_eq!(answer, correct);
11}

examples/defaults.rs (line 12)

4fn main() {
5    let question = "What is the answer to the Ultimate Question of Life, \
6                    the Universe, and Everything?";
7
8    let default = Answer::RESPONSE(String::from("42"));
9    let answer = Question::new(question)
10        .default(default.clone())
11        .show_defaults()
12        .ask()
13        .unwrap();
14    let correct = default;
15    assert_eq!(answer, correct);
16}

Source

pub fn confirm(&mut self) -> Answer

Ask a user a yes/no question until an acceptable response is given.

§Examples

Question::new("Continue?").confirm();

Examples found in repository ?

examples/yes_or_no.rs (line 5)

4fn main() {
5    let answer = Question::new("Continue?").confirm();
6    let correct = Answer::YES;
7    assert_eq!(answer, correct);
8}

More examples

Hide additional examples

examples/yes_no_with_defaults.rs (line 8)

4fn main() {
5    let answer = Question::new("Continue?")
6        .default(Answer::YES)
7        .show_defaults()
8        .confirm();
9
10    if answer == Answer::YES {
11        println!("Onward then!");
12    } else {
13        println!("Aborting...");
14    }
15}