Enum Arg 

pub enum Arg<'i> {
    Long(LongFlag<'i>),
    Short(ShortFlag),
    Word(Word<'i>),
    Separator {
        offset: usize,
    },
}

One lexed command-line item.

Its fields are public and plain so a dispatch! arm can match flags as patterns, both spellings at once:

use winnow::combinator::{dispatch, fail};
use winnow::prelude::*;
use winnow_args::BStr;
use winnow_args::combinator::args;
use winnow_args::token::{Arg, LongFlag, ShortFlag, arg};
use winnow_args::{Argv, Error};

let words = [BStr::new("-p"), BStr::new("x"), BStr::new("f")];
let (mut path, mut files) = (None::<String>, Vec::<String>::new());
let (p, f) = (&mut path, &mut files);
args(dispatch! {arg;
    a @ (Arg::Long(LongFlag { name: b"path", .. }) | Arg::Short(ShortFlag { letter: 'p', .. })) => {
        a.value_as().map(|v| *p = Some(v))
    },
    Arg::Word(w) => w.value_as("FILE").map(|file| f.push(file)),
    _ => fail,
})
.parse_next(&mut Argv::new(&words))?;
assert_eq!((path.as_deref(), &files[..]), (Some("x"), &["f".to_string()][..]));

Variants

Long(LongFlag<'i>)

--name or --name=value. The word is consumed whole.

Short(ShortFlag)

One letter of -abc. The stream is left on the next letter (or the attached value), or at the next word if this was the last letter.

Word(Word<'i>)

A word that is not a flag: a positional value, a lone -, or anything after --.

Separator

The first --.

Fields

offset: usize

Where it is.

Implementations

impl<'i> Arg<'i>

pub fn spelling(&self) -> String

The item as the user typed it, for error messages.

pub fn offset(&self) -> usize

Where the item starts.

pub fn unexpected(&self) -> Error

The error for this item when nothing accepts it.

pub fn check_switch(&self) -> Result<(), Error>

Finish a switch. Only a long flag can have been given a value, --verbose=yes, which is an error; in -vx the x is another letter.

pub fn read_value(&self, input: &mut Argv<'i>) -> Result<&'i BStr, Error>

Finish an option, committing: a missing value is an error, not a reason to try something else.

• --name=value: the attached text.
• -nvalue, -n=value: the rest of the bundle, less one =.
• --name value, -n value: the next word, unless it is flag-like. A lone - is a value; -- is not.

pub fn read_next(&self, input: &mut Argv<'i>) -> Result<&'i BStr, Error>

One more value for a flag that takes several (-platform_version macos 11.0 12.0): the next word, whatever it looks like.

pub fn read_more( &self, input: &mut Argv<'i>, options: ValueOptions, terminator: Option<&BStr>, ) -> Option<&'i BStr>

One more value for a flag that takes a variable number of them (--include a b): the next word, unless the words ran out, it is flag-like (as Arg::read_value_with judges it under options), or it is terminator, which is dropped.

pub fn check_values(&self, got: usize, min: usize) -> Result<(), Error>

Fail if a flag declared to take at least min values got fewer.

pub fn has_attached_value(&self, input: &Argv<'i>) -> bool

Whether a value is attached to this flag in its own word: --name=value, -nvalue. Asked before reading it.

pub fn read_value_with( &self, input: &mut Argv<'i>, options: ValueOptions, ) -> Result<&'i BStr, Error>

Arg::read_value under options: which detached words it may take.

pub fn read_value_or( &self, input: &mut Argv<'i>, missing: &'static BStr, ) -> &'i BStr

Arg::read_value for a flag whose value may be left out: where that would report a missing value, --color alone or before another flag, this gives missing instead.

pub fn read_value_or_with( &self, input: &mut Argv<'i>, options: ValueOptions, missing: &'static BStr, ) -> &'i BStr

Arg::read_value_or under options.

pub fn read_value_opt_with( &self, input: &mut Argv<'i>, options: ValueOptions, ) -> Option<&'i BStr>

Arg::read_value for a flag whose value may be left out, told apart from a value of zero length: --color alone or before another flag gives None, --color= gives Some(b""). What an Option field stores.

pub fn read_value_as<T: FromArg>( &self, input: &mut Argv<'i>, ) -> Result<T, Error>

Arg::read_value, converted with FromArg.

pub fn convert<T: FromArg>(&self, value: &BStr) -> Result<T, Error>

Convert value, one of this flag’s values, naming the flag on failure.

pub fn values_as<T: FromArg>( &self, delimiter: u8, ) -> impl Parser<Argv<'i>, Vec<T>, Error>

Arg::read_value split on delimiter, each piece converted.

pub fn switch(&self) -> impl Parser<Argv<'i>, (), Error>

Arg::check_switch as a parser, for a dispatch! arm.

pub fn value(&self) -> impl Parser<Argv<'i>, &'i BStr, Error>

Arg::read_value as a parser, for a dispatch! arm.

pub fn value_or<T: FromArg>( &self, missing: &'static BStr, ) -> impl Parser<Argv<'i>, T, Error>

Arg::read_value_or, converted, as a parser for a dispatch! arm.

pub fn value_or_with<T: FromArg>( &self, options: ValueOptions, missing: &'static BStr, ) -> impl Parser<Argv<'i>, T, Error>

Arg::read_value_or_with, converted, as a parser for a dispatch! arm.

pub fn value_as_with<T: FromArg>( &self, options: ValueOptions, ) -> impl Parser<Argv<'i>, T, Error>

Arg::read_value_with, converted, as a parser for a dispatch! arm.

pub fn value_as<T: FromArg>(&self) -> impl Parser<Argv<'i>, T, Error>

Arg::read_value_as as a parser, for a dispatch! arm.

Trait Implementations

impl<'i> Clone for Arg<'i>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'i> Copy for Arg<'i>

impl<'i> Debug for Arg<'i>

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

Formats the value using the given formatter.

impl<'i> Eq for Arg<'i>

impl<'i, const N: usize> Parser<Argv<'i>, Arg<'i>, Error> for Named<N>

One occurrence of the flag’s name, value not yet read.

fn parse_next(&mut self, input: &mut Argv<'i>) -> Result<Arg<'i>, Error>

Take tokens from the Stream, turning it into the output

fn parse( &mut self, input: I, ) -> Result<O, ParseError<I, <E as ParserError<I>>::Inner>>

where Self: Sized, I: Stream + StreamIsPartial, E: ParserError<I>, <E as ParserError<I>>::Inner: ParserError<I>,

Parse all of input, generating O from it

fn parse_iter(&mut self, input: I) -> ParseIter<'_, Self, I, O, E>

where Self: Sized, I: Stream + StreamIsPartial, E: ParserError<I>, <E as ParserError<I>>::Inner: ParserError<I>,

Repeat this parse until all of input is consumed, generating O from it

fn parse_peek(&mut self, input: I) -> Result<(I, O), E>

Take tokens from the Stream, turning it into the output

fn by_ref(&mut self) -> ByRef<'_, Self, I, O, E>

where Self: Sized,

Treat &mut Self as a parser

fn value<O2>(self, val: O2) -> Value<Self, I, O, O2, E>

where Self: Sized, O2: Clone,

Produce the provided value

fn default_value<O2>(self) -> DefaultValue<Self, I, O, O2, E>

where Self: Sized, O2: Default,

Produce a type’s default value

fn void(self) -> Void<Self, I, O, E>

where Self: Sized,

Discards the output of the Parser

fn output_into<O2>(self) -> OutputInto<Self, I, O, O2, E>

where Self: Sized, O: Into<O2>,

Convert the parser’s output to another type using std::convert::From

fn take(self) -> Take<Self, I, O, E>

where Self: Sized, I: Stream,

Produce the consumed input as produced value.

fn with_taken(self) -> WithTaken<Self, I, O, E>

where Self: Sized, I: Stream,

Produce the consumed input with the output

fn span(self) -> Span<Self, I, O, E>

where Self: Sized, I: Stream + Location,

Produce the location of the consumed input as produced value.

fn with_span(self) -> WithSpan<Self, I, O, E>

where Self: Sized, I: Stream + Location,

Produce the location of consumed input with the output

fn map<G, O2>(self, map: G) -> Map<Self, G, I, O, O2, E>

where G: FnMut(O) -> O2, Self: Sized,

Maps a function over the output of a parser

fn try_map<G, O2, E2>(self, map: G) -> TryMap<Self, G, I, O, O2, E, E2>

where Self: Sized, G: FnMut(O) -> Result<O2, E2>, I: Stream, E: FromExternalError<I, E2> + ParserError<I>,

Applies a function returning a Result over the output of a parser.

fn verify_map<G, O2>(self, map: G) -> VerifyMap<Self, G, I, O, O2, E>

where Self: Sized, G: FnMut(O) -> Option<O2>, I: Stream, E: ParserError<I>,

Apply both Parser::verify and Parser::map.

fn flat_map<G, H, O2>(self, map: G) -> FlatMap<Self, G, H, I, O, O2, E>

where Self: Sized, G: FnMut(O) -> H, H: Parser<I, O2, E>,

Creates a parser from the output of this one

fn parse_to<O2>(self) -> ParseTo<Self, I, O, O2, E>

where Self: Sized, I: Stream, O: ParseSlice<O2>, E: ParserError<I>,

Apply std::str::FromStr to the output of the parser

fn verify<G, O2>(self, filter: G) -> Verify<Self, G, I, O, O2, E>

where Self: Sized, G: FnMut(&O2) -> bool, I: Stream, O: Borrow<O2>, E: ParserError<I>, O2: ?Sized,

Returns the output of the child parser if it satisfies a verification function.

fn context<C>(self, context: C) -> Context<Self, I, O, E, C>

where Self: Sized, I: Stream, E: AddContext<I, C> + ParserError<I>, C: Clone + Debug,

If parsing fails, add context to the error

fn context_with<F, C, FI>( self, context: F, ) -> ContextWith<Self, I, O, E, F, C, FI>

where Self: Sized, I: Stream, E: AddContext<I, C> + ParserError<I>, F: Fn() -> FI + Clone, C: Debug, FI: Iterator<Item = C>,

If parsing fails, dynamically add context to the error

fn map_err<G, E2>(self, map: G) -> MapErr<Self, G, I, O, E, E2>

where G: FnMut(E) -> E2, Self: Sized,

Maps a function over the error of a parser

fn complete_err(self) -> CompleteErr<Self, I, O, E>

where Self: Sized,

Transforms Incomplete into Backtrack

fn err_into<E2>(self) -> ErrInto<Self, I, O, E, E2>

where Self: Sized, E: Into<E2>,

Convert the parser’s error to another type using std::convert::From

impl<'i> PartialEq for Arg<'i>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'i> StructuralPartialEq for Arg<'i>