Rust Command Line Arguments

by
Previous
Next

What are Command Line Arguments?

Command-line arguments are extra pieces of information you provide to a program when you run it from a terminal or command prompt.

They allow users to pass input to the program without modifying the code, making the program more flexible and configurable.

Example: Command-Line Input

$ my_program arg1 arg2 arg3
  • You can see, my_program is the name of the executable.
  • arg1, arg2, and arg3 are command-line arguments.

These arguments can be used to control how the program behaves, for example, specifying filenames, configuration options, or any data the program needs at runtime.

In Rust, you can access these arguments using the std::env::args() function, which returns an iterator over all the arguments passed to the program.

Where we can use Command-Line Arguments in Real-Life Projects?

Command-line arguments are not just a programming concept; but they are widely used in real-life applications and projects. They allow users to interact with programs quickly without using a graphical interface.

We can use this in file processing tools, for example, read, modify, and convert files using command-line arguments, such as converting an image file PNG to JPG. Here, input.png and output.jpg are command-line arguments specifying the input and output files.

You can use this concept in multiple places like Automation Scripts, System Utilities, Data Analysis and Machine Learning, Network Tools, etc.

How to Handle Command Line Arguments in Rust?

Rust’s std::env module provides the args function to retrieve command-line arguments. The arguments are returned as an iterator, which can be collected into a vector for easier processing.

1) Getting Command Line Arguments

Rust provides the std::env::args() function to access all arguments passed to the program from the terminal.

  • env::args() returns an iterator over all the arguments passed, including the program name.
  • You can convert this iterator into a vector (Vec<String>) to work with the arguments easily.
  • The first argument (args[0]) is always the program name, and the rest are the inputs you provide.

Example: Retrieving Command-Line Arguments

use std::env;

fn main() {
    // Collect all arguments into a vector
    let arguments: Vec<String> = env::args().collect();

    println!("Total arguments passed (excluding program name): {}", arguments.len() - 1);
    
    for (index, arg) in arguments.iter().enumerate() {
        if index == 0 {
            println!("Program Name: {}", arg);
        } else {
            println!("Argument {}: {}", index, arg);
        }
    }
}

Explanation:

  • Rust allows you to read inputs passed when starting the program.
  • collect() converts the iterator into a Vec<String>.
  • The first argument (args[0]) is the program name, and subsequent arguments are user-provided.

Output Example:

$ cargo run hello world Rust
Total arguments passed (excluding program name): 3
Program Name: target/debug/my_program
Argument 1: hello
Argument 2: world
Argument 3: Rust

2) Ignoring the Program Name

When you run a Rust program from the terminal, the first argument (args[0]) is always the program’s own name or path.

In most real projects, you don’t need that; you only care about the actual inputs the user typed after the program name.

Rust makes it super easy to skip that first value. By using the .skip(1) method, you can ignore the program name and directly collect only the user-provided arguments.

Example: Ignoring the Program Name

use std::env;

fn main() {
    // Collect only the arguments provided by the user (ignore the program name)
    let user_inputs: Vec<String> = env::args().skip(1).collect();

    if user_inputs.is_empty() {
        println!("No arguments were provided. Please pass some values!");
    } else {
        println!("User-provided arguments:");
        for (index, arg) in user_inputs.iter().enumerate() {
            println!("Argument {}: {}", index + 1, arg);
        }
    }
}

Example Run

$ cargo run apple banana mango
User-provided arguments:
Argument 1: apple
Argument 2: banana
Argument 3: mango
  • Rust always includes the program name as the first argument.
  • Using .skip(1) simply tells Rust to ignore it and focus on the values you actually passed.

3) Accessing Specific Arguments

Sometimes, you don’t need all the command-line arguments, you just want to use a specific one.

For example, maybe the first argument is a username, the second is a file name, or the third is a number your program should process.

Since env::args() returns all the arguments as a Vec<String>, you can easily access them by their position (index) in the vector.

Example: Accessing Specific Arguments

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();

    if args.len() > 1 {
        println!("First Argument: {}", args[1]);
    } else {
        println!("No arguments provided!");
    }
}

Output Examples:

With Arguments:

$ cargo run rustacean
First argument provided: rustacean

Without an Arguments:

$ cargo run
No argument found! Please pass at least one value.

Explanation of this code:

  • All command-line inputs are stored in a vector (args).
  • args[0] is always the program name, so the first real argument starts from args[1].

4) Handling Missing or Invalid Arguments

Sometimes users forget to provide the required inputs or enter the wrong number of arguments. If your program doesn’t check this, it could panic or behave unpredictably.

Example: Validating Arguments

use std::env;

fn main() {
    // Collect all command-line arguments
    let args: Vec<String> = env::args().collect();

    // We expect exactly 2 arguments (excluding program name)
    if args.len() != 3 {
        eprintln!("Incorrect usage!");
        eprintln!("Usage: {} <name> <age>", args[0]);
        return;
    }

    // Safe to access because we've already checked the length
    let name = &args[1];
    let age = &args[2];

    println!("Name: {}", name);
    println!("Age: {}", age);
}

Output Examples:

Correct Usage:

cargo run Alice 25
Name: Alice
Age: 25

Incorrect Usage:

$ cargo run Alice
Incorrect usage!
Usage: target/debug/my_program <name> <age>

5) Parsing Numeric Arguments

Sometimes, your command-line program needs numbers instead of text, for example, when building a calculator, temperature converter, or math-based tool.

By default, all command-line arguments are read as strings, so we need to convert them into numbers before using them in calculations.

Rust provides the .parse() method to convert a string into a number type (like i32, f64, etc.).

Example: Parsing Numbers

use std::env;

fn main() {
    // Collect all arguments
    let args: Vec<String> = env::args().collect();

    // Expect exactly two numeric inputs
    if args.len() != 3 {
        eprintln!("Usage: {} <num1> <num2>", args[0]);
        return;
    }

    // Try to parse arguments into integers
    let num1: i32 = match args[1].parse() {
        Ok(value) => value,
        Err(_) => {
            eprintln!("Error: '{}' is not a valid number.", args[1]);
            return;
        }
    };

    let num2: i32 = match args[2].parse() {
        Ok(value) => value,
        Err(_) => {
            eprintln!("Error: '{}' is not a valid number.", args[2]);
            return;
        }
    };

    // Perform a simple calculation
    println!("Sum of {} and {} is: {}", num1, num2, num1 + num2);
}

Output Example:

$ cargo run 15 25
Sum of 15 and 25 is: 40

6) Using External Crates for Advanced Parsing

For complex command-line arguments, use crates like clap or structopt. These provide features like named flags and default values.

Example: Using clap for Named Arguments

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

The derive feature allows us to use a simple struct to define and parse arguments.

use clap::Parser;

/// A small demo CLI tool that takes two named arguments
#[derive(Parser)]
#[command(name = "My CLI Tool", about = "A simple example of using clap in Rust")]
struct Cli {
    /// Your first input value
    #[arg(short, long)]
    first: String,

    /// Your second input value
    #[arg(short, long)]
    second: String,
}

fn main() {
    // Automatically parse command-line arguments into the struct
    let args = Cli::parse();

    println!("First Value: {}", args.first);
    println!("Second Value: {}", args.second);
}

Output Example:

$ cargo run -- --first Hello --second Rust
First Value: Hello
Second Value: Rust
  • –first and –second are named arguments.
  • You can also use short forms like -f and -s if you specify them in the struct.

Learn Other Topics About Rust

Previous
Next

Leave a Comment