[][src]Crate simon

Simon (an Arg Functor)

A library for declaratively specifying and parsing command-line arguments.

Toy Example

extern crate simon;

let (name, age): (String, u8) =
    simon::opt_required("n", "name", "your name", "NAME")
       .both(
          simon::opt("a", "age", "your age", "NUM")
             .with_default(42)
       )
       .just_parse(&["--name", "Stephen", "-a", "26"])
       .expect("Invalid command line argument");

assert_eq!(name, "Stephen");
assert_eq!(age, 26);

Usage

Typical usage is to define a type to contain your command-line arguments (typically tuple or struct where each field corresponds to an argument), and then construct, from a library of combinators, a parser which knows how to parse a value of this type from command line arguments.

At the core of this library is the Arg trait. Implementations of Arg know how to parse a value of a particular type (Arg's associated type Item) out of command line arguments. This might be as simple as taking a string value directly from the command line arguments. More complicated Arg implementations combine multiple simpler Args together, or manipulate their output in some way. I'll sometimes refer to implementations of Arg where type Item = Foo as "parsers yielding a value of type Foo".

The ArgExt struct is a wrapper around Arg implementations, adding methods which can be chained to create more complex parsers.

This library provides "base" parsers, which parse individual command-line arguments, and "combinators" - methods of ArgExt which modify or combine simpler parsers. Base parsers for arguments which accept parameters have variants which yield values of inferred types, converted using FromStr, and additional variants which yield values converted from strings by a provided conversion function. There are also a handful of macros for ergonomics, and simplifying some common patterns.

In the example above, opt_required and opt are both parsers yielding values of inferred types (in this case String and u8), while both and with_default are combinators. The both combinators takes a pair of parsers, and creates a parser yielding the pair containing both parsers' outputs. The with_default combinator takes a parser which yields an optional value, and a value, and returns a parser which yields the provided value if a value was provided, and the default value otherwise.

Argument Types

This library recognises 5 types of command line argument:

  • a flag is a named argument with no parameter which may appear 0 or 1 times. Base parsers of flags yield bool values which are true when an argument appears once, and false otherwise.
  • a multi_flag is a named argument with no parameter which may appear an arbitrary number of times. Base parsers of multi_flags yield usize values equal to the number of times the argument was passed.
  • an opt is a named argument with a parameter, which may appear 0 or 1 times. Base parsers of opts yield Option<String> values which are Some(<value>) if the argument was passed, and None otherwise.
  • a multi_opt is a named argument with a value which may appear an arbitrary number of times. The argument name must appear before each value. Base parsers of multi_opts yield Vec<String> values, with an element for each value that was passed.
  • a free is an unnamed argument. An arbitrary number of frees may be passed. Base parsers of frees yield 'Vec` values, with an element for each value that was passed.

Errors

Parse Errors

Parse errors are the result of invalid command-line arguments being passed to a program. In addition to the Item associated type, the Arg trait has an additional associated type named Error. Implementations of Arg can use this type to return errors detected during parsing. Combinators typically propagate errors of child parsers through their own Errors, though they are of course free to handle these errors themselves. Some example parse errors:

  • missing required arguments
  • parameters passed which can't be converted to the required type
  • passing multiple mutually exclusive arguments

Spec Errors

Spec errors are problems with the specification of arguments themselves. Some examples of spec errors:

  • specifying the same argument name multiple times
  • specifying a short name longer than 1 character
  • specifying a long name with a length of 1 character
  • specifying neither a short name, nor a long name

Since spec errors don't depend on the specific arguments passed to a program, running a program once is usually enough to convince yourself that it is free of these errors. As such, spec errors cause panics while parsing.

If however, your program's arguments are generated dynamically (such as from a config file or locale), you want a way to handle spec errors. The combinator ArgExt::valid creates a parser which treats spec errors as if they were parse errors - returning an error during parsing rather than panicking.

Parsing real command-line arguments

The Toy Example above specified the arguments in a slice. In practice, most programs will read actual command-line arguments. Methods for running a parser on real command-line arguments are ArgExt::parse_env and ArgExt::parse_env_or_exit, and their variants.

Help and Usage

The combinator ArgExt::with_help creates a parser which accepts a help flag. The ArgExt::with_help_default combinator is the same, but it uses the flag "-h" and "--help".

The ArgExt::parse_env function returns a Usage in addition to a parsed value or error, which can be rendered (Usage::render) to produce documentation on arguments, suitable for printing when help was requested, or the user have invalid input.

The methods ArgExt::parse_env_or_exit and ArgExt::parse_env_default_or_exit are only available on values produced by ArgExt::with_help and ArgExt::with_help_default irrespectively. These functions run the parser on the program's command-line arguments, and print usage and exit if a parser error was detected, or help was requested, and returns the parsed value otherwise.

Re-exports

pub use arg::Arg;
pub use ext::ArgExt;
pub use ext::HelpOr;

Modules

arg
ext
util
validation

Macros

args_all
args_all_depend
args_either
args_map
unflatten_closure

Functions

flag
free
free_by
free_str
multi_flag
multi_opt
multi_opt_by
multi_opt_str
opt
opt_by
opt_by_default
opt_by_default_str
opt_by_required
opt_default
opt_default_str
opt_required
opt_str
value