[TOC]
通过 clap3学习rust derive宏
tldr: 本文主要介绍了 clap3 的 builder api, derive api 的使用；然后通过 derive api 源码为例学习 derive macro；
clap一个用来编写cli app的 rust 库，主要用来解析命令行的参数；下面是一个使用 clap3 builder api的例子：
clap3 builder api example （V1)
use clap::{Arg, App, Parser};
fn main() {
let matches = App::new("Novice Program")
.version("1.0")
.author("cywang.master@gmail.com")
.arg(Arg::new("hostname")
.short('h')
.long("hostname")
.help("Server hostname")
.takes_value(true)
)
.arg(Arg::new("port")
.short('p')
.long("port")
.help("Server port (default: 6379)")
.default_value("6379")
.takes_value(true)
)
.arg(Arg::new("prod")
.long("prod")
.help("Active prod mode")
.takes_value(false)
)
.get_matches();
let hostname = matches.value_of("hostname").unwrap();
let port = matches.value_of("port").unwrap();
let prod = matches.is_present("prod");
println!("hostname={}, port={}, prod={}", hostname, port, prod);
}
通过 clap::builder::command::App::new() 初始化一个App struct; 最后调用 get_matches() 方法去解析命令行参数到App struct;
App struct 定义如下： （只展示了常用的部分字段）
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct App<'help> {
id: Id,
name: String,
author: Option<&'help str>,
version: Option<&'help str>,
usage_str: Option<&'help str>,
usage_name: Option<String>,
settings: AppFlags,
args: MKeyMap<'help>,
}
执行 cargo run -- --help 时显示结果如下图：
第一行是 name version；第二行是 author 信息；接下来是usage信息；最后的 OPTIONS 就是我们定义的args, --help, --version是clap默认定义的；
提升 builder api 的开发体验 (V2)
上面的builder api example已经能够把参数解析到App struct了, 但开发体验特别差；
试想一下你定义完args，合作开发的同伴还需要看上面的 Arg::new("name")...才能知道
该怎么使用你定义的args; 自然而然的一个提升开发体验的方法就是把所有定义的args放到
一个struct里面，同伴只需要使用实例化的struct就可以直接使用预先定义的args.
优化后的代码只是添加了一个 Config struct,然后手动从App args里面取值然后赋值给Config的成员；
use clap::{Arg, App, Parser};
#[derive(Debug)]
#[allow(dead_code)]
struct Config {
hostname: String,
port: String,
prod: bool,
}
fn main() {
let matches = App::new("Novice Program")
.version("1.0")
.author("cywang.master@gmail.com")
.arg(Arg::new("hostname")
.short('h')
.long("hostname")
.help("Server hostname")
.takes_value(true)
)
.arg(Arg::new("port")
.short('p')
.long("port")
.help("Server port (default: 6379)")
.default_value("6379")
.takes_value(true)
)
.arg(Arg::new("prod")
.long("prod")
.help("Active prod mode")
.takes_value(false)
)
.get_matches();
// let hostname = matches.value_of("hostname").unwrap();
// let port = matches.value_of("port").unwrap();
// let prod = matches.is_present("prod");
// println!("hostname={}, port={}, prod={}", hostname, port, prod);
let config = Config {
hostname: matches.value_of("hostname").unwrap().to_string(),
port: matches.value_of("port").unwrap().to_string(),
prod: matches.is_present("prod"),
};
println!("{:#?}", config)
}
使用 derive api 提升开发体验 (V3)
上面的写法太啰嗦了，定义args和定义struct是工作量的上的重复，从App struct取值手动赋值到Config也是一个很人肉的方法；于是就有了derive api来提升开发体验；代码如下：
use clap::{Arg, App, Parser};
#[derive(Debug, Parser)]
#[clap(version, author)]
struct DeriveConfig {
#[clap(short, long, help = "Server hostname")]
hostname: String,
#[clap(short, long, default_value = "6379", help = "Server port (default: 6379)")]
port: String,
#[clap(long, help = "Active prod mode")]
prod: bool,
}
fn main() {
let config: DeriveConfig = DeriveConfig::parse();
println!("{:#?}", config);
}
上面的代码非常简洁，怎么做到的呢？其实就是通过rust的 derive macro来实现上面V2版本中我们手动写的那堆builder api的代码；
上面的#[derive(Parser)] #[clap(long...)]... 相当于做了一些配置，用于编写derive宏时根据配置生成代码。
查看宏生成的代码
我们可以对 【使用 derive api 提升开发体验 (V3)】中的代码使用cargo expand 来查看rust 宏生成的代码；
这里有一个知识点，使用宏和手动解析赋值的性能完全一致，因为宏的代码生成发生在编译阶段；
通过宏代码查看整个解析赋值过程
main方法里面调用了parse方法，DeriveConfig::parse()，可以从宏生成代码里面发现这一行
impl clap::Parser for DeriveConfig {}
<span id="parse"></span>
这里给 DeriveConfig 实现了 Parser trait; 然后看看clap3源码的 parse()方法的默认实现如下：
fn parse() -> Self {
let mut matches = <Self as CommandFactory>::command().get_matches();
let res = <Self as FromArgMatches>::from_arg_matches_mut(&mut matches)
.map_err(format_error::<Self>);
match res {
Ok(s) => s,
Err(e) => {
// Since this is more of a development-time error, we aren't doing as fancy of a quit
// as `get_matches`
e.exit()
}
}
}
这里首先调用了clap::derive::CommandFactory的command方法，看看clap3的源码command方法的实现里面调用了自身的into_app方法
fn command<'help>() -> Command<'help> {
#[allow(deprecated)]
Self::into_app()
}
然后看derive宏生产的代码里面对into_app的实现
impl clap::CommandFactory for DeriveConfig {
fn into_app<'b>() -> clap::Command<'b> {
let __clap_app = clap::Command::new("clap3");
<Self as clap::Args>::augment_args(__clap_app)
}
fn into_app_for_update<'b>() -> clap::Command<'b> {
let __clap_app = clap::Command::new("clap3");
<Self as clap::Args>::augment_args_for_update(__clap_app)
}
}
into_app首先调用了clap::Command::new， 和我们builder api里面的App::new等价;
然后调用了augment_args方法，看看derive宏生产的augment_args方法
fn augment_args<'b>(__clap_app: clap::Command<'b>) -> clap::Command<'b> {
{
let __clap_app = __clap_app;
let __clap_app = __clap_app.arg({
#[allow(deprecated)]
let arg = clap::Arg::new("hostname")
.takes_value(true)
.value_name("HOSTNAME")
.required(true && clap::ArgAction::StoreValue.takes_values())
.validator(|s| ::std::str::FromStr::from_str(s).map(|_: String| ()))
.value_parser(clap::builder::ValueParser::string())
.action(clap::ArgAction::StoreValue);
let arg = arg.short('h').long("hostname").help("Server hostname");
arg
});
let __clap_app = __clap_app.arg({
#[allow(deprecated)]
let arg = clap::Arg::new("port")
.takes_value(true)
.value_name("PORT")
.required(false && clap::ArgAction::StoreValue.takes_values())
.validator(|s| ::std::str::FromStr::from_str(s).map(|_: String| ()))
.value_parser(clap::builder::ValueParser::string())
.action(clap::ArgAction::StoreValue);
let arg = arg
.short('p')
.long("port")
.default_value("6379")
.help("Server port (default: 6379)");
arg
});
let __clap_app = __clap_app.arg({
#[allow(deprecated)]
let arg = clap::Arg::new("prod").takes_value(false);
let arg = arg.long("prod").help("Active prod mode");
arg
});
__clap_app.version("0.1.0").author("gimmi7")
}
}
这段代码很熟悉把，就是我们通过builder api构造App struct时手动写的代码；
再看看 <a href="#parse">clap3源码的 parse()方法的默认实现</a>
执行完 command方法后和我们在 builder api 里面做的一样，调用get_matches()解析命令行参数；
按照我们优化版本的builder api，接下来需要做的事情，就是从App struct把arg取出来赋值给定义struct;
parse()方法接下来调用了 from_arg_matches_mut(&mut matches), 看看derive宏生成的from_arg_matches_mut；
fn from_arg_matches_mut(
__clap_arg_matches: &mut clap::ArgMatches,
) -> ::std::result::Result<Self, clap::Error> {
#![allow(deprecated)]
let v = DeriveConfig {
hostname: __clap_arg_matches
.get_one::<String>("hostname")
.map(|s| ::std::ops::Deref::deref(s))
.ok_or_else(|| {
clap::Error::raw(clap::ErrorKind::MissingRequiredArgument, {
let res = ::alloc::fmt::format(::core::fmt::Arguments::new_v1(
&["The following required argument was not provided: "],
&[::core::fmt::ArgumentV1::new_display(&"hostname")],
));
res
})
})
.and_then(|s| {
::std::str::FromStr::from_str(s).map_err(|err| {
clap::Error::raw(clap::ErrorKind::ValueValidation, {
let res = ::alloc::fmt::format(::core::fmt::Arguments::new_v1(
&["Invalid value for ", ": "],
&[
::core::fmt::ArgumentV1::new_display(&"hostname"),
::core::fmt::ArgumentV1::new_display(&err),
],
));
res
})
})
})?,
port: __clap_arg_matches
.get_one::<String>("port")
.map(|s| ::std::ops::Deref::deref(s))
.ok_or_else(|| {
clap::Error::raw(clap::ErrorKind::MissingRequiredArgument, {
let res = ::alloc::fmt::format(::core::fmt::Arguments::new_v1(
&["The following required argument was not provided: "],
&[::core::fmt::ArgumentV1::new_display(&"port")],
));
res
})
})
.and_then(|s| {
::std::str::FromStr::from_str(s).map_err(|err| {
clap::Error::raw(clap::ErrorKind::ValueValidation, {
let res = ::alloc::fmt::format(::core::fmt::Arguments::new_v1(
&["Invalid value for ", ": "],
&[
::core::fmt::ArgumentV1::new_display(&"port"),
::core::fmt::ArgumentV1::new_display(&err),
],
));
res
})
})
})?,
prod: ::std::convert::From::from(__clap_arg_matches.is_present("prod")),
};
::std::result::Result::Ok(v)
}
这段代码还是很熟悉把，就是我们在优化版本的 builder api 实现里面从 matches 取出args赋值到定义的struct的过程；
至此，clap3 derive宏做了生么事情已经完全清晰了，接下来我们就要看看怎么利用derive宏来实现自动生成这些代码；
首先是clap::Parse的proc_macro_derive定义;将TokenStream解析为AST（abstract syntax tree),然后调用derives::derive_parser(&input),生成代码
#[proc_macro_derive(Parser, attributes(clap, structopt))]
#[proc_macro_error]
pub fn parser(input: TokenStream) -> TokenStream {
let input: DeriveInput = parse_macro_input!(input);
derives::derive_parser(&input).into()
}
derive_parse主要调用了 gen_for_struct 方法
fn gen_for_struct(
name: &Ident,
generics: &Generics,
fields: &Punctuated<Field, Comma>,
attrs: &[Attribute],
) -> TokenStream {
let into_app = into_app::gen_for_struct(name, generics, attrs);
let args = args::gen_for_struct(name, generics, fields, attrs);
let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
quote! {
impl #impl_generics clap::Parser for #name #ty_generics #where_clause {}
#into_app
#args
}
}
let into_app = into_app::gen_for_struct(name, generics, attrs);生成了 clap::CommandFactory::into_app()的代码；
let args = args::gen_for_struct(name, generics, fields, attrs);生成了 clap::FromArgMatches::from_arg_matches_mut()以及clap::Args::augment_args的代码；
生成代码的逻辑其实就是根据我们定义的struct的 fields 以及在每个filed上面写的clap attribute,来构造App struct 以及为我们自定义的 struct 赋值；
整个宏的编写过程就是： 从TokenStream -> 通过syn::parse解析得到 AST -> 根据AST编写需要生成的rust代码 -> 通过 quote::quote!(rust代码) 将rust代码转换成TokenStream;
当然这里面的难点在于没有一个足够好用的IDE能够在编写宏代码时自动提示，自动补全，所以编写宏的过程开发体验不会太好。
好处当然就很大了，就像clap derive api,可以把一个50多行的代码压缩到20行解决，如果你自定义的命令行参数越多，压缩比也会越高。
