kong

package
v0.7.17 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Args 

func Args(cli any) ([]help.Arg, error)

Args extracts positional argument entries from a CLI struct's reflected metadata. It returns entries suitable for use in help.Args content.

func CSVFlagPlaceholders added in v0.6.14 

func CSVFlagPlaceholders() konglib.Option

CSVFlagPlaceholders returns a Kong option that makes Kong describe CSVFlag values using each flag's name (for example, --route=ROUTE) instead of the Go type name (--route=CSV-FLAG). Explicit placeholder tags are preserved.

Pass this option to konglib.New or konglib.Must.

func CompletionCommand 

func CompletionCommand(genFunc func() *complete.Generator) konglib.Option

CompletionCommand returns a konglib.Option that registers a hidden "completion" subcommand powered by clib. Pass this to konglib.New.

The genFunc is called at run time to build the generator, so the full parser model is available.

func FlagSections 

func FlagSections(flags []complete.FlagMeta) []help.Section

FlagSections builds flag help sections from reflected FlagMeta. Flags are grouped by their Group field (from clib:"group='...'"). Compound group names ("Section/SubGroup") split flags within the same section into separate FlagGroup entries (blank line separator). Sections appear in first-seen order, with ungrouped flags in an "Options" section. Hidden flags and positional args are skipped.

func HelpPrinter 

func HelpPrinter(
	r *help.Renderer,
	sections func() ([]help.Section, error),
	opts ...help.Option,
) konglib.HelpPrinter

HelpPrinter returns a kong.HelpPrinter that renders the sections returned by the provided callback. By default, the description blurb and examples are hidden on -h and shown on --help (examples last); pass help.WithAlwaysShowDescription and/or help.WithAlwaysShowExamples to disable this.

func HelpPrinterFunc 

func HelpPrinterFunc(
	r *help.Renderer,
	sections func(*konglib.Context) ([]help.Section, error),
	opts ...help.Option,
) konglib.HelpPrinter

HelpPrinterFunc returns a context-aware kong.HelpPrinter. The sections callback receives the kong context, allowing help output to vary by subcommand. By default, the description blurb and examples are hidden on -h and shown on --help (examples last); pass help.WithAlwaysShowDescription and/or help.WithAlwaysShowExamples to disable this.

func NodeSections 

func NodeSections(ctx *konglib.Context, opts ...NodeSectionsOption) ([]help.Section, error)

NodeSections builds help sections from the kong parse context. It determines the active node via ctx.Selected() (falls back to the application root) and produces Usage, Arguments, Aliases, Commands, and flag sections.

func NodeSectionsFunc 

func NodeSectionsFunc(opts ...NodeSectionsOption) func(*konglib.Context) ([]help.Section, error)

NodeSectionsFunc returns a sections callback for use with HelpPrinterFunc, with the given options applied.

func Reflect 

func Reflect(cli any) ([]complete.FlagMeta, error)

Reflect extracts flag metadata from a CLI struct by reading Kong-style struct tags. It reads the bare-tag format: name:"foo" help:"..." short:"x" etc.

func Subcommands 

func Subcommands(parser *konglib.Kong) []complete.SubSpec

Subcommands extracts subcommand completion specs from a kong parser's model. Each visible subcommand produces a SubSpec with its flags (excluding kong's built-in --help flag).

Types

type CSVFlag 

type CSVFlag struct {
	Values []string
}

CSVFlag implements kong.MapperValue that splits comma-separated values.

func (*CSVFlag) Decode 

func (c *CSVFlag) Decode(ctx *konglib.DecodeContext) error

Decode implements kong.MapperValue by splitting comma-separated values.

func (*CSVFlag) String 

func (c *CSVFlag) String() string

String returns the comma-separated string representation.

type CompletionFlags 

type CompletionFlags struct {
	Complete            string `name:"@complete"            help:"Dynamic completion type"     hidden:""`
	Shell               string `name:"@shell"               help:"Shell type for completions"  hidden:""`
	InstallCompletion   bool   `name:"install-completion"   help:"Install shell completions"   hidden:""`
	UninstallCompletion bool   `name:"uninstall-completion" help:"Uninstall shell completions" hidden:""`
	PrintCompletion     bool   `name:"print-completion"     help:"Print completion script"     hidden:""`
	// contains filtered or unexported fields
}

CompletionFlags provides embeddable Kong flags for shell completion management. Embed this in your CLI struct to get --@complete, --@shell, --install-completion, --uninstall-completion, and --print-completion flags automatically.

For pre-parse usage, see Preflight.

func Preflight 

func Preflight() (CompletionFlags, []string, bool)

Preflight scans os.Args for completion flags, allowing completion to be handled before the CLI parser. This is useful for subcommand-based CLIs where the parser requires a subcommand but completion flags are standalone.

Returns a populated CompletionFlags, any positional args found after "--", and true if a completion flag was found. When ok is false, the caller should proceed with normal CLI parsing.

Usage: 

if f, args, ok := clib.Preflight(); ok {
    gen := complete.NewGenerator("myapp").FromFlags(flags)
    gen.Subs = clib.Subcommands(parser)
    f.Handle(gen, handler, complete.WithArgs(args))
    return
}

func (*CompletionFlags) Handle 

func (f *CompletionFlags) Handle(
	gen *complete.Generator,
	handler complete.Handler,
	opts ...complete.PreflightOption,
) (bool, error)

Handle checks whether a completion action was requested and executes it. Returns true if a completion action was handled (caller should exit). The handler callback is invoked for --@complete=<type> requests; it receives the completion type and resolved shell name.

type NodeSectionsOption 

type NodeSectionsOption func(*nodeSectionsConfig)

NodeSectionsOption configures NodeSections behavior.

func WithArguments 

func WithArguments(cli any) NodeSectionsOption

WithArguments uses reflected struct tag metadata for the Arguments section instead of kong's parse context. This provides richer descriptions from clib tags (e.g. terse, help).

func WithHideArguments 

func WithHideArguments() NodeSectionsOption

WithHideArguments suppresses the "Arguments" section from the output.

func WithHideCommandAliases added in v0.7.6 

func WithHideCommandAliases() NodeSectionsOption

WithHideCommandAliases omits command aliases from help output.

func WithInlineCommandAliases added in v0.7.6 

func WithInlineCommandAliases() NodeSectionsOption

WithInlineCommandAliases keeps alias commands in the Commands section instead of placing them in a separate Aliases section.

func WithOptionsTitle added in v0.6.12 

func WithOptionsTitle(title string) NodeSectionsOption

WithOptionsTitle sets the section title for local and merged flags instead of the default "Options".

func WithSeparateGlobalOptions added in v0.6.12 

func WithSeparateGlobalOptions() NodeSectionsOption

WithSeparateGlobalOptions splits inherited (ancestor) flags into their own "Global Options" section, below the selected command's local "Options". By default both share one "Options" section (local first, then a blank-line-separated inherited subgroup).

func WithSeparateGlobalOptionsName added in v0.6.12 

func WithSeparateGlobalOptionsName(title string) NodeSectionsOption

WithSeparateGlobalOptionsName is WithSeparateGlobalOptions with a custom section title instead of the default "Global Options".

func WithShowAliases 

func WithShowAliases() NodeSectionsOption

WithShowAliases opts into rendering the "Aliases" section. By default aliases are hidden - they exist to make commands callable by alternate names but are not advertised in help output unless explicitly enabled globally with this option, or per-command via the `show-aliases:""` struct tag.

type Option 

type Option = complete.PreflightOption

Option configures Handle behavior.

func WithArgs 

func WithArgs(args []string) Option

WithArgs passes preceding positional args to the completion handler.

func WithQuiet 

func WithQuiet(quiet bool) Option

WithQuiet suppresses output during install/uninstall.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.