Rust 命令列程式開發：錯誤處理與輸出控制

Rust 的型別系統和所有權機制讓開發者能寫出更安全可靠的程式碼，即使在資源管理複雜的命令列程式開發中也能展現優勢。本文將以 catsay 程式為例，示範如何使用 Rust 建立一個功能完善的命令列工具，涵蓋引數解析、錯誤處理、彩色輸出、檔案讀取、標準輸入處理以及整合測試等導向。透過 clap 函式函式庫，我們可以輕鬆定義和解析命令列引數，例如布林旗標和檔案路徑。colored 函式函式庫則能讓輸出更具可讀性，方便使用者區分不同型別的訊息。而 anyhow 函式函式庫則能簡化錯誤處理流程，提供更友善的錯誤訊息。此外，我們將示範如何從檔案和標準輸入讀取訊息，讓程式更具彈性。最後，我們將使用 assert_cmd 函式函式庫示範如何撰寫整合測試，確保程式的功能正確性。

錯誤處理：使用布林值旗標

在命令列程式中，旗標（flag）是用來控制程式行為的引數。例如，使用者可以透過新增特定的旗標來啟用或停用某些功能。Rust的clap函式庫提供了一種方便的方式來解析命令列旗標。以下是一個簡單的例子：

use clap::{App, Arg};

fn main() {
    let matches = App::new("myapp")
        .arg(Arg::with_name("dead")
            .long("dead")
            .help("使貓的眼睛變成x"))
        .get_matches();

    let eye = if matches.is_present("dead") {
        "x"
    } else {
        "o"
    };

    println!(" \\");
    println!(" \\");
    println!(" /\\_/\\");

    println!(" ( {} {} )", eye, eye);
    println!(" =( I )=");
}

在這個例子中，--dead旗標用來控制貓的眼睛是否顯示為"x"。如果使用者提供了這個旗標，則eye變數將被設為"x"，否則它將被設為"o"。

輸出到STDERR

在Unix-like系統中，標準錯誤（STDERR）是一個特殊的流，用於輸出錯誤訊息。Rust提供了一個名為eprintln!的巨集，用於將輸出導向STDERR。以下是如何使用它的例子：

fn main() {
    // ...

    if message.to_lowercase() == "woof" {
        eprintln!("貓不應該像狗一樣吠叫。");
    }

    // ...
}

在這個例子中，如果使用者試圖讓貓說"woof"，程式將輸出一條錯誤訊息到STDERR。

測試輸出

要測試程式的輸出，可以使用重導命令將STDOUT和STDERR分別導向不同的檔案。例如：

cargo run "woof" 1> stdout.txt 2> stderr.txt

然後，可以使用cat命令檢視這些檔案的內容：

$ cat stdout.txt
woof
\
\
/\_/\

( o o )
=( I )=

$ cat stderr.txt
貓不應該像狗一樣吠叫。

這些命令可以幫助您瞭解程式的輸出並進行除錯。

命令列程式設計：使用 Rust 和 Colored 函式庫

在命令列程式設計中，為了讓使用者更容易理解和區分不同的訊息，通常會使用不同顏色的文字來呈現。這篇文章將介紹如何使用 Rust 和 Colored 函式庫來實作彩色的命令列輸出。

安裝 Colored 函式庫

首先，需要將 Colored 函式庫新增到您的 Cargo.toml 檔案中。您可以使用以下命令來新增：

cargo add colored

然後，確認您的 Cargo.toml 檔案中已經包含了 Colored 函式庫的版本：

[dependencies]
colored = "2.0.0"

使用 Colored 函式庫

Colored 函式庫提供了一個 Colorize trait，實作了在 &str 和 String 上的彩色函式。這些函式包括：

文字顏色：.red(), .green(), .blue(), 等
背景顏色：.on_red(), .on_green(), .on_blue(), 等
亮色版本：.bright_red(), .on_bright_green(), 等
樣式：.bold(), .underline(), .italic(), 等

以下是如何使用這些函式來修改 src/main.rs 檔案：

use colored::Colorize;

fn main() {
    let message = "A cat shouldn't bark like a dog.";
    let eye = "o";

    println!("{}", message.bright_yellow().underline().on_purple());
    println!(" \\");
    println!(" \\");
    println!(" /\\_/\\");
    println!(" ( {} {} )", eye.red().bold());
    println!(" =( I )=");
}

在這個範例中，message 的文字顏色被設定為亮黃色，並且加上了下劃線和紫色背景。同時，eye 的文字顏色被設定為紅色和粗體。

執行程式

最後，執行您的程式，觀察彩色的命令列輸出：

cargo run

這將會顯示一條彩色的文字訊息，包括黃色和紅色的文字，以及紫色背景。

讀取圖片檔案

在命令列應用程式中，讀取檔案是一種常見的操作。Cowsay 有一個 -f 選項，允許您傳入自訂的牛圖檔案。現在，您將實作一個簡化版本的這個功能，以學習如何在 Rust 中讀取檔案。

首先，新增一個選項，允許您指定圖片檔案的路徑：

#[derive(Parser)]
struct Options {
    // ...
    #[clap(short = 'f', long = "file")]
    /// 從指定的檔案載入圖片
    catfile: Option<std::path::PathBuf>,
}

這段程式碼中，有幾點需要注意：

在 #[clap(...)] 註解中，短選項 (-f) 和長選項 (--file) 的名稱與 Options 結構中的欄位名稱 (catfile) 不同。您可以使用使用者友好的名稱來命名選項和旗標，而保持變數名稱有意義。
在 Option<T> 中，我們使用 std::path::PathBuf 而不是原始字串。PathBuf 可以幫助我們更強壯地處理檔案路徑，因為它隱藏了許多作業系統在表示路徑方面的差異（例如，正斜線與反斜線）。
這個 catfile 選項是可選的，所以它被包裹在 Option<T> 中。如果該欄位沒有被提供，它將簡單地是 Option::None。注意，有其他選項型別，例如 Vec<T>，它代表了一個引數列表，而 u64 則表示了一個引數的發生次數，例如 -v、-vv 和 -vvv，它們常被用來設定詳細程度。

現在，如果您再次執行 cargo run -- --help，您應該會看到一個新的部分，稱為「選項」：

$ cargo run -- --help
...
用法：catsay [選項] [訊息]
引數：
  [訊息] 貓說什麼？ [預設： Meow!]
選項：
  -d, --dead 讓貓看起來像死了一樣
  -f, --file <CATFILE> 從指定的檔案載入圖片
  -h, --help 列印幫助

一旦您有了 --file 選項，您就可以在 main() 中讀取指定路徑的檔案，以載入外部檔案並渲染它。修改 src/main.rs 如下：

fn main() {
    // ...
    match &options.catfile {
        // ...
    }
}

在這裡，您需要完成 match 陳述式，以根據 catfile 選項的值來讀取檔案。您可以使用 std::fs::read_to_string 函式來讀取檔案的內容。

建立命令列程式

在這個章節中，我們將探討如何建立一個命令列程式。命令列程式是一種可以從終端機或命令提示符執行的程式，通常用於自動化任務或提供簡單的使用者介面。

讀取檔案內容

要建立一個命令列程式，首先需要讀取檔案內容。以下是如何使用 Rust 的 std::fs::read_to_string 函式讀取檔案內容的範例：

let cat_template = std::fs::read_to_string(path)
    .expect(&format!("could not read file {:?}", path));

這段程式碼會讀取指定路徑的檔案內容，並將其存入 cat_template 變數中。如果檔案不存在或無法讀取，程式會終止並顯示錯誤訊息。

替換佔位符

在上面的範例中，檔案內容中有一個佔位符 {eye}，需要被替換為實際的眼睛符號。由於 format! 宏需要在編譯時知道格式化字串，因此無法直接使用 format! 來替換佔位符。相反，需要使用 String.replace 函式來替換佔位符：

let eye = format!("{}", eye.red().bold());
let cat_picture = cat_template.replace("{eye}", &eye);

這段程式碼會將 {eye} 佔位符替換為實際的眼睛符號，並存入 cat_picture 變數中。

列印結果

最後，需要將結果列印到終端機。以下是如何使用 println! 宏列印結果的範例：

println!("{}", &cat_picture);

這段程式碼會將 cat_picture 變數的內容列印到終端機。

範例檔案

以下是範例檔案的內容：

\ 
\ / 
) 
( (__/

這個檔案包含了一個簡單的貓圖片，眼睛符號使用 {eye} 佔位符代表。

匹配陳述式

在上面的範例中，使用了 match 陳述式來檢查 options.catfile 是否為 Some(PathBuf) 或 None。如果是 None，就會列印預設的貓圖片。如果是 Some(PathBuf)，就會讀取檔案內容並替換佔位符。以下是 match 陳述式的範例：

match options.catfile {
    Some(path) => {
        // 讀取檔案內容並替換佔位符
    }
    None => {
        // 列印預設的貓圖片
    }
}

這個 match 陳述式會根據 options.catfile 的值來決定要執行哪一段程式碼。

錯誤處理機制

在開發指令列程式時，錯誤處理是一個非常重要的方面。到目前為止，我們一直使用 unwrap() 或 expect() 來處理可能失敗的函式。但是，這種方法並不理想，因為當 Result 傳回 Err 時，程式會直接當機，並且我們無法從錯誤中還原或提供更好的錯誤資訊。

使用 `?` 運運算元

為了改善錯誤處理，我們可以使用 ? 運運算元。這個運運算元可以讓我們在函式中輕鬆地處理錯誤。以下是如何使用 ? 運運算元的例子：

let cat_template = std::fs::read_to_string(path)?;

這行程式碼會在 read_to_string() 函式傳回 Err 時，直接傳回錯誤給呼叫者。這樣，我們就可以在呼叫者中處理錯誤。

修改 `main()` 函式簽名

但是，為了使用 ? 運運算元，我們需要修改 main() 函式的簽名。因為 main() 函式可能會傳回錯誤，所以我們需要指定傳回型別為 Result<(), Box<dyn std::error::Error>>。這個型別表示 main() 函式可能會傳回一個空的 Result，或者是一個包含錯誤資訊的 Box<dyn std::error::Error>。

以下是修改過的 main() 函式簽名：

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ...
}

在這個簽名中，() 代表空的 Result，而 Box<dyn std::error::Error> 代表包含錯誤資訊的 Box。這樣，我們就可以在 main() 函式中使用 ? 運運算元來處理錯誤。

完整的錯誤處理機制

現在，我們可以使用 ? 運運算元來處理錯誤，並且在 main() 函式中傳回錯誤給呼叫者。以下是完整的錯誤處理機制：

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let cat_template = std::fs::read_to_string(path)?;
    // ...
    Ok(())
}

在這個例子中，如果 read_to_string() 函式傳回 Err，則 main() 函式會直接傳回錯誤給呼叫者。如果 main() 函式執行成功，則會傳回 Ok(())。

圖表翻譯：

  graph LR
    A[main()] --> B[read_to_string()]
    B --> C[Ok()]
    B --> D[Err()]
    C --> E[傳回 Ok()]
    D --> F[傳回 Err()]
    F --> G[呼叫者處理錯誤]

這個圖表展示了錯誤處理機制的流程。如果 read_to_string() 函式傳回 Ok，則 main() 函式會傳回 Ok。如果 read_to_string() 函式傳回 Err，則 main() 函式會傳回 Err，並且呼叫者會處理錯誤。

建立命令列程式

在命令列程式中，錯誤處理是一個非常重要的部分。當使用者輸入錯誤的引數或檔案不存在時，程式應該能夠提供一個友善的錯誤訊息，以幫助使用者瞭解發生了什麼錯誤。

例如，當使用者執行以下命令時：

cargo run -- -f no/such/file.txt

程式應該會顯示一個錯誤訊息，指出檔案不存在：

Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }

但是，這個錯誤訊息對於使用者來說可能不是很友善。為了提供一個更友善的錯誤訊息，我們可以使用 anyhow crate。

首先，需要在 Cargo.toml 中新增 anyhow 依賴：

[dependencies]
anyhow = "1.0.70"

然後，需要在 main.rs 中匯入 anyhow 並使用 Context trait 來包裝原始錯誤：

use anyhow::{Context, Result};

fn main() -> Result<()> {
    // ...

    std::fs::read_to_string(path).with_context(|| format!("Could not read file {:?}", path))?;
    // ...
}

這樣，當檔案不存在時，程式會顯示一個更友善的錯誤訊息：

Error: Could not read file "no/such/file.txt"

這個錯誤訊息更容易讓使用者瞭解發生了什麼錯誤。

內容解密：

在上面的程式碼中，with_context 函式被用來包裝原始錯誤。這個函式會傳回一個新的 Result，其中包含原始錯誤和一個額外的上下文訊息。這個上下文訊息可以用來提供一個更友善的錯誤訊息給使用者。

圖表翻譯：

以下是程式碼的流程圖：

  flowchart TD
    A[開始] --> B[讀取檔案]
    B --> C[檔案不存在]
    C --> D[顯示錯誤訊息]
    D --> E[結束]

這個流程圖顯示了程式的執行流程。當檔案不存在時，程式會顯示一個錯誤訊息給使用者。

命令列工具開發：錯誤處理和管道輸出

在命令列工具開發中，錯誤處理和管道輸出是兩個非常重要的方面。錯誤處理可以幫助我們更好地處理程式中的錯誤，而管道輸出可以讓我們將工具的輸出傳遞給其他工具，從而實作工具之間的協同工作。

錯誤處理

錯誤處理是命令列工具開發中的一個關鍵方面。好的錯誤處理可以幫助使用者快速地瞭解錯誤的原因和解決方法。在Rust中，我們可以使用Result型別來處理錯誤。Result型別是一個列舉型別，它可以代表兩種可能的結果：Ok和Err。Ok代表成功的結果，而Err代表失敗的結果。

use std::io;

fn read_file(filename: &str) -> Result<String, io::Error> {
    let contents = std::fs::read_to_string(filename)?;
    Ok(contents)
}

在上面的例子中，read_file函式傳回一個Result型別的值。如果檔案讀取成功，則傳回Ok，否則傳回Err。

使用anyhow crate進行錯誤處理

anyhow crate是一個Rust的錯誤處理函式庫，它提供了一個簡單的方式來處理錯誤。使用anyhow crate，我們可以將錯誤轉換為一個統一的錯誤型別，並且可以輕鬆地新增錯誤的上下文資訊。

use anyhow::{Context, Result};

fn read_file(filename: &str) -> Result<String> {
    let contents = std::fs::read_to_string(filename).context("could not read file")?;
    Ok(contents)
}

在上面的例子中，read_file函式傳回一個Result型別的值。如果檔案讀取失敗，則傳回一個錯誤資訊，包括檔名稱和錯誤原因。

管道輸出

管道輸出是命令列工具開發中的另一個重要方面。管道輸出可以讓我們將工具的輸出傳遞給其他工具，從而實作工具之間的協同工作。

cargo run > output.txt

在上面的例子中，cargo run的輸出被重定向到output.txt檔案中。

NO_COLOR環境變數

NO_COLOR環境變數是一個非正式的標準，用於控制命令列工具的顏色輸出。如果設定NO_COLOR環境變數為1，則命令列工具將不會輸出顏色。

NO_COLOR=1 cargo run

在上面的例子中，cargo run的輸出不會包含顏色。

命令列程式開發：從 STDIN 讀取輸入

在命令列程式開發中，能夠從 STDIN 讀取輸入是一個重要的功能，讓程式能夠與其他程式進行互動。下面我們將探討如何修改程式，使其能夠從 STDIN 讀取輸入。

修改程式結構

首先，我們需要修改 Options 結構體，加入一個布林值欄位 stdin，用於指示是否從 STDIN 讀取輸入。

#[derive(Parser)]
struct Options {
    // ...
    #[clap(short = 'i', long = "stdin")]
    /// Read the message from STDIN instead of the argument
    stdin: bool,
}

接下來，我們需要修改 main 函式，當 options.stdin 為 true 時，從 STDIN 讀取輸入。

fn main() -> Result<()> {
    let options = Options::parse();

    let mut message = String::new();

    if options.stdin {
        io::stdin().read_to_string(&mut message)?;
    } else {
        message = options.message;
    }

    // ...
}

在上面的程式碼中，我們使用 io::stdin() 函式從 STDIN 讀取輸入，並將其儲存在 message 變數中。

測試程式

現在，我們可以使用 echo 命令將輸入匯入程式中。

$ echo -n "Hello World" | cargo run -- --stdin

這將輸出：

Meow!
\
\

/\_/\

( o o )

=( I )=

這表明程式已經成功從 STDIN 讀取輸入。

整合測試

整合測試是確保程式正確執行的重要步驟。下面我們將探討如何撰寫整合測試。

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

    #[test]
    fn test_stdin() {
        // ...
    }
}

在上面的程式碼中，我們定義了一個測試模組 tests，其中包含一個測試函式 test_stdin。這個函式將測試程式從 STDIN 讀取輸入的功能。

建立命令列程式

測試命令列程式通常涉及執行命令，然後驗證其傳回碼和 STDOUT/STDERR 輸出。這可以很容易地使用 Rust 的單元測試框架來完成。但是，撰寫 shell 指令碼意味著您需要實作自己的斷言和測試結果彙總和報告。幸運的是，Rust 的 std::process::Command 結構和 assert_cmd 函式函式庫可以幫助您測試程式。

首先，執行以下命令新增新的函式函式庫：

$ cargo add assert_cmd

然後，更新您的 Cargo.toml 檔案以包含新的依賴：

[package]
name = "catsay"
version = "0.1.0"
edition = "2021"

[dependencies]
// ...
assert_cmd = "2.0.10"

接下來，建立一個名為 tests 的資料夾在您的專案根目錄中，以存放測試。然後，建立一個名為 integration_test.rs 的檔案，並將以下程式碼貼入其中：

// tests/integration_test.rs
use std::process::Command; // 執行程式
use assert_cmd::prelude::*; // 新增方法於命令

#[test]
fn run_with_defaults() {
    Command::cargo_bin("catsay")
        .expect("binary exists")
        .assert()
        .success();
}

這個測試程式使用 Command::cargo_bin 方法執行 catsay 程式，然後使用 assert 方法驗證其傳回碼和輸出。 success 方法確認程式執行成功。

執行測試

您可以使用以下命令執行測試：

$ cargo test

這將執行所有測試，包括 run_with_defaults 測試。如果測試透過，您將看到成功的訊息。

新增更多測試

您可以新增更多測試以驗證您的程式的不同行為。例如，您可以測試程式的錯誤處理或輸出格式。只要建立新的測試函式，並使用 assert_cmd 函式函式庫來驗證您的程式的行為。

建立命令列程式

在建立命令列程式時，需要使用多個模組來輔助程式的開發。在這個例子中，我們使用了 std::process::Command 和 assert_cmd::prelude::* 模組。std::process::Command 提供了一個 Command 結構體，可以用來在新的程式中執行程式。assert_cmd::prelude::* 模組則匯入了一些有用的特性，延伸了 Command 來使其更適合於整合測試。

測試程式

在測試函式 run_with_defaults() 中，我們首先使用 Command::cargo_bin() 初始化命令。這個函式需要一個 cargo 建立的二進位制名稱，在這個例子中是 “catsay”。如果二進位制檔案不存在，則會傳回一個錯誤。因此，我們需要使用 .expect() 來解封裝它。然後，我們在命令上呼叫 assert()，這會產生一個 Assert 結構體。Assert 結構體提供了多種工具函式，來斷言命令的狀態和輸出。在這個例子中，我們使用了一個基本的斷言 `success()，來檢查命令是否成功執行。

執行測試

您可以使用以下命令執行測試：

$ cargo test

這將會編譯和執行測試程式，並輸出測試結果。

驗證輸出

在測試中，我們不僅要驗證命令是否成功執行，還要驗證其輸出是否正確。當您執行 catsay 程式時，它會輸出一隻貓說 “Meow!"。因此，我們可以驗證輸出中是否包含 “Meow!” 字串。為了做到這一點，我們可以使用 assert_cmd 的 stdout() 函式來取得命令的標準輸出。然後，我們可以使用 predicates 函式函式庫來驗證輸出是否包含 “Meow!"。

從使用者經驗視角來看，一個優秀的命令列程式不僅需要功能完善，更需要提供友善的使用者介面和錯誤處理機制。本文深入探討瞭如何使用 Rust 的 clap、colored、anyhow 和 assert_cmd 等函式函式庫構建一個功能豐富、使用者友善且易於測試的命令列程式。分析了從解析命令列引數、讀取檔案和標準輸入、彩色輸出、錯誤處理到整合測試的完整流程，並闡述瞭如何利用 std::process::Command 模組和 ? 運運算元簡化錯誤處理流程。同時，本文也強調了使用 anyhow 函式函式庫提供更友善的錯誤訊息的重要性，以及利用 assert_cmd 函式函式庫簡化整合測試流程的優勢。展望未來，隨著 Rust 生態系統的持續發展，更多便捷的函式函式庫和工具將湧現，進一步降低命令列程式開發的門檻，並提升使用者經驗。對於開發者而言，持續學習和應用這些新工具，將有助於打造更強大、更易用的命令列程式。玄貓認為，Rust 在命令列程式開發領域展現出巨大的潛力，值得開發者深入研究和應用。

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。

Rust 命令列程式開發：錯誤處理與輸出控制

錯誤處理：使用布林值旗標

輸出到STDERR

測試輸出

命令列程式設計：使用 Rust 和 Colored 函式庫

安裝 Colored 函式庫

使用 Colored 函式庫

執行程式

讀取圖片檔案

建立命令列程式

讀取檔案內容

替換佔位符

列印結果

範例檔案

匹配陳述式

錯誤處理機制

使用 ? 運運算元

修改 main() 函式簽名

完整的錯誤處理機制

圖表翻譯：

建立命令列程式

內容解密：

圖表翻譯：

命令列工具開發：錯誤處理和管道輸出

錯誤處理

使用anyhow crate進行錯誤處理

管道輸出

NO_COLOR環境變數

命令列程式開發：從 STDIN 讀取輸入

修改程式結構

測試程式

整合測試

建立命令列程式

執行測試

新增更多測試

建立命令列程式

測試程式

執行測試

驗證輸出

玄貓

使用 `?` 運運算元

修改 `main()` 函式簽名