flag

Documentation

Overview

Package flag provides a command line flag definition and parsing library.

Flag is intentionally internal so the only interaction is via the Flag option on a command.

Index

• func AddToSet[T flag.Flaggable](set *Set, f *Flag[T]) error
• type Config
• type Flag
  • func New[T flag.Flaggable](p *T, name string, short rune, usage string, config Config[T]) (*Flag[T], error)
  • func (f *Flag[T]) Default() string
  • func (f *Flag[T]) EnvVar() string
  • func (f *Flag[T]) IsSlice() bool
  • func (f *Flag[T]) Name() string
  • func (f *Flag[T]) NoArgValue() string
  • func (f *Flag[T]) Set(str string) error
  • func (f *Flag[T]) Short() rune
  • func (f *Flag[T]) String() string
  • func (f *Flag[T]) Type() string
  • func (f *Flag[T]) Usage() string
• type Set
  • func NewSet() *Set
  • func (s *Set) All() iter.Seq2[string, Value]
  • func (s *Set) Args() []string
  • func (s *Set) ExtraArgs() []string
  • func (s *Set) Get(name string) (Value, bool)
  • func (s *Set) GetShort(short rune) (Value, bool)
  • func (s *Set) Help() (value, ok bool)
  • func (s *Set) Parse(args []string) error
  • func (s *Set) Sorted() iter.Seq2[string, Value]
  • func (s *Set) Version() (value, ok bool)
• type Value

Functions

func AddToSet

func AddToSet[T flag.Flaggable](set *Set, f *Flag[T]) error

AddToSet adds a flag to the given Set.

Types

type Config

type Config[T flag.Flaggable] struct {
	// DefaultValue holds the intended default value of the flag.
	DefaultValue T
	// EnvVar is the name of an environment variable that may set this flag's value
	// if the flag is not explicitly provided on the command line.
	EnvVar string
}

Config represents the internal configuration of a Flag.

type Flag

type Flag[T flag.Flaggable] struct {
	// contains filtered or unexported fields
}

Flag represents a single command line flag.

func New

func New[T flag.Flaggable](p *T, name string, short rune, usage string, config Config[T]) (*Flag[T], error)

New constructs and returns a new Flag.

The name should be as it appears on the command line, e.g. "force" for a --force flag. An optional shorthand can be created by setting short to a single letter value, e.g. "f" to also create a -f version of "force".

func (*Flag[T]) Default

func (f *Flag[T]) Default() string

Default returns the default value for the flag, as a string.

If the flag's default is unset (i.e. the zero value for its type), an empty string is returned.

func (*Flag[T]) EnvVar

func (f *Flag[T]) EnvVar() string

EnvVar returns the name of the environment variable associated with this flag, or an empty string if none was configured.

func (*Flag[T]) IsSlice

func (f *Flag[T]) IsSlice() bool

IsSlice reports whether the flag holds a slice value that accumulates repeated calls to Set. Returns false for []byte and net.IP, which are parsed atomically.

func (*Flag[T]) Name

func (f *Flag[T]) Name() string

Name returns the name of the Flag.

func (*Flag[T]) NoArgValue

func (f *Flag[T]) NoArgValue() string

NoArgValue returns a string representation of value the flag should hold when it is given no arguments on the command line. For example a boolean flag --delete, when passed without arguments implies --delete true.

func (*Flag[T]) Set

func (f *Flag[T]) Set(str string) error

Set sets a Flag value based on string input, i.e. parsing from the command line.

func (*Flag[T]) Short

func (f *Flag[T]) Short() rune

Short returns the shorthand registered for the flag (e.g. -d for --delete), or NoShortHand if the flag should be long only.

func (*Flag[T]) String

func (f *Flag[T]) String() string

String implements fmt.Stringer for a Flag, and also implements the String part of Value, allowing a flag to print itself.

func (*Flag[T]) Type

func (f *Flag[T]) Type() string

Type returns a string representation of the type of the Flag.

func (*Flag[T]) Usage

func (f *Flag[T]) Usage() string

Usage returns the usage line for the flag.

type Set

type Set struct {
	// contains filtered or unexported fields
}

Set is a set of command line flags.

func NewSet

func NewSet() *Set

NewSet builds and returns a new set of flags.

func (*Set) All

func (s *Set) All() iter.Seq2[string, Value]

All returns an iterator through the flags in the flagset in alphabetical order by name.

func (*Set) Args

func (s *Set) Args() []string

Args returns a slice of all the non-flag arguments, including any following a "--" terminator.

func (*Set) ExtraArgs

func (s *Set) ExtraArgs() []string

ExtraArgs returns any arguments after a "--" was encountered, or nil if there were none.

func (*Set) Get

func (s *Set) Get(name string) (Value, bool)

Get gets a flag from the Set by name and a boolean to indicate whether it was present.

func (*Set) GetShort

func (s *Set) GetShort(short rune) (Value, bool)

GetShort gets a flag from the Set by it's shorthand and a boolean to indicate whether it was present.

func (*Set) Help

func (s *Set) Help() (value, ok bool)

Help returns whether the Set has a boolean flag named "help" and what the value of that flag is currently set to, it simplifies checking for --help.

func (*Set) Parse

func (s *Set) Parse(args []string) error

Parse parses flags and their values from the command line.

func (*Set) Sorted

func (s *Set) Sorted() iter.Seq2[string, Value]

Sorted returns an iterator through the flags in the flagset in alphabetical order by name.

func (*Set) Version

func (s *Set) Version() (value, ok bool)

Version returns whether the Set has a boolean flag named "version" and what the value of that flag is currently set to, it simplifies checking for --version.

type Value

type Value interface {
	// Name returns the name of the flag.
	Name() string

	// Short returns the shorthand of the flag (or NoShortHand).
	Short() rune

	// Usage returns the usage line for the flag.
	Usage() string

	// String returns the stored value of a flag as a string.
	String() string

	// Default return the default value of a flag as a string.
	//
	// If the flag's default is the zero value for it's type,
	// an empty string is returned.
	Default() string

	// EnvVar returns the name of the environment variable associated with this flag,
	// or an empty string if none was configured.
	EnvVar() string

	// NoArgValue returns astring representation of the value of the flag when no
	// args are passed (e.g --bool implies --bool true).
	NoArgValue() string

	// Type returns the string representation of the flag type e.g. "bool".
	Type() string

	// IsSlice reports whether the flag holds a slice value that accumulates
	// repeated calls to Set (e.g. []string, []int). Note that []byte and net.IP
	// are NOT slice flags in this sense — they are parsed atomically.
	IsSlice() bool

	// Set sets the stored value of a flag by parsing the string "str".
	Set(str string) error
}

Value is an interface representing a Flag value that can be set from the command line.