Crate lexopt

A pathologically simple command line argument parser.

Most argument parsers are declarative: you tell them what to parse, and they do it.

This one provides you with a stream of options and values and lets you figure out the rest.

Example

struct Args {
    thing: String,
    number: u32,
    shout: bool,
}

fn parse_args() -> Result<Args, lexopt::Error> {
    use lexopt::prelude::*;

    let mut thing = None;
    let mut number = 1;
    let mut shout = false;
    let mut parser = lexopt::Parser::from_env();
    while let Some(arg) = parser.next()? {
        match arg {
            Short('n') | Long("number") => {
                number = parser.value()?.parse()?;
            }
            Long("shout") => {
                shout = true;
            }
            Value(val) if thing.is_none() => {
                thing = Some(val.string()?);
            }
            Long("help") => {
                println!("Usage: hello [-n|--number=NUM] [--shout] THING");
                std::process::exit(0);
            }
            _ => return Err(arg.unexpected()),
        }
    }

    Ok(Args {
        thing: thing.ok_or("missing argument THING")?,
        number,
        shout,
    })
}

fn main() -> Result<(), lexopt::Error> {
    let args = parse_args()?;
    let mut message = format!("Hello {}", args.thing);
    if args.shout {
        message = message.to_uppercase();
    }
    for _ in 0..args.number {
        println!("{}", message);
    }
    Ok(())
}

Let’s walk through this:

• We start parsing with Parser::from_env.
• We call parser.next() in a loop to get all the arguments until they run out.
• We match on arguments. Short and Long indicate an option.
• To get the value that belongs to an option (like 10 in -n 10) we call parser.value().
  • This returns a standard OsString.
  • For convenience, use lexopt::prelude::* adds a .parse() method, analogous to str::parse.
  • Calling parser.value() is how we tell Parser that -n takes a value at all.
• Value indicates a free-standing argument.
  • if thing.is_none() is a useful pattern for positional arguments. If we already found thing we pass it on to another case.
  • It also contains an OsString.
    • The .string() method decodes it into a plain String.
• If we don’t know what to do with an argument we use return Err(arg.unexpected()) to turn it into an error message.
• Strings can be promoted to errors for custom error messages.

Modules

prelude

A small prelude for processing arguments.

Structs

Parser

A parser for command line arguments.

RawArgs

An iterator for the remaining raw arguments, returned by Parser::raw_args.

ValuesIter

An iterator for multiple option-arguments, returned by Parser::values.

Enums

Arg

A command line argument found by Parser, either an option or a positional argument.

Error

An error during argument parsing.

Traits

ValueExt

An optional extension trait with methods for parsing OsStrings.