arg

package
v0.15.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2024 License: MIT Imports: 9 Imported by: 8

Documentation

Index

Constants

View Source 
const (
	// 	VarBool option.
	VarBool uint8 = iota
	// 	VarInt option.
	VarInt
	// VarIntSlice option.
	VarIntSlice
	// 	VarFloat option.
	VarFloat
	// 	VarFloatSlice option.
	VarFloatSlice
	// 	VarString option.
	VarString
	// VarStringSlice option.
	VarStringSlice
)

Variable types

View Source 
const (
	// GroupDefault is the default group name.
	GroupDefault = "default"
)

Variables

View Source 
var (
	// ErrRunCommand is not really an error, but indicates a command was run.
	ErrRunCommand = errors.New("command run")
	// ErrNoArgs is returned when no arguments are provided.
	ErrNoArgs = errors.New("no arguments provided")
	// ErrIllegalChoice is returned when the argument isn't in the approved list of choices.
	ErrIllegalChoice = errors.New("illegal choice")
	// ErrMissingRequired is returned when a required option is missing.
	ErrMissingRequired = errors.New("missing required option")
	// ErrMissingParam is returned when an option is missing an argument.
	ErrMissingParam = errors.New("missing option parameter")
	// ErrMissingFunc is returned when a command is missing a function.
	ErrMissingFunc = errors.New("missing function")
	// ErrLongShort is returned when a short option is longer than one character.
	ErrLongShort = errors.New("short option must be one character")
	// ErrUnknownOption is returned when an undefined option is encountered.
	ErrUnknownOption = errors.New("unknown option")
	// ErrEmptyLong is returned when a long option is empty.
	ErrEmptyLong = errors.New("long option without a string")
	// ErrShortLong is returned when a long option is shorter than two characters.
	ErrShortLong = errors.New("long option must be at least two characters")
	// ErrUnknownType is returned when an unknown option variable type is encountered.
	ErrUnknownType = errors.New("unknown option type")
	// ErrNoPlaceholder is returned when a positional argument is missing a placeholder.
	ErrNoPlaceholder = errors.New("no placeholder")
)

Functions

This section is empty.

Types

type Command 

type Command struct {
	// Name of the command.
	Name string
	// Help text of the command.
	Help string
	// Func to execute the command.
	Func ToolCommand
	// Options for this command.
	Options *Options
	// Aliases for this command.
	Aliases []string
}

Command definition.

type CompCmd added in v0.3.0 

type CompCmd struct {
	// Name op the command.
	Name string
	// Options list.
	Options []CompOpt
}

CompCmd is a completion for a tool command.

type CompList added in v0.3.0 

type CompList struct {
	// AppName fot references.
	AppName string
	// Options for the main program.
	Options []CompOpt
	// Commands and their options.
	Commands []CompCmd
}

CompList is a list of commands with their options.

type CompOpt added in v0.3.0 

type CompOpt struct {
	// Name of the option.
	Name string
}

CompOpt is a completion option.

type Group 

type Group struct {
	// Name of the group.
	Name string
	// contains filtered or unexported fields
}

Group definition.

func (*Group) GetOptions 

func (g *Group) GetOptions() []*Option

GetOptions returns a slice of options.

func (*Group) Len 

func (g *Group) Len() int

Len returns the number of options in the group.

func (*Group) Less 

func (g *Group) Less(i, j int) bool

Less returns true if the first option comes before the second.

func (*Group) Sort 

func (g *Group) Sort()

Sort options in the group alphabetically.

func (*Group) Swap 

func (g *Group) Swap(i, j int)

Swap two options in the group.

type Option 

type Option struct {
	// Placeholder is the placeholder variable shown in help text.
	Placeholder string
	// ShortName of the option.
	ShortName string
	// LongName of the option.
	LongName string
	// Help text of the option.
	Help string

	// Value of the option.
	Value any
	// Default value if unspecified.
	Default any
	// Choices allowed for the option.
	Choices []any

	// Type of value.
	Type uint8
	// Required is true if this must be defined. A default would satisfy this.
	Required bool
}

Option definition.

func (*Option) ValidDefault added in v0.9.0 

func (o *Option) ValidDefault() bool

ValidDefault returns true if the default value is usable (not the zero-value).

type Options 

type Options struct {

	// Args contains args not parsed as options, commands or positional args.
	Args []string
	// contains filtered or unexported fields
}

Options base definition.

func New 

func New(name string) *Options

New options instance. name - Name of the program.

func (*Options) AddGroup 

func (opt *Options) AddGroup(group string) *Group

AddGroup adds a new group. This ensures the order for help listing.

func (*Options) Completions added in v0.3.0 

func (opt *Options) Completions() (string, error)

Completions returns a string containing the completion script.

func (*Options) GetBool 

func (opt *Options) GetBool(name string) bool

GetBool returns a bool option's value.

func (*Options) GetFloat 

func (opt *Options) GetFloat(name string) float64

GetFloat returns a float option's value.

func (*Options) GetGroup 

func (opt *Options) GetGroup(name string) *Group

GetGroup returns a pointer to a group.

func (*Options) GetGroups 

func (opt *Options) GetGroups() []*Group

GetGroups returns a slice of groups.

func (*Options) GetInt 

func (opt *Options) GetInt(name string) int

GetInt returns an int option's value.

func (*Options) GetOption 

func (opt *Options) GetOption(name string) *Option

GetOption returns a pointer to an option.

func (*Options) GetPosBool 

func (opt *Options) GetPosBool(placeholder string) bool

GetPosBool returns a positional boolean's value.

func (*Options) GetPosFloat 

func (opt *Options) GetPosFloat(placeholder string) float64

GetPosFloat returns a positional float's value.

func (*Options) GetPosFloatSlice 

func (opt *Options) GetPosFloatSlice(placeholder string) []float64

GetPosFloatSlice returns a positional float slice's values.

func (*Options) GetPosInt 

func (opt *Options) GetPosInt(placeholder string) int

GetPosInt returns a positional int's value.

func (*Options) GetPosIntSlice 

func (opt *Options) GetPosIntSlice(placeholder string) []int

GetPosIntSlice returns a positional int slice's values.

func (*Options) GetPosString 

func (opt *Options) GetPosString(placeholder string) string

GetPosString returns a positional string's value.

func (*Options) GetPosStringSlice 

func (opt *Options) GetPosStringSlice(placeholder string) []string

GetPosStringSlice returns a positional string slice's values.

func (*Options) GetString 

func (opt *Options) GetString(name string) string

GetString returns a string option's value.

func (*Options) GetStringSlice 

func (opt *Options) GetStringSlice(name string) []string

GetStringSlice returns a string slice option's value.

func (*Options) GroupCount 

func (opt *Options) GroupCount() int

GroupCount returns the number of groups.

func (*Options) HelpOrFail added in v0.11.0 

func (opt *Options) HelpOrFail()

HelpOrFail parses the CLI arguments, then prints the help text and exits if the -h flag is set, or prints an error and exits with exit code 2 if something went wrong.

func (*Options) HelpOrFailArgs added in v0.12.0 

func (opt *Options) HelpOrFailArgs(args []string)

HelpOrFailArgs works like HelpOrFail(), but takes a string slice to parse. Use os.Args[1:] to mimic HelpOrFail(), and increase the number for sub-commands.

func (*Options) Parse 

func (opt *Options) Parse(args []string) error

Parse command line arguments from a string slice. - If default help is defined, it will print the help message after parsing when "-h" or "--help" is supplied, then os.Exit(0). Returns ErrNoArgs if no arguments are supplied.

Tool commands, short options (single dash and one letter), long options (double dash and one or more letters), and positional arguments are each paarsed in the order they are supplied. If a positional argument is of a slice type, it will swallow all remaining arguments, including long and short options.

Single- and double-dash options found before any tool commands are parsed for the Options structure.

Tool commands break the parsing off, and calls the command with the remaining arguments after running 

any handlers for the pre-command options.

Options criteria: - Short options start with a single dash ("-"). - Short boolean options don't need to take a value. - Short boolean options require an equal sign ("=") after the option with a truthy or falsy value. - Truthy values are "true", "yes", "on", "1", and "t". - Falsy values are everything else. - Short options can be combined ("-a -b" can be written as "-ab"). - Combined short options allow only the last one to take a value. The ones before must be booleans.

- Long options start with a double dash ("--"). - Long options are followed by either whitespace or an equal sign ("--foo bar" or "--foo=bar").

func (*Options) ParseEnvironment added in v0.6.0 

func (opt *Options) ParseEnvironment(prefix, delimiter string) error

ParseEnvironment parses environment variables into options. By default, this parses uppercase versions of long options, but an optional prefix can be provided. So if you provide the prefix "moo" (case doesn't matter) and have a long option "host", this will be set if the envvar "MOO_HOST" is set. Delimiter is used when parsing slices. If unset, it defaults to a comma.

func (*Options) PrintHelp 

func (opt *Options) PrintHelp()

PrintHelp builds and prints the help text based on available options.

func (*Options) RemoveGroup 

func (opt *Options) RemoveGroup(name string)

RemoveGroup from map and order.

func (*Options) SetCommand 

func (opt *Options) SetCommand(name, help, group string, fn ToolCommand, aliases []string) *Command

SetCommand to a group.

func (*Options) SetDefaultHelp 

func (opt *Options) SetDefaultHelp(full bool)

SetDefaultHelp sets the default help option, optionally with a short "-h" flag.

func (*Options) SetFlag added in v0.14.0 

func (opt *Options) SetFlag(group, short, long, help string) error

SetFlag is a shortcut to create a bool option defaulting to false.

func (*Options) SetOption 

func (opt *Options) SetOption(group, short, long, help string, defaultvalue any, required bool, t uint8, choices []any) error

SetOption sets an option with parameters, or a flag.

func (*Options) SetPositional 

func (opt *Options) SetPositional(placeholder, help string, defaultvalue any, required bool, t uint8) error

SetPositional sets a positional argument. Arguments which aren't long or short options or tool commands are considered positional.

func (*Options) ShowOptions 

func (opt *Options) ShowOptions()

ShowOptions shows the values of all options. Used for debugging.

type ToolCommand 

type ToolCommand func(*Options) error

ToolCommand function signature.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.