Documentation ¶
Overview ¶
Package getoptions - Go option parser inspired on the flexibility of Perl’s GetOpt::Long.
It will operate on any given slice of strings and return the remaining (non used) command line arguments. This allows to easily subcommand.
See https://github.com/DavidGamba/go-getoptions for extra documentation details.
Features ¶
• Allow passing options and non-options in any order.
• Support for `--long` options.
• Support for short (`-s`) options with flexible behaviour (see https://github.com/DavidGamba/go-getoptions#operation_modes for details):
- Normal (default)
- Bundling
- SingleDash
• `Called()` method indicates if the option was passed on the command line.
• Multiple aliases for the same option. e.g. `help`, `man`.
• `CalledAs()` method indicates what alias was used to call the option on the command line.
• Simple synopsis and option list automated help.
• Boolean, String, Int and Float64 type options.
• Negatable Boolean options. For example: `--verbose`, `--no-verbose` or `--noverbose`.
• Options with Array arguments. The same option can be used multiple times with different arguments. The list of arguments will be saved into an Array like structure inside the program.
• Options with array arguments and multiple entries. For example: `color --rgb 10 20 30 --next-option`
• When using integer array options with multiple arguments, positive integer ranges are allowed. For example: `1..3` to indicate `1 2 3`.
• Options with key value arguments and multiple entries.
• Options with Key Value arguments. This allows the same option to be used multiple times with arguments of key value type. For example: `rpmbuild --define name=myrpm --define version=123`.
• Supports passing `--` to stop parsing arguments (everything after will be left in the `remaining []string`).
• Supports command line options with '='. For example: You can use `--string=mystring` and `--string mystring`.
• Allows passing arguments to options that start with dash `-` when passed after equal. For example: `--string=--hello` and `--int=-123`.
• Options with optional arguments. If the default argument is not passed the default is set. For example: You can call `--int 123` which yields `123` or `--int` which yields the given default.
• Allows abbreviations when the provided option is not ambiguous. For example: An option called `build` can be called with `--b`, `--bu`, `--bui`, `--buil` and `--build` as long as there is no ambiguity. In the case of ambiguity, the shortest non ambiguous combination is required.
• Support for the lonesome dash "-". To indicate, for example, when to read input from STDIO.
• Incremental options. Allows the same option to be called multiple times to increment a counter.
• Supports case sensitive options. For example, you can use `v` to define `verbose` and `V` to define `Version`.
• Support indicating if an option is required and allows overriding default error message.
• Errors exposed as public variables to allow overriding them for internationalization.
• Supports subcommands (stop parsing arguments when non option is passed).
• Multiple ways of managing unknown options:
- Fail on unknown (default).
- Warn on unknown.
- Pass through, allows for subcommands and can be combined with Require Order.
• Require order: Allows for subcommands. Stop parsing arguments when the first non-option is found. When mixed with Pass through, it also stops parsing arguments when the first unmatched option is found.
Panic ¶
The library will panic if it finds that the programmer (not end user):
• Defined the same alias twice.
• Defined wrong min and max values for SliceMulti methods.
Example ¶
package main import ( "fmt" "io/ioutil" "log" "os" "github.com/DavidGamba/go-getoptions" ) var logger = log.New(ioutil.Discard, "DEBUG: ", log.LstdFlags) func main() { // Declare the variables you want your options to update var debug bool var greetCount int var list map[string]string // Declare the GetOptions object opt := getoptions.New() // Options definition opt.Bool("help", false, opt.Alias("h", "?")) // Aliases can be defined opt.BoolVar(&debug, "debug", false) opt.IntVar(&greetCount, "greet", 0, opt.Required(), opt.Description("Number of times to greet."), // Set the automated help description opt.ArgName("number"), // Change the help synopsis arg from the default <int> to <number> ) opt.StringMapVar(&list, "list", 1, 99, opt.Description("Greeting list by language."), opt.ArgName("lang=msg"), // Change the help synopsis arg from <key=value> to <lang=msg> ) // // Parse cmdline arguments os.Args[1:] remaining, err := opt.Parse([]string{"-g", "2", "-l", "en='Hello World'", "es='Hola Mundo'"}) // Handle help before handling user errors if opt.Called("help") { fmt.Fprintf(os.Stderr, opt.Help()) os.Exit(1) } // Handle user errors if err != nil { fmt.Fprintf(os.Stderr, "ERROR: %s\n\n", err) fmt.Fprintf(os.Stderr, opt.Help(getoptions.HelpSynopsis)) os.Exit(1) } // Use the passed command line options... Enjoy! if debug { logger.SetOutput(os.Stderr) } logger.Printf("Unhandled CLI args: %v\n", remaining) // Use the int variable for i := 0; i < greetCount; i++ { fmt.Println("Hello World, from go-getoptions!") } // Use the map[string]string variable if len(list) > 0 { fmt.Printf("Greeting List:\n") for k, v := range list { fmt.Printf("\t%s=%s\n", k, v) } } }
Output: Hello World, from go-getoptions! Hello World, from go-getoptions! Greeting List: en='Hello World' es='Hola Mundo'
Index ¶
- Variables
- type CommandFn
- type GetOpt
- func (gopt *GetOpt) Alias(alias ...string) ModifyFn
- func (gopt *GetOpt) ArgName(name string) ModifyFn
- func (gopt *GetOpt) Bool(name string, def bool, fns ...ModifyFn) *bool
- func (gopt *GetOpt) BoolVar(p *bool, name string, def bool, fns ...ModifyFn)
- func (gopt *GetOpt) Called(name string) bool
- func (gopt *GetOpt) CalledAs(name string) string
- func (gopt *GetOpt) CustomCompletion(list []string) *GetOpt
- func (gopt *GetOpt) Description(msg string) ModifyFn
- func (gopt *GetOpt) Dispatch(ctx context.Context, helpCommandName string, args []string) error
- func (gopt *GetOpt) Float64(name string, def float64, fns ...ModifyFn) *float64
- func (gopt *GetOpt) Float64Optional(name string, def float64, fns ...ModifyFn) *float64
- func (gopt *GetOpt) Float64Var(p *float64, name string, def float64, fns ...ModifyFn)
- func (gopt *GetOpt) Float64VarOptional(p *float64, name string, def float64, fns ...ModifyFn)
- func (gopt *GetOpt) GetEnv(name string) ModifyFn
- func (gopt *GetOpt) Help(sections ...HelpSection) string
- func (gopt *GetOpt) HelpCommand(description string) *GetOpt
- func (gopt *GetOpt) HelpSynopsisArgs(args string) *GetOpt
- func (gopt *GetOpt) Increment(name string, def int, fns ...ModifyFn) *int
- func (gopt *GetOpt) IncrementVar(p *int, name string, def int, fns ...ModifyFn)
- func (gopt *GetOpt) Int(name string, def int, fns ...ModifyFn) *int
- func (gopt *GetOpt) IntOptional(name string, def int, fns ...ModifyFn) *int
- func (gopt *GetOpt) IntSlice(name string, min, max int, fns ...ModifyFn) *[]int
- func (gopt *GetOpt) IntSliceVar(p *[]int, name string, min, max int, fns ...ModifyFn)
- func (gopt *GetOpt) IntVar(p *int, name string, def int, fns ...ModifyFn)
- func (gopt *GetOpt) IntVarOptional(p *int, name string, def int, fns ...ModifyFn)
- func (gopt *GetOpt) InterruptContext() (ctx context.Context, cancel context.CancelFunc, done chan struct{})
- func (gopt *GetOpt) NewCommand(name string, description string) *GetOpt
- func (gopt *GetOpt) Option(name string) *option.Option
- func (gopt *GetOpt) Parse(args []string) ([]string, error)
- func (gopt *GetOpt) Required(msg ...string) ModifyFn
- func (gopt *GetOpt) Self(name string, description string) *GetOpt
- func (gopt *GetOpt) SetCommandFn(fn CommandFn) *GetOpt
- func (gopt *GetOpt) SetMapKeysToLower() *GetOpt
- func (gopt *GetOpt) SetMode(mode Mode) *GetOpt
- func (gopt *GetOpt) SetRequireOrder() *GetOpt
- func (gopt *GetOpt) SetUnknownMode(mode UnknownMode) *GetOpt
- func (gopt *GetOpt) String(name, def string, fns ...ModifyFn) *string
- func (gopt *GetOpt) StringMap(name string, min, max int, fns ...ModifyFn) map[string]string
- func (gopt *GetOpt) StringMapVar(m *map[string]string, name string, min, max int, fns ...ModifyFn)
- func (gopt *GetOpt) StringOptional(name string, def string, fns ...ModifyFn) *string
- func (gopt *GetOpt) StringSlice(name string, min, max int, fns ...ModifyFn) *[]string
- func (gopt *GetOpt) StringSliceVar(p *[]string, name string, min, max int, fns ...ModifyFn)
- func (gopt *GetOpt) StringVar(p *string, name, def string, fns ...ModifyFn)
- func (gopt *GetOpt) StringVarOptional(p *string, name, def string, fns ...ModifyFn)
- func (gopt *GetOpt) Stringer() string
- func (gopt *GetOpt) Value(name string) interface{}
- type HelpSection
- type Mode
- type ModifyFn
- type UnknownMode
Examples ¶
Constants ¶
This section is empty.
Variables ¶
Debug Logger instance set to `ioutil.Discard` by default. Enable debug logging by setting: `Debug.SetOutput(os.Stderr)`.
var ErrorHelpCalled = fmt.Errorf("help called")
ErrorHelpCalled - Indicates the help has been handled.
Functions ¶
This section is empty.
Types ¶
type GetOpt ¶
type GetOpt struct { // CommandFn CommandFn CommandFn // Debugging Writer io.Writer // io.Writer to write warnings to. Defaults to os.Stderr. // contains filtered or unexported fields }
GetOpt - main object.
func New ¶
func New() *GetOpt
New returns an empty object of type GetOpt. This is the starting point when using go-getoptions. For example:
opt := getoptions.New()
func (*GetOpt) Alias ¶ added in v0.12.0
Alias - Adds aliases to an option.
Example ¶
opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println("help called") } if opt.CalledAs("help") == "?" { fmt.Println("help called as ?") }
Output: help called help called as ?
func (*GetOpt) ArgName ¶ added in v0.13.0
ArgName - Add an argument name to an option for use in automated help. For example, by default a string option will have a default synopsis as follows:
--host <string>
If ArgName("hostname") is used, the synopsis will read:
--host <hostname>
Example ¶
opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) opt.String("host-default", "") opt.String("host-custom", "", opt.ArgName("hostname")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println(opt.Help()) }
Output: SYNOPSIS: go-getoptions.test [--help|-?] [--host-custom <hostname>] [--host-default <string>] [<args>] OPTIONS: --help|-? (default: false) --host-custom <hostname> (default: "") --host-default <string> (default: "")
func (*GetOpt) Bool ¶
Bool - define a `bool` option and its aliases. It returns a `*bool` pointing to the variable holding the result. If the option is found, the result will be the opposite of the provided default.
Example ¶
opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println(opt.Help()) }
Output: SYNOPSIS: go-getoptions.test [--help|-?] [<args>] OPTIONS: --help|-? (default: false)
func (*GetOpt) BoolVar ¶
BoolVar - define a `bool` option and its aliases. The result will be available through the variable marked by the given pointer. If the option is found, the result will be the opposite of the provided default.
Example ¶
var help bool opt := getoptions.New() opt.BoolVar(&help, "help", false, opt.Alias("?")) _, _ = opt.Parse([]string{"-?"}) if help { fmt.Println(opt.Help()) }
Output: SYNOPSIS: go-getoptions.test [--help|-?] [<args>] OPTIONS: --help|-? (default: false)
func (*GetOpt) Called ¶
Called - Indicates if the option was passed on the command line. If the `name` is an option that wasn't declared it will return false.
Example ¶
opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println("help called") } if opt.CalledAs("help") == "?" { fmt.Println("help called as ?") }
Output: help called help called as ?
func (*GetOpt) CalledAs ¶ added in v0.13.0
CalledAs - Returns the alias used to call the option. Empty string otherwise.
If the `name` is an option that wasn't declared it will return an empty string.
For options that can be called multiple times, the last alias used is returned.
Example ¶
opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println("help called") } if opt.CalledAs("help") == "?" { fmt.Println("help called as ?") }
Output: help called help called as ?
func (*GetOpt) CustomCompletion ¶ added in v0.14.0
CustomCompletion - Add a custom completion list.
func (*GetOpt) Description ¶ added in v0.13.0
Description - Add a description to an option for use in automated help.
Example ¶
opt := getoptions.New() opt.HelpSynopsisArgs("[<commands>]") opt.Bool("help", false, opt.Alias("?"), opt.Description("Show help.")) opt.String("hostname", "golang.org", opt.ArgName("host|IP"), opt.Description("Hostname to use.")) opt.String("user", "", opt.ArgName("user_id"), opt.Required(), opt.Description("User to login as.")) _, _ = opt.Parse([]string{"-?"}) if opt.Called("help") { fmt.Println(opt.Help()) }
Output: SYNOPSIS: go-getoptions.test --user <user_id> [--help|-?] [--hostname <host|IP>] [<commands>] REQUIRED PARAMETERS: --user <user_id> User to login as. OPTIONS: --help|-? Show help. (default: false) --hostname <host|IP> Hostname to use. (default: "golang.org")
func (*GetOpt) Dispatch ¶ added in v0.15.0
Dispatch - Call CommandFn for the program commands based on the contents of the args slice. By default, if given the helpCommandName (normally just "help") as the first argument, it will print the help for the parent. If given helpCommandName plus the name of the command, it will print the help for the command.
Example ¶
package main import ( "context" "errors" "fmt" "io/ioutil" "log" "os" "github.com/DavidGamba/go-getoptions" ) var dispatchLogger = log.New(ioutil.Discard, "DEBUG: ", log.LstdFlags) func listRun(ctx context.Context, opt *getoptions.GetOpt, args []string) error { fmt.Println("a, b, c, d") return nil } func main() { opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) opt.Bool("debug", false) opt.SetRequireOrder() opt.SetUnknownMode(getoptions.Pass) list := opt.NewCommand("list", "list stuff").SetCommandFn(listRun) list.Bool("list-opt", false) opt.HelpCommand("") remaining, err := opt.Parse([]string{"list"}) // <- argv set to call command if err != nil { fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } opt.Writer = os.Stdout // Print help to stdout instead of stderr for test purpose err = opt.Dispatch(context.Background(), "help", remaining) if err != nil { if errors.Is(err, getoptions.ErrorHelpCalled) { os.Exit(1) } fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } }
Output: a, b, c, d
Example (BHelp) ¶
package main import ( "context" "errors" "fmt" "io/ioutil" "log" "os" "github.com/DavidGamba/go-getoptions" ) var dispatchHelpLogger = log.New(ioutil.Discard, "DEBUG: ", log.LstdFlags) func dispatchHelpListRun(ctx context.Context, opt *getoptions.GetOpt, args []string) error { return nil } func main() { opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) opt.Bool("debug", false) opt.SetRequireOrder() opt.SetUnknownMode(getoptions.Pass) list := opt.NewCommand("list", "list stuff") list.SetCommandFn(dispatchHelpListRun) list.Bool("list-opt", false) opt.HelpCommand("") remaining, err := opt.Parse([]string{"help"}) // <- argv set to call help if err != nil { fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } opt.Writer = os.Stdout // Print help to stdout instead of stderr for test purpose err = opt.Dispatch(context.Background(), "help", remaining) if err != nil { if errors.Is(err, getoptions.ErrorHelpCalled) { os.Exit(1) } fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } }
Output: SYNOPSIS: go-getoptions.test [--debug] [--help|-?] <command> [<args>] COMMANDS: help Use 'go-getoptions.test help <command>' for extra details. list list stuff OPTIONS: --debug (default: false) --help|-? (default: false) Use 'go-getoptions.test help <command>' for extra details.
Example (CCommandHelp) ¶
package main import ( "context" "errors" "fmt" "io/ioutil" "log" "os" "github.com/DavidGamba/go-getoptions" ) var dispatchCommandHelpLogger = log.New(ioutil.Discard, "DEBUG: ", log.LstdFlags) func dispatchCommandHelpListRun(ctx context.Context, opt *getoptions.GetOpt, args []string) error { return nil } func main() { opt := getoptions.New() opt.Bool("help", false, opt.Alias("?")) opt.Bool("debug", false) opt.SetRequireOrder() opt.SetUnknownMode(getoptions.Pass) list := opt.NewCommand("list", "list stuff") list.SetCommandFn(dispatchCommandHelpListRun) list.Bool("list-opt", false) opt.HelpCommand("") remaining, err := opt.Parse([]string{"help", "list"}) // <- argv set to call command help if err != nil { fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } opt.Writer = os.Stdout // Print help to stdout instead of stderr for test purpose err = opt.Dispatch(context.Background(), "help", remaining) if err != nil { if errors.Is(err, getoptions.ErrorHelpCalled) { os.Exit(1) } fmt.Fprintf(os.Stderr, "ERROR: %s\n", err) os.Exit(1) } }
Output: NAME: go-getoptions.test list - list stuff SYNOPSIS: go-getoptions.test list [--debug] [--help|-?] [--list-opt] [<args>] OPTIONS: --debug (default: false) --help|-? (default: false) --list-opt (default: false)
func (*GetOpt) Float64Optional ¶ added in v0.23.0
Float64Optional - define an `float64` option and its aliases.
func (*GetOpt) Float64Var ¶
Float64Var - define an `float64` option and its aliases. The result will be available through the variable marked by the given pointer.
func (*GetOpt) Float64VarOptional ¶ added in v0.23.0
Float64VarOptional - define an `float64` option and its aliases. The result will be available through the variable marked by the given pointer.
func (*GetOpt) GetEnv ¶ added in v0.18.0
GetEnv - Will read an environment variable if set. Precedence higher to lower: CLI option, environment variable, option default.
Currently, only `opt.Bool`, `opt.BoolVar`, `opt.String`, and `opt.StringVar` are supported.
When an environment variable that matches the variable from opt.GetEnv is set, opt.GetEnv will set opt.Called(name) to true and will set opt.CalledAs(name) to the name of the environment variable used. In other words, when an option is required (opt.Required is set) opt.GetEnv satisfies that requirement.
When using `opt.GetEnv` with `opt.Bool` or `opt.BoolVar`, only the words "true" or "false" are valid. They can be provided in any casing, for example: "true", "True" or "TRUE".
NOTE: Non supported option types behave with a No-Op when `opt.GetEnv` is defined.
Example ¶
os.Setenv("_AWS_PROFILE", "production") var profile string opt := getoptions.New() opt.StringVar(&profile, "profile", "default", opt.GetEnv("_AWS_PROFILE")) _, _ = opt.Parse([]string{}) fmt.Println(profile) os.Unsetenv("_AWS_PROFILE")
Output: production
func (*GetOpt) Help ¶ added in v0.13.0
func (gopt *GetOpt) Help(sections ...HelpSection) string
Help - Default help string that is composed of the HelpSynopsis and HelpOptionList.
func (*GetOpt) HelpCommand ¶ added in v0.15.0
HelpCommand - Adds a help command with completion for all other commands.
NOTE: Define after all other commands have been defined.
func (*GetOpt) HelpSynopsisArgs ¶ added in v0.16.0
HelpSynopsisArgs - Defines the help synopsis args description. Defaults to: [<args>]
func (*GetOpt) Increment ¶
Increment - When called multiple times it increments the int counter defined by this option.
func (*GetOpt) IncrementVar ¶
IncrementVar - When called multiple times it increments the provided int.
func (*GetOpt) IntOptional ¶
IntOptional - define a `int` option and its aliases.
IntOptional will set the int to the provided default value when no value is given. For example, when called with `--intOpt 123`, the value is `123`. when called with `--intOpt` the value is the given default.
func (*GetOpt) IntSlice ¶ added in v0.11.0
IntSlice - define a `[]int` option and its aliases.
IntSlice will accept multiple calls to the same option and append them to the `[]int`. For example, when called with `--intRpt 1 --intRpt 2`, the value is `[]int{1, 2}`.
Additionally, IntSlice will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strRpt 1 2 3`, the value is `[]int{1, 2, 3}`. It could also be called with `--strRpt 1 --strRpt 2 --strRpt 3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strRpt 1 2 --strRpt 3`
Finally, positive integer ranges are allowed. For example, Instead of writing: `csv --columns 1 2 3` or `csv --columns 1 --columns 2 --columns 3` The input could be: `csv --columns 1..3`.
func (*GetOpt) IntSliceVar ¶ added in v0.11.0
IntSliceVar - define a `[]int` option and its aliases.
IntSliceVar will accept multiple calls to the same option and append them to the `[]int`. For example, when called with `--intRpt 1 --intRpt 2`, the value is `[]int{1, 2}`.
Additionally, IntSliceVar will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strRpt 1 2 3`, the value is `[]int{1, 2, 3}`. It could also be called with `--strRpt 1 --strRpt 2 --strRpt 3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strRpt 1 2 --strRpt 3`
Finally, positive integer ranges are allowed. For example, Instead of writing: `csv --columns 1 2 3` or `csv --columns 1 --columns 2 --columns 3` The input could be: `csv --columns 1..3`.
func (*GetOpt) IntVar ¶
IntVar - define an `int` option and its aliases. The result will be available through the variable marked by the given pointer.
func (*GetOpt) IntVarOptional ¶
IntVarOptional - define a `int` option and its aliases. The result will be available through the variable marked by the given pointer.
IntOptional will set the int to the provided default value when no value is given. For example, when called with `--intOpt 123`, the value is `123`. when called with `--intOpt` the value is the given default.
func (*GetOpt) InterruptContext ¶ added in v0.17.0
func (gopt *GetOpt) InterruptContext() (ctx context.Context, cancel context.CancelFunc, done chan struct{})
InterruptContext - Creates a top level context that listens to os.Interrupt, syscall.SIGHUP and syscall.SIGTERM and calls the CancelFunc if the signals are triggered. When the listener finishes its work, it sends a message to the done channel.
Use:
func main() { ... ctx, cancel, done := getoptions.InterruptContext() defer func() { cancel(); <-done }()
NOTE: InterruptContext is a method to reuse gopt.Writer
func (*GetOpt) NewCommand ¶ added in v0.17.0
NewCommand - Returns a new GetOpt object representing a new command.
func (*GetOpt) Parse ¶
Parse - Call the parse method when done describing. It will operate on any given slice of strings and return the remaining (non used) command line arguments. This allows to easily subcommand.
Parsing style is controlled by the `Set` methods (SetMode, SetRequireOrder, etc).
// Declare the GetOptions object opt := getoptions.New() ... // Parse cmdline arguments or any provided []string remaining, err := opt.Parse(os.Args[1:])
func (*GetOpt) Required ¶ added in v0.12.0
Required - Automatically return an error if the option is not called. Optionally provide an error message if the option is not called. A default error message will be used otherwise.
func (*GetOpt) Self ¶ added in v0.14.0
Self - Set a custom name and description that will show in the automated help. If name is an empty string, it will only use the description and use the name as the executable name.
func (*GetOpt) SetCommandFn ¶ added in v0.15.0
SetCommandFn - Defines the command entry point function.
func (*GetOpt) SetMapKeysToLower ¶ added in v0.11.0
SetMapKeysToLower - StringMap keys captured from StringMap are lower case. For example:
command --opt key=value
And:
command --opt KEY=value
Would both return `map[string]string{"key":"value"}`.
func (*GetOpt) SetMode ¶
SetMode - Sets the Operation Mode. The operation mode only affects options starting with a single dash '-'. The available operation modes are: normal, bundling or singleDash.
The following table shows the different operation modes given the string "-opt=arg".
.Operation Modes for string "-opt=arg" |=== |Mode |Description |normal |option: opt argument: arg |bundling |option: o argument: nil option: p argument: nil option: t argument: arg |singleDash |option: o argument: pt=arg |===
See https://github.com/DavidGamba/go-getoptions#operation_modes for more details.
func (*GetOpt) SetRequireOrder ¶
SetRequireOrder - Stop parsing options when a subcommand is passed. Put every remaining argument, including the subcommand, in the `remaining` slice.
A subcommand is assumed to be the first argument that is not an option or an argument to an option. When a subcommand is found, stop parsing arguments and let a subcommand handler handle the remaining arguments. For example:
command --opt arg subcommand --subopt subarg
In the example above, `--opt` is an option and `arg` is an argument to an option, making `subcommand` the first non option argument.
This method is useful when both the command and the subcommand have option handlers for the same option.
For example, with:
command --help
`--help` is handled by `command`, and with:
command subcommand --help
`--help` is not handled by `command` since there was a subcommand that caused the parsing to stop. In this case, the `remaining` slice will contain `['subcommand', '--help']` and that can be passed directly to a subcommand's option parser.
func (*GetOpt) SetUnknownMode ¶
func (gopt *GetOpt) SetUnknownMode(mode UnknownMode) *GetOpt
SetUnknownMode - Determines how to behave when encountering an unknown option.
• 'fail' (default) will make 'Parse' return an error with the unknown option information.
• 'warn' will make 'Parse' print a user warning indicating there was an unknown option. The unknown option will be left in the remaining array.
• 'pass' will make 'Parse' ignore any unknown options and they will be passed onto the 'remaining' slice. This allows for subcommands. TODO: Add aliases
func (*GetOpt) String ¶
String - define a `string` option and its aliases. If not called, the return value will be that of the given default `def`.
func (*GetOpt) StringMap ¶
StringMap - define a `map[string]string` option and its aliases.
StringMap will accept multiple calls of `key=value` type to the same option and add them to the `map[string]string` result. For example, when called with `--strMap k=v --strMap k2=v2`, the value is `map[string]string{"k":"v", "k2": "v2"}`.
Additionally, StringMap will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strMap k=v k2=v2 k3=v3`, the value is `map[string]string{"k":"v", "k2": "v2", "k3": "v3"}`. It could also be called with `--strMap k=v --strMap k2=v2 --strMap k3=v3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strMap k=v k2=v2 --strMap k3=v3`
func (*GetOpt) StringMapVar ¶ added in v0.14.0
StringMapVar - define a `map[string]string` option and its aliases.
StringMapVar will accept multiple calls of `key=value` type to the same option and add them to the `map[string]string` result. For example, when called with `--strMap k=v --strMap k2=v2`, the value is `map[string]string{"k":"v", "k2": "v2"}`.
Additionally, StringMapVar will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strMap k=v k2=v2 k3=v3`, the value is `map[string]string{"k":"v", "k2": "v2", "k3": "v3"}`. It could also be called with `--strMap k=v --strMap k2=v2 --strMap k3=v3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strMap k=v k2=v2 --strMap k3=v3`
func (*GetOpt) StringOptional ¶
StringOptional - define a `string` option and its aliases.
StringOptional will set the string to the provided default value when no value is given. For example, when called with `--strOpt value`, the value is `value`. when called with `--strOpt` the value is the given default.
func (*GetOpt) StringSlice ¶
StringSlice - define a `[]string` option and its aliases.
StringSlice will accept multiple calls to the same option and append them to the `[]string`. For example, when called with `--strRpt 1 --strRpt 2`, the value is `[]string{"1", "2"}`.
Additionally, StringSlice will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strRpt 1 2 3`, the value is `[]string{"1", "2", "3"}`. It could also be called with `--strRpt 1 --strRpt 2 --strRpt 3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strRpt 1 2 --strRpt 3`
func (*GetOpt) StringSliceVar ¶ added in v0.11.0
StringSliceVar - define a `[]string` option and its aliases.
StringSliceVar will accept multiple calls to the same option and append them to the `[]string`. For example, when called with `--strRpt 1 --strRpt 2`, the value is `[]string{"1", "2"}`.
Additionally, StringSliceVar will allow to define a min and max amount of arguments to be passed at once. For example, when min is 1 and max is 3 and called with `--strRpt 1 2 3`, the value is `[]string{"1", "2", "3"}`. It could also be called with `--strRpt 1 --strRpt 2 --strRpt 3` for the same result.
When min is bigger than 1, it is required to pass the amount of arguments defined by min at once. For example: with `min = 2`, you at least require `--strRpt 1 2 --strRpt 3`
func (*GetOpt) StringVar ¶
StringVar - define a `string` option and its aliases. The result will be available through the variable marked by the given pointer. If not called, the return value will be that of the given default `def`.
func (*GetOpt) StringVarOptional ¶
StringVarOptional - define a `string` option and its aliases. The result will be available through the variable marked by the given pointer.
StringVarOptional will set the string to the provided default value when no value is given. For example, when called with `--strOpt value`, the value is `value`. when called with `--strOpt` the value is the given default.
type HelpSection ¶ added in v0.14.0
type HelpSection int
HelpSection - Indicates what portion of the help to return.
const ( HelpName HelpSection HelpSynopsis HelpCommandList HelpOptionList )
Help Output Types
type UnknownMode ¶ added in v0.14.0
type UnknownMode int
UnknownMode - Unknown option mode
const ( Fail UnknownMode = iota Warn Pass )
Unknown option modes
Directories ¶
Path | Synopsis |
---|---|
Package completion - provides a Tree structure that can be used to define a program's completions.
|
Package completion - provides a Tree structure that can be used to define a program's completions. |
Package dag - Lightweight Directed Acyclic Graph (DAG) Build System.
|
Package dag - Lightweight Directed Acyclic Graph (DAG) Build System. |
examples
|
|
Package help - internal help handling code.
|
Package help - internal help handling code. |
Package option - internal option struct and methods.
|
Package option - internal option struct and methods. |
Package text - User facing strings.
|
Package text - User facing strings. |