flagalias

Documentation

Overview

Package flagalias owns parse-time aliases for Cobra/pflag commands.

An alias is another accepted spelling of one canonical flag. It is not a second pflag: parsing an alias resolves to the canonical flag before pflag applies the value, so type, default, Changed state, required/enum/input contracts, and repeated-flag behavior all stay attached to one object.

Value conversion for non-equivalent legacy inputs is a business compatibility concern, not an alias. Exact aliases always use the canonical flag's native occurrence semantics; domains must not add a separate conflict policy.

Index

• Constants
• func Aliases(flag *pflag.Flag) []string
• func Bind(cmd *cobra.Command, specs []Spec) error
• func InstallNormalizer(cmd *cobra.Command, rewrite func(name string) string)
• func MustBind(cmd *cobra.Command, specs []Spec)
• func Source(flag *pflag.Flag) string
• type InvalidValueAttribution
  • func InvalidValueAttributionOf(err error) (InvalidValueAttribution, bool)
• type Spec

Constants

const AnnotationAliases = "lark-cli/flag-aliases"

AnnotationAliases is attached to the canonical pflag. Consumers should use Aliases instead of reading the annotation directly.

Functions

func Aliases

func Aliases(flag *pflag.Flag) []string

Aliases returns a defensive copy of the raw accepted alias spellings stored on a canonical pflag. Alias order matches declaration order.

func Bind

func Bind(cmd *cobra.Command, specs []Spec) error

Bind installs exact-name aliases on cmd and records them on their canonical pflags for manifest/tooling introspection. Existing pflag normalization is composed first; alias resolution is then applied to the normalized spelling. The canonical pflag also remembers the spelling that supplied its most recently applied value so validation errors can point back to the caller's actual input without changing native repeated-flag semantics.

Bind is intentionally the only production owner of SetNormalizeFunc. It validates the complete accepted-name set before installing alias metadata or a normalizer, so a configuration error cannot leave aliases partially bound.

func InstallNormalizer

func InstallNormalizer(cmd *cobra.Command, rewrite func(name string) string)

InstallNormalizer composes an invisible parse-time flag-name rewrite onto cmd, chaining any normalizer already installed (its result feeds the next stage). Unlike Bind it records nothing on the canonical flags: rewrite is for spellings that must be accepted but must not surface as aliases in --help or the exported manifest — underscore folding, or domain compatibility forms a domain wants silently corrected rather than advertised. Keeping the call here preserves this package as the sole owner of SetNormalizeFunc (see the flag_alias_normalizer_owner source-contract lint), so Bind's alias mapping and a domain's normalizer compose in install order regardless of which ran first.

func MustBind

func MustBind(cmd *cobra.Command, specs []Spec)

MustBind is the flag-registration form of Bind. Cobra/pflag registration already treats duplicate or invalid flag definitions as programmer errors; MustBind preserves that startup-fail-fast contract for callers whose mount API does not return an error.

func Source

func Source(flag *pflag.Flag) string

Source returns the spelling that supplied the canonical flag's most recently applied value. It returns the canonical name when no alias occurrence has been applied. The returned name never includes leading dashes.

Types

type InvalidValueAttribution

type InvalidValueAttribution struct {
	Canonical string
	Source    string
}

InvalidValueAttribution identifies the canonical flag and the long-form spelling that supplied a value which pflag could not convert. Names do not include leading dashes.

func InvalidValueAttributionOf

func InvalidValueAttributionOf(err error) (InvalidValueAttribution, bool)

InvalidValueAttributionOf resolves a typed pflag conversion error for a flag managed by Bind. Ordinary pflags return ok=false so installing aliases does not broaden the root error contract for unrelated commands.

pflag's InvalidValueError does not report whether a canonical flag with a shorthand was supplied as -x or --long. That ambiguous case also returns ok=false; an alias spelling remains unambiguous because Bind records it before value conversion.

type Spec

type Spec struct {
	Canonical string
	Aliases   []string
}

Spec binds Aliases to one Canonical long-flag name. Names do not include the leading "--".