Struct Parser 

pub struct Parser<'a> { /* private fields */ }

A parser for command line arguments.

Implementations

impl<'a> Parser<'a>

pub fn new(raw: &'a dyn RawArgs) -> Parser<'a>

Create a parser from an iterator. This is useful for testing among other things.

The first item from the iterator must be the binary name, as from std::env::args_os.

The iterator is consumed immediately.

Example

let args = ["myapp", "-n", "10", "./foo.bar"];
let mut parser = lexarg_parser::Parser::new(&&args[1..]);

Examples found in repository

examples/hello.rs (line 17)

fn parse_args() -> Result<Args> {
    use lexarg::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let raw = std::env::args_os().collect::<Vec<_>>();
    let mut parser = lexarg::Parser::new(&raw);
    let bin_name = parser
        .next_raw()
        .expect("nothing parsed yet so no attached lingering")
        .expect("always at least one");
    let mut prev_arg = Value(bin_name);
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or_missing(Value(std::ffi::OsStr::new("NUM")))
                    .parse()
                    .within(arg)?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string("THING")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            Unexpected(_) => {
                return Err(LexError::msg("unexpected value")
                    .unexpected(arg)
                    .within(prev_arg)
                    .into());
            }
            _ => {
                return Err(LexError::msg("unexpected argument").unexpected(arg).into());
            }
        }
        prev_arg = arg;
    }

    Ok(Args {
        thing: thing
            .ok_or_missing(Value(std::ffi::OsStr::new("THING")))
            .within(Value(bin_name))?
            .to_owned(),
        number,
        shout,
    })
}

pub fn next_arg(&mut self) -> Option<Arg<'a>>

Get the next option or positional Arg.

Returns None if the command line has been exhausted.

Returns Arg::Unexpected on failure

Notes:

• = is always accepted as a [Arg::Short("=")]. If that isn’t the case in your application, you may want to special case the error for that.

Examples found in repository

examples/hello.rs (line 23)

fn parse_args() -> Result<Args> {
    use lexarg::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let raw = std::env::args_os().collect::<Vec<_>>();
    let mut parser = lexarg::Parser::new(&raw);
    let bin_name = parser
        .next_raw()
        .expect("nothing parsed yet so no attached lingering")
        .expect("always at least one");
    let mut prev_arg = Value(bin_name);
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or_missing(Value(std::ffi::OsStr::new("NUM")))
                    .parse()
                    .within(arg)?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string("THING")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            Unexpected(_) => {
                return Err(LexError::msg("unexpected value")
                    .unexpected(arg)
                    .within(prev_arg)
                    .into());
            }
            _ => {
                return Err(LexError::msg("unexpected argument").unexpected(arg).into());
            }
        }
        prev_arg = arg;
    }

    Ok(Args {
        thing: thing
            .ok_or_missing(Value(std::ffi::OsStr::new("THING")))
            .within(Value(bin_name))?
            .to_owned(),
        number,
        shout,
    })
}

pub fn next_flag_value(&mut self) -> Option<&'a OsStr>

Get a flag’s value

This function should normally be called right after seeing a flag that expects a value; positional arguments should be collected with Parser::next_arg().

A value is collected even if it looks like an option (i.e., starts with -).

None is returned if there is not another applicable flag value, including:

• No more arguments are present
• -- was encountered, meaning all remaining arguments are positional
• Being called again when the first value was attached (--flag=value, -Fvalue, -F=value)

Examples found in repository

examples/hello.rs (line 27)

fn parse_args() -> Result<Args> {
    use lexarg::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let raw = std::env::args_os().collect::<Vec<_>>();
    let mut parser = lexarg::Parser::new(&raw);
    let bin_name = parser
        .next_raw()
        .expect("nothing parsed yet so no attached lingering")
        .expect("always at least one");
    let mut prev_arg = Value(bin_name);
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or_missing(Value(std::ffi::OsStr::new("NUM")))
                    .parse()
                    .within(arg)?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string("THING")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            Unexpected(_) => {
                return Err(LexError::msg("unexpected value")
                    .unexpected(arg)
                    .within(prev_arg)
                    .into());
            }
            _ => {
                return Err(LexError::msg("unexpected argument").unexpected(arg).into());
            }
        }
        prev_arg = arg;
    }

    Ok(Args {
        thing: thing
            .ok_or_missing(Value(std::ffi::OsStr::new("THING")))
            .within(Value(bin_name))?
            .to_owned(),
        number,
        shout,
    })
}

pub fn next_attached_value(&mut self) -> Option<&'a OsStr>

Get a flag’s attached value (--flag=value, -Fvalue, -F=value)

This is a more specialized variant of Parser::next_flag_value for when only attached values are allowed, e.g. --color[=<when>].

pub fn next_raw(&mut self) -> Result<Option<&'a OsStr>, ()>

Get the next argument, independent of what it looks like

Returns Err(()) if an attached value is present

Examples found in repository

examples/hello.rs (line 19)

fn parse_args() -> Result<Args> {
    use lexarg::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let raw = std::env::args_os().collect::<Vec<_>>();
    let mut parser = lexarg::Parser::new(&raw);
    let bin_name = parser
        .next_raw()
        .expect("nothing parsed yet so no attached lingering")
        .expect("always at least one");
    let mut prev_arg = Value(bin_name);
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or_missing(Value(std::ffi::OsStr::new("NUM")))
                    .parse()
                    .within(arg)?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string("THING")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            Unexpected(_) => {
                return Err(LexError::msg("unexpected value")
                    .unexpected(arg)
                    .within(prev_arg)
                    .into());
            }
            _ => {
                return Err(LexError::msg("unexpected argument").unexpected(arg).into());
            }
        }
        prev_arg = arg;
    }

    Ok(Args {
        thing: thing
            .ok_or_missing(Value(std::ffi::OsStr::new("THING")))
            .within(Value(bin_name))?
            .to_owned(),
        number,
        shout,
    })
}

pub fn remaining_raw(&mut self) -> Result<impl Iterator<Item = &'a OsStr>, ()>

Collect all remaining arguments, independent of what they look like

Returns Err(()) if an attached value is present

pub fn peek_raw(&self) -> Result<Option<&'a OsStr>, ()>

Get the next argument, independent of what it looks like

Returns Err(()) if an attached value is present

Trait Implementations

impl<'a> Clone for Parser<'a>

fn clone(&self) -> Parser<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Parser<'a>

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

Formats the value using the given formatter.