README
¶
Completion and manual generator for kong
Create manual pages and completions for Go kong CLI programs
kong is a very nice command-line parser for Go. But it misses the
ability to generate (good) shell completions. There are some integrations but they require source level
changes. With king you can just generate the completion files separately from a kong.Node.
This package copies from gum and made into a standalone library + some extra features, like telling (via struct tags) how certain things must be completed. The Bash completions are completely reworked and for both Zsh and Bash have positional argument completion. For the Fish shell the origin gum completion was used and not made better.
King can also generate manual pages from a Kong node, see godoc for more information.
Any struct field can have an extra tag:
completion:""which contains a shell command that should be used for completion or a string between<and>which should be a Bash action as specified in thecompletefunction in bash(1), like<file>or<directory>. These are translated to things Zsh understands.
I use Zsh, so this is where my initial focus is. The Bash completion works, but can probably be done a lot better.
And for manual creation:
description:""text used in the description section of the manual page.deprecated:""this flag is deprecated.
Extra flags can be injected:
fl := &kong.Flag{
Value: &kong.Value{
Name: "man",
Help: "Show context-sensitive manual page.",
Tag: &kong.Tag{},
},
}
And then assign it the to Flags in Zsh, Bash or Man.
Note that for completion you give it a *kong.Node and the completion rolls out, for manual creation you give
it the root *kong.Nodeand a path through thecmd field names.
This is needed because we need a fully parsed Node tree as made by Kong to have access to all tags.
Run the tests to see example files being created.
Supported "actions"
The following actions are supported:
- "file", "directory"
- "group"
- "user"
- "export"
And are converted to the correct construct in the completion that is generated for the specific shell.
Status
- Bash: everything supported, actions, positional commands and flags.
- Zsh: everything supported, action, positional commands and flags.
- Fish: everything 'gum' supports, no actions, and probably no positional commands. Generally unfinished.
Documentation
¶
Overview ¶
Package king is used to generate completions for https://github.com/alecthomas/kong. Unlike most other completers this package also completes positional arguments for both Bash and Zsh. It can also be used to generate manual pages for a kong command line.
Index ¶
Constants ¶
const ManTemplate = `{{name -}}
{{synopsis -}}
{{description -}}
{{commands -}}
{{arguments -}}
{{options -}}
{{globals -}}
`
ManTemplate is the default manual page template used when generating a manual page. Where each function used is:
- name: generate a <cmdname> - <single line synopsis>. The node's help is used for this. The removes the final dot from the help, and lowercases the first letter if the word isn't all caps. The command's _altname_ is always used here.
- synopsis: shows the argument and options. If the node has aliases they are shown here as well.
- description: the description of the command's function. The node's (non-Kong) "description" tag is used for this.
- commands: a rundown of each of the subcommands this command has.
- arguments: a rundown of each of the arguments this command has.
- options: a list documenting each of the options.
- globals: any global flags, from m.Flags.
Note that the TOML manual header is always used.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bash ¶
type Bash struct {
Flags []*kong.Flag // Any global flags that the should Application Node have.
// contains filtered or unexported fields
}
Bash is a bash completion generator.
type Completer ¶
type Completer interface {
// Completion generates the completion for a shell starting with k. The altname - if not empty - takes
// precedence over k.Name.
Completion(k *kong.Node, altname string)
// Out returns the generated shell completion script.
Out() []byte
// Write writes the generated shell completion script to the appropiate file, for Zsh this is _exename and
// for Bash this is exename.bash, for manual this is m.name.m.Section. If the optional writer is given it
// contents is written to that.
Write(w ...io.Writer) error
}
The Completer interface must be implemented by every shell completer. It mainly serves for documentation.
type Fish ¶ added in v0.9.14
type Fish struct {
Flags []*kong.Flag // Any global flags that the should Application Node have.
// contains filtered or unexported fields
}
Fish is a fish shell completion generator.
type Man ¶ added in v0.9.2
type Man struct {
Section int // See mmark's documentation
Area string
WorkGroup string
Template string // If empty [ManTemplate] is used.
Flags []*kong.Flag // Any global flags that the should Application Node have. There are documented after the normal flags.
// contains filtered or unexported fields
}
Man is a manual page generator.
func (*Man) Manual ¶ added in v0.9.2
Manual generates a manual page for child node that can be found via field, where field may contain a space seperated list of node names: "mfa list", looks for the mfa node and its child named list. On the node k the following tags are used:
- cmd:"....": command name, overrides k.<named>.Name
- aliases:"...": any extra names that this command has.
- help:"...": line used in the NAME section: "cmd" - "help" text, as in "ls - list directory contents" if this text ends in a dot it is removed.
- description:".....": The entire description paragraph.
Note that any of these may contain markdown markup. The node k doesn't need any special
If path is empty, the manual page for k is returned, altname is used as an alternative name for this command, which is not found in any of the tags. This is also the default name under which the manual page is saved.
When path is is not empty it should have a list of command names which are followed to find the node for which we generate the manual page. This path is also used to construct the command line(s) in the synopsis.
rootname is the name of the main executable, this can't be put as a tag on the main node, as that node itself can't carry struct tags.
To generate a manual page for the main node, `k` we need a description and help, this can be done via:
type WrapT struct {
Wrap MyCli `cmd:"" help:"my help" description:"my desc"`
}
and then call Manual with: m.Manual(parser.Model.Node, "_wrap", "MyExec", "") The prevent "wrap" showing up as a valid command, is can be prefixed it with _. This only checked on the first element in path.
Source Files