用 Rust 从零实现 CLI 解析器:clap 到底替你做了什么
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)
}两个细节:
- 碰到取值的选项就要立刻
return——因为剩下的字符都归它了(-ovalue) - 值可能来自下一个 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、或者遇到解析边界不对时,就知道该往哪个方向去查。