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"`
		Hidden    string `help:"A hidden flag" hidden:""`

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

	Hidden struct{} `cmd:"" help:"A hidden command" hidden:""`

	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", "hidden":
	}
}

Documentation

Overview

Package 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"`
		Hidden    string `help:"A hidden flag" hidden:""`

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

	Hidden struct{} `cmd:"" help:"A hidden command" hidden:""`

	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", "hidden":
	}
}

Index

• func Command(parser *kong.Kong, opt ...Option) (complete.Command, error)
• func Complete(parser *kong.Kong, opt ...Option)
• type InstallCompletions
  • func (c *InstallCompletions) BeforeApply(ctx *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

Types

type InstallCompletions

type InstallCompletions struct {
	Uninstall bool
}

InstallCompletions is a kong command for installing or uninstalling shell completions

func (*InstallCompletions) BeforeApply

func (c *InstallCompletions) BeforeApply(ctx *kong.Context) error

BeforeApply installs completion into the users shell.

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