Enum Attr 

#[repr(u8)]
pub enum Attr {
    Positional,
    Named,
    Short(Option<char>),
    Subcommand,
    Counted,
    Config,
    EnvPrefix(Option<&'static str>),
    EnvAlias(&'static str),
    EnvSubst,
    EnvSubstAll,
    Help,
    Version,
    Completions,
    Origin(&'static str),
    Label(&'static str),
}

Args attribute types for field configuration.

Variants

Positional

Marks a field as a positional argument.

Usage: #[facet(args::positional)]

Named

Marks a field as a named argument.

Usage: #[facet(args::named)]

Short(Option<char>)

Specifies a short flag character for the field.

Usage: #[facet(args::short = 'v')] or just #[facet(args::short)]

Subcommand

Marks a field as a subcommand.

The field type must be an enum where each variant represents a subcommand. Variant names are converted to kebab-case for matching.

Usage: #[facet(args::subcommand)]

Counted

Marks a field as a counted flag.

Each occurrence of the flag increments the count. Works with both short flags (-vvv or -v -v -v) and long flags (--verbose --verbose). The field type must be an integer type (u8, u16, u32, u64, usize, i8, i16, i32, i64, isize). Uses saturating arithmetic to avoid overflow.

Usage: #[facet(args::named, args::short = 'v', args::counted)]

Config

Marks a field as a layered configuration field.

The field will be populated from merged configuration sources (CLI overrides, environment variables, config files) in priority order: CLI > env > file > default.

This automatically generates:

• --{field_name} <PATH> flag to specify config file path
• --{field_name}.foo.bar <VALUE> style CLI overrides
• Environment variable parsing
• Config file loading with multiple format support

Usage: #[facet(args::config)]

EnvPrefix(Option<&'static str>)

Specifies the environment variable prefix for a config field.

Must be used together with #[facet(args::config)].

Usage: #[facet(args::env_prefix = "MYAPP")]

Example: env_prefix = "MYAPP" results in MYAPP__FIELD__NAME env vars.

EnvAlias(&'static str)

Specifies an additional environment variable name for a config field.

This allows a field to be read from standard environment variables like DATABASE_URL or PORT in addition to the prefixed form.

The prefixed env var takes priority over aliases when both are set. Multiple aliases can be specified by using the attribute multiple times.

Usage: #[facet(args::env_alias = "DATABASE_URL")]

Example:

#[derive(Facet)]
struct Config {
    /// Also reads from $DATABASE_URL
    #[facet(args::env_alias = "DATABASE_URL")]
    database_url: String,

    /// Reads from $PORT or $HTTP_PORT
    #[facet(args::env_alias = "PORT", args::env_alias = "HTTP_PORT")]
    port: u16,
}

EnvSubst

Enables environment variable substitution for this field.

When enabled, ${VAR} patterns in the field’s value will be replaced with the corresponding environment variable. Supports default values with ${VAR:-default} syntax. Use $$ to escape a literal $.

Usage: #[facet(args::env_subst)]

Example:

#[derive(Facet)]
struct Config {
    #[facet(args::env_subst)]
    data_dir: PathBuf,  // "${BASE_PATH}/data" -> "/var/myapp/data"
}

EnvSubstAll

Enables environment variable substitution for all direct fields in a struct.

This is equivalent to adding #[facet(args::env_subst)] to each direct field. Does not propagate to nested structs (mirrors rename_all behavior), but does apply to flattened fields since they become direct children.

Usage: #[facet(args::env_subst_all)]

Example:

#[derive(Facet)]
#[facet(args::env_subst_all)]
struct Config {
    data_dir: PathBuf,   // gets env_subst
    cache_dir: PathBuf,  // gets env_subst
    nested: Other,       // nested.field does NOT get env_subst
}

Help

Marks a field as the help flag.

When this flag is set, the driver shows help and exits with code 0. The field should be a bool.

Usage: #[facet(figue::help)]

Version

Marks a field as the version flag.

When this flag is set, the driver shows version and exits with code 0. The field should be a bool.

Usage: #[facet(figue::version)]

Completions

Marks a field as the completions flag.

When this flag is set, the driver generates shell completions and exits with code 0. The field should be Option<Shell>.

Usage: #[facet(figue::completions)]

Origin(&'static str)

Specifies the origin path for field extraction.

Used in “requirements structs” to indicate which field from the parsed config should be extracted into this field. The path uses dot notation to navigate nested structures.

Usage: #[facet(args::origin = "config.database_url")]

Example:

use figue as args;

#[derive(Facet)]
struct MigrateRequirements {
    #[facet(args::origin = "config.database_url")]
    database_url: String,  // Required for this context

    #[facet(args::origin = "config.migrations_path")]
    migrations_path: PathBuf,
}

Label(&'static str)

Specifies a custom label for the help message.

When provided, this string is used instead of the Rust type name in the generated help (e.g., <MY_TYPE> instead of <STRING>).

Usage: #[facet(args::label = "MY_TYPE")]

Trait Implementations

impl Clone for Attr

fn clone(&self) -> Attr

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Attr

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

Formats the value using the given formatter.

impl<'ʄ> Facet<'ʄ> for Attr

const SHAPE: &'static Shape

The shape of this type, including: whether it’s a Struct, an Enum, something else?

impl PartialEq for Attr

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.