Struct Parser 

#[non_exhaustive]
pub struct Parser<'a> { /* private fields */ }

Builder for parsing command-line arguments with custom options.

Use this when you need to customize parsing behavior, such as providing a custom environment variable map instead of using the process environment.

Example

use std::collections::HashMap;
use usage::Spec;
use usage::parse::Parser;

let spec: Spec = r#"flag "--name <name>" env="NAME""#.parse().unwrap();
let env: HashMap<String, String> = [("NAME".into(), "john".into())].into();

let result = Parser::new(&spec)
    .with_env(env)
    .parse(&["cmd".into()])
    .unwrap();

Implementations

impl<'a> Parser<'a>

pub fn new(spec: &'a Spec) -> Self

Create a new parser for the given spec.

pub fn with_env(self, env: HashMap<String, String>) -> Self

Use a custom environment variable map instead of the process environment.

This is useful when parsing for tasks in a monorepo where the env vars come from a child config file rather than the current process environment.

pub fn with_mount_outputs(self, outputs: HashMap<String, String>) -> Self

Inject deterministic outputs for mount commands instead of executing them.

Keys are the exact run strings declared by mount nodes and values are the usage specs those commands would print. When this is set, every encountered mount must have an entry. Production parsing remains process-backed unless a caller explicitly opts into injection.

pub fn parse(self, input: &[String]) -> Result<ParseOutput, Error>

Parse the input arguments.

Returns the parsed arguments and flags, with defaults and env vars applied.

pub fn explain(self, input: &[String]) -> Result<ParseOutput, Error>

Everything the parse learned, whether or not it succeeded.

Parser::parse wants the first error and nothing else, which is right for a caller about to act on a command line. A caller that wants to explain one wants the opposite: the bindings that worked and every complaint about the rest, since a report saying only “missing required ” is the report you already had.

Failures that stop the parse dead — a mount that will not run, a word no declaration can take — still come back as Err. There is no output to describe in those cases; see Parser::explain for what to do about it.

pub fn explain_refused( self, input: &[String], ) -> Result<ParseOutput, Vec<TokenBinding>>

The binding phase’s own answer for a line Parser::explain refused.

Ok when the binding phase finished and the failure came after it — a flag left waiting for a value, say. Everything argv supplied is there and only the environment-and-defaults phase is missing.

Err when the binding phase is where it died, leaving the tokens it had attributed by then. Those words are most of what a report is for: “no declaration takes bogus” is more useful next to the three tokens that did bind than on its own. The word that caused the failure carries a role saying so, and everything still queued behind it is TokenRole::Unread, for the two failures a command line reaches on its own — a word nothing declares, and a flag a strict spec refuses. A failure in the spec rather than in the line, such as a mount that will not run, stops the trace where it stopped and the words past it carry no role.