Struct Parser 

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

A single-pass parse over argv.

Created with Parser::new and driven with Parser::next_event.

Implementations

impl<'t, 'a, 'v> Parser<'t, 'a, 'v>

where 't: 'v,

pub fn new(root: &'t Command<'t>, argv: &'a [&'v OsStr]) -> Parser<'t, 'a, 'v>

Begin parsing argv against root.

argv excludes the program name.

pub fn with_view(self, view: &'t ViewMeta<'t>) -> Parser<'t, 'a, 'v>

Restrict inherited root globals to those carried by an executable view.

pub fn command(&self) -> &'t Command<'t>

The command in scope: the root, or the deepest subcommand selected so far.

pub fn double_dash_seen(&self) -> bool

Whether a -- was consumed as a separator.

False when flag interpretation stopped for another reason, such as an automatic argument taking a value, and false for a -- that a preserve argument kept as a value.

pub fn command_path(&self) -> Vec<(&'t Command<'t>, usize)>

Every command entered so far, and where each one’s own words begin.

The ancestors are already kept for flag scoping; this is the same chain with the offsets, which is what lets a completion hand a callback the words of its command rather than of the deepest one — a global flag is declared on an ancestor.

pub fn help_span(&self) -> (usize, usize)

The argv range the help word resolved as a command path.

Empty unless the word was typed. Every token in it named a subcommand of the one before it — the parser resolved them itself, so nothing here is a flag or a flag’s value.

pub fn command_start(&self) -> usize

Where the command in scope began: the index in argv just after its name, or at the unmatched word routed into a default subcommand.

argv[command_start()..] is what that command was given, which is what a completion callback needs to be handed its own command’s half-parsed struct rather than the root’s.

pub fn flags_stopped(&self) -> bool

Whether flag interpretation has stopped, for any reason.

Wider than double_dash_seen, and the question completion asks: past a separator or past the first value of an automatic argument, a dash-prefixed word is a value, so there is no flag there to offer.

pub fn collecting(&self) -> Option<&'t Flag<'t>>

A variadic flag that is still claiming words.

Asked between events, because the answer is gone by the end: the call that finds argv exhausted is the one that clears it. A completion needs it — the next word after --tools a ⌶ is another tool, not the positional that follows.

pub fn pending_arg(&self) -> Option<&'t Arg<'t>>

The positional the next word would fill, if there is one left.

A variadic stays here until it reaches its bound, which is what makes it the answer to “what could go where the cursor is” as many times as it can be filled.

pub fn flags_in_scope(&self) -> impl Iterator<Item = &'t Flag<'t>>

Flags a word here could name: this command’s own, then any ancestor’s globals.

The same set the parser itself would look in, so what is offered and what is accepted cannot disagree — including the shadowing rule, where a subcommand redeclaring an inherited name hides it.

pub fn next_event(&mut self) -> Option<Result<Event<'t, 'a, 'v>, Error<'t, 'v>>>

Read the next event.

Returns None when argv is exhausted. An Err is terminal: the parse stops there, since continuing past a token that could not be understood would only produce bindings derived from a guess. Events already yielded before an error are therefore not a partial result to be used — a caller that assigned them into fields should discard the whole attempt.

One case is stronger than that, because the grammar demands it: a short bundle containing an unrecognized letter yields the error instead of, not after, the letters that did match.