README
¶
sopt
Simple option parser for Go.
What
This is a simple option parser with no dependencies outside the Go stdlib. The goal is to have the typical, most common use cases supported, including nested tool commands, and to be compilable with TinyGo.
Documentation
¶
Index ¶
- Constants
- Variables
- type Command
- type Group
- type Option
- type Options
- func (opt *Options) AddGroup(group string) *Group
- func (opt *Options) GetBool(name string) bool
- func (opt *Options) GetFloat(name string) float64
- func (opt *Options) GetGroup(name string) *Group
- func (opt *Options) GetGroups() []*Group
- func (opt *Options) GetInt(name string) int
- func (opt *Options) GetOption(name string) *Option
- func (opt *Options) GetPosBool(placeholder string) bool
- func (opt *Options) GetPosString(placeholder string) string
- func (opt *Options) GetPosStringSlice(placeholder string) []string
- func (opt *Options) GetString(name string) string
- func (opt *Options) GetStringSlice(name string) []string
- func (opt *Options) GroupCount() int
- func (opt *Options) Parse(emptyhelp bool) error
- func (opt *Options) ParseArgs(args []string) error
- func (opt *Options) PrintHelp()
- func (opt *Options) RemoveGroup(name string)
- func (opt *Options) SetCommand(name, help, group string, fn ToolCommand, aliases []string) *Command
- func (opt *Options) SetDefaultHelp()
- func (opt *Options) SetOption(group, short, long, help string, defaultvalue any, required bool, t uint8, ...) error
- func (opt *Options) SetPositional(placeholder, help string, defaultvalue any, required bool, t uint8) error
- func (opt *Options) ShowOptions()
- type ToolCommand
Constants ¶
const ( // VarTypeBool option. VarTypeBool uint8 = iota // VarTypeInt option. VarTypeInt // VarTypeFloat option. VarTypeFloat // VarTypeString option. VarTypeString // VarTypeStringSlice option. VarTypeStringSlice // VarTypePosStringSlice option. VarTypePosStringSlice )
Variable types
Variables ¶
var ( // ErrMissingRequired is returned when a required option is missing. ErrMissingRequired = errors.New("missing required option") // ErrMissingArgument is returned when an option is missing an argument. ErrMissingArgument = errors.New("missing argument") // 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 []*Option
// Aliases for this command.
Aliases []string
}
Command definition.
type Group ¶
type Group struct {
// Name of the group.
Name string
// contains filtered or unexported fields
}
Group definition.
func (*Group) GetOptions ¶
GetOptions returns a slice of options.
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.
type Options ¶
type Options struct {
// Remainder contains args not parsed as options, commands or positional args.
Remainder []string
// contains filtered or unexported fields
}
Options base definition.
func (*Options) GetPosBool ¶ added in v0.7.0
GetPosBool returns a positional boolean's value.
func (*Options) GetPosString ¶ added in v0.7.0
GetPosString returns a positional string's value.
func (*Options) GetPosStringSlice ¶ added in v0.8.0
GetPosStringSlice returns a positional string slice's values.
func (*Options) GetStringSlice ¶ added in v0.8.0
GetStringSlice returns a string slice option's value.
func (*Options) GroupCount ¶
GroupCount returns the number of groups.
func (*Options) Parse ¶
Parse the command line arguments from os.Args. Internally it calls ParseArgs. - If default help is defined, it will print the help message after parsing when "-h" or "--help" is supplied, then os.Exit(0). - If emptyhelp is true and no arguments are supplied, it will print the help message and os.Exit(0).
func (*Options) ParseArgs ¶
ParseArgs parses the supplied string slice as CLI arguments. 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) PrintHelp ¶
func (opt *Options) PrintHelp()
PrintHelp builds and prints the help text based on available options.
func (*Options) RemoveGroup ¶
RemoveGroup from map and order.
func (*Options) SetCommand ¶ added in v0.6.0
func (opt *Options) SetCommand(name, help, group string, fn ToolCommand, aliases []string) *Command
SetCommand to a group.
func (*Options) SetDefaultHelp ¶
func (opt *Options) SetDefaultHelp()
SetDefaultHelp sets the default help text.
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.
func (*Options) SetPositional ¶ added in v0.7.0
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.
Source Files