v0.24.0: New Features

As the releases before, this release has 100% test coverage.
Tested with Go 1.14, 1.15, 1.16 and Go 1.17.

New Features

• 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.

Fixes

• Fix spelling mistake in package dag: DephFirstSort() -> DepthFirstSort()

v0.23.0: Feature Updates

As the releases before, this release has 100% test coverage.
Tested with Go 1.14 and Go 1.15.

Feature Updates

• Introduce Float64Optional and Float64VarOptional to have complete method parity for String, Int and Float64 types.

• Support multi-line command descriptions.

• Add GetEnv support for missing single option types:

  • Int, IntVar, IntOptional, IntVarOptional
  • StringOptional, StringVarOptional
  • Float64, Float64Var, Float64Optional, Float64VarOptional

  NOTE: For numeric values, opt.Int and opt.Float64 and their derivatives, environment variable string conversion errors are ignored and the default value is assigned.

v0.22.0: Breaking Change

As the releases before, this release has 100% test coverage.
Tested with Go 1.14 and Go 1.15.

Bug fix

Fix completion issues where a completion that works when starting to complete from scratch fails when some args are deleted.

Fixed by changing the exit status when generating completions from 1 to 124.
Exit 124 means programmable completion restarts from the beginning, with an attempt to find a new compspec for that command.

Feature Removal

Removing negatable flags NBool and NBoolVar.
A feature that adds a bunch of complexity for very little value and prevents reading environment variables into booleans.

New Features

• opt.GetEnv Is now supported when using opt.Bool and opt.BoolVar.
  Previously only opt.String and opt.StringVar were supported.

  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".

• opt.Dispatch now automatically handles the help flag.
  The help flag needs to be defined at the top level.
  When the help flag is called and handled by a command opt.Dispatch now returns an error of type getoptions.ErrorHelpCalled.

  For example:

func main() {
	os.Exit(program())
}

func program() int {
	opt := getoptions.New()
	opt.Bool("help", false, opt.Alias("?"))    // Define the help flag as "--help" with alias "-?"
	list := opt.NewCommand("list", "list stuff").SetCommandFn(listRun)
	list.Bool("list-opt", false)
	opt.HelpCommand("")
	remaining, err := opt.Parse(os.Args[1:])
	if err != nil {
		fmt.Fprintf(os.Stderr, "ERROR: %s\n", err)
		os.Exit(1)
	}

	ctx, cancel, done := opt.InterruptContext()
	defer func() { cancel(); <-done }()

	err = opt.Dispatch(ctx, "help", remaining) // Use the same help flag "help".
	if err != nil {
		if errors.Is(err, getoptions.ErrorHelpCalled) {
			return 1
		}
		fmt.Fprintf(os.Stderr, "ERROR: %s\n", err)
		return 1
	}
	return 0
}

Now, calling program list --help or program list -? prints the help for the list command as well as calling program help list.

v0.21.0: Breaking Change

As the releases before, this release has 100% test coverage.

Drop support for Go versions before 1.14

Dropping support for Go 1.10, 1.11, 1.12 and 1.13 to leverage new errors and testing features.

In particular The errors.Is and errors.As features greatly simplify error testing and handling and are used in the new DAG build system.

New Feature

Introduces a new Directed Acyclic Graph Build System.

The build system is a separate import package: import "github.com/DavidGamba/go-getoptions/dag"

Documentation can be found in its own README.

v0.20.2: Feature Update

As the releases before, this release has 100% test coverage.

Deprecration WARNING

Support for Go 1.10, 1.11 and 1.12 will be dropped in a future release.
The errors.Is and errors.As features greatly simplify error testing and handling and will likely be introduced in the near future.

Improve autocompletion behaviour.

• Pass autocompletion entries to children.

From v0.20.0 all options started being passed to children commands.
Their completion entries were missing.

• Separate internal option completion between flags that don't expect an argument and options that do.
  When an option that expects an argument is found, the given argument won't break the completion chain.
  Only one argument is supported per option.

• Don't break autocompletion chain when there is an option in the chain that accepts an argument with =.
  For example: program --profile=dev <tab><tab> will show completions for program.

v0.20.1: Feature Update

As the releases before, this release has 100% test coverage.

• Improve autocompletion behaviour:

  Break words in COMP_LINE by matching against multiple spaces \s+ instead of a single one.

v0.20.0: Breaking Change

As the releases before, this release has 100% test coverage.

Method Deprecation

• Deprecate opt.SetOption

Since the introduction of opt.NewCommand(name, description string) there is a proper parent child relationship between commands.
There is no need to hack passing desired options to the child command, instead, now all options are automatically propagated to the child.

This has the side benefit to make the automated help clearer by listing all options that previously where only listed in one of the parent levels.

To update, remove calls to opt.SetOption, for example:

 	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.SetOption(opt.Option("help"), opt.Option("debug")).SetCommandFn(listRun)
+	list.SetCommandFn(listRun)
 	list.Bool("list-opt", false)
 	opt.HelpCommand("")
 	remaining, err := opt.Parse([]string{"list"})

Feature Update

• Automatically run opt.Parse when calling opt.Dispatch.

When defining a new command, we define the function that the command will run with command.SetCommandFn(commandFunction).
If the command is passed in the command line, opt.Dispatch calls the command function.
Previously, opt.Dispatch wasn't automatically calling opt.Parse in the command function so the first thing that every command function had to do was a call to parse.

For example:

func main() {
	opt := getoptions.New()
	list := opt.NewCommand("list", "list stuff")
	list.SetCommandFn(listRun)
	opt.HelpCommand("")
	remaining, err := opt.Parse(os.Args[1:])
	if err != nil {
		...
	}

	err = opt.Dispatch(context.Background(), "help", remaining)
	if err != nil {
		...
	}
}

func listRun(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
	remaining, err := opt.Parse(args)
	if err != nil {
		...
	}
	// Function code here
}

Now, the call opt.Parse is automated by opt.Dispatch so the command function is simplified to:

func listRun(ctx context.Context, opt *getoptions.GetOpt, args []string) error {
	// Function code here
}

Where the received opt has the arguments already parsed and the received args is the remaining arguments that didn't match any option.

v0.19.0: Feature update

As the releases before, this release has 100% test coverage.

Update

• opt.GetEnv now satisfies opt.Required:

When an environment variable that matches the variable from opt.GetEnv is set, opt.GetEnv will set opt.Called to true and will set opt.CalledAs 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.

• opt.GetEnv environment variable now shows in help output.

Example:

REQUIRED PARAMETERS:
    --access-key-id <string>        AWS Access Key ID. (env: AWS_ACCESS_KEY_ID)

    --role-arn <string>             Role ARN. (env: AWS_ROLE_ARN)

    --secret-access-key <string>    AWS Secret Access Key. (env: AWS_SECRET_ACCESS_KEY)

OPTIONS:
    --region <string>               Default Region. (default: "us-west-2", env: AWS_DEFAULT_REGION)

v0.18.0: Feature release

As the releases before, this release has 100% test coverage.

This release adds initial support for Environment Variables and adds lots of GoDoc examples.

New Features

• Initial support for environment variables has been added.

Currently, only opt.String and opt.StringVar are supported.

To use it, set the option modify function to opt.GetEnv.
For example:

var profile string
opt.StringVar(&profile, "profile", "default", opt.GetEnv("AWS_PROFILE"))

Or:

profile := opt.String("profile", "default", opt.GetEnv("AWS_PROFILE"))

NOTE: Non supported option types behave with a No-Op when opt.GetEnv is defined.

Minor changes

• Change opt.Dispatch signature to clarify the actual use of the variable.
  Additionally, actually use the variable, before it was hardcoded to "help".

-func (gopt *GetOpt) Dispatch(ctx context.Context, helpOptionName string, args []string) error
+func (gopt *GetOpt) Dispatch(ctx context.Context, helpCommandName string, args []string) error

v0.17.0: Breaking Changes

As the releases before, this release has 100% test coverage.

This release keeps on the work of removing the kinks around subcommands.
An example showing subcommands can be found in ./examples/mygit.

It also introduces the use of context to propagate cancelation signals, etc. to the child commands.

Finally, it introduces a new helper that captures interrupts (for example Ctrl-C) and returns a top level context.

Breaking changes

• Refactor NewCommmand as a method.
  This will allow the built-in help to have information about the parent.
  It might also help with autocompletion.

• Change sigature to opt.NewCommand(name, description string).
  It takes a name and description now.

• Change signature of CommandFn to have a context as the first argument.
  It will allow the parent to propagate cancelation signals, etc. to the child commands.
  This change goes along a change to the helper opt.Dispatch to also have a context as the first argument.

Updating:

-   list := getoptions.NewCommand().Self("list", "list instances").
+   list := opt.NewCommand("list", "list instances").
        SetOption(parent.Option("help"), parent.Option("debug")).
        SetCommandFn(runInstanceList)
    list.StringSlice("tag", 1, 99, opt.Alias("t"),
        opt.Description("Any AWS tags you want to list"))
-   opt.Command(list)

 ...

-   err = opt.Dispatch("help", remaining)
+   err = opt.Dispatch(context.Background(), "help", remaining)

 ...

-func runInstanceList(opt *getoptions.GetOpt, args []string) error {
+func runInstanceList(ctx context.Context, opt *getoptions.GetOpt, args []string) error {

New Features

• Introduce opt.InterruptContext(), a helper that returns a top level context that captures interrupt signals (os.Interrupt, syscall.SIGHUP, syscall.SIGTERM).
  An example can be found in ./examples/mygit.