asking/lib.rs
1//! Build async prompts for non-blocking user input!
2//!
3//! [Asynchronous I/O] allows the (usually slow) I/O operations run concurrently with
4//! the rest of your (highlt efficient) code.
5//!
6//! [Asynchronous I/O]: https://en.wikipedia.org/wiki/Asynchronous_I/O
7//!
8//! # Features
9//!
10//! - **[Asynchronous]** - You can work while the user inputs something and even timeout!
11//! - **Common patterns** - Built-in common question patterns including
12//! - **[`yn`]** - yes/no questions.
13//! - **[`date`]** - dates in `%Y-%m-%d` format.
14//! - **[`select`]** - choose one option.
15//! - **[`text`]** - just a String.
16//! - **[`T`]** - your own type! (implementing or not the trait [`FromStr`]).
17//! - **Cross-platform** - Generic on [`reader`] and [`writer`]!
18//! - **[`Help`] messages** - Help the user to input a correct answer.
19//! - **[`Test`] with feedback** - Test the input and, optionally, give feedback upon errors.
20//! - **[Default values]** - Add a value for empty inputs.
21//! - **Standardized [`error`] handling** - You can manage errors!
22//! - **[`Feedback`]** - Display a final message depending on the accepted value.
23//!
24//! [Asynchronous]: struct.QuestionBuilder.html#method.ask
25//! [`yn`]: fn.yn.html
26//! [`date`]: fn.date.html
27//! [`select`]: fn.select.html
28//! [`T`]: struct.QuestionBuilder.html#method.new
29//! [`FromStr`]: https://doc.rust-lang.org/core/str/trait.FromStr.html
30//! [`reader`]: struct.QuestionBuilder.html#method.reader
31//! [`writer`]: struct.QuestionBuilder.html#method.writer
32//! [`Help`]: struct.QuestionBuilder.html#method.help
33//! [`Test`]: struct.QuestionBuilder.html#method.test
34//! [Default values]: struct.QuestionBuilder.html#method.default_value
35//! [`error`]: error/enum.Processing.html
36//! [`Feedback`]: struct.QuestionBuilder.html#method.feedback
37//!
38//! # Quick example
39//!
40//! Give only five seconds to the user to confirm something, and continue upon no input! (instead of keep waiting)
41//!
42//! ```
43//! use asking::error::Processing;
44//! use std::time::Duration;
45//!
46//! let question = asking::yn()
47//! .message("Shall I continue? (you have 5 seconds to answer)")
48//! .default_value(true) // value upon empty input
49//! .timeout(Duration::from_secs(5_u64))
50//! .ask();
51//!
52//! match async_std::task::block_on(question) { // we decide to just wait, at most five secs
53//! Ok(true) => println!("Super!"),
54//! Ok(false) => println!("Okay, shutting down..."),
55//! Err(Processing::Timeout { .. }) => println!("I think you are not here, I will continue :)"), // Automatic decision!,
56//! _ => eprintln!("Error with questionnaire, try again later"),
57//! }
58//! ```
59//!
60//! Check out [more examples](https://github.com/saona-raimundo/asking/tree/main/examples)!
61
62// Testing code in README.md
63#[cfg(doctest)]
64doc_comment::doctest!("../README.md");
65
66/// Errors while asking a question.
67pub mod error;
68mod pattern;
69mod question;
70
71pub use pattern::{date, question, select, select_with_msg, text, yn};
72pub use question::{QuestionBuilder, StdQuestionBuilder};