may_clack/
lib.rs

1//! This is a rust port of <https://www.npmjs.com/package/@clack/prompts>
2//!
3//! ## Setup
4//!
5//! You can setup the start and end of a prompt session with the macros [`intro!`] and [`outro!`], respectively
6//!  
7//! ```
8//! use may_clack::{intro, outro};
9//!
10//! intro!("intro");
11//! // do stuff
12//! outro!("outro");
13//! ```
14//!
15//! ## Cancel
16//!
17//! When the user cancels a question, you can use the [`cancel!`] utility to provide a cancellation message.
18//!
19//! When cancelled the function will return a [`error::ClackError::Cancelled`],
20//! or you can check if it was cancelled using the [`traits::IsCancel`] trait extension.
21//!
22//! All input types that can return a `Cancelled` Err will also have the option to add a `.cancel` closure
23//!
24//! ```no_run
25//! use may_clack::{cancel, error::ClackError, input};
26//!
27//! let text = input("todo").interact();
28//! if let Err(ClackError::Cancelled) = text {
29//!     cancel!("operation cancelled");
30//! }
31//! ```
32//!
33//! ```
34//! use may_clack::{cancel, input, traits::IsCancel};
35//!
36//! let text = input("todo").interact();
37//! if text.is_cancel() {
38//!     cancel!("operation cancelled");
39//! }
40//! ```
41//!
42//! ## Info
43//!
44//! If you want to write a message in a prompting session you can use the [`info!`], [`warn!`] or [`err!`] utility.
45//!
46//! ```
47//! use may_clack::{err, info, intro, outro, warn};
48//!
49//! intro!("intro");
50//! // do stuff
51//! info!("info");
52//! // do stuff
53//! warn!("warn");
54//! // do stuff
55//! err!("err");
56//! // do stuff
57//! outro!("outro");
58//! ```
59//!
60//! ## General
61//!
62//! There are 6 components: [`input`](#input), [`confirm`](#confirm),
63//! [`select`](#select), [`multi_select`](#multi_select), [`multi_input`](#multi_input)
64//!
65//! Each of the input types returns a struct, that allows you to setup the prompt.  
66//! since every prompt needs a message the initial
67//!
68//! To actually prompt the user after setting up you have to call `.interact()`
69//!
70//! ```no_run
71//! use may_clack::confirm;
72//!
73//! # fn main() -> Result<(), may_clack::error::ClackError> {
74//! let answer = confirm("Yes or No?").interact()?;
75//! # Ok(())
76//! # }
77//! ```
78//!
79//! # Components
80//!
81//! ## Input
82//!
83//! The [`input::Input`] component accepts a single line of text.
84//!
85//! ```no_run
86//! use may_clack::input;
87//!
88//! # fn main() -> Result<(), may_clack::error::ClackError> {
89//! let answer = input("what is the meaning of life?")
90//!     .initial_value("42")
91//!     .interact()?;
92//! println!("{:?}", answer);
93//! # Ok(())
94//! # }
95//! ```
96//!
97//! ## Confirm
98//!
99//! The [`confirm::Confirm`] component accepts a yes or no answer.
100//!
101//! ```no_run
102//! use may_clack::confirm;
103//!
104//! # fn main() -> Result<(), may_clack::error::ClackError> {
105//! let answer = confirm("do you want to continue?").interact()?;
106//! println!("answer {:?}", answer);
107//! # Ok(())
108//! # }
109//! ```
110//!
111//! ## `Select`
112//!
113//! The [`select::Select`] component allows the user to choose one value from a list of options.
114//!
115//! ```no_run
116//! use may_clack::select;
117//!
118//! #[derive(Debug, Clone)]
119//! enum Fruit {
120//!     Mango,
121//!     Peach,
122//!     PassionFruit,
123//! }
124//!
125//! # fn main() -> Result<(), may_clack::error::ClackError> {
126//! let fruit = select("pick a fruit")
127//!     .option_hint(Fruit::Mango, "Mango", "The best one")
128//!     .option(Fruit::Peach, "Peach")
129//!     .option(Fruit::PassionFruit, "Passion fruit")
130//!     .interact()?;
131//! println!("fruit {:?}", fruit);
132//! # Ok(())
133//! # }
134//! ```
135//!
136//! ## `MultiSelect`
137//!
138//! The [`multi_select::MultiSelect`] component allows the user to choose multiple values from a list of options.
139//!
140//! ```no_run
141//! use may_clack::multi_select;
142//!
143//! # fn main() -> Result<(), may_clack::error::ClackError> {
144//! let toppings = multi_select("Choose your toppings")
145//!     .option("fruits", "Dried fruits")
146//!     .option("chocolate", "Chocolate chips")
147//!     .option_hint("sauce", "Chocolate sauce", "it's warm")
148//!     .interact()?;
149//! println!("toppings {:?}", toppings);
150//! # Ok(())
151//! # }
152//! ```
153//!
154//! ## `MultiInput`
155//!
156//! The [`multi_input::MultiInput`] component accepts multiple lines of text.
157//!
158//! ```no_run
159//! use may_clack::multi_input;
160//!
161//! # fn main() -> Result<(), may_clack::error::ClackError> {
162//! let lines = multi_input("idk").interact()?;
163//! println!("lines {:?}", lines);
164//! # Ok(())
165//! # }
166//! ```
167
168#![warn(missing_docs)]
169
170pub mod error;
171pub mod style;
172pub mod traits;
173
174pub mod confirm;
175pub mod input;
176pub mod multi_input;
177pub mod multi_select;
178pub mod select;
179
180mod macros;
181
182pub use confirm::confirm;
183pub use input::input;
184pub use multi_input::multi_input;
185pub use multi_select::multi_select;
186pub use select::select;
187
188// for the macros - don't use
189#[doc(hidden)]
190pub use owo_colors;
may_clack/lib.rs

may_clack/
lib.rs
