Chapter 12
An I/O Project: Building a Command Line Program
This chapter is a recap of the many skills you’ve learned so far and an exploration of a few more standard library features. We build a command line tool that interacts with file and command line input/output to practice the Rust concepts you now have under your belt.
- 12.1 Accepting Command Line Arguments
- 12.2 Reading a File
- 12.3 Refactoring to Improve Modularity and Error Handling
- 12.4 Adding Functionality with Test-Driven Development
- 12.5 Working with Environment Variables
- 12.6 Redirecting Errors to Standard Error
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
1
Chapter 12 · Introduction
Why a command line tool: our own grep
Rust’s speed, safety, single binary output, and cross-platform support make it an ideal language for creating command line tools. So for our project we’ll make our own version of the classic command line search tool grep.
Definition 12.1 (grep). Globally search a regular expression and print. In the simplest use case, grep takes a file path and a string as its arguments; it reads the file, finds the lines in that file that contain the string argument, and prints those lines.
Along the way, our tool will use the terminal features that many other command line tools use:
- We’ll read the value of an environment variable to allow the user to configure the behavior of our tool.
- We’ll print error messages to the standard error console stream (stderr) instead of standard output (stdout), so that, for example, the user can redirect successful output to a file while still seeing error messages onscreen.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
2
Chapter 12 · Introduction
What the project brings together
One Rust community member, Andrew Gallant, has already created a fully featured, very fast version of grep, called ripgrep. By comparison our version will be fairly simple, but this chapter gives you some of the background knowledge you need to understand a real-world project such as ripgrep.
Our grep project combines a number of concepts you’ve learned so far:
- Organizing code (Chapter 7)
- Using vectors and strings (Chapter 8)
- Handling errors (Chapter 9)
- Using traits and lifetimes where appropriate (Chapter 10)
- Writing tests (Chapter 11)
We’ll also briefly introduce closures, iterators, and trait objects, which Chapter 13 and Chapter 18 cover in detail.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
3
Chapter 12 · 12.1 Accepting Command Line Arguments
Creating the minigrep project
Create a new project with, as always, cargo new. We call it minigrep to distinguish it from the grep tool that you might already have on your system:
$ cargo new minigrep
Created binary (application) `minigrep` project
$ cd minigrep
The first task is to make minigrep accept its two command line arguments: the file path and a string to search for. We want to run the program with cargo run, two hyphens to indicate that the following arguments are for our program rather than for cargo, a string to search for, and a path to a file to search in:
$ cargo run -- searchstring example-filename.txt
Right now, the program generated by cargo new cannot process arguments we give it. Some existing libraries on crates.io can help with writing a program that accepts command line arguments, but because you’re just learning this concept, we implement this capability ourselves.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
4
Chapter 12 · 12.1 Accepting Command Line Arguments
Reading the argument values with std::env::args
To read the values of the command line arguments we pass to minigrep, we need the standard library function std::env::args. It returns an iterator of the command line arguments passed to minigrep. Iterators are covered fully in Chapter 13; for now you only need two details:
Definition 12.2 (Iterator). A value that produces a series of values. Calling the collect method on an iterator turns it into a collection, such as a vector, which contains all the elements the iterator produces.
Listing 12.1 reads any command line arguments passed to minigrep and collects the values into a vector.
Listing 12.1: Collecting the command line arguments into a vector and printing them — src/main.rs
use std::env;
fn main() {
let args: Vec<String> = env::args().collect();
dbg!(args);
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
5
Chapter 12 · 12.1 Accepting Command Line Arguments
Bringing std::env into scope, and invalid Unicode
First, we bring the std::env module into scope with a use statement so that we can use its args function. Notice that std::env::args is nested in two levels of modules.
- As discussed in Chapter 7, when the desired function is nested in more than one module, we’ve chosen to bring the parent module into scope rather than the function.
- By doing so, we can easily use other functions from std::env.
- It’s also less ambiguous than adding use std::env::args and then calling the function with just args, because args might easily be mistaken for a function that’s defined in the current module.
The args function and invalid Unicode
Remark. std::env::args will panic if any argument contains invalid Unicode. If your program needs to accept arguments containing invalid Unicode, use std::env::args_os instead: it returns an iterator that produces OsString values instead of String values. The book uses std::env::args for simplicity, because OsString values differ per platform and are more complex to work with than String values.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
6
Chapter 12 · 12.1 Accepting Command Line Arguments
Collecting into a vector, and a first run
On the first line of main, we call env::args and immediately use collect to turn the iterator into a vector containing all the values it produces. Because collect can create many kinds of collections, we explicitly annotate the type of args to specify that we want a vector of strings.
Remark. Although you very rarely need to annotate types in Rust, collect is one function you do often need to annotate, because Rust isn’t able to infer the kind of collection you want.
Finally, we print the vector using the debug macro dbg!. Running the code first with no arguments:
$ cargo run
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.61s
Running `target/debug/minigrep`
[src/main.rs:5:5] args = [
"target/debug/minigrep",
]
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
7
Chapter 12 · 12.1 Accepting Command Line Arguments
Running with arguments: the program name comes first
Now with two arguments:
$ cargo run -- needle haystack
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.57s
Running `target/debug/minigrep needle haystack`
[src/main.rs:5:5] args = [
"target/debug/minigrep",
"needle",
"haystack",
]
The first value in the vector is "target/debug/minigrep", the name of our binary. This matches the behavior of the arguments list in C, letting programs use the name by which they were invoked in their execution. Having the program name is often convenient — to print it in messages, or to change the program’s behavior based on what command line alias was used to invoke it. For this chapter we ignore it and save only the two arguments we need.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
8
Chapter 12 · 12.1 Accepting Command Line Arguments
Saving the argument values in variables
Next we save the two argument values in variables so that we can use them throughout the rest of the program.
Listing 12.2: Creating variables to hold the query argument and file path argument — src/main.rs
use std::env;
fn main() {
let args: Vec<String> = env::args().collect();
let query = &args[1];
let file_path = &args[2];
println!("Searching for {query}");
println!("In file {file_path}");
}
The program’s name takes up args[0], so we start at index 1: a reference to the first argument (the string to search for) goes in query, and one to the second (the file path) in file_path.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
9
Chapter 12 · 12.1 Accepting Command Line Arguments
Checking the saved arguments
We temporarily print the values of these variables to prove that the code is working as we intend. Running the program again with the arguments test and sample.txt:
$ cargo run -- test sample.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep test sample.txt`
Searching for test
In file sample.txt
Great, the program is working! The values of the arguments we need are being saved into the right variables.
Remark. Later we add error handling for potential erroneous situations, such as when the user provides no arguments. For now we ignore that situation and work on adding file-reading capabilities instead.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
10
Chapter 12 · 12.2 Reading a File
A sample file to search
Now we add functionality to read the file specified in the file_path argument. First we need a sample file to test it with: a small amount of text over multiple lines with some repeated words. Create a file called poem.txt at the root level of your project and enter Emily Dickinson’s poem “I’m Nobody! Who are you?”
Listing 12.3: A poem by Emily Dickinson makes a good test case. — poem.txt
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.
How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!
With the text in place, edit src/main.rs and add code to read the file, as shown in Listing 12.4.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
11
Chapter 12 · 12.2 Reading a File
Reading the file with fs::read_to_string
Listing 12.4: Reading the contents of the file specified by the second argument — src/main.rs
use std::env;
use std::fs;
fn main() {
// --snip--
println!("In file {file_path}");
let contents = fs::read_to_string(file_path)
.expect("Should have been able to read the file");
println!("With text:\n{contents}");
}
- First, a use statement brings in a relevant part of the standard library: we need std::fs to handle files.
- In main, the new statement fs::read_to_string takes the file_path, opens that file, and returns a value of type std::io::Result<String> that contains the file’s contents.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
12
Chapter 12 · 12.2 Reading a File
Running the file reader
Run it with any string as the first argument (searching isn’t implemented yet) and poem.txt as the second:
$ cargo run -- the poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With text:
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.
How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
13
Chapter 12 · 12.2 Reading a File
It works — but with two flaws to fix early
After reading the file, we again added a temporary println! statement that prints the value of contents, so that we can check that the program is working so far. Great! The code read and then printed the contents of the file.
But the code has a few flaws:
- The main function has multiple responsibilities. Generally, functions are clearer and easier to maintain if each function is responsible for only one idea.
- We’re not handling errors as well as we could.
The program is still small, so these flaws aren’t a big problem, but as the program grows it will be harder to fix them cleanly.
Remark. It’s good practice to begin refactoring early on when developing a program, because it’s much easier to refactor smaller amounts of code. We do that next.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
14
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Four problems to fix (1–2): structure
To improve our program, we fix four problems that have to do with the program’s structure and how it handles potential errors.
1. main performs two tasks
Our main function now parses arguments and reads files. As the program grows, the number of separate tasks main handles will increase. As a function gains responsibilities, it becomes more difficult to reason about, harder to test, and harder to change without breaking one of its parts. It’s best to separate functionality so that each function is responsible for one task.
2. Configuration and logic variables are mixed
query and file_path are configuration variables, while variables like contents are used to perform the program’s logic. The longer main becomes, the more variables we bring into scope, and the harder it is to keep track of the purpose of each. It’s best to group the configuration variables into one structure to make their purpose clear.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
15
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Four problems to fix (3–4): error handling
3. One unhelpful message for every read failure
We use expect to print an error message when reading the file fails, but it just prints Should have been able to read the file. Reading a file can fail in a number of ways — the file could be missing, or we might not have permission to open it. Regardless of the situation we’d print the same message, which wouldn’t give the user any information!
4. Error handling is scattered and unclear
If the user runs our program without specifying enough arguments, they get an index out of bounds error from Rust that doesn’t clearly explain the problem. It would be best if all the error-handling code were in one place, so future maintainers had only one place to consult if the error-handling logic needed to change. That also ensures we print messages that are meaningful to our end users.
We address these four problems by refactoring our project.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
16
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Separating concerns in binary projects
Allocating responsibility for multiple tasks to main is a problem common to many binary projects. So many Rust programmers split up the separate concerns of a binary program when main starts getting large.
The process
- Split your program into a main.rs file and a lib.rs file, and move your program’s logic to lib.rs.
- As long as your command line parsing logic is small, it can remain in main.
- When the parsing logic starts getting complicated, extract it from main into other functions or types.
What stays in main
- Calling the command line parsing logic with the argument values
- Setting up any other configuration
- Calling a run function in lib.rs
- Handling the error if run returns an error
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
17
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Why split main.rs and lib.rs
This pattern is about separating concerns:
main.rs handles running the program.
lib.rs handles all the logic of the task at hand.
- You can’t test the main function directly; this structure lets you test all of your program’s logic by moving it out of main.
- The code that remains in main will be small enough to verify its correctness by reading it.
Extracting the argument parser
We rework our program by following this process. First, we extract the functionality for parsing arguments into a function that main will call: Listing 12.5 shows the new start of main, which calls a new function parse_config that we define in src/main.rs.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
18
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Extracting a parse_config function
Listing 12.5: Extracting a parse_config function from main — src/main.rs
fn main() {
let args: Vec<String> = env::args().collect();
let (query, file_path) = parse_config(&args);
// --snip--
}
fn parse_config(args: &[String]) -> (&str, &str) {
let query = &args[1];
let file_path = &args[2];
(query, file_path)
}
We still collect the command line arguments into a vector, but instead of assigning index 1 to query and index 2 to file_path inside main, we pass the whole vector to parse_config.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
19
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
What moving to parse_config changes
- The parse_config function now holds the logic that determines which argument goes in which variable, and passes the values back to main.
- We still create the query and file_path variables in main, but main no longer has the responsibility of determining how the command line arguments and variables correspond.
Remark. This rework may seem like overkill for our small program, but we’re refactoring in small, incremental steps. After making this change, run the program again to verify that the argument parsing still works. It’s good to check your progress often, to help identify the cause of problems when they occur.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
20
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Grouping configuration values
We can take another small step to improve parse_config. Two signs show we don’t have the right abstraction yet:
- We return a tuple, but then immediately break that tuple into individual parts again.
- The config part of parse_config implies that the two values we return are related and are both part of one configuration value. We don’t currently convey this meaning in the structure of the data, other than by grouping the two values into a tuple.
Instead, we put the two values into one struct and give each of the struct fields a meaningful name. Doing so makes it easier for future maintainers of this code to understand how the different values relate to each other and what their purpose is. Listing 12.6 shows the improvements to parse_config.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
21
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Returning a Config struct: main
Listing 12.6: Refactoring parse_config to return an instance of a Config struct — src/main.rs
fn main() {
let args: Vec<String> = env::args().collect();
let config = parse_config(&args);
println!("Searching for {}", config.query);
println!("In file {}", config.file_path);
let contents = fs::read_to_string(config.file_path)
.expect("Should have been able to read the file");
// --snip--
}
main now stores the returned Config in a variable named config, and uses its fields instead of the separate query and file_path variables.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
22
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Returning a Config struct: the struct and parse_config
Listing 12.6 (continued) — src/main.rs
struct Config {
query: String,
file_path: String,
}
fn parse_config(args: &[String]) -> Config {
let query = args[1].clone();
let file_path = args[2].clone();
Config { query, file_path }
}
We added a struct named Config with fields query and file_path; parse_config now returns a Config value.
Config now contains owned String values instead of slices referencing args. The args variable in main owns the argument values and only lets parse_config borrow them, so we’d violate Rust’s borrowing rules if Config tried to take ownership of them.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
23
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Managing the String data with clone
There are a number of ways we could manage the String data. The easiest, though somewhat inefficient, route is to call the clone method on the values:
- It makes a full copy of the data for the Config instance to own, which takes more time and memory than storing a reference to the string data.
- But cloning also makes our code very straightforward, because we don’t have to manage the lifetimes of the references.
- In this circumstance, giving up a little performance to gain simplicity is a worthwhile trade-off.
The trade-offs of using clone
Remark. Many Rustaceans tend to avoid using clone to fix ownership problems because of its runtime cost; Chapter 13 shows more efficient methods for this type of situation. For now it’s okay to copy a few strings to keep making progress, because you make these copies only once and your file path and query string are very small. It’s better to have a working program that’s a bit inefficient than to try to hyperoptimize code on your first pass. As you become more experienced with Rust it gets easier to start with the most efficient solution, but for now it’s perfectly acceptable to call clone.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
24
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
From parse_config toward a constructor
Our code now more clearly conveys that query and file_path are related and that their purpose is to configure how the program will work. Any code that uses these values knows to find them in the config instance, in the fields named for their purpose.
Creating a constructor for Config
So far, we’ve extracted the logic that parses the command line arguments from main into parse_config. That helped us see that query and file_path were related, and that the relationship should be conveyed in our code. We then added a Config struct to name their related purpose and to return the values’ names as struct field names.
Now that the purpose of parse_config is to create a Config instance, we can change it from a plain function to a function named new that is associated with the Config struct. This makes the code more idiomatic: just as we create a String by calling String::new, we’ll create a Config by calling Config::new.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
25
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Changing parse_config into Config::new: main
Listing 12.7 shows the changes we need to make.
Listing 12.7: Changing parse_config into Config::new — src/main.rs
fn main() {
let args: Vec<String> = env::args().collect();
let config = Config::new(&args);
// --snip--
}
// --snip--
We’ve updated main where we were calling parse_config to instead call Config::new. The rest of main and the Config struct are unchanged.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
26
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Changing parse_config into Config::new: the impl block
Listing 12.7 (continued) — src/main.rs
impl Config {
fn new(args: &[String]) -> Config {
let query = args[1].clone();
let file_path = args[2].clone();
Config { query, file_path }
}
}
- We’ve changed the name of parse_config to new and moved it within an impl block, which associates the new function with Config.
- Try compiling this code again to make sure it works.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
27
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Fixing the error handling: index out of bounds
Now we work on fixing our error handling. Recall that accessing the values in the args vector at index 1 or index 2 will cause the program to panic if the vector contains fewer than three items. Running the program without any arguments looks like this:
$ cargo run
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep`
thread 'main' (6023615) panicked at src/main.rs:27:21:
index out of bounds: the len is 1 but the index is 1
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
The line index out of bounds: the len is 1 but the index is 1 is an error message intended for programmers. It won’t help our end users understand what they should do instead. Let’s fix that now.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
28
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Improving the error message
We add a check in new that verifies the slice is long enough before accessing index 1 and index 2. If it isn’t, the program panics and displays a better error message.
Listing 12.8: Adding a check for the number of arguments — src/main.rs
impl Config {
// --snip--
fn new(args: &[String]) -> Config {
if args.len() < 3 {
panic!("not enough arguments");
}
// --snip--
}
}
Like Guess::new in Listing 9.13, which called panic! for an out-of-range value, we check that args has at least 3 items, so the rest of the function can assume this condition has been met. With fewer than three items the condition is true, and panic! ends the program immediately.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
29
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
A better message — but still a panic
With these extra few lines in new, running the program without any arguments again gives:
$ cargo run
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep`
thread 'main' (6023776) panicked at src/main.rs:26:13:
not enough arguments
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
This output is better: we now have a reasonable error message. However, we also have extraneous information we don’t want to give to our users.
Remark. Perhaps the technique of Listing 9.13 isn’t the best one here: as discussed in Chapter 9, a call to panic! is more appropriate for a programming problem than a usage problem. Instead we use the other technique from Chapter 9 — returning a Result that indicates either success or an error.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
30
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Returning a Result instead of calling panic!
We can instead return a Result value that contains a Config instance in the successful case and describes the problem in the error case.
- We also change the function name from new to build, because many programmers expect new functions to never fail.
- When Config::build is communicating to main, we can use the Result type to signal there was a problem.
- Then we can change main to convert an Err variant into a more practical error for our users, without the surrounding text about thread 'main' and RUST_BACKTRACE that a call to panic! causes.
Listing 12.9 (next slide) shows the changes to the return value of the function we now call Config::build, and to its body, needed to return a Result.
Remark. This won’t compile until we update main as well, which we do in the listing after it.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
31
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Config::build returns a Result
Listing 12.9: Returning a Result from Config::build — src/main.rs
impl Config {
fn build(args: &[String]) -> Result<Config, &'static str> {
if args.len() < 3 {
return Err("not enough arguments");
}
let query = args[1].clone();
let file_path = args[2].clone();
Ok(Config { query, file_path })
}
}
- Success: a Config instance. Error: a string literal — our error values always have the 'static lifetime.
- In the body, we return an Err instead of calling panic!, and wrap the Config return value in an Ok.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
32
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Calling Config::build and handling errors
Returning an Err lets main handle the Result and exit cleanly. To print a user-friendly message we update main, and implement the nonzero exit code by hand instead of relying on panic!.
Listing 12.10: Exiting with an error code if building a Config fails — src/main.rs
use std::process;
fn main() {
let args: Vec<String> = env::args().collect();
let config = Config::build(&args).unwrap_or_else(|err| {
println!("Problem parsing arguments: {err}");
process::exit(1);
});
// --snip--
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
33
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
unwrap_or_else and closures
Listing 12.10 uses a method not yet covered in detail: unwrap_or_else, defined on Result<T, E> by the standard library. It lets us define custom, non-panic! error handling:
- If the Result is an Ok value, it behaves like unwrap: it returns the inner value that Ok is wrapping.
- If the value is an Err value, it calls the code in the closure we pass as its argument.
Definition 12.3 (Closure). An anonymous function that we define and pass as an argument — here, to unwrap_or_else. Its parameters appear between vertical pipes, as in |err|. Closures are covered in detail in Chapter 13.
For now, you just need to know that unwrap_or_else passes the inner value of the Err — in this case the static string "not enough arguments" that we added in Listing 12.9 — to our closure in the argument err that appears between the vertical pipes. The code in the closure can then use the err value when it runs.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
34
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
process::exit and a friendlier error
A new use line brings process from the standard library into scope. The closure run in the error case is only two lines: we print the err value and then call process::exit, which stops the program immediately and returns the number that was passed as the exit status code.
Definition 12.4 (Nonzero exit status). A convention by which a program signals to the process that called it that the program exited with an error state.
This is similar to the panic!-based handling of Listing 12.8, but we no longer get all the extra output. Great! This output is much friendlier for our users:
$ cargo run
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.48s
Running `target/debug/minigrep`
Problem parsing arguments: not enough arguments
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
35
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Extracting logic from main
Now that we’ve finished refactoring the configuration parsing, we turn to the program’s logic. As stated in “Separating Concerns in Binary Projects”, we extract a function named run that will hold all the logic currently in main that isn’t involved with setting up configuration or handling errors.
main: concise and easy to verify by inspection.
run and the rest: all the other logic, which we can write tests for.
Listing 12.11 (next slide) shows the small, incremental improvement of extracting a run function. The run function now contains all the remaining logic from main, starting from reading the file, and it takes the Config instance as an argument.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
36
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
The run function
Listing 12.11: Extracting a run function containing the rest of the program logic — src/main.rs
fn main() {
// --snip--
println!("Searching for {}", config.query);
println!("In file {}", config.file_path);
run(config);
}
fn run(config: Config) {
let contents = fs::read_to_string(config.file_path)
.expect("Should have been able to read the file");
println!("With text:\n{contents}");
}
// --snip--
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
37
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Returning errors from run
With the remaining logic separated into run, we can improve its error handling as we did with Config::build in Listing 12.9. Instead of letting the program panic by calling expect, run will return a Result<T, E> when something goes wrong. This lets us further consolidate the error-handling logic into main in a user-friendly way.
Listing 12.12: Changing the run function to return Result — src/main.rs
use std::error::Error;
// --snip--
fn run(config: Config) -> Result<(), Box<dyn Error>> {
let contents = fs::read_to_string(config.file_path)?;
println!("With text:\n{contents}");
Ok(())
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
38
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Change 1: the return type Result<(), Box<dyn Error>>
Listing 12.12 makes three significant changes. First, we changed the return type of run to Result<(), Box<dyn Error>>. The function previously returned the unit type, (), and we keep that as the value returned in the Ok case.
For the error type we used the trait object Box<dyn Error>, and brought std::error::Error into scope with a use statement at the top.
Definition 12.5 (Trait object Box<dyn Error>). A return type meaning that the function returns some type that implements the Error trait, without our having to specify which particular type the return value will be. The dyn keyword is short for dynamic. Trait objects are covered in Chapter 18.
This gives us flexibility to return error values that may be of different types in different error cases.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
39
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Changes 2 and 3: the ? operator and Ok(())
2. ? instead of expect
We removed the call to expect in favor of the ? operator, as discussed in Chapter 9. Rather than panic! on an error, ? returns the error value from the current function for the caller to handle.
3. Ok(()) on success
The run function now returns an Ok value in the success case. We declared its success type as (), so we need to wrap the unit type value in the Ok value.
Remark. This Ok(()) syntax might look a bit strange at first. But using () like this is the idiomatic way to indicate that we’re calling run for its side effects only; it doesn’t return a value we need.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
40
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
The unused Result warning
When you run this code, it compiles but displays a warning:
$ cargo run -- the poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
warning: unused `Result` that must be used
--> src/main.rs:19:5
|
19 | run(config);
| ^^^^^^^^^^^
|
= note: this `Result` may be an `Err` variant, which should be handled
= note: `#[warn(unused_must_use)]` (part of `#[warn(unused)]`) on by default
help: use `let _ = ...` to ignore the resulting value
|
19 | let _ = run(config);
| +++++++
warning: `minigrep` (bin "minigrep") generated 1 warning
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
41
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
The program still runs — but the Result is ignored
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.71s
Running `target/debug/minigrep the poem.txt`
Searching for the
In file poem.txt
With text:
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.
How dreary to be somebody!
How public, like a frog
To tell your name the livelong day
To an admiring bog!
Rust tells us that our code ignored the Result value, and that the Result value might indicate an error occurred. We’re not checking whether there was an error, and the compiler reminds us that we probably meant to have some error-handling code here! We rectify that problem now.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
42
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Handling errors returned from run in main
We check for errors with a technique similar to the one used with Config::build in Listing 12.10, with a slight difference:
fn main() {
// --snip--
println!("Searching for {}", config.query);
println!("In file {}", config.file_path);
if let Err(e) = run(config) {
println!("Application error: {e}");
process::exit(1);
}
}
- We use if let rather than unwrap_or_else: run returns () on success, so we only care about detecting an error — there is no value to unwrap.
- The bodies are the same in both cases: we print the error and exit.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
43
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Splitting code into a library crate
Our minigrep project is looking good so far! Now we split src/main.rs and put some code into src/lib.rs. That way, we can test the code and have a src/main.rs file with fewer responsibilities.
We define the code responsible for searching text in src/lib.rs rather than src/main.rs, which lets us (or anyone else using our minigrep library) call the searching function from more contexts than our minigrep binary. First, we define the search function signature, with a body that calls the unimplemented! macro; the signature is explained when we fill in the implementation.
Listing 12.13: Defining the search function in src/lib.rs — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
unimplemented!();
}
The pub keyword designates search as part of our library crate’s public API. We now have a library crate that we can use from our binary crate and that we can test!
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
44
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
Calling the library’s search from the binary
Listing 12.14: Using the minigrep library crate’s search function in src/main.rs — src/main.rs
// --snip--
use minigrep::search;
fn main() {
// --snip--
}
// --snip--
fn run(config: Config) -> Result<(), Box<dyn Error>> {
let contents = fs::read_to_string(config.file_path)?;
for line in search(&config.query, &contents) {
println!("{line}");
}
Ok(())
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
45
Chapter 12 · 12.3 Refactoring to Improve Modularity and Error Handling
What Listing 12.14 changes
- A use minigrep::search line brings the search function from the library crate into the binary crate’s scope.
- In run, rather than printing out the contents of the file, we call search, passing config.query and contents as arguments, and use a for loop to print each line returned from search that matched the query.
- This is also a good time to remove the println! calls in main that displayed the query and the file path, so that the program only prints the search results (if no errors occur).
Remark. The search function collects all the results into a vector it returns before any printing happens. This could be slow to display results when searching large files, because results aren’t printed as they’re found; Chapter 13 discusses a possible fix using iterators.
Whew! That was a lot of work, but it’s now much easier to handle errors and the code is more modular; almost all our work will be done in src/lib.rs from here on. Next we use this modularity for something difficult with the old code but easy with the new: we’ll write some tests!
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
46
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
The test-driven development process
With the search logic in src/lib.rs, separate from main, it’s much easier to write tests for the core functionality: we can call functions directly with various arguments and check return values, without calling our binary from the command line.
Definition 12.6 (Test-driven development, TDD). A process that repeats these steps:
- Write a test that fails, and run it to make sure it fails for the reason you expect.
- Write or modify just enough code to make the new test pass.
- Refactor the code you just added or changed, and make sure the tests continue to pass.
- Repeat from step 1!
Though it’s just one of many ways to write software, TDD can help drive code design. Writing the test before you write the code that makes it pass helps maintain high test coverage throughout the process.
We test-drive the functionality that actually searches for the query string in the file contents and produces a list of lines that match the query: the search function.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
47
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Writing a failing test
In src/lib.rs, we add a tests module with a test function, as in Chapter 11. The test function specifies the behavior we want search to have: it takes a query and the text to search, and returns only the lines from the text that contain the query. Listing 12.15 shows this test; the search stub from Listing 12.13 stays at the top of the file.
Listing 12.15: Creating a failing test for the search function for the functionality we wish we had — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
unimplemented!();
}
// --snip--
The tests module follows on the next slide.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
48
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
The one_result test
Listing 12.15 (continued) — src/lib.rs
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn one_result() {
let query = "duct";
let contents = "\
Rust:
safe, fast, productive.
Pick three.";
assert_eq!(vec!["safe, fast, productive."], search(query, contents));
}
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
49
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
What the test checks, and just enough code
- The test searches for the string "duct". The text searched is three lines, only one of which contains "duct"; we assert that search returns only the line we expect.
- The backslash after the opening double quote tells Rust not to put a newline character at the beginning of the contents of this string literal.
Run now, the test fails because unimplemented! panics with the message “not implemented”. Following TDD, we take a small step: just enough code that calling the function won’t panic, by always returning an empty vector. The test should then compile and fail, because an empty vector doesn’t match a vector containing the line "safe, fast, productive.".
Listing 12.16: Defining just enough of the search function so that calling it won’t panic (the tests module is unchanged) — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
vec![]
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
50
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Why search needs the lifetime 'a
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str>
We define an explicit lifetime 'a in the signature of search and use it with the contents argument and the return value. Recall from Chapter 10 that lifetime parameters specify which argument lifetime is connected to the lifetime of the return value.
- Here, the returned vector should contain string slices that reference slices of the argument contents (rather than the argument query).
- In other words, the data returned by search will live as long as the data passed into search in the contents argument.
Remark. This is important! The data referenced by a slice needs to be valid for the reference to be valid; if the compiler assumed we were making string slices of query rather than contents, it would do its safety checking incorrectly.
If we forget the lifetime annotations and try to compile this function, we get the error on the next slide.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
51
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Error E0106: missing lifetime specifier
$ cargo build
Compiling minigrep v0.1.0 (file:///projects/minigrep)
error[E0106]: missing lifetime specifier
--> src/lib.rs:1:51
|
1 | pub fn search(query: &str, contents: &str) -> Vec<&str> {
| ---- ---- ^ expected named lifetime parameter
|
= help: this function's return type contains a borrowed value, but the signature does not say
whether it is borrowed from `query` or `contents`
help: consider introducing a named lifetime parameter
|
1 | pub fn search<'a>(query: &'a str, contents: &'a str) -> Vec<&'a str> {
| ++++ ++ ++ ++
For more information about this error, try `rustc --explain E0106`.
error: could not compile `minigrep` (lib) due to 1 previous error
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
52
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Reading the lifetime error
Rust can’t know which of the two parameters we need for the output, so we need to tell it explicitly.
Remark. The help text suggests specifying the same lifetime parameter for all the parameters and the output type — which is incorrect! Because contents is the parameter that contains all of our text, and we want to return the parts of that text that match, contents is the only parameter that should be connected to the return value using the lifetime syntax.
Compiler’s suggestion (too strict):
query: &'a str, contents: &'a str
What we want:
query: &str, contents: &'a str
Other programming languages don’t require you to connect arguments to return values in the signature, but this practice will get easier over time. You might want to compare this example with the examples in “Validating References with Lifetimes” in Chapter 10.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
53
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Writing code to pass the test: the plan
Currently, our test is failing because we always return an empty vector. To fix that and implement search, our program needs to follow these steps:
- Iterate through each line of the contents.
- Check whether the line contains our query string.
- If it does, add it to the list of values we’re returning.
- If it doesn’t, do nothing.
- Return the list of results that match.
We work through each step, starting with iterating through lines.
Remark. In the next three listings only the search function changes; the tests module with one_result stays as in Listing 12.15.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
54
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Iterating through lines with the lines method
Rust has a helpful method to handle line-by-line iteration of strings, conveniently named lines. Note that this won’t compile yet.
Listing 12.17: Iterating through each line in contents — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
for line in contents.lines() {
// do something with line
}
}
The lines method returns an iterator. Iterators are covered in depth in Chapter 13, but recall that you saw this way of using an iterator in Listing 3.5, where a for loop with an iterator ran some code on each item in a collection.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
55
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Searching each line for the query
Next, we check whether the current line contains our query string. Fortunately, strings have a helpful method named contains that does this for us! Note that this still won’t compile yet.
Listing 12.18: Adding functionality to see whether the line contains the string in query — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
for line in contents.lines() {
if line.contains(query) {
// do something with line
}
}
}
At the moment, we’re building up functionality. To get the code to compile, we need to return a value from the body, as we indicated we would in the function signature.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
56
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Storing matching lines
To finish, we store the matching lines: make a mutable vector before the for loop, call push to store each matching line in it, and return the vector after the loop.
Listing 12.19: Storing the lines that match so that we can return them — src/lib.rs
pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
let mut results = Vec::new();
for line in contents.lines() {
if line.contains(query) {
results.push(line);
}
}
results
}
Now search should return only the lines that contain query, and our test should pass.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
57
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
The test passes
Let’s run the test:
$ cargo test
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `test` profile [unoptimized + debuginfo] target(s) in 1.22s
Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)
running 1 test
test tests::one_result ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)
...
Our test passed, so we know it works! (The elided rest of the output reports 0 tests for src/main.rs and for the doc-tests.)
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
58
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Refactoring later, and a first real search
At this point, we could consider opportunities for refactoring the implementation of search while keeping the tests passing to maintain the same functionality. The code isn’t too bad, but it doesn’t take advantage of some useful features of iterators. We return to this example in Chapter 13, which explores iterators in detail, and look at how to improve it.
Now the entire program should work! First, a word that should return exactly one line from the Emily Dickinson poem: frog.
$ cargo run -- frog poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.38s
Running `target/debug/minigrep frog poem.txt`
How public, like a frog
Cool!
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
59
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
Many matches, and no match
A word that matches multiple lines, like body:
$ cargo run -- body poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep body poem.txt`
I'm nobody! Who are you?
Are you nobody, too?
How dreary to be somebody!
Finally, make sure we don’t get any lines for a word that isn’t anywhere in the poem, such as monomorphization:
$ cargo run -- monomorphization poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep monomorphization poem.txt`
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
60
Chapter 12 · 12.4 Adding Functionality with Test-Driven Development
A mini version of a classic tool
Excellent! We’ve built our own mini version of a classic tool and learned a lot about how to structure applications. We’ve also learned a bit about file input and output, lifetimes, testing, and command line parsing.
Table 12.1: How the minigrep code is organized at this point
| File | Holds |
|---|---|
| src/main.rs | main: collect args, Config::build (exit 1 on error), call run, print “Application error” and exit 1 |
| src/main.rs | Config { query, file_path } and run: read the file with ?, print each line search returns |
| src/lib.rs | pub fn search, plus the tests module with the one_result test |
To round out this project, we briefly demonstrate how to work with environment variables and how to print to standard error, both of which are useful when you’re writing command line programs.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
61
Chapter 12 · 12.5 Working with Environment Variables
Case-insensitive search via an environment variable
We improve the minigrep binary with an extra feature: an option for case-insensitive searching that the user can turn on via an environment variable.
Definition 12.7 (Environment variable). A named value set in the user’s environment (for example, a terminal session) that a program can read to configure its behavior.
We could make this feature a command line option and require users to enter it each time they want it to apply. By making it an environment variable instead, users set it once and have all their searches be case insensitive in that terminal session.
Writing a failing test for case-insensitive search
We add a new search_case_insensitive function to the library, called when the environment variable has a value. Following TDD, the first step is again a failing test: a new test for the new function, and our old test renamed from one_result to case_sensitive to clarify the differences between the two tests.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
62
Chapter 12 · 12.5 Working with Environment Variables
The case_sensitive test
Listing 12.20: Adding a new failing test for the case-insensitive function we’re about to add (the search function above it is unchanged) — src/lib.rs
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn case_sensitive() {
let query = "duct";
let contents = "\
Rust:
safe, fast, productive.
Pick three.
Duct tape.";
assert_eq!(vec!["safe, fast, productive."], search(query, contents));
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
63
Chapter 12 · 12.5 Working with Environment Variables
The case_insensitive test
Listing 12.20 (continued) — src/lib.rs
#[test]
fn case_insensitive() {
let query = "rUsT";
let contents = "\
Rust:
safe, fast, productive.
Pick three.
Trust me.";
assert_eq!(
vec!["Rust:", "Trust me."],
search_case_insensitive(query, contents)
);
}
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
64
Chapter 12 · 12.5 Working with Environment Variables
What the two tests check
case_sensitive
We’ve edited the old test’s contents too: a new line "Duct tape." with a capital D, which shouldn’t match the query "duct" when we search in a case-sensitive manner.
Changing the old test this way helps ensure we don’t accidentally break the case-sensitive search we’ve already implemented. This test should pass now, and should continue to pass as we work on the case-insensitive search.
case_insensitive
The new test uses "rUsT" as its query. In search_case_insensitive, it should match the line containing "Rust:" with a capital R, and the line "Trust me.", even though both have different casing from the query.
This is our failing test: it fails to compile, because we haven’t yet defined search_case_insensitive. Feel free to add a skeleton that always returns an empty vector, as in Listing 12.16, to see the test compile and fail.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
65
Chapter 12 · 12.5 Working with Environment Variables
Implementing search_case_insensitive
Listing 12.21: Defining the search_case_insensitive function to lowercase the query and the line before comparing them — src/lib.rs
pub fn search_case_insensitive<'a>(
query: &str,
contents: &'a str,
) -> Vec<&'a str> {
let query = query.to_lowercase();
let mut results = Vec::new();
for line in contents.lines() {
if line.to_lowercase().contains(&query) {
results.push(line);
}
}
results
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
66
Chapter 12 · 12.5 Working with Environment Variables
How the lowercase comparison works
search_case_insensitive is almost the same as search; the only difference is that we lowercase the query and each line.
- We lowercase the query string and store it in a new variable with the same name, shadowing the original. Whether the user’s query is "rust", "RUST", "Rust", or "rUsT", we treat it as if it were "rust" and are insensitive to the case.
- query is now a String rather than a string slice, because to_lowercase creates new data rather than referencing existing data: the slice "rUsT" doesn’t contain a lowercase u or t for us to use, so we must allocate a new String containing "rust". Passing query to contains now needs an ampersand, because contains is defined to take a string slice.
- We call to_lowercase on each line to lowercase all characters. With both line and query lowercased, we find matches no matter what the case of the query is.
Remark. While to_lowercase handles basic Unicode, it won’t be 100 percent accurate. A real application would need a bit more work here, but this section is about environment variables, not Unicode.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
67
Chapter 12 · 12.5 Working with Environment Variables
Both tests pass
Let’s see if this implementation passes the tests:
$ cargo test
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `test` profile [unoptimized + debuginfo] target(s) in 1.33s
Running unittests src/lib.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)
running 2 tests
test tests::case_insensitive ... ok
test tests::case_sensitive ... ok
test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s
Running unittests src/main.rs (target/debug/deps/minigrep-9cd200e5fac0fc94)
...
Great! They passed. (The elided rest again reports 0 tests for src/main.rs and the doc-tests.)
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
68
Chapter 12 · 12.5 Working with Environment Variables
Adding an ignore_case option to Config
Now we call search_case_insensitive from run. First, we add a configuration option to the Config struct to switch between case-sensitive and case-insensitive search. Adding this field causes compiler errors, because we aren’t initializing it anywhere yet:
use minigrep::{search, search_case_insensitive};
// --snip--
pub struct Config {
pub query: String,
pub file_path: String,
pub ignore_case: bool,
}
We added the ignore_case field that holds a Boolean. Next, run must check the field’s value and use it to decide whether to call search or search_case_insensitive, as Listing 12.22 shows. This still won’t compile yet.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
69
Chapter 12 · 12.5 Working with Environment Variables
run chooses the search function
Listing 12.22: Calling either search or search_case_insensitive based on the value in config.ignore_case — src/main.rs
// --snip--
fn run(config: Config) -> Result<(), Box<dyn Error>> {
let contents = fs::read_to_string(config.file_path)?;
let results = if config.ignore_case {
search_case_insensitive(&config.query, &contents)
} else {
search(&config.query, &contents)
};
for line in results {
println!("{line}");
}
Ok(())
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
70
Chapter 12 · 12.5 Working with Environment Variables
Checking the environment variable with env::var
Finally, we need to check for the environment variable. The functions for working with environment variables are in the env module of the standard library, which is already in scope at the top of src/main.rs. We use the var function from env to check whether any value has been set for an environment variable named IGNORE_CASE (Listing 12.23, next slide).
let ignore_case = env::var("IGNORE_CASE").is_ok();
Here, we create a new variable, ignore_case. To set its value, we call env::var and pass it the name of the IGNORE_CASE environment variable. env::var returns a Result:
- the successful Ok variant, containing the value of the environment variable, if the variable is set to any value;
- the Err variant if the environment variable is not set.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
71
Chapter 12 · 12.5 Working with Environment Variables
Config::build reads IGNORE_CASE
Listing 12.23: Checking for any value in an environment variable named IGNORE_CASE — src/main.rs
impl Config {
fn build(args: &[String]) -> Result<Config, &'static str> {
if args.len() < 3 {
return Err("not enough arguments");
}
let query = args[1].clone();
let file_path = args[2].clone();
let ignore_case = env::var("IGNORE_CASE").is_ok();
Ok(Config {
query,
file_path,
ignore_case,
})
}
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
72
Chapter 12 · 12.5 Working with Environment Variables
Why is_ok, and where the flag goes
We use the is_ok method on the Result to check whether the environment variable is set, which means the program should do a case-insensitive search. If IGNORE_CASE isn’t set to anything, is_ok returns false and the program performs a case-sensitive search.
Remark. We don’t care about the value of the environment variable, just whether it’s set or unset — so we check is_ok rather than using unwrap, expect, or any of the other methods we’ve seen on Result.
We pass the value in the ignore_case variable to the Config instance, so that the run function can read that value and decide whether to call search_case_insensitive or search, as implemented in Listing 12.22.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
73
Chapter 12 · 12.5 Working with Environment Variables
Running without and with IGNORE_CASE
First, without the environment variable set and with the query to, which should match any line containing the word to in all lowercase:
$ cargo run -- to poem.txt
Compiling minigrep v0.1.0 (file:///projects/minigrep)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.0s
Running `target/debug/minigrep to poem.txt`
Are you nobody, too?
How dreary to be somebody!
Looks like that still works! Now run the program with IGNORE_CASE set to 1 but with the same query to:
$ IGNORE_CASE=1 cargo run -- to poem.txt
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
74
Chapter 12 · 12.5 Working with Environment Variables
PowerShell, and the case-insensitive result
In PowerShell, you need to set the environment variable and run the program as separate commands:
PS> $Env:IGNORE_CASE=1; cargo run -- to poem.txt
This makes IGNORE_CASE persist for the remainder of your shell session. It can be unset with the Remove-Item cmdlet:
PS> Remove-Item Env:IGNORE_CASE
We should get lines that contain to that might have uppercase letters:
Are you nobody, too?
How dreary to be somebody!
To tell your name the livelong day
To an admiring bog!
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
75
Chapter 12 · 12.5 Working with Environment Variables
Command line arguments vs environment variables
Excellent, we also got lines containing To! Our minigrep program can now do case-insensitive searching controlled by an environment variable. Now you know how to manage options set using either command line arguments or environment variables.
Some programs allow arguments and environment variables for the same configuration. In those cases, the programs decide that one or the other takes precedence.
Example 12.8. An exercise on your own: control case sensitivity through either a command line argument or an environment variable. Decide whether the command line argument or the environment variable should take precedence if the program is run with one set to case sensitive and one set to ignore case.
The std::env module contains many more useful features for dealing with environment variables: check out its documentation to see what is available.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
76
Chapter 12 · 12.6 Redirecting Errors to Standard Error
Standard output and standard error
At the moment, we’re writing all of our output to the terminal using the println! macro. In most terminals, there are two kinds of output:
Definition 12.9 (Standard output and standard error). Two output streams of a terminal program: standard output (stdout) for general information, and standard error (stderr) for error messages.
This distinction enables users to choose to direct the successful output of a program to a file but still print error messages to the screen.
Remark. The println! macro is only capable of printing to standard output, so we have to use something else to print to standard error.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
77
Chapter 12 · 12.6 Redirecting Errors to Standard Error
Checking where errors are written
First, we observe how the content printed by minigrep is currently written to standard output — including the error messages we want to write to standard error instead. We redirect the standard output stream to a file while intentionally causing an error. We don’t redirect the standard error stream, so any content sent to standard error will continue to display on the screen.
Command line programs are expected to send error messages to the standard error stream, so that we can still see error messages on the screen even if we redirect the standard output stream to a file. Our program is not currently well behaved: we’re about to see that it saves the error message output to a file instead!
We run the program with > and the file path, output.txt, that we want to redirect the standard output stream to. We pass no arguments, which should cause an error:
$ cargo run > output.txt
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
78
Chapter 12 · 12.6 Redirecting Errors to Standard Error
The error message ended up in the file
The > syntax tells the shell to write the contents of standard output to output.txt instead of the screen. We didn’t see the error message we were expecting printed to the screen, so it must have ended up in the file. This is what output.txt contains:
output.txt
Problem parsing arguments: not enough arguments
Yup, our error message is being printed to standard output. It’s much more useful for error messages like this to be printed to standard error, so that only data from a successful run ends up in the file. We’ll change that.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
79
Chapter 12 · 12.6 Redirecting Errors to Standard Error
Printing errors to standard error with eprintln!
Because of our earlier refactoring, all the code that prints error messages is in one function, main. The standard library provides the eprintln! macro, which prints to the standard error stream, so we change the two places that called println! to print errors to use eprintln! instead.
Listing 12.24: Writing error messages to standard error instead of standard output using eprintln! — src/main.rs
fn main() {
let args: Vec<String> = env::args().collect();
let config = Config::build(&args).unwrap_or_else(|err| {
eprintln!("Problem parsing arguments: {err}");
process::exit(1);
});
if let Err(e) = run(config) {
eprintln!("Application error: {e}");
process::exit(1);
}
}
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
80
Chapter 12 · 12.6 Redirecting Errors to Standard Error
Errors on screen, results in the file
An error run
Run the program again the same way, without any arguments and redirecting standard output with >:
$ cargo run > output.txt
Problem parsing arguments: not enough arguments
Now we see the error onscreen and output.txt contains nothing, which is the behavior we expect of command line programs.
A successful run
With arguments that don’t cause an error, still redirecting standard output to a file:
$ cargo run -- to poem.txt > output.txt
Nothing appears in the terminal; output.txt holds our results:
Are you nobody, too?
How dreary to be somebody!
We now use standard output for successful output and standard error for error output, as appropriate.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
81
Chapter 12 · Summary
Chapter summary
This chapter recapped some of the major concepts you’ve learned so far and covered how to perform common I/O operations in Rust. By using command line arguments, files, environment variables, and the eprintln! macro for printing errors, you’re now prepared to write command line applications. Combined with the concepts in previous chapters, your code will be well organized, store data effectively in the appropriate data structures, handle errors nicely, and be well tested.
Table 12.2: The I/O tools minigrep uses
| Need | Tool |
|---|---|
| Command line arguments | std::env::args().collect() into a Vec<String>; parsed by Config::build |
| Reading a file | std::fs::read_to_string, errors propagated with ? as Box<dyn Error> |
| Environment variables | std::env::var("IGNORE_CASE").is_ok() |
| Errors and exit status | eprintln! to standard error, then std::process::exit(1) |
Remark. Next, Chapter 13 explores some Rust features that were influenced by functional languages: closures and iterators.
The Rust Programming Language · Ch.12 An I/O Project: Building a Command Line Program
82