diff --git a/README.md b/README.md index be44b82..f11e50d 100644 --- a/README.md +++ b/README.md @@ -3,35 +3,36 @@ # Kong is a command-line parser for Go [![](https://godoc.org/github.com/alecthomas/kong?status.svg)](http://godoc.org/github.com/alecthomas/kong) [![CircleCI](https://img.shields.io/circleci/project/github/alecthomas/kong.svg)](https://circleci.com/gh/alecthomas/kong) - + 1. [Introduction](#introduction) -1. [Help](#help) -1. [Command handling](#command-handling) +2. [Help](#help) +3. [Command handling](#command-handling) 1. [Switch on the command string](#switch-on-the-command-string) - 1. [Attach a `Run(...) error` method to each command](#attach-a-run-error-method-to-each-command) -1. [BeforeApply\(\), AfterApply\(\) and the Bind\(\) option](#BeforeApply-AfterApply-and-the-bind-option) -1. [Flags](#flags) -1. [Commands and sub-commands](#commands-and-sub-commands) -1. [Branching positional arguments](#branching-positional-arguments) -1. [Terminating positional arguments](#terminating-positional-arguments) -1. [Slices](#slices) -1. [Maps](#maps) -1. [Custom named decoders](#custom-named-decoders) -1. [Custom decoders \(mappers\)](#custom-decoders-mappers) -1. [Supported tags](#supported-tags) -1. [Variable interpolation](#variable-interpolation) -1. [Modifying Kong's behaviour](#modifying-kongs-behaviour) + 2. [Attach a `Run(...) error` method to each command](#attach-a-run-error-method-to-each-command) +4. [Hooks: BeforeResolve(), BeforeApply(), AfterApply() and the Bind() option](#hooks-beforeresolve-beforeapply-afterapply-and-the-bind-option) +5. [Flags](#flags) +6. [Commands and sub-commands](#commands-and-sub-commands) +7. [Branching positional arguments](#branching-positional-arguments) +8. [Terminating positional arguments](#terminating-positional-arguments) +9. [Slices](#slices) +10. [Maps](#maps) +11. [Custom named decoders](#custom-named-decoders) +12. [Custom decoders (mappers)](#custom-decoders-mappers) +13. [Supported tags](#supported-tags) +14. [Variable interpolation](#variable-interpolation) +15. [Modifying Kong's behaviour](#modifying-kongs-behaviour) 1. [`Name(help)` and `Description(help)` - set the application name description](#namehelp-and-descriptionhelp---set-the-application-name-description) - 1. [`Configuration(loader, paths...)` - load defaults from configuration files](#configurationloader-paths---load-defaults-from-configuration-files) - 1. [`Resolver(...)` - support for default values from external sources](#resolver---support-for-default-values-from-external-sources) - 1. [`*Mapper(...)` - customising how the command-line is mapped to Go values](#mapper---customising-how-the-command-line-is-mapped-to-go-values) - 1. [`ConfigureHelp(HelpOptions)` and `Help(HelpFunc)` - customising help](#configurehelphelpoptions-and-helphelpfunc---customising-help) - 1. [`Bind(...)` - bind values for callback hooks and Run\(\) methods](#bind---bind-values-for-callback-hooks-and-run-methods) - 1. [Other options](#other-options) + 2. [`Configuration(loader, paths...)` - load defaults from configuration files](#configurationloader-paths---load-defaults-from-configuration-files) + 3. [`Resolver(...)` - support for default values from external sources](#resolver---support-for-default-values-from-external-sources) + 4. [`*Mapper(...)` - customising how the command-line is mapped to Go values](#mapper---customising-how-the-command-line-is-mapped-to-go-values) + 5. [`ConfigureHelp(HelpOptions)` and `Help(HelpFunc)` - customising help](#configurehelphelpoptions-and-helphelpfunc---customising-help) + 6. [`Bind(...)` - bind values for callback hooks and Run() methods](#bind---bind-values-for-callback-hooks-and-run-methods) + 7. [Other options](#other-options) - + + ## Introduction Kong aims to support arbitrarily complex command-line structures with as little developer effort as possible. @@ -74,6 +75,7 @@ func main() { } ``` + ## Help Help is automatically generated. With no other arguments provided, help will display a full summary of all available commands. @@ -114,10 +116,12 @@ eg. -f, --force Force removal. -r, --recursive Recursively remove files. + ## Command handling There are two ways to handle commands in Kong. + ### Switch on the command string When you call `kong.Parse()` it will return a unique string representation of the command. Each command branch in the hierarchy will be a bare word and each branching argument or required positional argument will be the name surrounded by angle brackets. Here's an example: @@ -157,6 +161,7 @@ func main() { This has the advantage that it is convenient, but the downside that if you modify your CLI structure, the strings may change. This can be fragile. + ### Attach a `Run(...) error` method to each command A more robust approach is to break each command out into their own structs: @@ -212,7 +217,8 @@ func main() { ``` -## Hooks: BeforeResolve(), BeforeSet(), AfterSet() and the Bind() option + +## Hooks: BeforeResolve(), BeforeApply(), AfterApply() and the Bind() option If a node in the grammar has a `BeforeResolve(...)`, `BeforeApply(...) error` and/or `AfterApply(...) error` method, those methods will be called before validation/assignment and after validation/assignment, respectively. @@ -245,6 +251,7 @@ func main() { } ``` + ## Flags Any [mapped](#mapper---customising-how-the-command-line-is-mapped-to-go-values) field in the command structure *not* tagged with `cmd` or `arg` will be a flag. Flags are optional by default. @@ -257,6 +264,7 @@ type CLI struct { } ``` + ## Commands and sub-commands Sub-commands are specified by tagging a struct field with `cmd`. Kong supports arbitrarily nested commands. @@ -274,6 +282,7 @@ type CLI struct { } ``` + ## Branching positional arguments In addition to sub-commands, structs can also be configured as branching positional arguments. @@ -301,12 +310,14 @@ var CLI struct { This looks a little verbose in this contrived example, but typically this will not be the case. + ## Terminating positional arguments If a [mapped type](#mapper---customising-how-the-command-line-is-mapped-to-go-values) is tagged with `arg` it will be treated as the final positional values to be parsed on the command line. If a positional argument is a slice, all remaining arguments will be appended to that slice. + ## Slices Slice values are treated specially. First the input is split on the `sep:""` tag (defaults to `,`), then each element is parsed by the slice element type and appended to the slice. If the same value is encountered multiple times, elements continue to be appended. @@ -325,6 +336,7 @@ var CLI struct { } ``` + ## Maps Maps are similar to slices except that only one key/value pair can be assigned per value, and the `sep` tag denotes the assignment character and defaults to `=`. @@ -347,6 +359,7 @@ var CLI struct { For flags, multiple key+value pairs should be separated by `;` eg. `--set="key1=value1;key2=value2"`. + ## Custom named decoders Kong includes a number of builtin custom type mappers. These can be used by @@ -365,11 +378,13 @@ specifies the element type. For maps, the tag has the format `tag:"[]:[]"` where either may be omitted. + ## Custom decoders (mappers) If a field implements the [MapperValue](https://godoc.org/github.com/alecthomas/kong#MapperValue) interface it will be used to decode arguments into the field. + ## Supported tags Tags can be in two forms: @@ -399,6 +414,7 @@ Both can coexist with standard Tag parsing. | `group:"X"` | Logical group for a flag or command. | | `prefix:"X"` | Prefix for all sub-flags. | + ## Variable interpolation Kong supports limited variable interpolation into help strings, enum lists and @@ -433,12 +449,14 @@ func main() { } ``` + ## Modifying Kong's behaviour Each Kong parser can be configured via functional options passed to `New(cli interface{}, options...Option)`. The full set of options can be found [here](https://godoc.org/github.com/alecthomas/kong#Option). + ### `Name(help)` and `Description(help)` - set the application name description Set the application name and/or description. @@ -447,6 +465,7 @@ The name of the application will default to the binary name, but can be overridd As with all help in Kong, text will be wrapped to the terminal. + ### `Configuration(loader, paths...)` - load defaults from configuration files This option provides Kong with support for loading defaults from a set of configuration files. Each file is opened, if possible, and the loader called to create a resolver for that file. @@ -457,12 +476,14 @@ eg. kong.Parse(&cli, kong.Configuration(kong.JSON, "/etc/myapp.json", "~/.myapp.json")) ``` + ### `Resolver(...)` - support for default values from external sources Resolvers are Kong's extension point for providing default values from external sources. As an example, support for environment variables via the `env` tag is provided by a resolver. There's also a builtin resolver for JSON configuration files. Example resolvers can be found in [resolver.go](https://github.com/alecthomas/kong/blob/master/resolver.go). + ### `*Mapper(...)` - customising how the command-line is mapped to Go values Command-line arguments are mapped to Go values via the Mapper interface: @@ -485,6 +506,7 @@ All builtin Go types (as well as a bunch of useful stdlib types like `time.Time` 3. `TypeMapper(reflect.Type, Mapper)`. 4. `ValueMapper(interface{}, Mapper)`, passing in a pointer to a field of the grammar. + ### `ConfigureHelp(HelpOptions)` and `Help(HelpFunc)` - customising help The default help output is usually sufficient, but if not there are two solutions. @@ -492,10 +514,12 @@ The default help output is usually sufficient, but if not there are two solution 1. Use `ConfigureHelp(HelpOptions)` to configure how help is formatted (see [HelpOptions](https://godoc.org/github.com/alecthomas/kong#HelpOptions) for details). 2. Custom help can be wired into Kong via the `Help(HelpFunc)` option. The `HelpFunc` is passed a `Context`, which contains the parsed context for the current command-line. See the implementation of `PrintHelp` for an example. + ### `Bind(...)` - bind values for callback hooks and Run() methods See the [section on hooks](#BeforeApply-AfterApply-and-the-bind-option) for details. + ### Other options The full set of options can be found [here](https://godoc.org/github.com/alecthomas/kong#Option).