我们要运用目前为止学到的 Rust 编程语言知识来制作出属于我们的「grep」(globally search a regular expression and print)程序。简单来说,grep 程序可以用来寻找特定文件中的特定字符串。grep 程序可以透过命令行参数来传入文件路径和要寻找的字符串,运行的时候就可以读取这个文件中所有包含要寻找的字符串的该行数据,并将其印出。

就像其它的命令行程序一样,我们要制作的 grep 程序也会有自己的命令行参数,并且能将错误消息和我们要的文件数据分别输出到标准错误(stderr)和标准输出(stdout)中。除了基本的程序观念外,我们的 grep 程序还会用到以下我们已经学习过的 Rust 观念:

1. 模块。
2. Vec 和 String 集合。
3. 错误处理。
4. 特性和生命周期。
5. 测试。

首先用 Cargo 创建出一个名叫 minigrep 的应用程序项目。

读取命令行的参数

如果要使用 cargo run 指令来编译和运行项目,且顺便在运行项目主程序的时候顺便从命令行代入参数,可以直接将参数接在 cargo run 指令之后。举例来说,假设我们的 grep 程序第一个参数是要搜索的字符串 searchstring,第二个的参数是要被搜索指定字符串的文件路径 example-filename.txt。指令如下:

cargo run searchstring example-filename.txt

如果要在 Rust 程序中读到透过命令行传进来的参数,可以使用标准函数库 std::env 模块提供的 args 函数。这个 args 函数会回传一个 Args 结构体,有实作一些迭代器的相关特性,因此可以使用 collect 方法来产生 Vec 结构体。程序如下:

use std::env;

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

    println!("{args:?}", );
}

运行 cargo run searchstring example-filename.txt 指令看看,结果如下:

印出命令行参数的 cargo run 结果

args 函数所回传的 Vec 结构体,索引 0 的位置会是调用这个程序所使用的字符串,之后的元素才是额外传入的参数。我们要做的 grep 程序,会使用到索引 1 和索引 2 的元素,可以另外使用其它变量来借用它们。程序如下:

use std::env;

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

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

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

运行 cargo run searchstring example-filename.txt 指令看看,结果如下:

印出查找字符串与文件路径的结果

读取文件

Rust 编程语言的标准函数库中的 std::fs 模块,可以用来处理文件相关的操作。std::fs 模块的 File 结构体提供了 open 函数,能够传入文件路径来打开指定的文件,其结构实体实作了 std::io::prelude 模块提供的 Read 特性,可以使用 read_to_string 方法,来读取整个文件内容并直接存到 String 结构实体中。

程序如下:

use std::env;
use std::fs::File;
use std::io::prelude::*;

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

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

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

    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

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

我们直接在 main 函数来处理命令行传进来的参数,以及文件的打开与读取,这样的作法目前并没有什么太大的问题,但是一旦程序功能变多,如果还是通通都在 main 函数中处理的话,会变得很难阅读、测试和维护。并且我们在使用 open 函数打开文件的时候,是直接用 Result 枚举实体所提供的 expect 方法来处理当实体为 Err 变体时的情形,然而,open 函数并不会只有文件不存在的情况才会回传 Err 变体,我们必须要提供用户更详细的错误信息!再来,如果用户在使用命令行运行我们的程序时,并没有额外再多传入二个参数,来指定要搜索的字符串和要被搜索的文件,程序第 8 行和第 9 行就会有超出数组索引范围的问题。

在设计命令行程序时,可以参考以下准则:

1. 将程序逻辑写在 lib.rs 文件,在 main.rs 文件中应用。
2. 如果命令行参数的逻辑很简单,可以直接写在 main.rs 文件中。
3. 当命令行参数的逻辑变得更加复杂时,要将其移动到 lib.rs 文件。
4. main 函数的责任为:调用处理命令行参数逻辑的函数或方法、建构组态设置、以建构出来的组态设置来调用 lib.rs 文件的 run 函数、处理函数或方法回传的错误。

main.rs 文件用来处理进入程序和离开程序的流程,lib.rs 文件用来处理程序的主要逻辑。如此一来,main.rs 文件中的程序就会足够精简,让我们可以快速地就由阅读代码来判断 main 函数的正确性,因为我们很难撰写一个测试来去做 main 函数的功能验证。

修改一下目前 minigrep 项目的程序,在 src 目录下创建出 lib.rs 文件,并将处理命令行参数的逻辑部份在 lib.rs 文件中另外实作出 Config 结构体来处理。如下:

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

我们添加了 Config 结构体来保存 query 和 filepath 的信息,并替它实作出一个 new 函数,可以传入命令行参数来检查参数数量,并创建出 Config 结构实体或是错误消息来经由 Result 枚举包裹回传。

main.rs 文件也修改如下:

use std::env;
use std::fs::File;
use std::io::prelude::*;

use minigrep::*;

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

    let config = Config::new(&args).unwrap();

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

    let mut f = File::open(config.filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

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

以上程序,第 10 行我们直接使用 unwrap 方法来处理 new 函数所回传的 Result 枚举实体,遇到命令行参数不足的情形,程序就会发生 panic。

运行 cargo run 指令看看,结果如下:

参数不足时发生 panic 的结果

然而,这样的错误消息对于一般不懂开发程序的用户来说是很不友善的,我们需要使用其它的方式来处理 new 函数回传的错误。Result 枚举的实体除了有提供 unwrap 和 expect 方法外,还有一个常用的 unwrap_or_else 方法。unwrap_or_else 方法可以直接从参数传入一个「闭包」(closure),「闭包」类似没有名称的函数,可以透过变量、参数来进行保存与传递。调用 unwrap_or_else 方法的实体如果是 Ok 变体的话,行为和 unwrap 方法一样;但如果是 Err 变体的话,则会去运行传入的闭包。闭包的实作方式跟函数很像,差别只在于闭包的参数是使用 | 语法来定义,而不是函数所用的小括号 (),且闭包的参数会被自动进行类型推论,不需要特别去明确指定类型。

使用 unwrap_or_else 方法将程序修改成如下:

use std::env;
use std::fs::File;
use std::io::prelude::*;
use std::process;

use minigrep::*;

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

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

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

    let mut f = File::open(config.filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

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

我们在闭包中,将 Err 实体直接印出到标准错误,并且使用 Rust 编程语言的标准函数库中的 std::process 模块所提供的 exit 函数,让程序回传 1。运行程序时,操作系统会打开新的进程(process)来处理,这个进程在结束的时候也会有个整数回传值,称作退出状态码(Exit Code)。一般程序在完全正常的运作下结束,运行该程序的进程会回传 0,否则就会是其它非 0 的值。在 Linux 操作系统下,shell 中前一个进程的退出状态码,会保存到 $? 变量中,因此可以使用 echo $? 来查看退出状态码。

运行 cargo run 指令和 echo $? 指令看看,结果如下:

以 echo $? 查看退出状态码

再来将目前 main 函数中打开与读取文件的程序也改写至 lib.rs 文件中,并实作出 run 函数,如下:

use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

pub fn run(config: Config) {
    let contents = open_read_file(&config.filepath);

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

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}
use std::env;
use std::process;

use minigrep::*;

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

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

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

    run(config);
}

接着我们要来实作搜索字符串的程序了,由于这个是比较复杂的逻辑,我们先从定义函数的签名和回传值类型开始,接着撰写测试,最后才是实作搜索字符串的逻辑部份。

我们先在 lib.rs 文件中实作出一个最简单的 search 函数,这个函数需要接受 run 函数先前于 Config 结构实体的 query 字段和 contents 变量所保存的字符串作为参数,然后回传所有寻找到子字符串的该行的字符串切片。由于我们不知道一个文件内究竟会有多少行被搜索到,因此 search 函数回传的字符串切片应该要使用 Vec 结构实体来保存。

程序如下:

use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    vec![]
}

pub fn run(config: Config) {
    let contents = open_read_file(&config.filepath);

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

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}

这边在定义 search 函数的时候使用了泛型来明确定义 contents 参数和回传的 Vec 结构实体所保存的元素的生命周期必须要是一样的,因为 Vec 结构实体的元素就是从 contents 参数来的,它们的生命周期必须要一样。在 search 函数主体,我们只先回传一个空的 Vec 结构实体,确保目前的程序可以通过编译。

接下来要撰写测试,我们需要先想好一个或是数个使用 search 函数的不同案例。举例来说,假设输入的文件内容是以下这段文字:

Rust:
safe, fast, productive.
Pick three.

则当我们搜索 duct 字符串的时候,search 函数应该要回传只存着一个元素 safe, fast, productive. 的 Vec 结构实体。程序如下:

use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> {
    vec![]
}

pub fn run(config: Config) {
    let contents = open_read_file(&config.filepath);

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

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "Rust:\nsafe, fast, productive.\nPick three.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

此时使用 cargo test 指令来测试项目,结果如下:

one_result 测试失败的结果

one_result 测试函数测试失败是很正常的,因为我们还没有真的把 search 函数实作出来嘛!

将 search 函数的主体修改如下:

use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

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
}

pub fn run(config: Config) {
    let contents = open_read_file(&config.filepath);

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

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "Rust:\nsafe, fast, productive.\nPick three.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

程序第 23 行,使用 Vec 结构体的 new 函数创建出一个 Vec 结构实体,并且指派给 results 变量保存。程序第 25 行,使用 for 循环搭配字符串的 lines 方法来走访字符串的各行,line 变量的类型为字符串切片。程序第 26 行,使用字符串提供的 contains 方法来寻找其是否含有指定的子字符串。程序第 27 行,如果目前走访的该行含有我们要找的子字符串,就将该行保存到 Vec 结构实体中。程序第 31 行,回传 Vec 结构实体。

此时使用 cargo test 指令来测试项目,结果如下:

one_result 测试通过的结果

one_result 测试函数成功通过测试了!

接下来我们要把 search 函数应用在 run 函数内,将程序修改如下:

use std::error::Error;
use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        Ok(Config { query, filepath })
    }
}

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
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = open_read_file(&config.filepath);

    for line in search(&config.query, &contents) {
        println!("{line}");
    }

    Ok(())
}

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "Rust:\nsafe, fast, productive.\nPick three.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }
}

程序第 1 行,将 Rust 编程语言标准函数库中 std::error 模块的 Error 特性给引入到目前程序的 scope。程序第 35 行,让 run 函数可以回传一个 Result 枚举的实体,泛型的部份第一个参数使用空元组类型,也就是说 Ok 变体会包裹着空元组;第二个参数使用 Box 结构体,其泛型的第一个参数为 Error 特性,也就是说 Err 变体会包裹着 Box<dyn Error> 的实体,有关于 Box 结构体和 dyn 关键字的用法之后的章节才会介绍。程序第 38 行,我们直接使用 for 循环去走访 search 函数回传的 Vec 结构实体,而不是使用其提供的 iter 方法来创建迭代器再进行走访,这是因为 Vec 结构体本身有实作 IntoIterator 特性,使用在 for 循环时会自动进入其所实作好要被使用的迭代器。有关于迭代器的概念会在之后的章节介绍。

接着将 main 函数修改如下:

use std::env;
use std::process;

use minigrep::*;

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

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

    if let Err(e) = minigrep::run(config) {
        eprintln!("Application error: {e}");

        process::exit(1);
    }
}

如此一来我们初步的 grep 程序就算是完成啦!

在 Linux 操作系统环境下,运行 cargo run bash /etc/passwd 指令,就可以查看哪些 Linux 系统的用户使用 bash shell。如下图:

以 grep 程序搜索使用 bash 的用户

再来我们要强化这个 grep 程序,替它加上忽略大小写的搜索功能,可以借由环境变量 CASE_INSENSITIVE 来设置搜索时要不要忽略英文字母大小写。如下:

use std::env;
use std::error::Error;
use std::fs::File;
use std::io::prelude::*;

pub struct Config {
    pub query: String,
    pub filepath: String,
    pub case_sensitive: bool,
}

impl Config {
    pub fn new(args: &[String]) -> Result<Config, &str> {
        if args.len() < 3 {
            return Err("not enough arguments");
        }

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

        let case_sensitive = env::var("CASE_INSENSITIVE").is_err();

        Ok(Config { query, filepath, case_sensitive })
    }
}

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
}

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
}

pub fn run(config: Config) -> Result<(), Box<dyn Error>> {
    let contents = open_read_file(&config.filepath);

    for line in if config.case_sensitive {
        search(&config.query, &contents)
    } else {
        search_case_insensitive(&config.query, &contents)
    } {
        println!("{line}");
    }

    Ok(())
}

fn open_read_file(filepath: &str) -> String {
    let mut f = File::open(filepath).expect("file not found");

    let mut contents = String::new();
    f.read_to_string(&mut contents).expect("something went wrong reading the file");

    contents
}

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn one_result() {
        let query = "duct";
        let contents = "Rust:\nsafe, fast, productive.\nPick three.";

        assert_eq!(vec!["safe, fast, productive."], search(query, contents));
    }

    #[test]
    fn case_insensitive() {
        let query = "rUsT";
        let contents = "Rust:\nsafe, fast, productive.\nPick three.\nTrust me.";

        assert_eq!(vec!["Rust:", "Trust me."], search_case_insensitive(query, contents));
    }
}

为了要能够在 Rust 程序中读取 CASE_INSENSITIVE 环境变量,我们需要使用 Rust 编程语言的标准函数库中提供的 std::env 模块所提供的 var 函数,这个函数可以传入要取得值的变量名称,会回传一个 Result 枚举实体,其 Ok 变体所包裹的值为 String 结构实体。程序第 21 行,直接使用了 Result 枚举实体的 is_err 方法来判断 Result 枚举实体是否为 Err 变体,并将这个布尔值指派给声明出来的 case_sensitive 变量保存,换句话说,当 CASE_INSENSITIVE 环境变量有被设置,且它是正确的「Unicode」数据时,case_sensitive 变量就会是 false,反之就是 true。程序第 9 行,我们替 Config 结构体增加了一个 case_sensitive 字段,用来保存程序第 21 行 case_sensitive 变量的值。

我们添加了一个新的测试函数 case_insensitive,用来测试新实作出来的 search_case_insensitive 函数的功能是否正确。search_case_insensitive 函数和 search 函数的实作逻辑差异不大,只差在 search_case_insensitive 函数会在搜索字符串前,将字符串都使用 to_lowercase 方法转成小写。

在 run 函数中,我们使用 if 关键字判断 Config 结构实体的 case_sensitive 字段,如果它是 true,就调用 search 函数;如果它是 false,就调用 search_case_insensitive 函数。

在 Linux 操作系统环境下,运行 cargo run bAsh /etc/passwd 和 CASE_INSENSITIVE=1 cargo run bAsh /etc/passwd 指令。如下图:

以 CASE_INSENSITIVE 忽略大小写搜索

运行 cargo run bAsh /etc/passwd 指令会搜索不到任何结果,因为 bAsh 在 /etc/passwd 文件中并不存在。而 CASE_INSENSITIVE=1 cargo run bAsh /etc/passwd 则会搜索到结果,因为 CASE_INSENSITIVE 环境变量有被设置了,因此可以不用管 bAsh 的大小写,而 bash 在 /etc/passwd 文件中是存在的,所以能搜索到一些结果。

总结

在这个章节中,我们练习实作出了一个非常简单、能读取文件、命令行参数和环境变量的 grep 程序,也初步使用到了「闭包」。下一章中,我们将会更深入地学习「闭包」和「迭代器」的用法。

下一章:闭包和迭代器。