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

may_clack/
lib.rs
