kongplete

README

kongplete

You kongplete me.

kongplete lets you generate shell completions for your command-line programs using github.com/alecthomas/kong and github.com/posener/complete.

Examples

// This example is adapted from the shell example in github.com/alecthomas/kong

package main

import (
	"fmt"
	"os"

	"github.com/alecthomas/kong"
	"github.com/posener/complete"
	"github.com/willabides/kongplete"
)

var shellCli struct {
	Rm struct {
		User      string `help:"Run as user." short:"u" default:"default"`
		Force     bool   `help:"Force removal." short:"f"`
		Recursive bool   `help:"Recursively remove files." short:"r"`

		Paths []string `arg:"" help:"Paths to remove." type:"path" name:"path" predictor:"file"`
	} `cmd:"" help:"Remove files."`

	Ls struct {
		Paths []string `arg:"" optional:"" help:"Paths to list." type:"path" predictor:"file"`
	} `cmd:"" help:"List paths."`

	Debug bool `help:"Debug mode."`

	InstallCompletions kongplete.InstallCompletions `cmd:"" help:"install shell completions"`
}

func main() {
	// Create a kong parser as usual, but don't run Parse quite yet.
	parser := kong.Must(&shellCli,
		kong.Name("shell"),
		kong.Description("A shell-like example app."),
		kong.UsageOnError(),
	)

	// Run kongplete.Complete to handle completion requests
	kongplete.Complete(parser,
		kongplete.WithPredictor("file", complete.PredictFiles("*")),
	)

	// Proceed as normal after kongplete.Complete.
	ctx, err := parser.Parse(os.Args[1:])
	parser.FatalIfErrorf(err)

	switch ctx.Command() {
	case "rm <path>":
		fmt.Println(shellCli.Rm.Paths, shellCli.Rm.Force, shellCli.Rm.Recursive)

	case "ls":
	}
}

Documentation

Overview

You kongplete me.

kongplete lets you generate shell completions for your command-line programs using github.com/alecthomas/kong and github.com/posener/complete.

Example

// This example is adapted from the shell example in github.com/alecthomas/kong

package main

import (
	"fmt"
	"os"

	"github.com/alecthomas/kong"
	"github.com/posener/complete"
	"github.com/willabides/kongplete"
)

var shellCli struct {
	Rm struct {
		User      string `help:"Run as user." short:"u" default:"default"`
		Force     bool   `help:"Force removal." short:"f"`
		Recursive bool   `help:"Recursively remove files." short:"r"`

		Paths []string `arg:"" help:"Paths to remove." type:"path" name:"path" predictor:"file"`
	} `cmd:"" help:"Remove files."`

	Ls struct {
		Paths []string `arg:"" optional:"" help:"Paths to list." type:"path" predictor:"file"`
	} `cmd:"" help:"List paths."`

	Debug bool `help:"Debug mode."`

	InstallCompletions kongplete.InstallCompletions `cmd:"" help:"install shell completions"`
}

func main() {
	// Create a kong parser as usual, but don't run Parse quite yet.
	parser := kong.Must(&shellCli,
		kong.Name("shell"),
		kong.Description("A shell-like example app."),
		kong.UsageOnError(),
	)

	// Run kongplete.Complete to handle completion requests
	kongplete.Complete(parser,
		kongplete.WithPredictor("file", complete.PredictFiles("*")),
	)

	// Proceed as normal after kongplete.Complete.
	ctx, err := parser.Parse(os.Args[1:])
	parser.FatalIfErrorf(err)

	switch ctx.Command() {
	case "rm <path>":
		fmt.Println(shellCli.Rm.Paths, shellCli.Rm.Force, shellCli.Rm.Recursive)

	case "ls":
	}
}

Index

• func Command(parser *kong.Kong, opt ...Option) (complete.Command, error)
• func Complete(parser *kong.Kong, opt ...Option)
• func InstallShellCompletions(k *kong.Context) error
• func UninstallShellCompletions(k *kong.Context) error
• type InstallCompletions
  • func (c *InstallCompletions) Run(k *kong.Context) error
• type Option
  • func WithErrorHandler(handler func(error)) Option
  • func WithExitFunc(exitFunc func(code int)) Option
  • func WithPredictor(name string, predictor complete.Predictor) Option
  • func WithPredictors(predictors map[string]complete.Predictor) Option

Examples

• Package

Functions

func Command

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

Command returns a completion Command for a kong parser

func Complete

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

Complete runs completion for a kong parser

func InstallShellCompletions

func InstallShellCompletions(k *kong.Context) error

InstallShellCompletions is a helper to install completions for a kong context

func UninstallShellCompletions

func UninstallShellCompletions(k *kong.Context) error

UninstallShellCompletions is a helper to uninstall completions for a kong context

Types

type InstallCompletions

type InstallCompletions struct {
	Uninstall bool
}

InstallCompletions is a kong command for installing or uninstalling shell completions

func (*InstallCompletions) Run

func (c *InstallCompletions) Run(k *kong.Context) error

Run runs InstallCompletions

type Option

type Option func(*options)

Option is a configuration option for running Complete

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