Struct Docopt

pub struct Docopt { /* private fields */ }

The main Docopt type, which is constructed with a Docopt usage string.

This can be used to match command line arguments to produce a ArgvMap.

Implementations

impl Docopt

pub fn new<S>(usage: S) -> Result<Docopt, Error>

where S: Deref<Target = str>,

Parse the Docopt usage string given.

The Docopt value returned may be used immediately to parse command line arguments with a default configuration.

If there was a problem parsing the usage string, a Usage error is returned.

Examples found in repository

examples/cp.rs (line 22)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/optional_command.rs (line 68)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/verbose_multiple.rs (line 30)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/cargo.rs (line 52)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.options_first(true).deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/decode.rs (line 35)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    println!("\nSome values:");
    println!("  Speed: {}", args.flag_speed);
    println!("  Drifting? {}", args.flag_drifting);
    println!("  Names: {:?}", args.arg_name);
    println!("  Command 'ship' invoked? {:?}", args.cmd_ship);
}

examples/hashmap.rs (line 24)

fn main() {
    let version = "1.2.3".to_owned();
    let args = Docopt::new(USAGE)
                      .and_then(|dopt| dopt.version(Some(version)).parse())
                      .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    // You can conveniently access values with `get_{bool,count,str,vec}`
    // functions. If the key doesn't exist (or if, e.g., you use `get_str` on
    // a switch), then a sensible default value is returned.
    println!("\nSome values:");
    println!("  Speed: {}", args.get_str("--speed"));
    println!("  Drifting? {}", args.get_bool("--drifting"));
    println!("  Names: {:?}", args.get_vec("<name>"));
    println!("  Command 'ship' invoked? {:?}", args.get_bool("ship"));
}

pub fn deserialize<'a, 'de: 'a, D>(&'a self) -> Result<D, Error>

where D: Deserialize<'de>,

Parse and deserialize the given argv.

This is a convenience method for parse().and_then(|vals| vals.deserialize()).

For details on how decoding works, please see the documentation for ArgvMap.

Examples found in repository

examples/cp.rs (line 23)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/optional_command.rs (line 69)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/verbose_multiple.rs (line 31)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/cargo.rs (line 53)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.options_first(true).deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

examples/decode.rs (line 36)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    println!("\nSome values:");
    println!("  Speed: {}", args.flag_speed);
    println!("  Drifting? {}", args.flag_drifting);
    println!("  Names: {:?}", args.arg_name);
    println!("  Command 'ship' invoked? {:?}", args.cmd_ship);
}

pub fn parse(&self) -> Result<ArgvMap, Error>

Parse command line arguments and try to match them against a usage pattern specified in the Docopt string.

If there is a match, then an ArgvMap is returned, which maps flags, commands and arguments to values.

If parsing the command line arguments fails, then an Argv error is returned. If parsing succeeds but there is no match, then a NoMatch error is returned. Both of these errors are always returned inside a WithProgramUsage error.

If special handling of help or version is enabled (the former is enabled by default), then Help or Version errors are returned if --help or --version is present.

Examples found in repository

examples/hashmap.rs (line 25)

fn main() {
    let version = "1.2.3".to_owned();
    let args = Docopt::new(USAGE)
                      .and_then(|dopt| dopt.version(Some(version)).parse())
                      .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    // You can conveniently access values with `get_{bool,count,str,vec}`
    // functions. If the key doesn't exist (or if, e.g., you use `get_str` on
    // a switch), then a sensible default value is returned.
    println!("\nSome values:");
    println!("  Speed: {}", args.get_str("--speed"));
    println!("  Drifting? {}", args.get_bool("--drifting"));
    println!("  Names: {:?}", args.get_vec("<name>"));
    println!("  Command 'ship' invoked? {:?}", args.get_bool("ship"));
}

pub fn argv<I, S>(self, argv: I) -> Docopt

where I: IntoIterator<Item = S>, S: AsRef<str>,

Set the argv to be used for Docopt parsing.

By default, when no argv is set, and it is automatically taken from std::env::args().

The argv given must be the full set of argv passed to the program. e.g., ["cp", "src", "dest"] is right while ["src", "dest"] is wrong.

pub fn options_first(self, yes: bool) -> Docopt

Enables the “options first” Docopt behavior.

The options first behavior means that all flags must appear before position arguments. That is, after the first position argument is seen, all proceeding arguments are interpreted as positional arguments unconditionally.

Examples found in repository

examples/cargo.rs (line 53)

fn main() {
    let args: Args = Docopt::new(USAGE)
        .and_then(|d| d.options_first(true).deserialize())
        .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);
}

pub fn help(self, yes: bool) -> Docopt

Enables automatic handling of --help.

When this is enabled and --help appears anywhere in the arguments, then a Help error will be returned. You may then use the exit method on the error value to conveniently quit the program (which will print the full usage string to stdout).

Note that for this to work, --help must be a valid pattern.

When disabled, there is no special handling of --help.

pub fn version(self, version: Option<String>) -> Docopt

Enables automatic handling of --version.

When this is enabled and --version appears anywhere in the arguments, then a Version(s) error will be returned, where s is the string given here. You may then use the exit method on the error value to convenient quit the program (which will print the version to stdout).

When disabled (a None value), there is no special handling of --version.

Examples found in repository

examples/hashmap.rs (line 25)

fn main() {
    let version = "1.2.3".to_owned();
    let args = Docopt::new(USAGE)
                      .and_then(|dopt| dopt.version(Some(version)).parse())
                      .unwrap_or_else(|e| e.exit());
    println!("{:?}", args);

    // You can conveniently access values with `get_{bool,count,str,vec}`
    // functions. If the key doesn't exist (or if, e.g., you use `get_str` on
    // a switch), then a sensible default value is returned.
    println!("\nSome values:");
    println!("  Speed: {}", args.get_str("--speed"));
    println!("  Drifting? {}", args.get_bool("--drifting"));
    println!("  Names: {:?}", args.get_vec("<name>"));
    println!("  Command 'ship' invoked? {:?}", args.get_bool("ship"));
}

Trait Implementations

impl Clone for Docopt

fn clone(&self) -> Docopt

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Docopt

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.