// Copyright 2017 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//! Handles argument parsing.
//!
//! # Example
//!
//! ```
//! const ARGUMENTS: &'static [Argument] = &[
//! Argument::positional("FILES", "files to operate on"),
//! Argument::short_value('p', "program", "PROGRAM", "Program to apply to each file"),
//! Argument::short_value('c', "cpus", "N", "Number of CPUs to use. (default: 1)"),
//! Argument::flag("unmount", "Unmount the root"),
//! Argument::short_flag('h', "help", "Print help message."),
//! ];
//!
//! let match_res = set_arguments(args, ARGUMENTS, |name, value| {
//! match name {
//! "" => println!("positional arg! {}", value.unwrap()),
//! "program" => println!("gonna use program {}", value.unwrap()),
//! "cpus" => {
//! let v: u32 = value.unwrap().parse().map_err(|_| {
//! Error::InvalidValue {
//! value: value.unwrap().to_owned(),
//! expected: "this value for `cpus` needs to be integer",
//! }
//! })?;
//! }
//! "unmount" => println!("gonna unmount"),
//! "help" => return Err(Error::PrintHelp),
//! _ => unreachable!(),
//! }
//! }
//!
//! match match_res {
//! Ok(_) => println!("running with settings"),
//! Err(Error::PrintHelp) => print_help("best_program", "FILES", ARGUMENTS),
//! Err(e) => println!("{}", e),
//! }
//! ```
use std::fmt;
use std::result;
/// An error with argument parsing.
pub enum Error {
/// There was a syntax error with the argument.
Syntax(String),
/// The argumen's name is unused.
UnknownArgument(String),
/// The argument was required.
ExpectedArgument(String),
/// The argument's given value is invalid.
InvalidValue {
value: String,
expected: &'static str,
},
/// The argument was already given and none more are expected.
TooManyArguments(String),
/// The argument expects a value.
ExpectedValue(String),
/// The help information was requested
PrintHelp,
}
impl fmt::Display for Error {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
&Error::Syntax(ref s) => write!(f, "syntax error: {}", s),
&Error::UnknownArgument(ref s) => write!(f, "unknown argument: {}", s),
&Error::ExpectedArgument(ref s) => write!(f, "expected argument: {}", s),
&Error::InvalidValue {
ref value,
expected,
} => write!(f, "invalid value {:?}: {}", value, expected),
&Error::TooManyArguments(ref s) => write!(f, "too many arguments: {}", s),
&Error::ExpectedValue(ref s) => write!(f, "expected parameter value: {}", s),
&Error::PrintHelp => write!(f, "help was requested"),
}
}
}
/// Result of a argument parsing.
pub type Result<T> = result::Result<T, Error>;
/// Information about an argument expected from the command line.
///
/// # Examples
///
/// To indicate a flag style argument:
///
/// ```
/// Argument::short_flag('f', "flag", "enable awesome mode")
/// ```
///
/// To indicate a parameter style argument that expects a value:
///
/// ```
/// // "VALUE" and "NETMASK" are placeholder values displayed in the help message for these
/// // arguments.
/// Argument::short_value('v', "val", "VALUE", "how much do you value this usage information")
/// Argument::value("netmask", "NETMASK", "hides your netface")
/// ```
///
/// To indicate an argument with no short version:
///
/// ```
/// Argument::flag("verbose", "this option is hard to type quickly")
/// ```
///
/// To indicate a positional argument:
///
/// ```
/// Argument::positional("VALUES", "these are positional arguments")
/// ```
#[derive(Default)]
pub struct Argument {
/// The name of the value to display in the usage information. Use None to indicate that there
/// is no value expected for this argument.
pub value: Option<&'static str>,
/// Optional single character shortened argument name.
pub short: Option<char>,
/// The long name of this argument.
pub long: &'static str,
/// Helpfuly usage information for this argument to display to the user.
pub help: &'static str,
}
impl Argument {
pub fn positional(value: &'static str, help: &'static str) -> Argument {
Argument {
value: Some(value),
long: "",
help: help,
..Default::default()
}
}
pub fn value(long: &'static str, value: &'static str, help: &'static str) -> Argument {
Argument {
value: Some(value),
long: long,
help: help,
..Default::default()
}
}
pub fn short_value(short: char,
long: &'static str,
value: &'static str,
help: &'static str)
-> Argument {
Argument {
value: Some(value),
short: Some(short),
long: long,
help: help,
}
}
pub fn flag(long: &'static str, help: &'static str) -> Argument {
Argument {
long: long,
help: help,
..Default::default()
}
}
pub fn short_flag(short: char, long: &'static str, help: &'static str) -> Argument {
Argument {
short: Some(short),
long: long,
help: help,
..Default::default()
}
}
}
fn parse_arguments<I, R, F>(args: I, mut f: F) -> Result<()>
where I: Iterator<Item = R>,
R: AsRef<str>,
F: FnMut(&str, Option<&str>) -> Result<()>
{
enum State {
// Initial state at the start and after finishing a single argument/value.
Top,
// The remaining arguments are all positional.
Positional,
// The next string is the value for the argument `name`.
Value { name: String },
}
let mut s = State::Top;
for arg in args {
let arg = arg.as_ref();
s = match s {
State::Top => {
if arg == "--" {
State::Positional
} else if arg.starts_with("--") {
let param = arg.trim_left_matches('-');
if param.contains('=') {
let mut iter = param.splitn(2, '=');
let name = iter.next().unwrap();
let value = iter.next().unwrap();
if name.is_empty() {
return Err(Error::Syntax("expected parameter name before `=`"
.to_owned()));
}
if value.is_empty() {
return Err(Error::Syntax("expected parameter value after `=`"
.to_owned()));
}
f(name, Some(value))?;
State::Top
} else {
if let Err(e) = f(param, None) {
if let Error::ExpectedValue(_) = e {
State::Value { name: param.to_owned() }
} else {
return Err(e);
}
} else {
State::Top
}
}
} else if arg.starts_with("-") {
if arg.len() == 1 {
return Err(Error::Syntax("expected argument short name after `-`"
.to_owned()));
}
let name = &arg[1..2];
let value = if arg.len() > 2 { Some(&arg[2..]) } else { None };
if let Err(e) = f(name, value) {
if let Error::ExpectedValue(_) = e {
State::Value { name: name.to_owned() }
} else {
return Err(e);
}
} else {
State::Top
}
} else {
f("", Some(&arg))?;
State::Positional
}
}
State::Positional => {
f("", Some(&arg))?;
State::Positional
}
State::Value { name } => {
f(&name, Some(&arg))?;
State::Top
}
};
}
Ok(())
}
/// Parses the given `args` against the list of know arguments `arg_list` and calls `f` with each
/// present argument and value if required.
///
/// This function guarantees that only valid long argument names from `arg_list` are sent to the
/// callback `f`. It is also guaranteed that if an arg requires a value (i.e.
/// `arg.value.is_some()`), the value will be `Some` in the callbacks arguments. If the callback
/// returns `Err`, this function will end parsing and return that `Err`.
///
/// See the [module level](index.html) example for a usage example.
pub fn set_arguments<I, R, F>(args: I, arg_list: &[Argument], mut f: F) -> Result<()>
where I: Iterator<Item = R>,
R: AsRef<str>,
F: FnMut(&str, Option<&str>) -> Result<()>
{
parse_arguments(args, |name, value| {
let mut matches = None;
for arg in arg_list {
if let Some(short) = arg.short {
if name.len() == 1 && name.starts_with(short) {
if value.is_some() != arg.value.is_some() {
return Err(Error::ExpectedValue(short.to_string()));
}
matches = Some(arg.long);
}
}
if matches.is_none() && arg.long == name {
if value.is_some() != arg.value.is_some() {
return Err(Error::ExpectedValue(arg.long.to_owned()));
}
matches = Some(arg.long);
}
}
match matches {
Some(long) => f(long, value),
None => Err(Error::UnknownArgument(name.to_owned())),
}
})
}
/// Prints command line usage information to stdout.
///
/// Usage information is printed according to the help fields in `args` with a leading usage line.
/// The usage line is of the format "`program_name` [ARGUMENTS] `required_arg`".
pub fn print_help(program_name: &str, required_arg: &str, args: &[Argument]) {
println!("Usage: {} {}{}\n",
program_name,
if args.is_empty() { "" } else { "[ARGUMENTS] " },
required_arg);
if args.is_empty() {
return;
}
println!("Argument{}:", if args.len() > 1 { "s" } else { "" });
for arg in args {
match arg.short {
Some(ref s) => print!(" -{}, ", s),
None => print!(" "),
}
if arg.long.is_empty() {
print!(" ");
} else {
print!("--");
}
print!("{:<12}", arg.long);
if let Some(v) = arg.value {
if arg.long.is_empty() {
print!(" ");
} else {
print!("=");
}
print!("{:<10}", v);
} else {
print!("{:<11}", "");
}
println!("{}", arg.help);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_help() {
let arguments = [Argument::short_flag('h', "help", "Print help message.")];
let match_res = set_arguments(["-h"].iter(), &arguments[..], |name, _| {
match name {
"help" => return Err(Error::PrintHelp),
_ => unreachable!(),
};
});
match match_res {
Err(Error::PrintHelp) => {}
_ => unreachable!(),
}
}
#[test]
fn mixed_args() {
let arguments =
[Argument::positional("FILES", "files to operate on"),
Argument::short_value('p', "program", "PROGRAM", "Program to apply to each file"),
Argument::short_value('c', "cpus", "N", "Number of CPUs to use. (default: 1)"),
Argument::flag("unmount", "Unmount the root"),
Argument::short_flag('h', "help", "Print help message.")];
let mut unmount = false;
let match_res = set_arguments(["--cpus", "3", "--program", "hello", "--unmount", "file"]
.iter(),
&arguments[..],
|name, value| {
match name {
"" => assert_eq!(value.unwrap(), "file"),
"program" => assert_eq!(value.unwrap(), "hello"),
"cpus" => {
let c: u32 = value
.unwrap()
.parse()
.map_err(|_| {
Error::InvalidValue {
value: value.unwrap().to_owned(),
expected: "this value for `cpus` needs to be integer",
}
})?;
assert_eq!(c, 3);
}
"unmount" => unmount = true,
"help" => return Err(Error::PrintHelp),
_ => unreachable!(),
};
Ok(())
});
assert!(match_res.is_ok());
assert!(unmount);
}
#[test]
fn name_value_pair() {
let arguments =
[Argument::short_value('c', "cpus", "N", "Number of CPUs to use. (default: 1)")];
let match_res = set_arguments(["-c", "5", "--cpus", "5", "-c5", "--cpus=5"].iter(),
&arguments[..],
|name, value| {
assert_eq!(name, "cpus");
assert_eq!(value, Some("5"));
Ok(())
});
assert!(match_res.is_ok());
}
}