Struct FlagBuilder 

pub struct FlagBuilder { /* private fields */ }

Consuming builder for Flag.

Obtain via Flag::builder. Call FlagBuilder::build when done.

Examples

let flag = Flag::builder("output")
    .short('o')
    .description("Output format")
    .takes_value()
    .default_value("text")
    .build()
    .unwrap();

assert!(flag.takes_value);
assert_eq!(flag.default.as_deref(), Some("text"));

Implementations

impl FlagBuilder

pub fn short(self, c: char) -> Self

Set the short single-character form of this flag (e.g. 'v' for -v).

pub fn description(self, d: impl Into<String>) -> Self

Set the human-readable description shown in help output.

pub fn required(self) -> Self

Mark this flag as required.

The parser will return crate::ParseError::MissingFlag if the flag is absent from the invocation.

pub fn takes_value(self) -> Self

Mark this flag as value-taking.

When set, the parser expects either --name=value or --name value syntax. Without this, the flag is boolean and the mere presence of the flag sets the value to "true".

pub fn default_value(self, d: impl Into<String>) -> Self

Set the default value used when this flag is not provided.

Only meaningful for optional (!required) value-taking flags. If the flag is absent from the invocation, the default is inserted into crate::ParsedCommand::flags automatically by the parser.

pub fn choices( self, choices: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Restrict this flag’s value to one of the given choices.

Only meaningful for value-taking flags (takes_value()). The parser returns crate::ParseError::InvalidChoice if the provided value is not in the list.

Examples

let flag = Flag::builder("format")
    .takes_value()
    .choices(["json", "yaml", "text"])
    .build()
    .unwrap();
let expected: Vec<String> = vec!["json".into(), "yaml".into(), "text".into()];
assert_eq!(flag.choices.as_deref(), Some(expected.as_slice()));

pub fn repeatable(self) -> Self

Allow this flag to be specified more than once.

For boolean flags: occurrences are counted and stored as a numeric string. For value-taking flags: values are collected into a JSON array string.

Examples

let flag = Flag::builder("verbose").repeatable().build().unwrap();
assert!(flag.repeatable);

pub fn env(self, var_name: impl Into<String>) -> Self

Register an environment variable as a fallback source for this flag.

When the flag is not provided on the command line, the parser calls std::env::var(var_name). If the variable is set and non-empty, its value is used (validated against choices if set). The full lookup order is: CLI → env var → default value → required error.

Examples

let flag = Flag::builder("token").takes_value().env("DEPLOY_TOKEN").build().unwrap();
assert_eq!(flag.env.as_deref(), Some("DEPLOY_TOKEN"));

pub fn build(self) -> Result<Flag, BuildError>

Consume the builder and return a Flag.

Errors

Returns BuildError::EmptyCanonical if the flag name is empty or consists entirely of whitespace.

Examples

assert!(Flag::builder("verbose").build().is_ok());
assert_eq!(Flag::builder("").build().unwrap_err(), BuildError::EmptyCanonical);