Skip to content

Commit a9428d4

Browse files
joshkajoshka
committed
docs: add examples to readme
- Add a readme.rs example - Use VHS to generate the output gifs - Adds a script to generate and publish all the gifs in one go - Images are published to VHS rather than committed to the repo to avoid bloating the repo size See <https://github.com/charmbracelet/vhs> for more info on VHS Alternative to: console-rs#258
1 parent 6244c77 commit a9428d4

12 files changed

+438
-0
lines changed

‎README.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,164 @@ Best paired with other libraries in the family:
1111
* [console](https://github.com/console-rs/console)
1212
* [indicatif](https://github.com/console-rs/indicatif)
1313

14+
## Usage
15+
16+
Add the library to your `Cargo.toml`:
17+
18+
```shell
19+
cargo add dialoguer
20+
```
21+
22+
## Examples
23+
24+
### Confirm
25+
26+
Docs: [dialoguer::Confirm](https://docs.rs/dialoguer/latest/dialoguer/struct.Confirm.html)
27+
28+
```rust
29+
use dialoguer::{theme::ColorfulTheme, Confirm};
30+
31+
if Confirm::with_theme(&ColorfulTheme::default())
32+
.with_prompt("Do you want to continue?")
33+
.interact()?
34+
{
35+
println!("Looks like you want to continue");
36+
}
37+
```
38+
39+
![confirm](https://vhs.charm.sh/vhs-5ianSRV6gBIQw8zHbXZs7X.gif)
40+
41+
With a default value:
42+
43+
```rust
44+
use dialoguer::{theme::ColorfulTheme, Confirm};
45+
46+
if Confirm::new()
47+
.with_prompt("Do you want to continue?")
48+
.default(true)
49+
.interact()?
50+
{
51+
println!("Looks like you want to continue");
52+
}
53+
```
54+
55+
![confirm-with-default](https://vhs.charm.sh/vhs-KumYDsqM2KSxaMUHRr8IV.gif)
56+
57+
## Input
58+
59+
Docs: [dialoguer::Input](https://docs.rs/dialoguer/latest/dialoguer/struct.Input.html)
60+
61+
```rust
62+
use dialoguer::{theme::ColorfulTheme, Input};
63+
64+
let name: String = dialoguer::Input::with_theme(&ColorfulTheme::default())
65+
.with_prompt("What is your name?")
66+
.interact()?;
67+
println!("Hello, {name}");
68+
```
69+
70+
![input](https://vhs.charm.sh/vhs-7EYUy5VCybcotdxrL8QCXk.gif)
71+
72+
## Password
73+
74+
Docs: [dialoguer::Password](https://docs.rs/dialoguer/latest/dialoguer/struct.Password.html)
75+
76+
```rust
77+
use dialoguer::{theme::ColorfulTheme, Password};
78+
79+
let password: String = Password::with_theme(&ColorfulTheme::default())
80+
.with_prompt("Enter your password")
81+
.interact()?;
82+
println!("Your password is: {password}");
83+
```
84+
85+
![password](https://vhs.charm.sh/vhs-1HTgKYmFc09dNtuHu5hWOO.gif)
86+
87+
## Editor
88+
89+
Docs: [dialoguer::Editor](https://docs.rs/dialoguer/latest/dialoguer/struct.Editor.html)
90+
91+
```rust
92+
use dialoguer::Editor;
93+
94+
match dialoguer::Editor::new().edit("Some content")? {
95+
Some(content) => println!("Content: {content:?}"),
96+
None => println!("File was not saved"),
97+
}
98+
```
99+
100+
![editor](https://vhs.charm.sh/vhs-3DISbkWUNwMms076djOQ3e.gif)
101+
102+
## Select
103+
104+
Docs: [dialoguer::Select](https://docs.rs/dialoguer/latest/dialoguer/struct.Select.html)
105+
106+
```rust
107+
use dialoguer::{theme::ColorfulTheme, Select};
108+
109+
let items = vec!["Apple", "Banana", "Cherry"];
110+
let selection = Select::with_theme(&ColorfulTheme::default())
111+
.with_prompt("What is your favourite fruit?")
112+
.items(&items)
113+
.interact()?;
114+
println!("You picked: {selection}", selection = items[selection]);
115+
```
116+
117+
![select](https://vhs.charm.sh/vhs-3ylAvmWOIiBkYexnG7j4F9.gif)
118+
119+
## FuzzySelect
120+
121+
Docs: [dialoguer::FuzzySelect](https://docs.rs/dialoguer/latest/dialoguer/struct.FuzzySelect.html)
122+
123+
```rust
124+
use dialoguer::{theme::ColorfulTheme, FuzzySelect};
125+
126+
let items = vec!["Apple", "Banana", "Cherry"];
127+
let selection = FuzzySelect::with_theme(&ColorfulTheme::default())
128+
.with_prompt("What is your favourite fruit?")
129+
.items(&items)
130+
.interact()?;
131+
println!("You picked: {selection}", selection = items[selection]);
132+
```
133+
134+
![fuzzy-select](https://vhs.charm.sh/vhs-3JUdbUNwnUKWVjk6J5XoKh.gif)
135+
136+
## MultiSelect
137+
138+
Docs: [dialoguer::MultiSelect](https://docs.rs/dialoguer/latest/dialoguer/struct.MultiSelect.html)
139+
140+
```rust
141+
use dialoguer::{theme::ColorfulTheme, MultiSelect};
142+
143+
let items = vec!["Apple", "Banana", "Cherry"];
144+
let selection = MultiSelect::with_theme(&ColorfulTheme::default())
145+
.with_prompt("What are your favourite fruits?")
146+
.items(&items)
147+
.interact()?;
148+
let selected_items: Vec<_> = selection.iter().map(|i| items[*i]).collect();
149+
println!("You picked: {selected_items:?}");
150+
```
151+
152+
![multi-select](https://vhs.charm.sh/vhs-5Jje1Pdxsw4w5jLJjeWNbI.gif)
153+
154+
## Sort
155+
156+
Docs: [dialoguer::Sort](https://docs.rs/dialoguer/latest/dialoguer/struct.Sort.html)
157+
158+
```rust
159+
use dialoguer::{theme::ColorfulTheme, Sort};
160+
161+
let items = vec!["Apple", "Banana", "Cherry"];
162+
let selection = Sort::with_theme(&ColorfulTheme::default())
163+
.with_prompt("Sort the fruits")
164+
.items(&items)
165+
.interact()?;
166+
let sorted_items: Vec<_> = selection.iter().map(|i| items[*i]).collect();
167+
println!("You sorted: {sorted_items:?}");
168+
```
169+
170+
![sort](https://vhs.charm.sh/vhs-mcxq0aABXECgIdafLBNZN.gif)
171+
14172
## License and Links
15173

16174
* [Documentation](https://docs.rs/dialoguer/)

‎examples/readme.rs‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
//! The purpose of this example is to provide simple examples of how to use each of the dialoguer
2+
//! prompts.
3+
4+
use std::{env::args, thread, time::Duration};
5+
6+
#[cfg(feature = "fuzzy-select")]
7+
use dialoguer::FuzzySelect;
8+
use dialoguer::{theme::ColorfulTheme, Confirm, MultiSelect, Password, Select, Sort};
9+
10+
fn main() -> dialoguer::Result<()> {
11+
match args().nth(1) {
12+
None => println!("No argument provided"),
13+
Some(arg) => run(arg)?,
14+
}
15+
Ok(())
16+
}
17+
18+
fn run(arg: String) -> Result<(), dialoguer::Error> {
19+
match arg.as_str() {
20+
"confirm" => confirm()?,
21+
"confirm-with-default" => confirm_with_default()?,
22+
"input" => input()?,
23+
"password" => password()?,
24+
"editor" => editor()?,
25+
"select" => select()?,
26+
"multi-select" => multi_select()?,
27+
#[cfg(feature = "fuzzy-select")]
28+
"fuzzy-select" => fuzzy_select()?,
29+
"sort" => sort()?,
30+
_ => println!("Invalid argument"),
31+
}
32+
thread::sleep(Duration::from_secs(3)); // give the VHS tape time to capture the effect
33+
Ok(())
34+
}
35+
36+
fn confirm() -> dialoguer::Result<()> {
37+
if Confirm::with_theme(&ColorfulTheme::default())
38+
.with_prompt("Do you want to continue?")
39+
.interact()?
40+
{
41+
println!("Looks like you want to continue");
42+
}
43+
Ok(())
44+
}
45+
46+
fn confirm_with_default() -> dialoguer::Result<()> {
47+
if Confirm::with_theme(&ColorfulTheme::default())
48+
.with_prompt("Do you want to continue?")
49+
.default(true)
50+
.interact()?
51+
{
52+
println!("Looks like you want to continue");
53+
}
54+
Ok(())
55+
}
56+
57+
fn input() -> dialoguer::Result<()> {
58+
let name: String = dialoguer::Input::with_theme(&ColorfulTheme::default())
59+
.with_prompt("What is your name?")
60+
.interact()?;
61+
println!("Hello, {name}");
62+
Ok(())
63+
}
64+
65+
fn password() -> dialoguer::Result<()> {
66+
let password: String = Password::with_theme(&ColorfulTheme::default())
67+
.with_prompt("Enter your password")
68+
.interact()?;
69+
println!("Your password is: {password}");
70+
Ok(())
71+
}
72+
73+
fn editor() -> dialoguer::Result<()> {
74+
match dialoguer::Editor::new().edit("Some content")? {
75+
Some(content) => println!("Content: {content:?}"),
76+
None => println!("File was not saved"),
77+
}
78+
Ok(())
79+
}
80+
81+
fn select() -> dialoguer::Result<()> {
82+
let items = vec!["Apple", "Banana", "Cherry"];
83+
let selection = Select::with_theme(&ColorfulTheme::default())
84+
.with_prompt("What is your favourite fruit?")
85+
.items(&items)
86+
.interact()?;
87+
println!("You picked: {selection}", selection = items[selection]);
88+
Ok(())
89+
}
90+
91+
#[cfg(feature = "fuzzy-select")]
92+
fn fuzzy_select() -> dialoguer::Result<()> {
93+
let items = vec!["Apple", "Banana", "Cherry"];
94+
let selection = FuzzySelect::with_theme(&ColorfulTheme::default())
95+
.with_prompt("What is your favourite fruit?")
96+
.items(&items)
97+
.interact()?;
98+
println!("You picked: {selection}", selection = items[selection]);
99+
Ok(())
100+
}
101+
102+
fn multi_select() -> dialoguer::Result<()> {
103+
let items = vec!["Apple", "Banana", "Cherry"];
104+
let selection = MultiSelect::with_theme(&ColorfulTheme::default())
105+
.with_prompt("What are your favourite fruits?")
106+
.items(&items)
107+
.interact()?;
108+
let selected_items: Vec<_> = selection.iter().map(|i| items[*i]).collect();
109+
println!("You picked: {selected_items:?}");
110+
Ok(())
111+
}
112+
113+
fn sort() -> dialoguer::Result<()> {
114+
let items = vec!["Apple", "Banana", "Cherry"];
115+
let selection = Sort::with_theme(&ColorfulTheme::default())
116+
.with_prompt("Sort the fruits")
117+
.items(&items)
118+
.interact()?;
119+
let sorted_items: Vec<_> = selection.iter().map(|i| items[*i]).collect();
120+
println!("You sorted: {sorted_items:?}");
121+
Ok(())
122+
}

‎examples/vhs/confirm-with-default.tape‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Output target/confirm-with-default.gif
2+
3+
Set Width 1200
4+
Set Height 250
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme confirm-with-default" Enter
9+
Show
10+
Sleep 2s
11+
Enter
12+
Sleep 2s

‎examples/vhs/confirm.tape‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Output target/confirm.gif
2+
3+
Set Width 1200
4+
Set Height 250
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme confirm" Enter
9+
Show
10+
Sleep 2s
11+
Type "y"
12+
Sleep 2s

‎examples/vhs/editor.tape‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
Output target/editor.gif
2+
3+
Set Width 1200
4+
Set Height 250
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "EDITOR=vim cargo run --quiet --example readme editor" Enter
9+
Show
10+
Sleep 2s
11+
Type "CHello, World!" Escape
12+
Type "ZZ"
13+
Sleep 2s

‎examples/vhs/fuzzy-select.tape‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
Output target/fuzzy-select.gif
2+
3+
Set Width 1200
4+
Set Height 350
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme --features=fuzzy-select fuzzy-select" Enter
9+
Show
10+
Sleep 2s
11+
Type "a"
12+
Sleep 1s
13+
Down
14+
Sleep 1s
15+
Enter
16+
17+
Sleep 2s

‎examples/vhs/input.tape‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Output target/input.gif
2+
3+
Set Width 1200
4+
Set Height 250
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme input" Enter
9+
Show
10+
Sleep 2s
11+
Type "pksunkara" Enter
12+
Sleep 2s

‎examples/vhs/multi-select.tape‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Output target/multi-select.gif
2+
3+
Set Width 1200
4+
Set Height 350
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme multi-select" Enter
9+
Show
10+
Sleep 2s
11+
Down
12+
Sleep 1s
13+
Space
14+
Sleep 1s
15+
Down
16+
Sleep 1s
17+
Space
18+
Sleep 1s
19+
Enter
20+
21+
Sleep 2s

‎examples/vhs/password.tape‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Output target/input.gif
2+
3+
Set Width 1200
4+
Set Height 250
5+
Set Theme "Aardvark Blue"
6+
7+
Hide
8+
Type "cargo run --quiet --example readme password" Enter
9+
Show
10+
Sleep 2s
11+
Type "Password123!" Enter
12+
Sleep 2s

0 commit comments

Comments
 (0)