flag

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 Flag
  • func New[T Flaggable](p *T, name string, short rune, value T, usage string) (Flag[T], error)
  • 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 Flaggable
• type Set
  • func NewSet() *Set
  • 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) (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.

Functions

func AddToSet

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

AddToSet adds a flag to the given Set.

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 Flag

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

Flag represents a single command line flag.

func New

func New[T Flaggable](p *T, name string, short rune, value T, usage string) (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".

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]) 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 Flaggable

type Flaggable interface {
	int |
		int8 |
		int16 |
		int32 |
		int64 |
		uint |
		uint8 |
		uint16 |
		uint32 |
		uint64 |
		uintptr |
		float32 |
		float64 |
		string |
		bool |
		[]byte |
		Count |
		time.Time |
		time.Duration |
		net.IP |
		[]int |
		[]int8 |
		[]int16 |
		[]int32 |
		[]int64 |
		[]uint |
		[]uint16 |
		[]uint32 |
		[]uint64 |
		[]float32 |
		[]float64 |
		[]string
}

Flaggable is a type constraint that defines any type capable of being parsed as a command line 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) 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) (err error)

Parse parses flags and their values from the command line.

func (*Set) Usage

func (s *Set) Usage() (string, error)

Usage returns a string containing the usage info of all flags in the set.

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 {
	// Return the name of the flag
	Name() string

	// Return the shorthand of the flag (or NoShortHand)
	Short() rune

	// Return the usage line for the flag
	Usage() string

	// Print the stored value of a flag
	String() string

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

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

	// Set 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.