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) -> Self

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-parser.rs (line 15)

fn parse_args() -> Result<Args, &'static str> {
    #![allow(clippy::enum_glob_use)]
    use lexarg_parser::Arg::*;

    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::Parser::new(&raw);
    let _bin_name = parser.next_raw();
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or("`--number` requires a value")?
                    .to_str()
                    .ok_or("invalid number")?
                    .parse()
                    .map_err(|_e| "invalid number")?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.to_str().ok_or("invalid string")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => {
                return Err("unexpected argument");
            }
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?.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-parser.rs (line 17)

fn parse_args() -> Result<Args, &'static str> {
    #![allow(clippy::enum_glob_use)]
    use lexarg_parser::Arg::*;

    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::Parser::new(&raw);
    let _bin_name = parser.next_raw();
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or("`--number` requires a value")?
                    .to_str()
                    .ok_or("invalid number")?
                    .parse()
                    .map_err(|_e| "invalid number")?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.to_str().ok_or("invalid string")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => {
                return Err("unexpected argument");
            }
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?.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-parser.rs (line 21)

fn parse_args() -> Result<Args, &'static str> {
    #![allow(clippy::enum_glob_use)]
    use lexarg_parser::Arg::*;

    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::Parser::new(&raw);
    let _bin_name = parser.next_raw();
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or("`--number` requires a value")?
                    .to_str()
                    .ok_or("invalid number")?
                    .parse()
                    .map_err(|_e| "invalid number")?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.to_str().ok_or("invalid string")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => {
                return Err("unexpected argument");
            }
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?.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-parser.rs (line 16)

fn parse_args() -> Result<Args, &'static str> {
    #![allow(clippy::enum_glob_use)]
    use lexarg_parser::Arg::*;

    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::Parser::new(&raw);
    let _bin_name = parser.next_raw();
    while let Some(arg) = parser.next_arg() {
        match arg {
            Short("n") | Long("number") => {
                number = parser
                    .next_flag_value()
                    .ok_or("`--number` requires a value")?
                    .to_str()
                    .ok_or("invalid number")?
                    .parse()
                    .map_err(|_e| "invalid number")?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.to_str().ok_or("invalid string")?);
            }
            Short("h") | Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => {
                return Err("unexpected argument");
            }
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?.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

Formats the value using the given formatter.