Struct ArgumentParser

pub struct ArgumentParser<'parser> { /* private fields */ }

The main argument parser class

Implementations

impl<'parser> ArgumentParser<'parser>

pub fn new() -> ArgumentParser<'parser>

Create an empty argument parser

Examples found in repository

examples/subcommands.rs (line 30)

fn play_command(verbose: bool, args: Vec<String>) {
    let mut output = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays a sound");
        ap.refer(&mut output)
            .add_option(&["--output"], Store,
                r#"Output sink to play to"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Output: {}", verbose, output);
}

fn record_command(verbose: bool, args: Vec<String>) {
    let mut input = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Records a sound");
        ap.refer(&mut input)
            .add_option(&["--input"], Store,
                r#"Output source to record from"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Input: {}", verbose, input);
}

fn main() {
    let mut verbose = false;
    let mut subcommand = Command::play;
    let mut args = vec!();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays or records sound");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut subcommand).required()
            .add_argument("command", Store,
                r#"Command to run (either "play" or "record")"#);
        ap.refer(&mut args)
            .add_argument("arguments", List,
                r#"Arguments for command"#);
        ap.stop_on_first_argument(true);
        ap.parse_args_or_exit();
    }

    args.insert(0, format!("subcommand {:?}", subcommand));
    match subcommand {
        Command::play => play_command(verbose, args),
        Command::record => record_command(verbose, args),
    }
}

examples/greeting.rs (line 9)

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.add_option(&["-V", "--version"],
            Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");
        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);
}

examples/structure.rs (line 18)

fn main() {
    let mut options = Options {
        verbose: false,
        name: "World".to_string(),
    };
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.refer(&mut options.verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut options.name)
            .add_option(&["--name"], Store,
            "Name for the greeting");
        match ap.parse_args() {
            Ok(()) => {}
            Err(x) => {
                exit(x);
            }
        }
    }

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

pub fn refer<'x, T>( &'x mut self, val: &'parser mut T, ) -> Box<Ref<'parser, 'x, T>>

Borrow mutable variable for an argument

This returns Ref object which should be used configure the option

Examples found in repository

examples/subcommands.rs (line 32)

fn play_command(verbose: bool, args: Vec<String>) {
    let mut output = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays a sound");
        ap.refer(&mut output)
            .add_option(&["--output"], Store,
                r#"Output sink to play to"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Output: {}", verbose, output);
}

fn record_command(verbose: bool, args: Vec<String>) {
    let mut input = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Records a sound");
        ap.refer(&mut input)
            .add_option(&["--input"], Store,
                r#"Output source to record from"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Input: {}", verbose, input);
}

fn main() {
    let mut verbose = false;
    let mut subcommand = Command::play;
    let mut args = vec!();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays or records sound");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut subcommand).required()
            .add_argument("command", Store,
                r#"Command to run (either "play" or "record")"#);
        ap.refer(&mut args)
            .add_argument("arguments", List,
                r#"Arguments for command"#);
        ap.stop_on_first_argument(true);
        ap.parse_args_or_exit();
    }

    args.insert(0, format!("subcommand {:?}", subcommand));
    match subcommand {
        Command::play => play_command(verbose, args),
        Command::record => record_command(verbose, args),
    }
}

examples/greeting.rs (line 13)

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.add_option(&["-V", "--version"],
            Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");
        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);
}

examples/structure.rs (line 20)

fn main() {
    let mut options = Options {
        verbose: false,
        name: "World".to_string(),
    };
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.refer(&mut options.verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut options.name)
            .add_option(&["--name"], Store,
            "Name for the greeting");
        match ap.parse_args() {
            Ok(()) => {}
            Err(x) => {
                exit(x);
            }
        }
    }

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

pub fn add_option<F: IFlagAction + 'parser>( &mut self, names: &[&'parser str], action: F, help: &'parser str, )

Add option to argument parser

This is only useful for options that don’t store value. For example Print(...)

Examples found in repository

examples/greeting.rs (lines 11-12)

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.add_option(&["-V", "--version"],
            Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");
        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);
}

pub fn set_description(&mut self, descr: &'parser str)

Set description of the command

Examples found in repository

examples/subcommands.rs (line 31)

fn play_command(verbose: bool, args: Vec<String>) {
    let mut output = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays a sound");
        ap.refer(&mut output)
            .add_option(&["--output"], Store,
                r#"Output sink to play to"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Output: {}", verbose, output);
}

fn record_command(verbose: bool, args: Vec<String>) {
    let mut input = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Records a sound");
        ap.refer(&mut input)
            .add_option(&["--input"], Store,
                r#"Output source to record from"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Input: {}", verbose, input);
}

fn main() {
    let mut verbose = false;
    let mut subcommand = Command::play;
    let mut args = vec!();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays or records sound");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut subcommand).required()
            .add_argument("command", Store,
                r#"Command to run (either "play" or "record")"#);
        ap.refer(&mut args)
            .add_argument("arguments", List,
                r#"Arguments for command"#);
        ap.stop_on_first_argument(true);
        ap.parse_args_or_exit();
    }

    args.insert(0, format!("subcommand {:?}", subcommand));
    match subcommand {
        Command::play => play_command(verbose, args),
        Command::record => record_command(verbose, args),
    }
}

examples/greeting.rs (line 10)

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.add_option(&["-V", "--version"],
            Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");
        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);
}

examples/structure.rs (line 19)

fn main() {
    let mut options = Options {
        verbose: false,
        name: "World".to_string(),
    };
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.refer(&mut options.verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut options.name)
            .add_option(&["--name"], Store,
            "Name for the greeting");
        match ap.parse_args() {
            Ok(()) => {}
            Err(x) => {
                exit(x);
            }
        }
    }

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

pub fn print_help(&self, name: &str, writer: &mut dyn Write) -> IoResult<()>

Print help

Usually command-line option is used for printing help, this is here for any awkward cases

pub fn print_usage(&self, name: &str, writer: &mut dyn Write) -> IoResult<()>

Print usage

Usually printed into stderr on error of command-line parsing

pub fn parse( &self, args: Vec<String>, stdout: &mut dyn Write, stderr: &mut dyn Write, ) -> Result<(), i32>

Parse arguments

This is most powerful method. Usually you need parse_args or parse_args_or_exit instead

Examples found in repository

examples/subcommands.rs (line 35)

fn play_command(verbose: bool, args: Vec<String>) {
    let mut output = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays a sound");
        ap.refer(&mut output)
            .add_option(&["--output"], Store,
                r#"Output sink to play to"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Output: {}", verbose, output);
}

fn record_command(verbose: bool, args: Vec<String>) {
    let mut input = "".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Records a sound");
        ap.refer(&mut input)
            .add_option(&["--input"], Store,
                r#"Output source to record from"#);
        match ap.parse(args, &mut stdout(), &mut stderr()) {
            Ok(()) =>  {}
            Err(x) => {
                std::process::exit(x);
            }
        }
    }
    println!("Verbosity: {}, Input: {}", verbose, input);
}

pub fn error(&self, command: &str, message: &str, writer: &mut dyn Write)

Write an error similar to one produced by the library itself

Only needed if you like to do some argument validation that is out of scope of the argparse

pub fn stop_on_first_argument(&mut self, want_stop: bool)

Configure parser to ignore options when first non-option argument is encountered.

Useful for commands that want to pass following options to the subcommand or subprocess, but need some options to be set before command is specified.

Examples found in repository

examples/subcommands.rs (line 79)

fn main() {
    let mut verbose = false;
    let mut subcommand = Command::play;
    let mut args = vec!();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays or records sound");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut subcommand).required()
            .add_argument("command", Store,
                r#"Command to run (either "play" or "record")"#);
        ap.refer(&mut args)
            .add_argument("arguments", List,
                r#"Arguments for command"#);
        ap.stop_on_first_argument(true);
        ap.parse_args_or_exit();
    }

    args.insert(0, format!("subcommand {:?}", subcommand));
    match subcommand {
        Command::play => play_command(verbose, args),
        Command::record => record_command(verbose, args),
    }
}

pub fn silence_double_dash(&mut self, silence: bool)

Do not put double-dash (bare --) into argument

The double-dash is used to stop parsing options and treat all the following tokens as the arguments regardless of whether they start with dash (minus) or not.

The method only useful for List arguments. On by default. The method allows to set option to false so that cmd xx -- yy will get xx -- yy as arguments instead of xx yy by default. This is useful if your -- argument is meaningful. Only first double-dash is ignored by default.

pub fn parse_args(&self) -> Result<(), i32>

Convenience method to parse arguments

On error returns error code that is supposed to be returned by an application. (i.e. zero on --help and 2 on argument error)

Examples found in repository

examples/structure.rs (line 26)

fn main() {
    let mut options = Options {
        verbose: false,
        name: "World".to_string(),
    };
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.refer(&mut options.verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut options.name)
            .add_option(&["--name"], Store,
            "Name for the greeting");
        match ap.parse_args() {
            Ok(()) => {}
            Err(x) => {
                exit(x);
            }
        }
    }

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

pub fn parse_args_or_exit(&self)

The simplest conveninece method

The method returns only in case of successful parsing or exits with appropriate code (including successful on --help) otherwise.

Examples found in repository

examples/greeting.rs (line 19)

fn main() {
    let mut verbose = false;
    let mut name = "World".to_string();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Greet somebody.");
        ap.add_option(&["-V", "--version"],
            Print(env!("CARGO_PKG_VERSION").to_string()), "Show version");
        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);
}

examples/subcommands.rs (line 80)

fn main() {
    let mut verbose = false;
    let mut subcommand = Command::play;
    let mut args = vec!();
    {
        let mut ap = ArgumentParser::new();
        ap.set_description("Plays or records sound");
        ap.refer(&mut verbose)
            .add_option(&["-v", "--verbose"], StoreTrue,
            "Be verbose");
        ap.refer(&mut subcommand).required()
            .add_argument("command", Store,
                r#"Command to run (either "play" or "record")"#);
        ap.refer(&mut args)
            .add_argument("arguments", List,
                r#"Arguments for command"#);
        ap.stop_on_first_argument(true);
        ap.parse_args_or_exit();
    }

    args.insert(0, format!("subcommand {:?}", subcommand));
    match subcommand {
        Command::play => play_command(verbose, args),
        Command::record => record_command(verbose, args),
    }
}