Add Bash Completion Support

README.md

@@ -24,6 +24,7 @@
   - [Default Values](#default-values)
   - [Place-holders in Help](#place-holders-in-help)
   - [Consuming all remaining arguments](#consuming-all-remaining-arguments)
+  - [Bash/ZSH Shell Completion](#bashzsh-shell-completion)
   - [Supporting -h for help](#supporting--h-for-help)
   - [Custom help](#custom-help)
 
@@ -508,6 +509,100 @@ And use it like so:
 ips := IPList(kingpin.Arg("ips", "IP addresses to ping."))
 ```
 
+### Bash/ZSH Shell Completion
+
+By default, all flags and commands/subcommands generate completions 
+internally.
+
+Out of the box, CLI tools using kingpin should be able to take advantage 
+of completion hinting for flags and commands. By specifying 
+`--completion-bash` as the first argument, your CLI tool will show 
+possible subcommands. By ending your argv with `--`, hints for flags 
+will be shown.
+
+To allow your end users to take advantage you must package a 
+`/etc/bash_completion.d` script with your distribution (or the equivalent 
+for your target platform/shell). An alternative is to instruct your end 
+user to source a script from their `bash_profile` (or equivalent).
+
+Fortunately Kingpin makes it easy to generate or source a script for use
+with end users shells. `./yourtool --completion-script-bash` and 
+`./yourtool --completion-script-zsh` will generate these scripts for you.
+
+**Installation by Package**
+
+For the best user experience, you should bundle your pre-created 
+completion script with your CLI tool and install it inside 
+`/etc/bash_completion.d` (or equivalent). A good suggestion is to add 
+this as an automated step to your build pipeline, in the implementation 
+is improved for bug fixed.
+
+**Installation by `bash_profile`**
+
+Alternatively, instruct your users to add an additional statement to 
+their `bash_profile` (or equivalent):
+
+```
+eval "$(your-cli-tool --completion-script-bash)"
+```
+
+Or for ZSH
+
+```
+eval "$(your-cli-tool --completion-script-zsh)"
+```
+
+#### Additional API
+To provide more flexibility, a completion option API has been
+exposed for flags to allow user defined completion options, to extend
+completions further than just EnumVar/Enum. 
+
+
+**Provide Static Options**
+
+When using an `Enum` or `EnumVar`, users are limited to only the options 
+given. Maybe we wish to hint possible options to the user, but also 
+allow them to provide their own custom option. `HintOptions` gives
+this functionality to flags.
+
+```
+app := kingpin.New("completion", "My application with bash completion.")
+app.Flag("port", "Provide a port to connect to").
+    Required().
+    HintOptions("80", "443", "8080").
+    IntVar(&c.port)
+```
+
+**Provide Dynamic Options**
+Consider the case that you needed to read a local database or a file to 
+provide suggestions. You can dynamically generate the options
+
+```
+func listHosts(args []string) []string {
+  // Provide a dynamic list of hosts from a hosts file or otherwise
+  // for bash completion. In this example we simply return static slice.
+
+  // You could use this functionality to reach into a hosts file to provide
+  // completion for a list of known hosts.
+  return []string{"sshhost.example", "webhost.example", "ftphost.example"}
+}
+
+app := kingpin.New("completion", "My application with bash completion.")
+app.Flag("flag-1", "").HintAction(listHosts).String()
+```
+
+**EnumVar/Enum**
+When using `Enum` or `EnumVar`, any provided options will be automatically
+used for bash autocompletion. However, if you wish to provide a subset or 
+different options, you can use `HintOptions` or `HintAction` which will override
+the default completion options for `Enum`/`EnumVar`.
+
+
+**Examples**
+You can see an in depth example of the completion API within 
+`examples/completion/main.go`
+
+
 ### Supporting -h for help
 
 `kingpin.CommandLine.HelpFlag.Short('h')`

app.go

@@ -21,10 +21,7 @@ type ApplicationValidator func(*Application) error
 // An Application contains the definitions of flags, arguments and commands
 // for an application.
 type Application struct {
-	*flagGroup
-	*argGroup
-	*cmdGroup
-	actionMixin
+	cmdMixin
 	initialized bool
 
 	Name string
@@ -38,6 +35,7 @@ type Application struct {
 	terminate      func(status int) // See Terminate()
 	noInterspersed bool             // can flags be interspersed with args (or must they come first)
 	defaultEnvars  bool
+	completion     bool
 
 	// Help flag. Exposed for user customisation.
 	HelpFlag *FlagClause
@@ -50,19 +48,23 @@ type Application struct {
 // New creates a new Kingpin application instance.
 func New(name, help string) *Application {
 	a := &Application{
-		flagGroup:     newFlagGroup(),
-		argGroup:      newArgGroup(),
 		Name:          name,
 		Help:          help,
 		writer:        os.Stderr,
 		usageTemplate: DefaultUsageTemplate,
 		terminate:     os.Exit,
 	}
+	a.flagGroup = newFlagGroup()
+	a.argGroup = newArgGroup()
 	a.cmdGroup = newCmdGroup(a)
 	a.HelpFlag = a.Flag("help", "Show context-sensitive help (also try --help-long and --help-man).")
 	a.HelpFlag.Bool()
 	a.Flag("help-long", "Generate long help.").Hidden().PreAction(a.generateLongHelp).Bool()
 	a.Flag("help-man", "Generate a man page.").Hidden().PreAction(a.generateManPage).Bool()
+	a.Flag("completion-bash", "Output possible completions for the given args.").Hidden().BoolVar(&a.completion)
+	a.Flag("completion-script-bash", "Generate completion script for bash.").Hidden().PreAction(a.generateBashCompletionScript).Bool()
+	a.Flag("completion-script-zsh", "Generate completion script for ZSH.").Hidden().PreAction(a.generateZSHCompletionScript).Bool()
+
 	return a
 }
 
@@ -84,6 +86,24 @@ func (a *Application) generateManPage(c *ParseContext) error {
 	return nil
 }
 
+func (a *Application) generateBashCompletionScript(c *ParseContext) error {
+	a.Writer(os.Stdout)
+	if err := a.UsageForContextWithTemplate(c, 2, BashCompletionTemplate); err != nil {
+		return err
+	}
+	a.terminate(0)
+	return nil
+}
+
+func (a *Application) generateZSHCompletionScript(c *ParseContext) error {
+	a.Writer(os.Stdout)
+	if err := a.UsageForContextWithTemplate(c, 2, ZshCompletionTemplate); err != nil {
+		return err
+	}
+	a.terminate(0)
+	return nil
+}
+
 // DefaultEnvars configures all flags (that do not already have an associated
 // envar) to use a default environment variable in the form "<app>_<flag>".
 //
@@ -145,17 +165,48 @@ func (a *Application) parseContext(ignoreDefault bool, args []string) (*ParseCon
 // This will populate all flag and argument values, call all callbacks, and so
 // on.
 func (a *Application) Parse(args []string) (command string, err error) {
-	context, err := a.ParseContext(args)
-	if err != nil {
+
+	context, parseErr := a.ParseContext(args)
+	selected := []string{}
+	var setValuesErr error
+
+	if context == nil {
+		// Since we do not throw error immediately, there could be a case
+		// where a context returns nil. Protect against that.
+		return "", parseErr
+	}
+
+	if err = a.setDefaults(context); err != nil {
 		return "", err
 	}
-	a.maybeHelp(context)
-	if !context.EOL() {
-		return "", fmt.Errorf("unexpected argument '%s'", context.Peek())
+
+	selected, setValuesErr = a.setValues(context)
+
+	if err = a.applyPreActions(context, !a.completion); err != nil {
+		return "", err
 	}
-	command, err = a.execute(context)
-	if err == ErrCommandNotSpecified {
-		a.writeUsage(context, nil)
+
+	if a.completion {
+		a.generateBashCompletion(context)
+		a.terminate(0)
+	} else {
+		if parseErr != nil {
+			return "", parseErr
+		}
+
+		a.maybeHelp(context)
+		if !context.EOL() {
+			return "", fmt.Errorf("unexpected argument '%s'", context.Peek())
+		}
+
+		if setValuesErr != nil {
+			return "", setValuesErr
+		}
+
+		command, err = a.execute(context, selected)
+		if err == ErrCommandNotSpecified {
+			a.writeUsage(context, nil)
+		}
 	}
 	return command, err
 }
@@ -325,22 +376,8 @@ func checkDuplicateFlags(current *CmdClause, flagGroups []*flagGroup) error {
 	return nil
 }
 
-func (a *Application) execute(context *ParseContext) (string, error) {
+func (a *Application) execute(context *ParseContext, selected []string) (string, error) {
 	var err error
-	selected := []string{}
-
-	if err = a.setDefaults(context); err != nil {
-		return "", err
-	}
-
-	selected, err = a.setValues(context)
-	if err != nil {
-		return "", err
-	}
-
-	if err = a.applyPreActions(context); err != nil {
-		return "", err
-	}
 
 	if err = a.validateRequired(context); err != nil {
 		return "", err
@@ -492,18 +529,21 @@ func (a *Application) applyValidators(context *ParseContext) (err error) {
 	return err
 }
 
-func (a *Application) applyPreActions(context *ParseContext) error {
+func (a *Application) applyPreActions(context *ParseContext, dispatch bool) error {
 	if err := a.actionMixin.applyPreActions(context); err != nil {
 		return err
 	}
 	// Dispatch to actions.
-	for _, element := range context.Elements {
-		if applier, ok := element.Clause.(actionApplier); ok {
-			if err := applier.applyPreActions(context); err != nil {
-				return err
+	if dispatch {
+		for _, element := range context.Elements {
+			if applier, ok := element.Clause.(actionApplier); ok {
+				if err := applier.applyPreActions(context); err != nil {
+					return err
+				}
 			}
 		}
 	}
+
 	return nil
 }
 
@@ -564,6 +604,83 @@ func (a *Application) FatalIfError(err error, format string, args ...interface{}
 	}
 }
 
+func (a *Application) completionOptions(context *ParseContext) []string {
+	args := context.rawArgs
+
+	var (
+		currArg string
+		prevArg string
+		target  cmdMixin
+	)
+
+	numArgs := len(args)
+	if numArgs > 1 {
+		args = args[1:]
+		currArg = args[len(args)-1]
+	}
+	if numArgs > 2 {
+		prevArg = args[len(args)-2]
+	}
+
+	target = a.cmdMixin
+	if context.SelectedCommand != nil {
+		// A subcommand was in use. We will use it as the target
+		target = context.SelectedCommand.cmdMixin
+	}
+
+	if (currArg != "" && strings.HasPrefix(currArg, "--")) || strings.HasPrefix(prevArg, "--") {
+		// Perform completion for A flag. The last/current argument started with "-"
+		var (
+			flagName  string // The name of a flag if given (could be half complete)
+			flagValue string // The value assigned to a flag (if given) (could be half complete)
+		)
+
+		if strings.HasPrefix(prevArg, "--") && !strings.HasPrefix(currArg, "--") {
+			// Matches: 	./myApp --flag value
+			// Wont Match: 	./myApp --flag --
+			flagName = prevArg[2:] // Strip the "--"
+			flagValue = currArg
+		} else if strings.HasPrefix(currArg, "--") {
+			// Matches: 	./myApp --flag --
+			// Matches:		./myApp --flag somevalue --
+			// Matches: 	./myApp --
+			flagName = currArg[2:] // Strip the "--"
+		}
+
+		options, flagMatched, valueMatched := target.FlagCompletion(flagName, flagValue)
+		if valueMatched {
+			// Value Matched. Show cmdCompletions
+			return target.CmdCompletion()
+		}
+
+		// Add top level flags if we're not at the top level and no match was found.
+		if context.SelectedCommand != nil && flagMatched == false {
+			topOptions, topFlagMatched, topValueMatched := a.FlagCompletion(flagName, flagValue)
+			if topValueMatched {
+				// Value Matched. Back to cmdCompletions
+				return target.CmdCompletion()
+			}
+
+			if topFlagMatched {
+				// Top level had a flag which matched the input. Return it's options.
+				options = topOptions
+			} else {
+				// Add top level flags
+				options = append(options, topOptions...)
+			}
+		}
+		return options
+	} else {
+		// Perform completion for sub commands.
+		return target.CmdCompletion()
+	}
+}
+
+func (a *Application) generateBashCompletion(context *ParseContext) {
+	options := a.completionOptions(context)
+	fmt.Printf("%s", strings.Join(options, "\n"))
+}
+
 func envarTransform(name string) string {
 	return strings.ToUpper(envarTransformRegexp.ReplaceAllString(name, "_"))
 }