Crate polyflag 

Repeatable comma-separated set-style cli flags.

Given a fixed list of known tokens, parse one occurrence of a flag whose value is a comma-separated list of those tokens, accumulating into a HashSet. A - prefix on a token removes it from the set instead of adding. Unknown tokens error.

Each KnownToken has a single canonical spelling plus zero or more Aliases. Aliases let multiple input spellings (e.g. nocolor and no-color) resolve to the same canonical entry, so callers test set.contains("nocolor") regardless of which spelling the user typed.

Designed for flags like --quirks=foo,bar --quirks=-foo where the final state is {bar}. Order across flag occurrences matters; order within a single occurrence also matters (left-to-right).

Resolution complexity is O(input_tokens x canonicals x aliases). Fine for the small flag tables this crate targets; do not graft a runtime plugin loader on top.

Example

use std::collections::HashSet;
use polyflag::{KnownToken, apply, token};

const KNOWN: &[KnownToken] = &[
    token!("foo"),
    token!("bar"; "barre"),
    token!("baz"; "baz-alt", deprecated "old-baz"),
];
let mut set: HashSet<&'static str> = HashSet::new();

apply("foo,barre", KNOWN, &mut set).unwrap();
apply("baz",       KNOWN, &mut set).unwrap();
apply("bar,-foo",  KNOWN, &mut set).unwrap();

assert!(set.contains("bar") && set.contains("baz"));
assert!(!set.contains("foo"));
// aliases never live in the set; only canonicals do.
assert!(!set.contains("barre"));

Macros

debug_check_known

Wrap check_known in a debug_assert!-shaped call site. Identical runtime semantics to calling check_known directly (both are stripped in release), but makes intent unambiguous at the call site:

token

Construct a KnownToken tersely.

Structs

Alias

One alias spelling for a KnownToken.

KnownToken

One entry in the caller’s known-token table: a canonical spelling plus zero or more aliases that resolve to it, and an optional default marker for tokens that should be in the set before any cli/env input.

Resolved

Result of resolving one input token against a known-token list.

UnknownToken

Returned when an input token (with any leading - stripped) does not appear as a canonical or alias in the caller’s known list.

Enums

AliasStatus

How an alias is treated by callers that surface user-facing messaging.

ResolvedKind

Why an input matched – mirrors AliasStatus plus a ResolvedKind::Canonical variant for canonical-spelling input.

Functions

apply

Apply one occurrence of a set flag’s value to set.

apply_env_for_flag

Apply an env-var-sourced default for the named cli flag to set.

apply_env_for_flag_with_callback

Like apply_env_for_flag, but threads a deprecation callback through to apply_with_callback.

apply_with_callback

Like apply, but invokes on_deprecated(input_spelling, canonical) each time an input token resolves through a AliasStatus::Deprecated alias. Hidden aliases never call back; canonicals and Alternative aliases never call back.

canonicalize

Look up input (one bare token, no - prefix) against known. Returns the canonical entry and how the input matched. None if the input is not a canonical or alias for any known token.

check_known

defaults

Seed a fresh HashSet with the canonicals of every KnownToken marked default = true. Use as the starting set before applying any env-var or cli occurrences, so the caller’s table doubles as both the schema and the on-by-default policy.

env_var_name

Compute the env var name corresponding to a flag, using the same derivation as apply_env_for_flag. Exposed so callers can include the resolved name in error messages without repeating the rule.

format_known_for_help

Render the known-token table as a comma-separated string suitable for embedding in help text or error messages. Canonicals are joined with ", "; non-AliasStatus::Hidden aliases for each canonical are listed parenthetically. Hidden aliases are omitted (that’s their point).