Clap - accept string, integer, floating point numbers, booleans on the command line

Part of the series about Clap.

In the first article we saw how to get started with Clap and how to accept a single parameter that is expected to be String.

In this example we'll see how to accept a number of parameters.

• One of them is a String.
• One is an integer number of type i32.
• Another integer number of type u8.
• A floating point number of type f32.
• A boolean (bool)
• A std::path::PathBuf.

To be clear, by default Rust sees all the parameters as strings. What Clap does is it tries to convert the received string to the appropriate type of value as we describe in the definition of the struct. If the conversion (parsing) fails then Clap will stop the running of the program and provides and error message. In this case the exit-code of the program will be 2.

Setup - Cargo.toml

We have the same dependencies as before, the Clap crate with the derive feature.

examples/clap/numbers-strings-bool/Cargo.toml

[package]
name = "numbers-strings-bool"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
clap = { version = "4.4.11", features = ["derive"] }

Source code

examples/clap/numbers-strings-bool/src/main.rs

use clap::Parser;

#[derive(Parser)]
#[command(version)]
struct Cli {
    #[arg(long)]
    host: String,

    #[arg(long)]
    port: i32,

    #[arg(long)]
    small: u8,

    #[arg(long)]
    float: f32,

    #[arg(long)]
    debug: bool,

    #[arg(long)]
    path: std::path::PathBuf,
}

fn main() {
    let args = Cli::parse();
    println!("host:  {}", args.host);
    println!("port   {}", args.port);
    println!("small: {}", args.small);
    println!("float: {}", args.float);
    println!("debug: {}", args.debug);
    println!("path:  {}", args.path.display());
    // `PathBuf` cannot be formatted with the default formatter; call `.display()` on it
}

Usage:

If we provide all the values as expected, it works fine:

$ cargo run -- --host 127.0.0.1 --port 5000 --small 42 --float 3.14 --path .

host:  127.0.0.1
port   5000
small: 42
float: 3.14
debug: false
path:  .

Note, for the path parameter we had to call display, otherwise we get an error:

`PathBuf` cannot be formatted with the default formatter; call `.display()` on it

Help

Clap provides a default help message describing how to use the command, what parameters to supply.

$ cargo run -- --help

Usage: numbers-strings-bool [OPTIONS] --host <HOST> --port <PORT> --small <SMALL> --float <FLOAT> --path <PATH>

Options:
      --host <HOST>
      --port <PORT>
      --small <SMALL>
      --float <FLOAT>
      --debug
      --path <PATH>
  -h, --help           Print help
  -V, --version        Print version

We can take a look at the exit code:

$ echo $?

2

Invalid value

If the user supplies a value that cannot be converted to the appropriate type then Clap will provide and error messages and exit with exit-code 2. For example here were provide 500 to the small parameter that is defined as u8 that means it is expected to be between 0-255.

$ cargo run -- --host 127.0.0.1 --port 5000 --small 500 --float 3.14 --path .

error: invalid value '500' for '--small ': 500 is not in 0..=255

To see the exit code:

On MS Windows we can see the exit code this way:

In another example we supplied a floating point number to the `port` parameter that was defined as `i32`,
that is an integer.

To see the exit code run: