komplete

README

komplete is a command-line completion engine for the Kong CLI parser See API Reference for usage information.

This software is made available under the BSD-3 license. See LICENSE for the full license text.

Documentation

Overview

Package komplete is a package for generating completions for Kong CLIs.

To use it, build a Kong parser from your CLI grammar, and then call Run with it to run the completion logic. This will automatically determine if the CLI is being invoked as a completion script or as a regular command.

parser, err := kong.New(cli)
// ...
komplete.Run(parser)

Command is provided as a convenient subcommand for generating completion scripts for various shells.

Custom logic to predict values for flags and arguments can be provided through WithPredictor. Install a predictor with a name, and refer to it in your CLI grammar with the `predictor:"name"` tag.

type CLI struct {
	Name string `help:"Name of the branch" predictor:"branches"`
	// ...
}

// ...
komplete.Run(parser,
	komplete.WithPredictor("branches", branchesPredictor),
	// ...
)

Index

• func Run(parser *kong.Kong, opts ...Option)
• type Args
  • func (as Args) String() string
• type Command
  • func (cmd *Command) Run(kctx *kong.Context) (err error)
• type Option
  • func WithPredictor(name string, predictor Predictor) Option
  • func WithTransformCompleted(fn func([]string) []string) Option
• type PredictFunc
  • func (f PredictFunc) Predict(cargs Args) []string
• type Predictor

Functions

func Run

func Run(parser *kong.Kong, opts ...Option)

Run runs the CLI argument completer if the user has requested completions. Otherwise, this is a no-op.

Types

type Args

type Args struct {
	// Completed is a list of arguments that have already been completed,
	// preceding the argument currently being typed.
	Completed []string

	// Last is the typed portion of the current argument.
	// Predictions will typically be matched against this.
	Last string
}

Args holds the command line completion arguments.

func (Args) String

func (as Args) String() string

type Command

type Command struct {
	Shell string `enum:"bash,zsh,fish," arg:"" default:"" optional:"" help:"Shell to generate completions for."`
}

Command is the command to run to generate the completion script. It is intended to be used as a subcommand of the main CLI.

func (*Command) Run

func (cmd *Command) Run(kctx *kong.Context) (err error)

Run runs the completion script generator. It will print the completion script to stdout and exit.

type Option

type Option func(*options)

Option customizes completion logic.

func WithPredictor

func WithPredictor(name string, predictor Predictor) Option

WithPredictor adds a named predictor to the completion logic.

Flags and arguments can request a predictor for their values by adding a `predictor:"name"` tag to the field.

type CLI struct {
	Name string `help:"Name of the branch" predictor:"branches"`
	// ...
}

komplete.Run(parser,
	komplete.WithPredictor("branches", branchesPredictor),
)

func WithTransformCompleted

func WithTransformCompleted(fn func([]string) []string) Option

WithTransformCompleted allows modifying the list of completed arguments, allowing replication of any os.Args transformations.

type PredictFunc

type PredictFunc func(Args) []string

PredictFunc is a function that predicts completions for a set of arguments.

func (PredictFunc) Predict

func (f PredictFunc) Predict(cargs Args) []string

Predict calls the function to predict completions.

type Predictor

type Predictor interface {
	Predict(Args) []string
}

Predictor predicts completions for a given set of arguments.