Writing a CLI App in Rust (Part 1) - Building Minigrep

This guide walks through building a simplified version of the classic command-line tool grep (globally search a regular expression and print). Named minigrep, this project applies core Rust concepts—including vectors, strings, error handling, structs, lifetime trade-offs, and modular design—to construct a production-grade command-line utility.

1. Project Setup and Reading Command-Line Arguments

To begin, initialize a new binary package using Cargo. This creates the project directory structure and a default main.rs file.

cargo new minigrep
cd minigrep

The first requirement of a command-line interface (CLI) application is the ability to accept and parse command-line arguments. In Rust, the standard library provides the std::env module to interact with the execution environment.

Reading Arguments with std::env::args

To read arguments, use the std::env::args function, which returns an iterator over the arguments passed to the program. To convert this iterator into a usable collection, chain it with the collect method.

// src/main.rs
use std::env;

fn main() {
    // We must explicitly annotate the type of `args` because `collect` 
    // can produce many different types of collections.
    let args: Vec<String> = env::args().collect();
    println!("{:?}", args);
}

Understanding the Type Annotation Requirement

Note: The collect function is highly versatile. Because it can transform an iterator into a Vec, a VecDeque, a HashSet, or other collections, the Rust compiler cannot infer your desired output type. Specifying : Vec<String> is strictly required.

Executing the Program

Run the application using cargo run. If no additional arguments are provided, the program still receives one default argument:

cargo run

Output:

["target/debug/minigrep"]

The first element in the vector (index 0) is always the path to the executable binary.

To pass arguments to your program through Cargo, place them after a double dash (--):

cargo run -- needle haystack

Output:

["target/debug/minigrep", "needle", "haystack"]

2. Parsing Arguments and Extracting Variables

For minigrep to function, it needs two specific inputs from the user:

1. The Query: The string to search for.
2. The Filename: The path to the file in which to search.

Since the binary path occupies index 0 of the arguments vector, the query will be at index 1 and the filename will be at index 2.

use std::env;

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

    // Extract references to the arguments at index 1 and 2
    let query = &args[1];
    let filename = &args[2];

    println!("Searching for {}", query);
    println!("In file {}", filename);
}

Testing the Extraction

Run the program with a sample query and filename:

cargo run -- test sample.txt

Output:

Searching for test
In file sample.txt

3. Reading Files with the File System Module

With the filename successfully parsed, the next step is to read the target file's contents. First, create a sample text file named poem.txt in the root directory of your project (at the same level as the Cargo.toml file).

I'm nobody! Who are you?
Are you nobody, too?
Then there's a pair of us - don't tell!
They'd banish us, you know.

Reading File Contents to a String

To read files, import the file system module std::fs. The fs::read_to_string function takes a file path, opens the file, and returns a Result<String, std::io::Error> containing the file's contents.

use std::env;
use std::fs;

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

    let query = &args[1];
    let filename = &args[2];

    println!("Searching for {}", query);
    println!("In file {}", filename);

    // Read the file and panic with a custom message if it fails
    let contents = fs::read_to_string(filename)
        .expect("Something went wrong reading the file");

    println!("With text:\n{}", contents);
}

Execution Flow Walkthrough

4. The Need for Refactoring: Identifying Architectural Flaws

While the current implementation works, it suffers from several design flaws that will hinder maintainability, testability, and robust error handling as the application grows.

The Four Core Problems

1. Violation of the Single Responsibility Principle (SRP): The main function is currently responsible for argument parsing, file reading, and output management. A function should ideally have only one responsibility.
2. Implicit Configuration Coupling: The variables query and filename are logically coupled as the configuration of our tool, but they are managed as independent, disconnected variables throughout main.
3. Fragile Error Handling: If the user runs the program without passing enough arguments (e.g., cargo run), the program attempts to access indices 1 or 2 of a vector that only has a length of 1. This causes an index out-of-bounds panic:
   TEXT

   Copy

   thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1'
   

   This error message is cryptic and exposes internal implementation details to the end-user.
4. Decentralized Error Handling: Errors are handled inline using .expect(). If multiple operations can fail, error handling logic becomes scattered across the codebase instead of being managed in a unified, clean way.

The Binary/Library Separation Pattern

To resolve these issues, the Rust community utilizes a standard architectural pattern for command-line tools:

• main.rs (Binary Crate): Acts as the entry point. It is responsible only for parsing arguments, setting up configuration, calling the core logic, and handling exit statuses on failure.
• lib.rs (Library Crate): Houses all the core business logic, search algorithms, and domain structures. This makes the core logic highly testable and decoupled from the CLI interface.

5. Refactoring Step 1: Grouping Configuration with Structs

To address the coupling of configuration variables, we will group query and filename into a single struct named Config. We will also extract the parsing logic out of main into a dedicated helper function called parse_config.

Defining the Struct and Parsing Function

struct Config {
    query: String,
    filename: String,
}

fn parse_config(args: &[String]) -> Config {
    // We clone the strings to take full ownership of the data.
    let query = args[1].clone();
    let filename = args[2].clone();

    Config { query, filename }
}

The Ownership and Cloning Trade-off

Notice that we call .clone() on the string slices instead of storing references like &str inside the struct.

Note: While cloning introduces a minor runtime performance cost because it allocates heap memory, it keeps our code simple and safe. In a future chapter, we will optimize this using iterators and lifetimes to avoid cloning entirely.

Updating main to Use Config

use std::env;
use std::fs;

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

    let config = parse_config(&args);

    println!("Searching for {}", config.query);
    println!("In file {}", config.filename);

    let contents = fs::read_to_string(config.filename)
        .expect("Something went wrong reading the file");

    println!("With text:\n{}", contents);
}

6. Refactoring Step 2: Implementing a Constructor (Config::new)

The parse_config function is closely tied to the Config struct. In idiomatic Rust, we express this coupling by turning the standalone function into an associated constructor function inside an impl block for Config.

impl Config {
    // By convention, constructor functions are named `new`
    fn new(args: &[String]) -> Config {
        let query = args[1].clone();
        let filename = args[2].clone();

        Config { query, filename }
    }
}

Updating the Call Site in main

Instead of calling parse_config(&args), we now instantiate the configuration using the associated function syntax:

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

    // Call the constructor
    let config = Config::new(&args);
    
    // ... rest of main ...
}

7. Improving Error Handling: Replacing Panics with Results

Currently, if the user does not provide enough arguments, the program panics when trying to access args[1] or args[2]. Let's add validation to ensure the vector contains at least three elements (the binary path, the query, and the filename).

Naive Validation (Using panic!)

We can check the length of the slice inside Config::new and panic with a clear message:

impl Config {
    fn new(args: &[String]) -> Config {
        if args.len() < 3 {
            panic!("not enough arguments");
        }

        let query = args[1].clone();
        let filename = args[2].clone();

        Config { query, filename }
    }
}

While this prints a cleaner message (not enough arguments), calling panic! is still suboptimal. Panics are intended for unrecoverable programming bugs, not user input errors. A panic prints a full stack trace and debug information that is confusing to end-users.

Idiomatic Validation (Using Result)

Instead of panicking, we should return a Result from our constructor. This allows the calling function (main) to decide how to handle the error gracefully.

impl Config {
    // We return a Result containing either a Config or a static string slice error
    fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let filename = args[2].clone();

        Ok(Config { query, filename })
    }
}

Handling the Result in main with unwrap_or_else

To handle the Result cleanly without panicking, we use the unwrap_or_else method defined on Result<T, E>.

• If the result is Ok, unwrap_or_else unwraps and returns the inner Config value.
• If the result is Err, it executes the closure (anonymous function) passed to it. Inside this closure, we print the error message and exit the process cleanly.

use std::env;
use std::fs;
use std::process; // Imported to handle clean process exits

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

    // If Config::new returns an Err, the closure executes
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1); // Exit with status code 1 (failure)
    });

    println!("Searching for {}", config.query);
    println!("In file {}", config.filename);

    let contents = fs::read_to_string(config.filename)
        .expect("Something went wrong reading the file");

    println!("With text:\n{}", contents);
}

Testing the Graceful Exit

If we run the program without arguments now:

cargo run

Output:

Problem parsing arguments: not enough arguments

The program exits immediately with status code 1 and does not print any panic backtrace noise.

8. Extracting Core Logic into the run Function

To complete the refactoring of main, we need to extract the core logic (reading the file and printing its contents) into a separate function named run. This leaves main responsible only for configuration setup and error handling.

Defining the run Function

The run function will take a Config instance and return a Result. If successful, it returns the unit type (). If it fails, it returns an error.

To allow run to return different types of errors (such as file-not-found or permission errors), we use a trait object: Box<dyn std::error::Error>.

use std::error::Error;

// Box<dyn Error> means the function will return a type that implements 
// the Error trait, allocated on the heap, without specifying the exact concrete type.
fn run(config: Config) -> Result<(), Box<dyn Error>> {
    // The `?` operator will return the error from the current function 
    // if read_to_string fails, instead of panicking.
    let contents = fs::read_to_string(config.filename)?;

    println!("With text:\n{}", contents);

    // Return Ok containing the unit type on success
    Ok(())
}

Handling run Errors in main

Since run returns a Result<(), Box<dyn Error>> on failure but returns nothing of interest on success, we do not need unwrap_or_else. Instead, we use the if let syntax to check if the function returned an Err variant.

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

    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });

    println!("Searching for {}", config.query);
    println!("In file {}", config.filename);

    // Check if run returned an error
    if let Err(e) = run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

Testing File System Errors

If we run the program with a file that does not exist:

cargo run -- test non_existent_file.txt

Output:

Searching for test
In file non_existent_file.txt
Application error: No such file or directory (os error 2)

The application catches the error returned by fs::read_to_string via the ? operator, propagates it up to main, and prints a clean, user-friendly error message before exiting.

9. Complete Code Walkthrough: Before vs. After

Below is a comparison of the codebase's evolution, highlighting how we separated concerns and improved error handling.

Comparison of Error Handling Strategies

The Complete Refactored src/main.rs

Here is the complete, clean, and refactored code for Part 1 of the CLI application:

use std::env;
use std::error::Error;
use std::fs;
use std::process;

// 1. Configuration Structure
struct Config {
    query: String,
    filename: String,
}

impl Config {
    // Constructor with validation and error propagation
    fn new(args: &[String]) -> Result<Config, &'static str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

        let query = args[1].clone();
        let filename = args[2].clone();

        Ok(Config { query, filename })
    }
}

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

    // Parse configuration and handle errors cleanly
    let config = Config::new(&args).unwrap_or_else(|err| {
        println!("Problem parsing arguments: {}", err);
        process::exit(1);
    });

    println!("Searching for {}", config.query);
    println!("In file {}", config.filename);

    // Execute core logic and handle runtime errors cleanly
    if let Err(e) = run(config) {
        println!("Application error: {}", e);
        process::exit(1);
    }
}

// 3. Core Logic
fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = fs::read_to_string(config.filename)?;

    println!("With text:\n{}", contents);

    Ok(())
}

Summary and Key Takeaways

• Command-Line Arguments: Use std::env::args to access arguments. Because collect can build many types of collections, you must explicitly annotate the target variable type as Vec<String>.
• The Binary Path: The first element in the arguments vector (index 0) is always the path to the compiled binary. User-provided arguments start at index 1.
• Single Responsibility Principle: Refactoring code to separate configuration parsing from core logic keeps functions small, readable, and easy to maintain.
• Struct Constructors: Implementing a new function inside an impl block is the standard Rust convention for defining constructor functions.
• Cloning vs. Lifetimes: Using .clone() on strings inside a configuration struct is a simple way to resolve ownership issues without needing complex lifetime annotations ('a), though it comes with a small heap-allocation performance cost.
• Idiomatic Error Handling: Avoid using panic! or .expect() for user-facing input errors. Instead, return a Result and handle errors gracefully using unwrap_or_else and the ? operator.
• Trait Objects for Errors: Returning Result<(), Box<dyn Error>> allows a function to return any type of error that implements the standard Error trait, making error propagation flexible and clean.