返回文章列表

用 Rust 从零实现 CLI 解析器:clap 到底替你做了什么

420 字·4 分钟阅读
Rust从零造轮子工具

clap 大概是 Rust 生态里最成功的库之一。但它太成功了,成功到很多人的 CLI 里藏着一堆自己没意识到的解析 bug。

这篇从零写一个参数解析器。目标不是替代 clap,而是把命令行解析里真正麻烦的边界情况摆出来。


命令行的语法比你想的复杂

先看几条人人都在用、但很少想过规则的写法:

git commit -am "fix"        # -a 和 -m 合并,且 m 后跟值
curl -o out.txt -L url      # 不同选项的取参方式
ls --color=auto -l          # 长选项用 = 传值
grep -- -foo file           # -- 之后全是位置参数
rm -rf -file                # -file 是选项 f,i,l,e 还是位置参数?
redis-cli -p -6379          # 负数端口?

最后两条就是经典分歧点。 GNU 风格的约定是:

  • -file 视为 -f -i -l -e(短选项合并)
  • -6379 视为值,因为数字开头的参数不作为选项

这篇要实现的就是这个语义。

先定义要解析成什么

解析结果需要包含:选项的值、位置参数、以及"是否出现过"。

use std::collections::HashMap;
 
#[derive(Debug, Default)]
pub struct Matches {
    flags: HashMap<String, usize>,      // 布尔开关,记录出现次数
    options: HashMap<String, Vec<String>>, // 带值的选项
    positionals: Vec<String>,
}
 
impl Matches {
    pub fn contains(&self, name: &str) -> bool {
        self.flags.contains_key(name) || self.options.contains_key(name)
    }
 
    pub fn get_one(&self, name: &str) -> Option<&str> {
        self.options.get(name)?.last().map(|s| s.as_str())
    }
 
    pub fn get_many(&self, name: &str) -> &[String] {
        self.options.get(name).map(|v| v.as_slice()).unwrap_or(&[])
    }
}

用 Vec<String> 存选项值而不是单个 String,是为了支持 -v -v -v 这种重复出现的写法。

描述参数:一个小的规格结构

#[derive(Clone)]
pub struct ArgSpec {
    pub name: &'static str,
    pub short: Option<char>,
    pub long: Option<&'static str>,
    pub takes_value: bool,
    pub multiple: bool,
}
 
pub struct Command {
    args: Vec<ArgSpec>,
    allow_positionals: bool,
}
 
impl Command {
    pub fn flag(name: &'static str, short: char, long: &'static str) -> ArgSpec {
        ArgSpec { name, short: Some(short), long: Some(long), takes_value: false, multiple: false }
    }
 
    pub fn option(name: &'static str, short: char, long: &'static str) -> ArgSpec {
        ArgSpec { name, short: Some(short), long: Some(long), takes_value: true, multiple: false }
    }
 
    pub fn new(args: Vec<ArgSpec>) -> Self {
        Self { args, allow_positionals: true }
    }
}

核心解析循环

pub fn parse(cmd: &Command, argv: &[String]) -> Result<Matches, ParseError> {
    let mut m = Matches::default();
    let mut i = 0;
    let mut only_positionals = false; // -- 之后的都当位置参数
 
    while i < argv.len() {
        let arg = &argv[i];
 
        // 1. 处理 -- 分隔符
        if arg == "--" {
            only_positionals = true;
            i += 1;
            continue;
        }
 
        // 2. 判断是选项还是位置参数
        let is_option = !only_positionals && arg.starts_with('-') && arg != "-";
 
        if !is_option {
            m.positionals.push(arg.clone());
            i += 1;
            continue;
        }
 
        // 3. 长选项 --name / --name=value
        if let Some(rest) = arg.strip_prefix("--") {
            i = parse_long(cmd, rest, argv, i, &mut m)?;
            continue;
        }
 
        // 4. 短选项 -a / -abc / -o value / -ovalue
        let rest = &arg[1..];
        i = parse_short(cmd, rest, argv, i, &mut m)?;
    }
 
    Ok(m)
}

-- 的处理是最容易被忽略、也最容易出安全问题的:当一个位置参数以 - 开头时(比如文件名 -foo),-- 是唯一能正确传它的方式。

对 rm 这类命令,忽略 -- 语义甚至可能造成误删——这也是很多 CLI 安全建议里强调"必须支持 --"的原因。

长选项:= 和空格两种取值方式

fn parse_long(
    cmd: &Command,
    rest: &str,
    argv: &[String],
    mut i: usize,
    m: &mut Matches,
) -> Result<usize, ParseError> {
    // 拆出名字和可能的内联值
    let (name, inline) = match rest.split_once('=') {
        Some((n, v)) => (n, Some(v.to_string())),
        None => (rest, None),
    };
 
    let spec = cmd
        .args
        .iter()
        .find(|a| a.long == Some(name))
        .ok_or_else(|| ParseError::UnknownOption(format!("--{name}")))?;
 
    if spec.takes_value {
        let value = match inline {
            Some(v) => v,
            None => {
                // 值在下一个 argv 里
                i += 1;
                argv.get(i)
                    .ok_or_else(|| ParseError::MissingValue(spec.name))?
                    .clone()
            }
        };
        m.options.entry(spec.name.to_string()).or_default().push(value);
    } else {
        if inline.is_some() {
            return Err(ParseError::UnexpectedValue(format!("--{name}")));
        }
        *m.flags.entry(spec.name.to_string()).or_default() += 1;
    }
 
    Ok(i + 1)
}

--flag=value 要报错。 布尔选项给值是无意义的,静默忽略会让用户以为设置生效了。

短选项:合并、取值、内联值

短选项是三个问题的叠加:

-a                单个标志
-abc              合并的三个标志
-o value          选项 + 下一个参数作为值
-ovalue           选项 + 内联值

处理方式是在一个 arg 内部从左往右扫:

fn parse_short(
    cmd: &Command,
    rest: &str,
    argv: &[String],
    mut i: usize,
    m: &mut Matches,
) -> Result<usize, ParseError> {
    let chars: Vec<char> = rest.chars().collect();
    let mut j = 0;
 
    while j < chars.len() {
        let c = chars[j];
        let spec = cmd
            .args
            .iter()
            .find(|a| a.short == Some(c))
            .ok_or_else(|| ParseError::UnknownOption(format!("-{c}")))?;
 
        if spec.takes_value {
            // 剩下的字符当成内联值
            let remainder: String = chars[j + 1..].iter().collect();
            let value = if !remainder.is_empty() {
                remainder
            } else {
                i += 1;
                argv.get(i)
                    .ok_or_else(|| ParseError::MissingValue(spec.name))?
                    .clone()
            };
 
            m.options.entry(spec.name.to_string()).or_default().push(value);
            return Ok(i + 1); // 值吃完,这个 arg 结束了
        }
 
        // 是标志,记录后继续扫下一个字符
        *m.flags.entry(spec.name.to_string()).or_default() += 1;
        j += 1;
    }
 
    Ok(i + 1)
}

两个细节:

  1. 碰到取值的选项就要立刻 return——因为剩下的字符都归它了(-ovalue)
  2. 值可能来自下一个 argv(-o value),所以 i 要加一

短选项合并的语义决定了:一个 - 开头的 arg 里,只有最后一个字符可能"挂"一个值。

负数怎么办

现在回到开头的 redis-cli -p -6379。当前代码会认为 -6379 是一个选项,然后报"未知选项 6"。

正确行为要看规则。 主流做法有两种:

方案 A:把"数字开头的短参数"当作值。

fn looks_like_negative_number(arg: &str) -> bool {
    arg.starts_with('-')
        && arg.len() > 1
        && arg[1..].chars().next().map_or(false, |c| c.is_ascii_digit())
}
 
// 在取值时:
let next = argv.get(i + 1);
if spec.takes_value {
    // 允许值是负数
}

方案 B:只有声明了 allow_hyphen_values 的选项才接受负数。 clap 走的就是这条路——默认不接负数,需要显式开启。

我偏向方案 B,因为它更明确:负数是不是值,是个语义问题,不该靠格式猜。

pub struct ArgSpec {
    // ...
    pub allow_hyphen_values: bool,
}

取值时判断:

    let candidate = argv.get(i + 1);
    let value = match candidate {
        Some(v) if !v.starts_with('-') || spec.allow_hyphen_values => v.clone(),
        Some(_) => return Err(ParseError::MissingValue(spec.name)),
        None => return Err(ParseError::MissingValue(spec.name)),
    };

这个坑在爬虫、数据处理类工具里特别常见——某个参数要传负数或 - 开头的字符串时,用户会发现怎么传都被当成选项。

子命令:分派问题

git commit、cargo build 这类结构,解析上其实不难:第一个位置参数如果是已注册的子命令,就把剩下的参数交给它的解析器。

enum Node {
    Command { cmd: Command, subcommands: HashMap<String, Node> },
    SubCommand { node: Box<Node> },
}

解析时:

    // 在 parse 循环里,遇到第一个位置参数时检查
    if !only_positionals && m.positionals.is_empty() {
        if let Some(sub) = subcommands.get(arg) {
            let rest = &argv[i + 1..];
            return dispatch(sub, rest); // 递归下去
        }
    }

关键点:子命令必须在"第一个位置参数"的位置匹配。 如果把它放到后面判断,mytool --verbose commit 和 mytool commit --verbose 的语义就不一致了。

help 输出:自动生成,别手写

解析器最重要的"用户界面"其实是 --help。手写 help 必然和代码脱节。

既然有 ArgSpec,直接生成:

pub fn render_help(cmd: &Command, bin: &str) -> String {
    let mut out = format!("Usage: {bin} [OPTIONS] [ARGS]\n\nOptions:\n");
 
    for arg in &cmd.args {
        let short = arg.short.map(|c| format!("-{c}")).unwrap_or_default();
        let long = arg.long.map(|l| format!("--{l}")).unwrap_or_default();
        let sep = if !short.is_empty() && !long.is_empty() { ", " } else { "  " };
        let value = if arg.takes_value { " <VALUE>" } else { "" };
 
        out.push_str(&format!("  {short}{sep}{long}{value}\n"));
    }
    out
}

输出:

Usage: mycli [OPTIONS] [ARGS]
 
Options:
  -v, --verbose
  -o, --output <VALUE>
  -p, --port <VALUE>

--help 必须是"零成本"的:用户敲错时看到的第一条信息就是它,信息不全的 help 等于没有。

解析顺序:什么时候检查必填项

一个容易写错的点:必填校验必须在全部参数解析完之后,不能边解析边校验。

pub fn validate(cmd: &Command, m: &Matches) -> Result<(), ParseError> {
    for arg in &cmd.required {
        if !m.contains(arg.name) {
            return Err(ParseError::MissingRequired(arg.name));
        }
    }
    Ok(())
}

因为 -v --port 8080 里,--port 出现在 -v 之后——如果边解析边校验"port 出现了吗",会在还没读到它的时候就报错。

解析和校验是两个阶段。先收集全部信息,再统一判断合法性。

结论

一个够用的 CLI 解析器,要处理的就这几件事:

-- 之后全当位置参数;长选项支持 --k=v;短选项要支持合并和内联值;- 开头的值(比如负数)要显式声明才接受;子命令在第一个位置参数处分派;help 从规格自动生成;必填校验放到最后统一做。

这几条也是 clap 帮你处理的事情。理解了它们,你在换语言写 CLI、或者遇到解析边界不对时,就知道该往哪个方向去查。