Creating a CLI with Rust
source link: https://dev.to/spaghetti_rs/creating-a-cli-with-rust-4m7b
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Setup
⚠ Warning
This post requires basic understanding of some programming concepts as structs, functions, modules, and I/O handling. It is also recommended to have Rust knowledge, if you are new to programming I highly recommend you to check out this video and/or if you are new to Rust, you should read the official book.
Before getting into our hacker mood,
let's create a cargo project and install the packages we'll need:
cargo new ferris-say
Enter fullscreen mode
Exit fullscreen mode
Now, open your Cargo.toml, and add this below [dependencies]
:
[dependencies]
ansi_term = "0.12.1"
clap = { version = "3.1.6", features = ["derive"] }
Enter fullscreen mode
Exit fullscreen mode
Or, if you have cargo edit (which I prefer using), write right in your terminal:
cargo add ansi_term
cargo add clap --features derive
Enter fullscreen mode
Exit fullscreen mode
After it's installed, we're ready to go to the next step.
Getting input from arguments
The crate clap that we just installed and used in the snippet below, helps us not only to parse but to validate the an input given by the user. Let's see how to implement and use it into our application.
First thing is to create a function called input
here we'll handle and parse the arguments provided; Our Cli will request only two arguments to work with: quote
and color
but for color
we need an enum as we'll only allow to use a few types of colors (but a cool ones).
The function signature
The function signatures let us to know how many parameters will it receive and what will be the output generated, and let's bring into scope both of the crate we'll be using along this tutorial:
// Imports
use ansi_term::{self, Colour};
use clap::{ArgEnum, Parser};
fn input() -> (String, Colour)
Enter fullscreen mode
Exit fullscreen mode
Parsing the input
#[derive(Parser, Debug)]
#[clap(author, version, about = "cowsay rusty version")]
struct Args {
/// Quote that ferris will say
#[clap(short, long)]
quote: String,
/// Colors to choose
#[clap(arg_enum)]
color: Colors,
}
Enter fullscreen mode
Exit fullscreen mode
The Parser
trait that our struct
derives, parses all the arguments provided by the user and turns it into that struct fields. As you can see, we only have two fields, so it means, we'll only receive two arguments, as we state before.
Note that quote
is the type of String
and color
is the type of Colors
, but it doesn't exist yet, so let's create it.
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum, Debug)]
enum Colors {
// Not black because it's the background color
Red,
Green,
Yellow,
Blue,
Purple,
Cyan,
White,
}
Enter fullscreen mode
Exit fullscreen mode
Focus on that ArgEnum
derived trait, that means: "Hey, this enum's variants are the only few valid types for a argument" and clap will ensure that the argument provided fits into it.
Once we have our Colors
enum, let's handle each variant using the classic match statement.
Handling the input
At this point we already brought into scope our ansi_term
crate so it's time to use it
// Imports
use clap::{ArgEnum, Parser};
use ansi_term::{self, Colour} // -> This one
// fn input(){...}
Enter fullscreen mode
Exit fullscreen mode
So we can crate a match statement to filter through the Colors
(our enum) variants, return a Colour
(ansi_term's enum) variant and bind it to a variale named color_matched
.
First, create a new instance of Args
. To access to its field (quote
and color
) we need to use the dot notation:
// ...
let args = Args::parse();
// to access to the quote:
args.quote
// to access to the color:
args.color // If you want to show through terminal remember using ":?"
Enter fullscreen mode
Exit fullscreen mode
Now we are up to handle:
// ...
let color_matched = match args.color {
Colors::Red => Colour::Red,
Colors::Green => Colour::Green,
Colors::Yellow => Colour::Yellow,
Colors::Blue => Colour::Blue,
Colors::Purple => Colour::Purple,
Colors::Cyan => Colour::Cyan,
Colors::White => Colour::White,
};
println!("The user picked the color {:?}", color_matched);
Enter fullscreen mode
Exit fullscreen mode
Last thing to do is return the tuple:
//...
(args.quote, color_matched)
Enter fullscreen mode
Exit fullscreen mode
Time to test it!
cargo build
target/debug/ferris_say.exe -h
ferris-say 0.1.0
cowsay rusty version
USAGE:
ferris_say.exe --quote <QUOTE> <COLOR>
ARGS:
<COLOR> Colors to choose [possible values: red, green, yellow, blue, purple,
cyan, white]
OPTIONS:
-h, --help Print help information
-q, --quote <QUOTE> Quote that ferris will say
-V, --version Print version information
Enter fullscreen mode
Exit fullscreen mode
passing the -h
or --help
shows the arguments we can use.
Once we know what are the arguments, we're able to use it correctly.
target/debug/ferris_say.exe -q "Hello world!" red
The user picked the color Red
Enter fullscreen mode
Exit fullscreen mode
But...what if I pass a color that isn't valid?
target/debug/ferris_say.exe -q "hello world!" black
error: "black" isn't a valid value for '<COLOR>'
[possible values: red, green, yellow, blue, purple, cyan, white]
USAGE:
ferris_say.exe --quote <QUOTE> <COLOR>
For more information try --help
Enter fullscreen mode
Exit fullscreen mode
We are ready to go to the next step: drawing the ferris.
Draw the ferris
Here, I highly recommend you just to copy and paste the drawing. But first, let's create another function draw
:
The function signature
fn draw(quote: &str, color: &Colour)
Enter fullscreen mode
Exit fullscreen mode
Inside the draw
function:
// Ferris drawing
const FERRIS: &'static str = r"
.
.
.
█ █ █ █
▀█ ▄█████▄ █▀
▀▄███▀█▀███▄▀
▄▀███▀▀▀███▀▄
█ ▄▀▀▀▀▀▀▀▄ █
";
println!("{}", format!("\"{}\"{}", quote, color.paint(FERRIS)));
Enter fullscreen mode
Exit fullscreen mode
A r""
String is called as "raw string", in short, it tells the compiler to ignore every scape character, It's easier for us to draw our ferris that way. On the other hand we have a format!
macro, we use it as we'll place the text right above the ferris. It will be better illustrated as we run the program.
Last but not least color is a Colour instance passed by reference, that means we can use the paint
that receives a &str params. It "paints" the text to a given color.
Finally inside our main function
:
fn main() {
let (q, c) = input();
draw(&q, &c)
}
Enter fullscreen mode
Exit fullscreen mode
Final code
We'll split it into parts to understand how it works.
use ansi_term::{self, Colour}; // 0.12.1
use clap::{ArgEnum, Parser};
fn draw(quote: &str, color: &Colour) {
// Ferris drawing
const FERRIS: &'static str = r"
.
.
.
█ █ █ █
▀█ ▄█████▄ █▀
▀▄███▀█▀███▄▀
▄▀███▀▀▀███▀▄
█ ▄▀▀▀▀▀▀▀▄ █
";
println!("{}", format!("\"{}\"{}", quote, color.paint(FERRIS)));
}
fn input()-> (String, Colour) {
#[derive(Parser, Debug)]
#[clap(author, version, about = "cowsay rusty version")]
struct Args {
/// Quote that ferris will say
#[clap(short, long)]
quote: String,
/// Colors to choose
#[clap(arg_enum)]
color: Colors,
}
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ArgEnum, Debug)]
enum Colors {
// Not black because it's the our background color
Red,
Green,
Yellow,
Blue,
Purple,
Cyan,
White,
}
let args = Args::parse();
// validate colors argument:
let color_matched = match args.color {
Colors::Red => Colour::Red,
Colors::Green => Colour::Green,
Colors::Yellow => Colour::Yellow,
Colors::Blue => Colour::Blue,
Colors::Purple => Colour::Purple,
Colors::Cyan => Colour::Cyan,
Colors::White => Colour::White,
};
(args.quote, color_matched)
}
fn main() {
let (q, c) = input();
draw(&q, &c)
}
Enter fullscreen mode
Exit fullscreen mode
I hope you guys enjoyed this tutorial, any comment or suggestion my email is opened!
This post is also available in my personal blog
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK