Trait CommandArgs 

pub trait CommandArgs: Sized {
    type Partial;

    const COMMAND: &'static Command<'static>;
    const META: &'static CommandMeta<'static>;
    const SETTINGS_BINDINGS: &'static [(&'static str, &'static str)] = _;

    // Required methods
    fn start() -> Self::Partial;
    fn apply(partial: &mut Self::Partial, event: &Event<'_, '_, '_>) -> bool;
    fn build<'t, 'v>(partial: Self::Partial) -> Result<Self, Error<'t, 'v>>;

    // Provided methods
    fn apply_mirrored_global(
        partial: &mut Self::Partial,
        event: &Event<'_, '_, '_>,
    ) -> bool { ... }
    fn settings_given(
        partial: &Self::Partial,
    ) -> Vec<(&'static str, SettingGiven)> { ... }
    fn any_given(partial: &Self::Partial) -> Option<&'static str> { ... }
    fn exclusive_given(partial: &Self::Partial) -> Option<&'static str> { ... }
    fn deprecations(partial: &Self::Partial, out: &mut Vec<Warning<'static>>) { ... }
    fn deprecations_for_view_path(
        partial: &Self::Partial,
        remaining_descendants: usize,
        out: &mut Vec<Warning<'static>>,
    ) { ... }
    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 { ... }
    fn apply_defaults(partial: &mut Self::Partial) { ... }
    fn apply_defaults_for_view(
        partial: &mut Self::Partial,
        view: Option<&'static ViewMeta<'static>>,
    ) { ... }
    fn apply_env(partial: &mut Self::Partial) { ... }
    fn apply_env_for_view(
        partial: &mut Self::Partial,
        view: Option<&'static ViewMeta<'static>>,
    ) { ... }
    fn apply_env_for_view_path(
        partial: &mut Self::Partial,
        remaining_descendants: usize,
    ) { ... }
    fn check<'t, 'v>(partial: &mut Self::Partial) -> Result<(), Error<'t, 'v>> { ... }
    fn check_with_args_override_self<'t, 'v>(
        partial: &mut Self::Partial,
        args_override_self: bool,
    ) -> Result<(), Error<'t, 'v>> { ... }
    fn check_with_args_override_self_for_view<'t, 'v>(
        partial: &mut Self::Partial,
        args_override_self: bool,
        view: Option<&'static ViewMeta<'static>>,
    ) -> Result<(), Error<'t, 'v>> { ... }
    fn check_for_view_path<'t, 'v>(
        partial: &mut Self::Partial,
        remaining_descendants: usize,
    ) -> Result<(), Error<'t, 'v>> { ... }
    fn omit_own_for_view(partial: &mut Self::Partial) { ... }
    fn any_standing(standing: &Self) -> Option<&'static str> { ... }
    fn apply_defaults_update(partial: &mut Self::Partial, standing: &Self) { ... }
    fn apply_env_update(partial: &mut Self::Partial, standing: &Self) { ... }
    fn check_update<'t, 'v>(
        partial: &mut Self::Partial,
        standing: &Self,
    ) -> Result<(), Error<'t, 'v>> { ... }
    fn check_update_with_args_override_self<'t, 'v>(
        partial: &mut Self::Partial,
        args_override_self: bool,
        standing: &Self,
    ) -> Result<(), Error<'t, 'v>> { ... }
    fn merge<'t, 'v>(
        partial: Self::Partial,
        standing: &mut Self,
    ) -> Result<(), Error<'t, 'v>> { ... }
}

Required Associated Constants

const COMMAND: &'static Command<'static>

The parse tables for this command.

A const rather than a method, because a parent splices it into its own static tables and a method call is not allowed there. That is the whole reason this trait exists: the tables stay static all the way down, so nothing is built at run time to start a parse.

const META: &'static CommandMeta<'static>

The metadata for this command.

Provided Associated Constants

const SETTINGS_BINDINGS: &'static [(&'static str, &'static str)] = _

Every flag this command reads into a setting, and the setting it sets.

Empty by default, so a command that binds nothing implements nothing and a parent can ask any command without knowing which kind it got. What a parent joins into its own table, and what usage_config::Registry::drift is held against.

Required Associated Types

type Partial

Values collected so far. Partly-filled by construction, since a parse can stop early.

No Default bound: CommandArgs::start is what produces a fresh one, because a command with subcommands of its own has nested state that a derived Default cannot set up.

Required Methods

fn start() -> Self::Partial

A partial with any declared defaults already in place.

Not Default::default(), because a default has to be there before parsing starts: nothing afterwards distinguishes it from what the user typed.

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

Take one event, and say whether it belonged to this command.

Keys are unique across a CLI, so an event that is not this command’s is left for whoever owns it rather than mistaken for a local field.

fn build<'t, 'v>(partial: Self::Partial) -> Result<Self, Error<'t, 'v>>

Build the struct from what was collected.

Fallible because a command can require a subcommand of its own, and “none was given” is only knowable here — at the point where the value has to exist.

Provided Methods

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

Mirror a redeclared child flag’s value into this command’s matching global field.

This deliberately skips occurrence and relationship bookkeeping: the token was parsed against the child’s declaration, so policies such as exclusive and overrides belong to that declaration even though clap-compatible typed access exposes the value at both levels. The default keeps hand-written implementations source compatible.

fn settings_given(partial: &Self::Partial) -> Vec<(&'static str, SettingGiven)>

The settings this command line gave values for.

From the partial rather than from the built struct, and only for flags that were actually given: a bool field is false whether the flag was left off or negated, and the command line outranks every file on the machine.

Empty by default, for the same reason as CommandArgs::SETTINGS_BINDINGS.

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

One declaration in this command that ended up being given, if any.

Used to enforce relationships across a flattened CommandArgs boundary, where the parent can see the nested partial only through this trait.

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

One exclusive flag in this command that was given, if any.

Like CommandArgs::any_given, this is the composition point for flattened argument groups and selected subcommands. Parents need the latter to apply whole-invocation exclusivity and its requiredness escape across a command boundary.

fn deprecations(partial: &Self::Partial, out: &mut Vec<Warning<'static>>)

The deprecated declarations this command line actually used.

Read from the partial rather than from the built struct, because a struct cannot answer what the parse saw: a bool field is false whether the flag was absent or negated. Asked after the environment has been applied, since a value that arrived through a variable used the deprecated declaration just as much as a typed word did — while a declared default is nothing anybody asked for, and does not warn.

The milestone gate is deliberately not applied here. A nested command’s tables say nothing about the root’s version, and a CLI with a computed runtime_version only settles it at run time, so crate::warn::retain_reached is applied once by the entry point that knows it.

Empty by default, like the rest of the composition points, so a hand-written implementation with nothing to report is not forced to say so.

fn deprecations_for_view_path( partial: &Self::Partial, remaining_descendants: usize, out: &mut Vec<Warning<'static>>, )

Report deprecations while traversing the injected parents of a view.

remaining_descendants is non-zero only for commands that are routing to the promoted command rather than contributing their own surface, exactly as CommandArgs::check_for_view_path means it. Those commands are structural under the view — the program’s own identity — so nothing about them is reported.

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

Find an argument by any selector it accepts.

Parents use this to enforce a relationship declared beside a flattened argument group. The default keeps hand-written implementations source compatible.

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

Whether a selected argument has an explicitly supplied value.

This is the value-aware half needed by conditional defaults and requirements.

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

Reset the flag named by selector after an overriding token wins.

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

Whether this event binds the flag named by selector.

fn apply_defaults(partial: &mut Self::Partial)

Fill fields in this command from their declared defaults.

Kept separate from CommandArgs::check so a parent can preserve defaults in a flattened argument group while an unrelated exclusive flag suppresses only that group’s missing-value checks.

fn apply_defaults_for_view( partial: &mut Self::Partial, view: Option<&'static ViewMeta<'static>>, )

Fill defaults for fields visible through an executable view.

Derived implementations filter flattened root arguments to selected globals. The default preserves hand-written implementations and ordinary parsing behavior.

fn apply_env(partial: &mut Self::Partial)

Fill fields in this command from their declared environment variables.

A parent calls this before relationships that cross a flattened CommandArgs boundary, so those relationships see the same values as the nested command’s own checks. Empty by default for hand-written implementations.

fn apply_env_for_view( partial: &mut Self::Partial, view: Option<&'static ViewMeta<'static>>, )

Fill environment fallbacks for fields visible through an executable view.

fn apply_env_for_view_path( partial: &mut Self::Partial, remaining_descendants: usize, )

Fill environment fallbacks while traversing the injected parents of a view.

remaining_descendants is non-zero only for commands that are routing to the promoted command rather than contributing their own surface. Derived commands recurse through their selected subcommand without applying their own fallbacks.

fn check<'t, 'v>(partial: &mut Self::Partial) -> Result<(), Error<'t, 'v>>

Everything this command decides after the last token: required-ness, choices, and how many values a variadic got.

Separate from CommandArgs::build because only the command that was actually reached is judged — a flag that install requires says nothing about an invocation that ran run. Defaulted, so a hand-written implementation with nothing to check is not forced to say so — and adding a check to the derive does not break one.

fn check_with_args_override_self<'t, 'v>( partial: &mut Self::Partial, args_override_self: bool, ) -> Result<(), Error<'t, 'v>>

Run checks under the repeat policy of the command that composed these args.

A flattened argument group is part of its parent’s command, so the parent’s args_override_self setting governs repeats in the group as well. Hand-written implementations keep their existing behavior through this default.

fn check_with_args_override_self_for_view<'t, 'v>( partial: &mut Self::Partial, args_override_self: bool, view: Option<&'static ViewMeta<'static>>, ) -> Result<(), Error<'t, 'v>>

Run checks under a parent command’s repeat policy and executable projection.

fn check_for_view_path<'t, 'v>( partial: &mut Self::Partial, remaining_descendants: usize, ) -> Result<(), Error<'t, 'v>>

Check a command while traversing the injected parents of a view.

An injected parent is structural: its own defaults and validation do not belong to the promoted executable. Derived commands recurse until the promoted command, which is then checked normally.

fn omit_own_for_view(partial: &mut Self::Partial)

Mark this command’s own fields as outside an injected executable-view path.

Derived implementations propagate the marker through flattened argument groups so building the enclosing Rust value uses typed defaults instead of parsing empty argv.

fn any_standing(standing: &Self) -> Option<&'static str>

One declaration in this command whose value the caller already had.

The standing counterpart of CommandArgs::any_given, and the reason it is asked of the built struct rather than of a partial: an update merges a parse into a value the caller owns, and a value cannot be run backwards through FromStr into the bytes a partial holds. So presence is what the type itself can answer — a filled Option, a collection with items, a set switch — and a plain value is always present.

None by default, which is what a hand-written implementation that does not take part in updates should say.

fn apply_defaults_update(partial: &mut Self::Partial, standing: &Self)

CommandArgs::apply_defaults, filling only what the caller does not already have.

A default never overwrites a value the caller set deliberately, so an update with no relevant argv cannot change the struct.

fn apply_env_update(partial: &mut Self::Partial, standing: &Self)

CommandArgs::apply_env, filling only what the caller does not already have.

fn check_update<'t, 'v>( partial: &mut Self::Partial, standing: &Self, ) -> Result<(), Error<'t, 'v>>

CommandArgs::check against the union of this argv and what the caller had.

Required-ness, conflicts and the rest see a field the caller already filled as present, so an update validates both inputs together rather than this argv alone.

fn check_update_with_args_override_self<'t, 'v>( partial: &mut Self::Partial, args_override_self: bool, standing: &Self, ) -> Result<(), Error<'t, 'v>>

CommandArgs::check_with_args_override_self against the same union.

fn merge<'t, 'v>( partial: Self::Partial, standing: &mut Self, ) -> Result<(), Error<'t, 'v>>

Overwrite the fields this argv gave, and leave the rest of standing alone.

The default replaces the whole value, which is all a hand-written implementation that cannot see its own fields can promise. A derived one merges field by field: a field this command line said nothing about keeps the value it had.

Dyn Compatibility

This trait is not dyn compatible.

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

Implementors