Starting with Tests

So far in this book, I’ve shown you how to write tests after writing the programs to get you used to the idea of testing and to practice the basics of the Rust language. Starting with this chapter, I want you to think about the tests before you start writing the program. Tests force you to consider the program’s requirements and how you will verify that the program works as expected. Ultimately, I want to draw your attention to test-driven development (TDD) as described in a book by that title written by Kent Beck (Addison-Wesley). TDD advises we write the tests before writing the code, as shown in Figure 3-1. Technically, TDD involves writing tests as you add each feature, and I will demonstrate this technique in later chapters. Because I’ve written all the tests for the program, you might consider this more like test-first development. Regardless of how and when the tests are written, the point is to emphasize testing at the beginning of the process. Once your program passes the tests, you can use the tests to improve and refactor your code, perhaps by reducing the lines of code or by finding a faster implementation.

Figure 3-1. The test-driven development cycle starts with writing a test and then the code that passes it.

Copy the 03_catr/tests directory into your new catr directory. Don’t copy anything but the tests, as you will write the rest of the code yourself. On a Unix-type system, you can copy this directory and its contents using the cp command with the recursive -r option:

$ cd catr
$ cp -r ~/command-line-rust/03_catr/tests .

$ tree -L 2
.
├── Cargo.toml
├── src
│   └── main.rs
└── tests
    ├── cli.rs
    ├── expected
    └── inputs

Run cargo test to download the dependencies, compile your program, and run the tests, all of which should fail. Starting with this chapter, I’ll get you started with the basics of setting up each program, give you the info you need to write the program, and let you finish writing it using the tests to guide you.

The programs we’ve written in this book so far have been pretty short. The typical programs you will write in your career will likely be much longer. Starting with this program, I suggest you divide the code into a library in src/lib.rs and a binary in src​/⁠main.rs that will call library functions. I believe this organization makes it easier to test and grow applications over time.

I’ll demonstrate how to use a library with the default “Hello, world!” then I’ll show how to use this structure to write echor. To start, move all the important bits from src/main.rs into a function called run in src/lib.rs. This function will return a kind of Result to indicate success or failure. This is similar to the TestResult type alias from Chapter 2, but whereas TestResult always returns the unit type () in the Ok variant, MyResult can return an Ok that contains any type, which is represented using the generic T in the following code:

use std::error::Error; 

type MyResult<T> = Result<T, Box<dyn Error>>;

pub fn run() -> MyResult<()> { 
    println!("Hello, world!"); 
    Ok(()) 
}

Import the Error trait for representing error values.

Create a MyResult to represent an Ok value for any type T or some Err value that implements the Error trait.

Define a public (pub) function that returns either Ok containing the unit type () or some error Err.

Print Hello, world!

Return an indication that the function ran successfully.

To call the run function, change src/main.rs to the following. Note that the functions in src/lib.rs are available through the crate named catr:

fn main() {
    if let Err(e) = catr::run() { 
        eprintln!("{}", e); 
        std::process::exit(1); 
    }
}

Execute the catr::run function and check if the return value matches Err(e), where e is some value that implements the Error trait, which means, among other things, that it can be printed.

Use the eprintln! (error print line) macro to print the error message to STDERR.

Exit the program with a nonzero value to indicate an error.

If you execute cargo run, you should see Hello, world! as before.

Defining the Parameters

Now that your code has a more formal structure, it’s time to modify it to meet the criteria for echor. Let’s start by adding the program’s command-line parameters, which I suggest you represent using a struct called Config. A struct definition is similar to a class definition in object-oriented languages. In this case, we want a struct that describes the names and types of the arguments to the program. Specifically, echor requires a list of input filenames and the -n and -b flags for numbering the lines of output.

#[derive(Debug)] 
pub struct Config { 
    files: Vec<String>, 
    number_lines: bool, 
    number_nonblank_lines: bool, 
}

The derive macro adds the Debug trait so the struct can be printed.

Define a public struct called Config.

The files will be a vector of strings.

This is a Boolean value to indicate whether or not to print the line numbers.

This is a Boolean to control printing line numbers only for nonblank lines.

To use a struct, you create an instance of it with specific values. In the following sketch of a get_args function, you can see it finishes by creating a new Config with the runtime values from the user. Add use clap::{App, Arg} and this function to your src/lib.rs. Use what you learned from Chapter 2 to complete this function on your own:

pub fn get_args() -> MyResult<Config> { 
    let matches = App::new("catr")
        .version("0.1.0")
        .author("Ken Youens-Clark <kyclark@gmail.com>")
        .about("Rust cat")
        // What goes here? 
        .get_matches();

    Ok(Config { 
        files: ...,
        number_lines: ...,
        number_nonblank_lines: ...,
    })
}

This is a public function that returns a MyResult that will contain either a Config on success or an error.

You should define the parameters here.

Return an Ok variant containing a Config using the supplied values.

This means the run function needs to be updated to accept a Config argument. For now, print it:

pub fn run(config: Config) -> MyResult<()> { 
    dbg!(config); 
    Ok(())
}

The function will accept a Config struct and will return Ok with the unit type if successful.

Use the dbg! (debug) macro to print the configuration.

fn main() {
    if let Err(e) = catr::get_args().and_then(catr::run) { 
        eprintln!("{}", e); 
        std::process::exit(1); 
    }
}

If the catr::get_args function returns an Ok(config) value, use Result​::and_then to pass the config to catr::run.

If either get_args or run returns an Err, print it to STDERR.

Exit the program with a nonzero value.

When run with the -h or --help flags, your program should print a usage like this:

$ cargo run --quiet -- --help
catr 0.1.0
Ken Youens-Clark <kyclark@gmail.com>
Rust cat

USAGE:
    catr [FLAGS] [FILE]...

FLAGS:
    -h, --help               Prints help information
    -n, --number             Number lines
    -b, --number-nonblank    Number nonblank lines
    -V, --version            Prints version information

ARGS:
    <FILE>...    Input file(s) [default: -]

With no arguments, your program should print a configuration structure like this:

$ cargo run
[src/lib.rs:52] config = Config {
    files: [ 
        "-",
    ],
    number_lines: false, 
    number_nonblank_lines: false,
}

The default files should contain a dash (-) for STDIN.

The Boolean values should default to false.

Run it with some arguments and be sure the config looks like this:

$ cargo run -- -n tests/inputs/fox.txt
[src/lib.rs:52] config = Config {
    files: [
        "tests/inputs/fox.txt", 
    ],
    number_lines: true, 
    number_nonblank_lines: false,
}

The positional file argument is parsed into the files.

The -n option causes number_lines to be true.

While the BSD version will allow both -n and -b, the challenge program should consider these to be mutually exclusive and generate an error when they’re used together:

$ cargo run -- -b -n tests/inputs/fox.txt
error: The argument '--number-nonblank' cannot be used with '--number'

All set? Compare what you have to my get_args function:

pub fn get_args() -> MyResult<Config> {
    let matches = App::new("catr")
        .version("0.1.0")
        .author("Ken Youens-Clark <kyclark@gmail.com>")
        .about("Rust cat")
        .arg(
            Arg::with_name("files") 
                .value_name("FILE")
                .help("Input file(s)")
                .multiple(true)
                .default_value("-"),
        )
        .arg(
            Arg::with_name("number") 
                .short("n")
                .long("number")
                .help("Number lines")
                .takes_value(false)
                .conflicts_with("number_nonblank"),
        )
        .arg(
            Arg::with_name("number_nonblank") 
                .short("b")
                .long("number-nonblank")
                .help("Number non-blank lines")
                .takes_value(false),
        )
        .get_matches();

    Ok(Config {
        files: matches.values_of_lossy("files").unwrap(), 
        number_lines: matches.is_present("number"), 
        number_nonblank_lines: matches.is_present("number_nonblank"),
    })
}

This positional argument is for the files and is required to have at least one value that defaults to a dash (-).

This is an option that has a short name -n and a long name --number. It does not take a value because it is a flag. When present, it will tell the program to print line numbers. It cannot occur in conjunction with -b.

The -b|--number-nonblank flag controls whether or not to print line numbers for nonblank lines.

Because at least one value is required, it should be safe to call Option::unwrap.

The two Boolean options are either present or not.

You should be able to pass at least a couple of the tests if you execute cargo test at this point. There will be a great deal of output showing you all the failing test output, but don’t despair. You will soon see a fully passing test suite.

Now that you have validated all the arguments, you are ready to process the files and create the correct output. First, modify the run function in src/lib.rs to print each filename:

pub fn run(config: Config) -> MyResult<()> {
    for filename in config.files { 
        println!("{}", filename); 
    }
    Ok(())
}

Iterate through each filename.

Print the filename.

Run the program with some input files. In the following example, the bash shell will expand the file glob1 *.txt into all filenames that end with the extension .txt:

$ cargo run -- tests/inputs/*.txt
tests/inputs/empty.txt
tests/inputs/fox.txt
tests/inputs/spiders.txt
tests/inputs/the-bustle.txt

Windows PowerShell can expand file globs using Get-ChildItem:

> cargo run -q -- -n (Get-ChildItem .\tests\inputs\*.txt)
C:\Users\kyclark\work\command-line-rust\03_catr\tests\inputs\empty.txt
C:\Users\kyclark\work\command-line-rust\03_catr\tests\inputs\fox.txt
C:\Users\kyclark\work\command-line-rust\03_catr\tests\inputs\spiders.txt
C:\Users\kyclark\work\command-line-rust\03_catr\tests\inputs\the-bustle.txt

The next step is to try to open each filename. When the filename is a dash, you should open STDIN; otherwise, attempt to open the given filename and handle errors. For the following code, you will need to expand your imports in src/lib.rs to the following:

use clap::{App, Arg};
use std::error::Error;
use std::fs::File;
use std::io::{self, BufRead, BufReader};

fn open(filename: &str) -> MyResult<Box<dyn BufRead>> { 
    match filename {
        "-" => Ok(Box::new(BufReader::new(io::stdin()))), 
        _ => Ok(Box::new(BufReader::new(File::open(filename)?))), 
    }
}

// This will not compile
fn open(filename: &str) -> MyResult<dyn BufRead> {
    match filename {
        "-" => Ok(BufReader::new(io::stdin())),
        _ => Ok(BufReader::new(File::open(filename)?)),
    }
}

error[E0277]: the size for values of type `(dyn std::io::BufRead + 'static)`
cannot be known at compilation time
   --> src/lib.rs:88:28
    |
88  | fn open(filename: &str) -> MyResult<dyn BufRead> {
    |                            ^^^^^^^^^^^^^^^^^^^^^
    |                            doesn't have a size known at compile-time
    |
    = help: the trait `Sized` is not implemented for `(dyn std::io::BufRead
    + 'static)`

pub fn run(config: Config) -> MyResult<()> {
    for filename in config.files { 
        match open(&filename) { 
            Err(err) => eprintln!("Failed to open {}: {}", filename, err), 
            Ok(_) => println!("Opened {}", filename), 
        }
    }
    Ok(())
}

$ touch cant-touch-this && chmod 000 cant-touch-this

$ cargo run -- blargh cant-touch-this tests/inputs/fox.txt
Failed to open blargh: No such file or directory (os error 2)
Failed to open cant-touch-this: Permission denied (os error 13)
Opened tests/inputs/fox.txt

$ cargo run -- tests/inputs/fox.txt
The quick brown fox jumps over the lazy dog.

$ cat tests/inputs/fox.txt | cargo run
The quick brown fox jumps over the lazy dog.

$ cargo run -- - < tests/inputs/fox.txt
The quick brown fox jumps over the lazy dog.

$ cargo run -- -n tests/inputs/spiders.txt
     1	Don't worry, spiders,
     2	I keep house
     3	casually.

$ cargo run -- -b tests/inputs/the-bustle.txt
     1	The bustle in a house
     2	The morning after death
     3	Is solemnest of industries
     4	Enacted upon earth,—

     5	The sweeping up the heart,
     6	And putting love away
     7	We shall not want to use again
     8	Until eternity.