mcfg: update docs

This commit is contained in:
Brian Picciano 2019-05-18 12:50:04 -06:00
parent 60ea7d98eb
commit e9b7f24dba
3 changed files with 23 additions and 11 deletions

View File

@ -26,11 +26,10 @@ type cliTail struct {
}
// WithCLITail returns a Context which modifies the behavior of SourceCLI's
// Parse, if SourceCLI is used with that Context at all. Normally when SourceCLI
// encounters an unexpected Arg it will immediately return an error. This
// function modifies the Context to indicate to Parse that the unexpected Arg,
// and all subsequent Args (i.e. the tail) should be set to the returned
// []string value.
// Parse. Normally when SourceCLI encounters an unexpected Arg it will
// immediately return an error. This function modifies the Context to indicate
// to Parse that the unexpected Arg, and all subsequent Args (i.e. the tail),
// should be set to the returned []string value.
//
// The descr (optional) will be appended to the "Usage" line which is printed
// with the help document when "-h" is passed in.

View File

@ -304,9 +304,12 @@ func TestWithCLISubCommand(t *T) {
}
func ExampleWithCLISubCommand() {
// Create a new Context with a parameter "foo", which can be used across all
// sub-commands.
ctx := context.Background()
ctx, foo := WithInt(ctx, "foo", 0, "Description of foo.")
// Create a sub-command "a", which has a parameter "bar" specific to it.
var bar *int
ctx, aFlag := WithCLISubCommand(ctx, "a", "Description of a.",
func(ctx context.Context) context.Context {
@ -314,6 +317,7 @@ func ExampleWithCLISubCommand() {
return ctx
})
// Create a sub-command "b", which has a parameter "baz" specific to it.
var baz *int
ctx, bFlag := WithCLISubCommand(ctx, "b", "Description of b.",
func(ctx context.Context) context.Context {
@ -321,13 +325,15 @@ func ExampleWithCLISubCommand() {
return ctx
})
// Use Populate with manually generated CLI arguments, calling the "a"
// sub-command.
args := []string{"a", "--foo=1", "--bar=2"}
if _, err := Populate(ctx, &SourceCLI{Args: args}); err != nil {
panic(err)
}
fmt.Printf("foo:%d bar:%d aFlag:%v bFlag:%v\n", *foo, *bar, *aFlag, *bFlag)
// reset output for another Populate
// reset output for another Populate, this time calling the "b" sub-command.
*aFlag = false
args = []string{"b", "--foo=1", "--baz=3"}
if _, err := Populate(ctx, &SourceCLI{Args: args}); err != nil {

View File

@ -1,5 +1,12 @@
// Package mcfg provides a simple foundation for complex service/binary
// configuration, initialization, and destruction
// Package mcfg implements the creation of different types of configuration
// parameters and various methods of filling those parameters from external
// configuration sources (e.g. the command line and environment variables).
//
// Parameters are registered onto a context, and that same context is used later
// to collect and fulfill those parameters. When used with the mctx package's
// child/parent context functionality, the path of a context is incorporated
// into the parameter's full name in order to namespace parameters which exist
// in different contexts.
package mcfg
import (
@ -45,9 +52,9 @@ func sortParams(params []Param) {
})
}
// CollectParams returns all Params gathered by recursively retrieving them from
// this Context and its children. Returned Params are sorted according to their
// Path and Name.
// CollectParams gathers all Params by recursively retrieving them from this
// Context and its children. Returned Params are sorted according to their Path
// and Name.
func CollectParams(ctx context.Context) []Param {
var params []Param