Fully featured Go (golang) command line option parser with built-in auto-completion support.
As the releases before, this release has 100% test coverage. Tested with Go 1.16, 1.17, 1.18, 1.19, 1.20, 1.21 and 1.22.
Add opt.SetValue to allow setting the value of an option.
Add opt.SuggestedValues ModifyFn to allow setting autocompletion suggestions for an option.
Works just like the existing opt.ValidValues but it doesn't error out if the value is not in the list of suggestions.
opt.GetRequiredArg, opt.GetRequiredArgInt and opt.GetRequiredArgFloat64 to simplify handling required arguments and providing error messages.For example:
opt := getoptions.New()
opt.SetCommandFn(Run)
opt.HelpSynopsisArg("<arg1>", "arg1 desc")
opt.HelpSynopsisArg("<arg2>", "arg2 desc")
...
func Run(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
i, args, err := opt.GetRequiredArgInt(args)
if err != nil {
return err
}
...
return nil
}
If the argument is not provided, the error message will be:
ERROR: Missing required argument: <arg1>
If the argument is provided but it is not an integer, the error message will be:
ERROR: Argument error: Can't convert string to int: 'x'
As the releases before, this release has 100% test coverage. Tested with Go 1.16, 1.17, 1.18, 1.19, 1.20 and 1.21.
opt.SetCalled ModifyFn to allow setting an option as called.Useful when calling CommandFn directly and not through opt.Dispatch and without a call to opt.Parse.
It allows building a opt object using defaults and marking the options as called.
For example:
func Run(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
password := opt.Value("password").(string)
nopt := getoptions.New()
nopt.String("password", password, opt.SetCalled(opt.Called("password")))
nopt.Int("number", 123, opt.SetCalled(true))
nopt.Float64("float", 3.14) // opt.Called("float") is false but its value is set to 3.14
err := CommandFn(ctx, nopt, []string{})
As the releases before, this release has 100% test coverage. Tested with 1.16, 1.17, 1.18, 1.19, 1.20 and 1.21.
Dropping support for Go 1.14 and 1.15 to stop using deprecated io/ioutil.
ZSHELL=true in your environment.ZSHELL completion works by using bashcompinit using:
autoload bashcompinit
bashcompinit
complete -o default -C <tool> <tool>
Before this release, completions would stop after the = symbol because the completion system is targeting bash by default and bash handles = as a divider for completions.
By setting ZSHELL=true in your environment, the completion system will target zsh and not split completions on =.
NOTE: I couldn't find a non-explicit reliable way to auto-detect zsh.
As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16, 1.17, 1.18, 1.19 and 1.20.
Refactor and rename HelpSynopsisArgs
- opt.HelpSynopsisArgs("name")
+ opt.HelpSynopsisArg("name", "description")
Allow it to be called multiple times.
Add ARGUMENTS section in help.
Add graph name in log entries. Helpful when using more than one graph (graph of graphs).
As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16, 1.17, 1.18 and 1.19.
The ErrorParsing error indicates there was a problem parsing the cli args.
This can be used for example, to print the help only in cases where the user didn't enter valid cli args.
Refactor dag package tests to remove most sleeps.
Bug fix: Don't check for required options when the help option is passed
As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16 and Go 1.17.
SingleDash mode, if calling a single letter option with a single dash, and the option expects a value and the value wasn't provided with = or as a bundle then the option value wouldn't get registered.As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16 and Go 1.17.
HelpCommand is declared, inject a help subcommand to all commands, not just the ones that have children.
This really simplifies discoverabilty for new users.getoptions.Pass ensure that unknown options are passthrough in the same order they were given.
This is useful when doing wrappers.As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16 and Go 1.17.
This refactor brings major benefits in both parsing and autocompletion. In the initial implementation, completion was added as side logic to the existing parser code. In this implementation, completions are a first class citizen and share the same parsing tree structure that the rest of the library is using.
The parsing tree was refactored from the ground up to better accommodate commands and subcommands and also the extra use cases that have been popping up ever since autocompletion support was added.
The major user facing change is that instead of providing building blocks to build a command and subcommand experience, a single opt.Parse and opt.Dispatch call is required to handle options for commands and subcommands at all levels.
opt.HelpCommand there is no need to define a help option as it also declares one.- opt.Bool("help", false, opt.Alias("?"))
- opt.HelpCommand("")
+ opt.HelpCommand("help", opt.Alias("?"))
HelpCommand declaration.- err = opt.Dispatch(ctx, "help", remaining)
+ err = opt.Dispatch(ctx, remaining)
InterruptContext into a package level function and not a method of GetOpt.- ctx, cancel, done := opt.InterruptContext()
+ ctx, cancel, done := getoptions.InterruptContext()
Write io.Writer used to write warnings and errors (which defaults to os.Stderr) has been made into a package level variable and not a method of GetOpt.
CommandFn is no longer an exported field of GetOpt.
If this was ever used, now the canonical way to execute a command function is through opt.Dispatch.
Remove opt.Option, this was used in test code to return the internal representation of an option and shouldn't be accessed directly by an end user.
Remove opt.Stringer, this was used to print a text representation of the parsed structure but other than in test code there is little value for it.
Moved exported packages that this library uses into the internal directory so they can't be imported by other projects by mistake.
Change opt.CustomCompletion signature:
- func (gopt *GetOpt) CustomCompletion(list []string) *GetOpt
+ func (gopt *GetOpt) CustomCompletion(list ...string) *GetOpt
Autocompletion is super useful now.
New setting: opt.UnsetOptions
Since options are automatically inherited to commands and subcommands, in cases where you want to override that inheritance and delete the inherited options use this.
This is useful for wrapper commands.
When a command doesn't have a defined command fn but that command has children, a help landing page is displayed automatically.
As the releases before, this release has 100% test coverage. Tested with Go 1.14, 1.15, 1.16 and Go 1.17.
Add SetMaxParallel method to DAG graph to limit concurrency.
Add SetOutputBuffer method to DAG graph to allow buffering task output in memory and printing it at the end of the task execution for easier debugging.
Enable completion results after options that require arguments.
dag: DephFirstSort() -> DepthFirstSort()