"内置电池" 的序言，包含编写命令行界面工具和快速脚本的有用 crate、类型和函数。

这个序言旨在在 CLI 工具的通用环境中发挥作用，并尽量减少依赖。

适合这个序言的内容

• 参数解析，
• 日志记录，
• I/O 包括从 stdin 读取，
• 常见的文件操作和目录结构，
• 执行命令，
• stdlib 和语言功能的扩展，
• 摘要和校验和，
• 时间和持续时间
• 常用 stdlib 导入。

不包括的内容

• JSON 解析器或其他格式，
• HTTP 客户端或特定 API 客户端
• TLS 或其他加密库。

lib.rs:

"内置电池" 的序言，包含编写命令行界面工具和快速脚本的有用 crate、类型和函数。

这个序言旨在在 CLI 工具的通用环境中发挥作用，并尽量减少依赖。

基本的命令行界面程序模板

示例起始点，程序包含带帮助消息的命令行参数解析、日志设置和人性化的错误和 panic 消息。

use cotton::prelude::*;

/// Example script description
#[derive(Parser)]
struct Cli {
#[command(flatten)]
logging: ArgsLogger,

#[command(flatten)]
dry_run: ArgsDryRun,
}

fn main() -> FinalResult {
let Cli {
logging,
dry_run,
} = Cli::parse();
setup_logger(logging, vec![module_path!()]);

if !dry_run.enabled {
warn!("Hello world!");
}

Ok(())
}

功能

cotton 中总是包含一小批 crate。这些 crate 添加了一些常见的数据类型、语言可用性辅助工具和常见的标准库导入

• itertools - 扩展标准迭代器
• linked-hash-map 和 linked-hash_set - 有序映射和集合
• maybe-string - 处理可能是 UTF-8 编码的二进制数据
• boolinator - 将 [Option] 转换为 [bool]
• tap - 避免需要 let 绑定

Cotton 还总是导入大量常用标准库项。

所有其他依赖项都是可选的，可以通过禁用默认功能并选择仅选中 crate 来选择退出。

为了方便，已定义了功能来分组多个 crate

• regex - 正则表达式
• regex - Rust 的正则表达式实现
• args - 命令行参数解析
• clap - 简单易用、高效、功能齐全的命令行参数解析器
• logging - 日志宏和记录器
• log - Rust的轻量级日志门面
• stderrlog - 根据指定的详细程度将日志输出到stderr的日志记录器
• time - 时间和日期
• chrono - Rust的日期和时间库
• term - 与终端模拟器一起工作
• ansi_term - 用于ANSI终端颜色和样式的库（粗体，下划线）
• atty - 一个简单的查询atty的接口
• zzz - 带有合理默认值的快速进度条
• term_size - 确定终端大小和维度的函数
• hashing - 摘要计算和十六进制编码
• hex - 将数据编码和解码为十六进制表示形式
• sha2 - SHA-2哈希函数家族的纯Rust实现
• digest - 加密哈希函数和消息认证码的特质
• files - 文件元数据和临时文件
• tempfile - 用于管理临时文件和目录的库
• filetime - 在文件元数据中对时间戳的平台无关访问器
• file-mode - 解码Unix文件模式位，更改它们并将它们应用于文件
• file-owner - 设置和获取Unix文件所有者和组
• signals - UNIX信号处理
• signal-hook - Unix信号处理
• uninterruptible - 保留所选Unix信号抑制的守卫类型
• errors - 灵活的错误处理和错误上下文
• problem - 命令行应用程序或原型的错误处理
• error-context - 帮助将附加上下文信息添加到错误类型的方法和类型
• scopeguard - 当它超出作用域时将运行给定闭包的RAII作用域守卫
• assert_matches - 断言值匹配模式
• app - 应用程序环境
• directories - 一个小型中级库，提供特定平台的目录标准位置
• process - 运行程序和处理输入/输出
• shellwords - 根据UNIX Bourne shell的单词解析规则操作字符串
• exec - 使用POSIX exec函数用另一个程序替换正在运行的程序
• mkargs - 构建命令参数
• cradle - 轻松执行子进程

非默认功能

• backtrace - 为problem::Problem错误启用回溯（也可以运行程序时使用RUST_BACKTRACE=1）

例如，您可以在Cargo.toml中这样包含cotton

cotton = { version = "0.1.0", default-features = false, features = ["errors", "args", "logging", "app", "hashing", "process"] }

错误上下文

通常库不应该将上下文添加到错误中，因为它可能被认为对某些用途来说是敏感的。在此库中，默认提供上下文（如文件路径）。

静态错误类型

当您需要适当的错误处理（例如在内部模块中或需要特别处理错误时）时，请使用标准方法。

使用与 Debug、Display 和 Error 特性实现相关的枚举。添加额外的 From 实现以使 ? 操作符正常工作。

如果您需要向错误添加上下文，可以使用预定义的 error-context 包。

示例自定义静态错误类型实现

use cotton::prelude::*;

#[derive(Debug)]
enum FileResourceError {
FileDigestError(PathBuf, FileDigestError),
NotAFileError(PathBuf),
}

impl Display for FileResourceError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
// Do not include chained error message in the message; let the client handle this (e.g. with Problem type)
FileResourceError::FileDigestError(path, _) => write!(f, "digest of a file {:?} could not be calculated", path),
FileResourceError::NotAFileError(path) => write!(f, "path {:?} is not a file", path),
}
}
}

impl Error for FileResourceError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
// Chain the internal error
FileResourceError::FileDigestError(_, err) => Some(err),
FileResourceError::NotAFileError(_) => None,
}
}
}

// This allows for calls like `foo().wrap_error_while_with(|| self.path.clone())?` to add extra `PathBuf` context to the error
impl From<ErrorContext<FileDigestError, PathBuf>> for FileResourceError {
fn from(err: ErrorContext<FileDigestError, PathBuf>) -> FileResourceError {
FileResourceError::FileDigestError(err.context, err.error)
}
}