kongcompletion

README

Tab Completion for kong

kong-completion is a drop-in library that provides tab completion for CLI apps written with kong.

It currently supports the following shells:

• Bash
• Zsh
• Fish

kong-completion provides two main functionalities:

• It makes a kong app able to intercept and respond to tab completion requests. The completions are automatically derived from kong annotations. They can optionally be enhanced or adjusted with custom predictors.
• Since users have to manually activate the completion functionality in their shell, kong-completion provides a subcommand that instructs them how to achieve this.

Get Started

See the code of the sample app for how to use the library.

For the Completion subcommand, you can specify the following parameters in the annotation:

• completion-shell-default
  • Whether completions should fall back to the shell’s default ones, e.g. to complete file paths.
  • Possible values: true, false
  • Default value: true
  • Usage example: completion-shell-default:"false"

In case you want to compile and run the demo app, keep in mind that completions only work for binaries in your $PATH, not for local ones (e.g. with ./ prefix).

About

kong-completion is free and open-source software, distributed under the MIT license.

This library was originally based on kongplete.

Documentation

Index

• func Command(parser *kong.Kong, opt ...Option) (complete.Command, error)
• func Register(parser *kong.Kong, opt ...Option)
• type Completion
  • func (c *Completion) Help() string
  • func (c *Completion) Run(ctx *kong.Context) error
• type Option
  • func WithErrorHandler(handler func(error)) Option
  • func WithExitFunc(exitFunc func(code int)) Option
  • func WithFlagOverrides(overrides ...map[string]bool) Option
  • func WithPredictor(name string, predictor complete.Predictor) Option
  • func WithPredictors(predictors map[string]complete.Predictor) Option
• type PositionalPredictor
  • func (p *PositionalPredictor) Predict(a complete.Args) []string

Functions

func Command

func Command(parser *kong.Kong, opt ...Option) (complete.Command, error)

Command returns a completion Command for a kong parser

func Register

func Register(parser *kong.Kong, opt ...Option)

Register configures a kong app for intercepting completions.

Types

type Completion

type Completion struct {
	Shell string `arg:"" help:"The name of the shell you are using" enum:"bash,zsh,fish," default:""`
	Code  bool   `short:"c" help:"Generate the initialization code"`
}

Completion is a kong subcommand that prints out the shell code for initializing tab completion in various shells. It also educates the user what to do with the printed code.

func (*Completion) Help

func (c *Completion) Help() string

Help is a predefined kong method for printing the help text.

func (*Completion) Run

func (c *Completion) Run(ctx *kong.Context) error

Run is a predefined kong method that contains the command’s main procedure.

type Option

type Option func(*options)

Option is a configuration option for running Register

func WithErrorHandler

func WithErrorHandler(handler func(error)) Option

WithErrorHandler handle errors with completions

func WithExitFunc

func WithExitFunc(exitFunc func(code int)) Option

WithExitFunc the exit command that is run after completions

func WithFlagOverrides

func WithFlagOverrides(overrides ...map[string]bool) Option

WithFlagOverrides registers overrides for hidden commands / flags

func WithPredictor

func WithPredictor(name string, predictor complete.Predictor) Option

WithPredictor use the named predictor

func WithPredictors

func WithPredictors(predictors map[string]complete.Predictor) Option

WithPredictors use these predictors

type PositionalPredictor

type PositionalPredictor struct {
	Predictors []complete.Predictor
	ArgFlags   []string
	BoolFlags  []string
}

PositionalPredictor is a predictor for positional arguments

func (*PositionalPredictor) Predict

func (p *PositionalPredictor) Predict(a complete.Args) []string

Predict implements complete.Predict