kong

Documentation

Overview

Package kong adapts Conductor to kong-based CLIs: one call builds the parser with themed help, shell completions, version wiring and update notifications, mirroring the conventions of clib's cli/kong package.

Index

• type Flags
  • func (f Flags) ConductorFlags() conductor.Flags
• type Option
  • func WithBind(values ...any) Option
  • func WithCompletionHandler(handler complete.Handler) Option
  • func WithExitCode(fn func(error) int) Option
  • func WithGenerator(fn func(*complete.Generator)) Option
  • func WithKongOptions(opts ...konglib.Option) Option
  • func WithNoDefaultCommand() Option
  • func WithNodeSections(opts ...clibkong.NodeSectionsOption) Option
• type Program
  • func New(app *conductor.Runtime, cli any, opts ...Option) (*Program, error)
  • func (p *Program) Parse(args []string) (*konglib.Context, bool, int, error)
  • func (p *Program) Run(args []string) int
• type SelfUpdateFlag
  • func (f SelfUpdateFlag) SelfUpdateRequested() bool
• type UpdateCmd
  • func (c *UpdateCmd) Run(app *conductor.Runtime) error
• type VersionCmd
  • func (c *VersionCmd) Run(app *conductor.Runtime) error

Types

type Flags

type Flags struct {
	clibkong.CompletionFlags

	Verbose bool           `help:"Show debug logs"   short:"v"        xor:"verbosity"`
	Quiet   bool           `help:"Only show errors"  short:"q"        xor:"verbosity"`
	Color   clog.ColorMode `help:"When to use color" aliases:"colour" default:"auto"  enum:"auto,always,never"`

	VersionFlag konglib.VersionFlag `name:"version" help:"Print version information" short:"V" hidden:""`
}

Flags is the standard embeddable flag block: shell-completion management plus the verbosity/color/version trio every tool shares. Embedding it makes the CLI a conductor.FlagSource, so Program.Run applies the flags to clog automatically after parsing.

func (Flags) ConductorFlags

func (f Flags) ConductorFlags() conductor.Flags

ConductorFlags implements conductor.FlagSource.

type Option

type Option func(*config)

Option configures New.

func WithBind

func WithBind(values ...any) Option

WithBind binds extra values into the kong context for command Run methods.

func WithCompletionHandler

func WithCompletionHandler(handler complete.Handler) Option

WithCompletionHandler installs the callback invoked for dynamic --@complete requests; it receives the completion type and resolved shell.

func WithExitCode

func WithExitCode(fn func(error) int) Option

WithExitCode maps command errors to exit codes; see conductor.ExitCode.

func WithGenerator

func WithGenerator(fn func(*complete.Generator)) Option

WithGenerator customises the completion generator before the parser is built, e.g. to add dynamic argument specs.

func WithKongOptions

func WithKongOptions(opts ...konglib.Option) Option

WithKongOptions appends extra kong options after Conductor's own, so they can override any default.

func WithNoDefaultCommand

func WithNoDefaultCommand() Option

WithNoDefaultCommand skips kong dispatch in Program.Run for flag-only CLIs that inspect the parse result themselves.

func WithNodeSections

func WithNodeSections(opts ...clibkong.NodeSectionsOption) Option

WithNodeSections configures the help section builder.

type Program

type Program struct {
	Runtime *conductor.Runtime
	Parser  *konglib.Kong
	Gen     *complete.Generator
	// contains filtered or unexported fields
}

Program is the assembled kong CLI. All fields are exported and may be customised between New and Program.Run.

func New

func New(app *conductor.Runtime, cli any, opts ...Option) (*Program, error)

New builds the parser, completion generator and help wiring for cli, a pointer to a kong grammar struct (usually embedding Flags).

func (*Program) Parse

func (p *Program) Parse(args []string) (*konglib.Context, bool, int, error)

Parse is the granular path for tools that dispatch themselves: it handles completion preflight (the bool result reports a completion action ran and the caller should exit with the int code) and parses args, leaving flag application, notify and dispatch to the caller.

func (*Program) Run

func (p *Program) Run(args []string) int

Run is the one-call happy path: completion preflight, parse, standard flag application, update notification, dispatch, deferred hint flush, and exit code mapping. The caller passes the result to os.Exit.

type SelfUpdateFlag

type SelfUpdateFlag struct {
	SelfUpdate bool `name:"self-update" help:"Update to the latest version" hidden:""`
}

SelfUpdateFlag is an embeddable hidden --self-update flag for flag-only CLIs that have no subcommands to hang an update command off. When set, Program.Run performs the self-update via App.Updater instead of dispatching, and exits.

func (SelfUpdateFlag) SelfUpdateRequested

func (f SelfUpdateFlag) SelfUpdateRequested() bool

SelfUpdateRequested reports whether the self-update flag was set.

type UpdateCmd

type UpdateCmd struct {
	Check       bool `help:"Report whether an update is available without installing"`
	Stable      bool `help:"Install the latest stable release"                        clib:"group='Channel/0'" xor:"channel"`
	Dev         bool `help:"Install the latest source build"                          clib:"group='Channel/0'" xor:"channel"`
	NoUninstall bool `help:"Keep a conflicting installation in place"                 clib:"group='Cleanup/0'"`
}

UpdateCmd is an embeddable self-update subcommand:

Update kong.UpdateCmd `cmd:"" help:"Update <app> to the latest version"`

It dispatches on App.Updater's install method (brew, goinstall or github); tools distributed another way provide their own update command instead.

func (*UpdateCmd) Run

func (c *UpdateCmd) Run(app *conductor.Runtime) error

Run checks for or installs the update.

type VersionCmd

type VersionCmd struct {
	Detailed bool `help:"Show detailed build information" short:"d"`
}

VersionCmd is an embeddable `version` subcommand:

Version kong.VersionCmd `cmd:"" help:"Print version information"`

func (*VersionCmd) Run

func (c *VersionCmd) Run(app *conductor.Runtime) error

Run prints the version via the bound conductor.Runtime.