Trait ArgGroup 

pub trait ArgGroup: Sized {
    type Partial: Default;

    const NAME: &'static str;
    const FLAGS: &'static [&'static Flag<'static>];
    const FLAG_METAS: &'static [FlagMeta<'static>];
    const MEMBERS: &'static [&'static str];
    const MULTIPLE: bool = false;

    // Required methods
    fn apply(partial: &mut Self::Partial, event: &Event<'_, '_, '_>) -> bool;
    fn any_given(partial: &Self::Partial) -> Option<&'static str>;
    fn conflict(partial: &Self::Partial) -> Option<(&'static str, &'static str)>;
    fn build(partial: &Self::Partial) -> Option<Self>;
    fn argument_state(
        partial: &Self::Partial,
        selector: &str,
    ) -> Option<ArgumentState>;
    fn argument_matches(
        partial: &Self::Partial,
        selector: &str,
        value: &[u8],
    ) -> Option<bool>;
    fn displace(partial: &mut Self::Partial, selector: &str) -> bool;
    fn event_matches(event: &Event<'_, '_, '_>, selector: &str) -> bool;

    // Provided methods
    fn start() -> Self::Partial { ... }
    fn try_build(
        partial: &Self::Partial,
    ) -> Result<Option<Self>, Error<'static, 'static>> { ... }
    fn try_build_many(
        partial: &Self::Partial,
    ) -> Result<Vec<Self>, Error<'static, 'static>> { ... }
    fn standing_state(standing: &Self, selector: &str) -> Option<ArgumentState> { ... }
    fn standing_matches(
        standing: &Self,
        selector: &str,
        value: &[u8],
    ) -> Option<bool> { ... }
}

An enum whose variants are one command’s related flags.

What a CLI spells --json or --yaml and holds as a Mode, rather than as one bool per member plus a match over which of them is set. Nothing new reaches the spec: the enum lowers to a GroupMeta and the switches it names, so help, completions, and the reference implementation read the declaration every hand-written group does.

A field holding one says #[usage(arg_group)]. Option<Mode> is a group that may be left alone and a bare Mode is one that has to be given, which is how the rest of the derive reads required-ness from a type. There is no default variant, so required-ness has exactly one spelling. A group declared multiple is held by Vec<Mode> and retains every member in command-line order.

Required Associated Constants

const NAME: &'static str

What the group is called, in the emitted spec and in a failed check.

const FLAGS: &'static [&'static Flag<'static>]

One flag per variant, to splice into the holding command’s parse table.

A const for the same reason CommandArgs::COMMAND is: the tables stay static all the way down, so nothing is built at run time to start a parse.

const FLAG_METAS: &'static [FlagMeta<'static>]

Metadata for FLAGS, in the same order.

const MEMBERS: &'static [&'static str]

The selectors naming FLAGS, for GroupMeta::members.

Provided Associated Constants

const MULTIPLE: bool = false

Whether every member occurrence is retained rather than enforcing exclusivity.

Required Associated Types

type Partial: Default

Which members have been given so far. Partly-filled by construction, since a parse can stop early.

Required Methods

fn apply(partial: &mut Self::Partial, event: &Event<'_, '_, '_>) -> bool

Take one event, and say whether it named one of this group’s flags.

Keys are unique across a CLI, so an event that is not this group’s is left for whoever owns it.

fn any_given(partial: &Self::Partial) -> Option<&'static str>

The first member this command line gave, if any.

Named rather than a bare bool, so a parent enforcing exclusive across the group can say which flag it collided with — exactly as CommandArgs::any_given does.

fn conflict(partial: &Self::Partial) -> Option<(&'static str, &'static str)>

The first two members given together, in declaration order.

Exclusivity is the point of a group, so a second member is reported rather than silently resolved to whichever came last, and the pair is what the user has to choose between. Answered here rather than while binding for the same reason every other relationship is: the second member may still be ahead of the first.

fn build(partial: &Self::Partial) -> Option<Self>

The variant that was selected, or None when no member was given.

fn argument_state( partial: &Self::Partial, selector: &str, ) -> Option<ArgumentState>

Find a member by any selector it accepts.

Parents use this for requires / conflicts / conditional defaults that name a group member from beside the field — the same bridge CommandArgs::argument_state is for flattened argument groups.

fn argument_matches( partial: &Self::Partial, selector: &str, value: &[u8], ) -> Option<bool>

Whether a selected member is present as the given boolean value.

Members are switches, so only "true" / "false" are meaningful; anything else reports not matching rather than inventing a value.

fn displace(partial: &mut Self::Partial, selector: &str) -> bool

Clear the member named by selector after an overriding token wins.

fn event_matches(event: &Event<'_, '_, '_>, selector: &str) -> bool

Whether this event binds the member named by selector.

Provided Methods

fn start() -> Self::Partial

A fresh partial, with no member given.

Nothing to prepare, unlike CommandArgs::start: a group has no default variant, so there is no value that has to be in place before parsing begins.

fn try_build( partial: &Self::Partial, ) -> Result<Option<Self>, Error<'static, 'static>>

Build the selected variant, reporting a payload that could not be converted.

The default preserves hand-written implementations whose members are all switches. Derived groups with value-carrying variants override this and keep their raw word in Self::Partial until this step, just as an ordinary command field does.

fn try_build_many( partial: &Self::Partial, ) -> Result<Vec<Self>, Error<'static, 'static>>

Build every selected member in command-line order for a multiple group.

The default keeps hand-written exclusive groups source-compatible and gives a useful single-element answer when they are held by a collection accidentally; derived multiple groups override it with their ordered occurrence log.

fn standing_state(standing: &Self, selector: &str) -> Option<ArgumentState>

Self::argument_state for a value the caller already holds.

An update cannot recover the partial that produced this enum, so which member stands is read from the variant itself. None by default, which is what a hand-written implementation that does not take part in updates should say.

fn standing_matches( standing: &Self, selector: &str, value: &[u8], ) -> Option<bool>

Self::argument_matches for a value the caller already holds.

The twin of Self::standing_state, and needed for the same reason: a required_if_eq naming a member has to read the standing variant when this argv said nothing about the group, since the bytes it was parsed from are gone.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors