Struct SpecFlag 

#[non_exhaustive]
pub struct SpecFlag {

    pub name: String,
    pub usage: String,
    pub help: Option<String>,
    pub help_long: Option<String>,
    pub help_md: Option<String>,
    pub help_first_line: Option<String>,
    pub short: Vec<char>,
    pub hidden_short_aliases: Vec<char>,
    pub long: Vec<String>,
    pub hidden_aliases: Vec<String>,
    pub required: bool,
    pub required_if: Vec<String>,
    pub required_if_eq: Vec<SpecRequiredIfEq>,
    pub required_if_eq_all: Vec<SpecRequiredIfEq>,
    pub required_unless: Vec<String>,
    pub required_unless_all: Vec<String>,
    pub deprecated: Option<String>,
    pub deprecated_warn_at: Option<String>,
    pub deprecated_remove_at: Option<String>,
    pub var: bool,
    pub var_min: Option<usize>,
    pub var_max: Option<usize>,
    pub hide: bool,
    pub hide_default_value: bool,
    pub hide_env: bool,
    pub hide_env_values: bool,
    pub hide_possible_values: bool,
    pub hide_short_help: bool,
    pub hide_long_help: bool,
    pub global: bool,
    pub count: bool,
    pub arg: Option<SpecArg>,
    pub default: Vec<String>,
    pub negate: Option<String>,
    pub overrides: Vec<String>,
    pub conflicts: Vec<String>,
    pub requires: Vec<String>,
    pub requires_if: Vec<SpecRequiresIf>,
    pub default_if: Vec<SpecDefaultIf>,
    pub exclusive: bool,
    pub require_equals: bool,
    pub value_optional: bool,
    pub bool_value: bool,
    pub default_missing: Option<String>,
    pub effect: Option<SpecCommandEffect>,
    pub env: Option<String>,
    pub env_fallback: Vec<String>,
    pub deprecated_env: Vec<String>,
    pub help_heading: Option<String>,
    pub display_order: Option<usize>,
    pub action: SpecFlagAction,
}

A CLI flag/option specification.

Flags are optional arguments that start with - (short) or -- (long). They can be boolean switches or accept values.

Example

use usage::SpecFlag;

let flag = SpecFlag::builder()
    .short('v')
    .long("verbose")
    .help("Enable verbose output")
    .build();

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

Internal name for the flag (derived from long/short if not set)

usage: String

Generated usage string (e.g., “-v, –verbose”)

help: Option<String>

Short help text shown in command listings

help_long: Option<String>

Extended help text shown with –help

help_md: Option<String>

Markdown-formatted help text

help_first_line: Option<String>

First line of help text (auto-generated)

short: Vec<char>

Short flag characters (e.g., ‘v’ for -v)

hidden_short_aliases: Vec<char>

Short aliases accepted by parsing but omitted from help and completion.

long: Vec<String>

Long flag names (e.g., “verbose” for –verbose)

hidden_aliases: Vec<String>

Long aliases accepted by parsing but omitted from help and completion.

required: bool

Whether this flag must be provided

required_if: Vec<String>

Flags whose presence makes this flag required

required_if_eq: Vec<SpecRequiredIfEq>

Value conditions, any one of which makes this flag required.

required_if_eq_all: Vec<SpecRequiredIfEq>

Value conditions which must all match to make this flag required.

required_unless: Vec<String>

Flags whose absence makes this flag required

required_unless_all: Vec<String>

Only the presence of every selector waives this flag’s requirement.

deprecated: Option<String>

Deprecation message if this flag is deprecated

deprecated_warn_at: Option<String>

Version at which consumers should begin warning about this flag.

deprecated_remove_at: Option<String>

Version at which consumers expect this flag to be removed.

var: bool

Whether this flag can be specified multiple times

var_min: Option<usize>

Minimum number of times this flag must appear (for var flags)

var_max: Option<usize>

Maximum number of times this flag can appear (for var flags)

hide: bool

Whether to hide this flag from help output

hide_default_value: bool

Hide the default annotation while keeping the default behavior.

hide_env: bool

Hide the environment annotation entirely.

hide_env_values: bool

Hide an environment value while retaining its variable name.

hide_possible_values: bool

Hide possible values from help without changing validation.

hide_short_help: bool

Hide this flag only from short help.

hide_long_help: bool

Hide this flag only from long help.

global: bool

Whether this flag is available to all subcommands

count: bool

Whether this is a count flag (e.g., -vvv counts as 3)

arg: Option<SpecArg>

Argument specification if this flag takes a value

default: Vec<String>

Default value(s) if the flag is not provided

negate: Option<String>

Negation prefix (e.g., “no-” for –no-verbose)

overrides: Vec<String>

Flags that this flag mutually overrides; the last one provided wins

conflicts: Vec<String>

Flags that cannot be given alongside this one.

Distinct from SpecFlag::overrides, which is about the last one winning: conflicting flags are a mistake to report, not an order to resolve. clap has had conflicts_with for years and mise uses it forty times, so a spec generated from a clap command was losing it.

requires: Vec<String>

Flags that must also be given when this one is.

The positive form of SpecFlag::conflicts, and not the same statement as SpecFlag::required_if read backwards: required_if lives on the flag that becomes required, so declaring --out needs --format means editing --format, away from the flag the rule is about. requires lives on the flag that imposes the rule, which is where clap puts it and where a reader looks for it.

Nothing generated from a clap command can carry this: clap 4.6 has Arg::requires and its variants as setters with no getter, so a Command cannot be asked what it requires. A CLI that declares it here gains a constraint its generated spec never had.

requires_if: Vec<SpecRequiresIf>

Flags required when this flag is explicitly given a particular value.

Defaults do not activate the condition; command-line and environment values do. This matches clap’s requires_if/requires_ifs semantics.

default_if: Vec<SpecDefaultIf>

Defaults that apply when another flag is given.

First match wins. Only considered when this flag was not on the command line and has no environment value. An applied default_if is a default, not an explicit value: it satisfies requires and does not activate requires_if.

exclusive: bool

Whether this flag must be given on its own.

The whole-command form of SpecFlag::conflicts: --version and --help are the shape — asking for one means the rest of the command line has nothing to act on. Everything the command declares counts, positionals included, which is what makes this different from being in a group with every other flag.

require_equals: bool

Whether the value must be attached with =: --flag=value is accepted and --flag value is not. clap’s require_equals. Aube’s --inspect is the fleet case.

value_optional: bool

Whether a value-taking flag may be present without a value.

This is executable parser policy, distinct from the nested argument’s required bit, which controls whether help renders <VALUE> or [VALUE].

bool_value: bool

Whether a boolean switch accepts an explicit attached value.

Only --flag=true and --flag=false are values; a detached word remains a positional and the flag still renders without a value placeholder.

default_missing: Option<String>

Value used when the flag is present but no value is given.

clap’s default_missing_value: --color binds this string, --color=never binds never, and an absent flag stays absent (or takes Self::default). Combined with Self::require_equals, a following word is still refused (--inspect 9229) while a bare --inspect binds this.

clap 4 exposes this as a setter with no getter, so a spec generated from a clap command never carries it — same hole as Self::requires.

effect: Option<SpecCommandEffect>

Raises the effect of the command when this flag is supplied. See crate::spec::effect::SpecCommandEffect; never lowers it.

env: Option<String>

Environment variable that can set this flag’s value

env_fallback: Vec<String>

Ordered environment variables consulted after Self::env.

deprecated_env: Vec<String>

Ordered compatibility aliases consulted last and advertised as deprecated.

help_heading: Option<String>

Heading this flag is listed under in help output.

Purely presentational: it groups a long flag list into sections rather than changing how anything parses. A CLI with dozens of flags — mise groups its watch passthrough arguments this way — is unreadable without it.

display_order: Option<usize>

Explicit placement within its help section.

action: SpecFlagAction

Whether this flag binds a value or requests help/version output.

Implementations

impl SpecFlag

pub fn builder() -> SpecFlagBuilder

Create a new builder for SpecFlag

pub fn env_names(&self) -> impl Iterator<Item = &str>

Environment sources in precedence order: canonical, fallbacks, deprecated aliases.

pub fn allow_hyphen_values(&self) -> bool

pub fn usage(&self) -> String

Trait Implementations

impl Clone for SpecFlag

fn clone(&self) -> SpecFlag

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SpecFlag

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

Formats the value using the given formatter.

impl Default for SpecFlag

fn default() -> SpecFlag

Returns the “default value” for a type.

impl Display for SpecFlag

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

Formats the value using the given formatter.

impl Eq for SpecFlag

impl From<&SpecFlag> for KdlNode

fn from(flag: &SpecFlag) -> KdlNode

Converts to this type from the input type.

impl FromStr for SpecFlag

type Err = UsageErr

The associated error which can be returned from parsing.

fn from_str(input: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl Hash for SpecFlag

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for SpecFlag

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for SpecFlag

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.