Documentation
¶
Overview ¶
Package flag provides a command line flag definition and parsing library.
Flag is intentionally internal so the only interraction is via the Flag option on a command.
Index ¶
- Constants
- func AddToSet[T Flaggable](set *Set, flag Flag[T]) error
- type Count
- type Entry
- type Flag
- type Flaggable
- type Set
- func (s *Set) Args() []string
- func (s *Set) ExtraArgs() []string
- func (s *Set) Get(name string) (Entry, bool)
- func (s *Set) GetShort(short rune) (Entry, bool)
- func (s *Set) Help() (value, ok bool)
- func (s *Set) Parse(args []string) (err error)
- func (s *Set) Usage() (string, error)
- func (s *Set) Version() (value, ok bool)
- type Value
Constants ¶
const NoShortHand = rune(-1)
NoShortHand should be passed as the "short" argument to New if the desired flag should be the long hand version only e.g. --count, not -c/--count.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Count ¶
type Count uint
Count is a type used for a flag who's job is to increment a counter, e.g. a "verbosity" flag may be passed "-vvv" which should increase the verbosity level to 3.
type Entry ¶
type Entry struct {
Value Value // The actual Flag[T]
Name string // The full name of the flag e.g. "delete"
Usage string // The flag's usage message
DefaultValue string // String representation of the default flag value
DefaultValueNoArg string // String representation of the default flag value if used without an arg, e.g. boolean flags "--force" implies "--force true"
Shorthand rune // The optional shorthand e.g. 'd' or [NoShortHand]
}
Entry represents a single flag in the set, as stored.
type Flag ¶
type Flag[T Flaggable] struct { // contains filtered or unexported fields }
Flag represents a single command line flag.
func New ¶
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".
If you want the flag to be longhand only, pass "" for short.
var force bool flag.New(&force, "force", 'f', false, "Force deletion without confirmation")
func (Flag[T]) Set ¶
Set sets a Flag value based on string input, i.e. parsing from the command line.
func (Flag[T]) String ¶
String implements fmt.Stringer for a Flag, and also implements the String part of [pflag.Value], allowing a flag to print itself.
type Flaggable ¶
type Flaggable interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr | ~float32 | ~float64 | ~string | ~bool | ~[]byte | time.Time
}
Flaggable is a type constraint that defines any type capable of being parsed as a command line flag.
It's worth noting that the complete set of supported types is wider than this constraint appears as e.g. a time.Duration is actually just an int64 underneath, likewise a net.IP is actually just []byte.
type Set ¶
type Set struct {
// contains filtered or unexported fields
}
Set is a set of command line flags.
func (*Set) Args ¶
Args returns a slice of all the non-flag arguments, including any following a "--" terminator.
func (*Set) ExtraArgs ¶
ExtraArgs returns any arguments after a "--" was encountered, or nil if there were none.
func (*Set) Get ¶
Get gets a flag Entry from the Set by name and a boolean to indicate whether it was present.
func (*Set) GetShort ¶
GetShort gets a flag Entry from the Set by it's shorthand and a boolean to indicate whether it was present.
func (*Set) Help ¶
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.
type Value ¶
type Value interface {
String() string // Print the stored value of a flag
Type() string // Return the string representation of the flag type e.g. "bool"
Set(str string) error // Set the stored value of a flag by parsing the string "str"
}
Value is an interface representing a Flag value that can be set from the command line.
Source Files