Lib.rs

Importing

Edit your Cargo.toml to add rust-argparse to your project.

[dependencies]
argparse = "0.2.2"

Example

The following code is a simple Rust program with command-line arguments:

extern crate argparse;

use argparse::{ArgumentParser, StoreTrue, Store};

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {  // this block limits scope of borrows by ap.refer() method
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut name)
            .add_option(&["--name"], Store,
            "Name for the greeting");
        ap.parse_args_or_exit();
    }

    if verbose {
        println!("name is {}", name);
    }
    println!("Hello {}!", name);
}

Assuming the Rust code above is saved into a file greeting.rs, let's see what we have now:

$ rustc greeting.rs
$ ./greeting -h
Usage:
  ./greeting [OPTIONS]

Greet somebody.

Optional arguments:
  -h, --help  Show this help message and exit
  -v, --verbose
             Be verbose
  --name NAME Name for the greeting
$ ./greeting
Hello World!
$ ./greeting --name Bob
Hello Bob!
$ ./greeting -v --name Alice
name is Alice
Hello Alice!

Basic Workflow

extern crate argparse;
use argparse::ArgumentParser;

let mut parser = ArgumentParser::new();

parser.set_description("My command-line utility")

let mut verbose = false;
parser.refer(&mut verbose);

parser.refer(&mut verbose)
    .add_option(&["-v", "--verbose"], StoreTrue,
                "Be verbose");

parser.refer(&mut verbose)
    .add_option(&["-v", "--verbose"], StoreTrue,
                "Be verbose")
    .add_option(&["-q", "--quiet"], StoreFalse,
                "Be verbose");

let mut command = String;
parser.refer(&mut command)
    .add_argument("command", Store,
                  "Command to run");

struct Options {
    verbose: bool,
}
...
let mut options = Options { verbose: false };
parser.refer(&mut options.verbose)
    .add_option(&["-v"], StoreTrue,
                "Be verbose");

parser.parse_args_or_exit()

use std::process::exit;

match parser.parse_args() {
    Ok(()) =>  {}
    Err(x) => {
        std::process::exit(x);
    }
}

ArgumentParser Methods

parser.refer<T>(var: &mut T) -> Ref

Attach the variable to argument parser. The options are added to the returned Ref object and modify a variable passed to the method.

parser.add_option(names: &[&str], action: TypedAction, help: &str)

Add a single option which has no parameters. Most options must be added by refer(..) and methods on Ref object (see below).

Example:

ap.add_option(&["-V", "--version"],
    Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");

parser.set_description(descr: &str)

Set description that is at the top of help message.

parser.stop_on_first_argument(val: bool)

If called with true, parser will stop searching for options when first non-option (the one doesn't start with -) argument is encountered. This is useful if you want to parse following options with another argparser or external program.

parser.silence_double_dash(val: bool)

If called with true (default), parser will not treat first double dash -- as positional argument. Use false if you need to add some meaning to the -- marker.

parser.print_usage(name: &str, writer: &mut Write)

Prints usage string to stderr.

parser.print_help(name: &str, writer: &mut Write)

Writes help to writer, used by --help option internally.

parser.parse_args()

Method that does all the dirty work. And returns Result

parser.parse_args_or_exit()

Method that does all the dirty work. And in case of failure just exit()

Variable Reference Methods

The argparse::Ref object is returned from parser.refer(). The following methods are used to add and customize arguments:

option.add_option(names: &[&str], action: TypedAction, help: &str)

Add an option. All items in names should be either in format -X or --long-option (i.e. one dash and one char or two dashes and long name). How this option will be interpreted and whether it will have an argument dependes on the action. See below list of actions.

option.add_argument(name: &str, action: TypedAction, help: &str)

Add a positional argument

option.metavar(var: &str)

A name of the argument in usage messages (for options having argument).

option.envvar(var: &str)

A name of the environment variable to get option value from. The value would be parsed with FromStr::from_str, just like an option having Store action.

option.required()

The option or argument is required (it's optional by default). If multiple options or multiple arguments are defined for this reference at least one of them is required.

Actions

The following actions are available out of the box. They may be used in either add_option or add_argument:

Store

An option has single argument. Stores a value from command-line in a variable. Any type that has the FromStr and Clone traits implemented may be used.

StoreOption

As Store, but wrap value with Some for use with Option. For example:

let mut x: Option<i32> = None; ap.refer(&mut x).add_option(&["-x"], StoreOption, "Set var x");

StoreConst(value)

An option has no arguments. Store a hard-coded value into variable, when specified. Any type with the Clone trait implemented may be used.

PushConst(value)

An option has no arguments. Push a hard-coded value into variable, when specified. Any type which has the Clone type implemented may be used. Option might used for a list of operations to perform, when required is set for this variable, at least one operation is required.

StoreTrue

Stores boolean true value in a variable. (shortcut for StoreConst(true))

StoreFalse

Stores boolean false value in a variable. (shortcut for StoreConst(false))

IncrBy(num)

An option has no arguments. Increments the value stored in a variable by a value num. Any type which has the Add and Clone traits may be used.

DecrBy(nym)

Decrements the value stored in a variable by a value num. Any type which has the Add and Clone traits may be used.

Collect

When used for an --option, requires single argument. When used for a positional argument consumes all remaining arguments. Parsed options are added to the list. I.e. a Collect action requires a Vec<int> variable. Parses arguments using FromStr trait.

List

When used for positional argument, works the same as List. When used as an option, consumes all remaining arguments.

Note the usage of List is strongly discouraged, because of complex rules below. Use Collect and positional options if possible. But usage of List action may be useful if you need shell expansion of anything other than last positional argument.

Let's learn rules by example. For the next options:

ap.refer(&mut lst1).add_option(&["-X", "--xx"], List, "List1");
ap.refer(&mut lst2).add_argument("yy", List, "List2");

The following command line:

./run 1 2 3 -X 4 5 6

Will return [1, 2, 3] in the lst1 and the [4,5,6] in the lst2.

Note that using when using = or equivalent short option mode, the 'consume all' mode is not enabled. I.e. in the following command-line:

./run 1 2 -X3 4 --xx=5 6

The lst1 has [3, 5] and lst2 has [1, 2, 4, 6]. The argument consuming also stops on -- or the next option:

./run: -X 1 2 3 -- 4 5 6
./run: -X 1 2 --xx=3 4 5 6

Both of the above parse [4, 5, 6] as lst1 and the [1, 2, 3] as the lst2.

Print(value)

Print the text and exit (with status 0). Useful for --version option:

ap.add_option(&["-V", "--version"],
    Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");