mcfg

func AddParam ¶

func AddParam(cmp *mcmp.Component, param Param, opts ...ParamOption)

AddParam adds the given Param to the given Component. It will panic if a Param with the same Name already exists in the Component.

func Bool ¶

func Bool(cmp *mcmp.Component, name string, opts ...ParamOption) *bool

Bool returns a *bool which will be populated once Populate is run on the Component, and which defaults to false if unconfigured.

The default behavior of all Sources is that a boolean parameter will be set to true unless the value is "", 0, or false. In the case of the CLI Source the value will also be true when the parameter is used with no value at all, as would be expected.

func CLISubCommand ¶

func CLISubCommand(cmp *mcmp.Component, name, descr string, callback func(*mcmp.Component)) *bool

CLISubCommand establishes a sub-command which can be activated on the command-line. When a sub-command is given on the command-line, the bool returned for that sub-command will be set to true.

Additionally, the Component which was passed into Parse (i.e. the one passed into Populate) will be passed into the given callback, and can be modified for subsequent parsing. This allows for setting sub-command specific Params, sub-command specific runtime behavior (via mrun.WithStartHook), support for sub-sub-commands, and more. The callback may be nil.

If any sub-commands have been defined on a Component which is passed into Parse, it is assumed that a sub-command is required on the command-line.

When parsing the command-line options, it is assumed that sub-commands will be found before any other options.

This function panics if not called on a root Component (i.e. a Component which has no parents).

var (
	cmp           *mcmp.Component
	foo, bar, baz *int
	aFlag, bFlag  *bool
)

// resetExample re-initializes all variables used in this example. We'll
// call it multiple times to show different behaviors depending on what
// arguments are passed in.
resetExample := func() {
	// Create a new Component with a parameter "foo", which can be used across
	// all sub-commands.
	cmp = new(mcmp.Component)
	foo = Int(cmp, "foo")

	// Create a sub-command "a", which has a parameter "bar" specific to it.
	aFlag = CLISubCommand(cmp, "a", "Description of a.",
		func(cmp *mcmp.Component) {
			bar = Int(cmp, "bar")
		})

	// Create a sub-command "b", which has a parameter "baz" specific to it.
	bFlag = CLISubCommand(cmp, "b", "Description of b.",
		func(cmp *mcmp.Component) {
			baz = Int(cmp, "baz")
		})
}

// Use Populate with manually generated CLI arguments, calling the "a"
// sub-command.
resetExample()
args := []string{"a", "--foo=1", "--bar=2"}
if err := Populate(cmp, &SourceCLI{Args: args}); err != nil {
	panic(err)
}
fmt.Printf("foo:%d bar:%d aFlag:%v bFlag:%v\n", *foo, *bar, *aFlag, *bFlag)

// reset for another Populate, this time calling the "b" sub-command.
resetExample()
args = []string{"b", "--foo=1", "--baz=3"}
if err := Populate(cmp, &SourceCLI{Args: args}); err != nil {
	panic(err)
}
fmt.Printf("foo:%d baz:%d aFlag:%v bFlag:%v\n", *foo, *baz, *aFlag, *bFlag)

Output:

foo:1 bar:2 aFlag:true bFlag:false
foo:1 baz:3 aFlag:false bFlag:true

func CLITail ¶

func CLITail(cmp *mcmp.Component, descr string) *[]string

CLITail modifies the behavior of SourceCLI's Parse. Normally when SourceCLI encounters an unexpected Arg it will immediately return an error. This function modifies the Component 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.

This function panics if not called on a root Component (i.e. a Component which has no parents).

cmp := new(mcmp.Component)
foo := Int(cmp, "foo", ParamDefault(1), ParamUsage("Description of foo."))
tail := CLITail(cmp, "[arg...]")
bar := String(cmp, "bar", ParamDefault("defaultVal"), ParamUsage("Description of bar."))

err := Populate(cmp, &SourceCLI{
	Args: []string{"--foo=100", "arg1", "arg2", "arg3"},
})

fmt.Printf("err:%v foo:%v bar:%v tail:%#v\n", err, *foo, *bar, *tail)

Output:

err:<nil> foo:100 bar:defaultVal tail:[]string{"arg1", "arg2", "arg3"}

func Duration ¶

func Duration(cmp *mcmp.Component, name string, opts ...ParamOption) *mtime.Duration

Duration returns an *mtime.Duration which will be populated once Populate is run on the Component.

func Float64 ¶

func Float64(cmp *mcmp.Component, name string, opts ...ParamOption) *float64

Float64 returns a *float64 which will be populated once Populate is run on the Component

func Int ¶

func Int(cmp *mcmp.Component, name string, opts ...ParamOption) *int

Int returns an *int which will be populated once Populate is run on the Component.

func Int64 ¶

func Int64(cmp *mcmp.Component, name string, opts ...ParamOption) *int64

Int64 returns an *int64 which will be populated once Populate is run on the Component.

func JSON ¶

func JSON(cmp *mcmp.Component, name string, into interface{}, opts ...ParamOption)

JSON reads the parameter value as a JSON value and unmarshals it into the given interface{} (which should be a pointer) once Populate is run on the Component.

The receiver (into) is also used to determine the default value. ParamDefault should not be used as one of the opts.

func Populate ¶

func Populate(cmp *mcmp.Component, src Source) error

Populate uses the Source to populate the values of all Params which were added to the given Component, and all of its children. Populate may be called multiple times with the same Component, each time will only affect the values of the Params which were provided by the respective Source.

Source may be nil to indicate that no configuration is provided. Only default values will be used, and if any parameters are required this will error.

Populating Params can affect the Component itself, for example in the case of sub-commands.

func String ¶

func String(cmp *mcmp.Component, name string, opts ...ParamOption) *string

String returns a *string which will be populated once Populate is run on the Component.

func TS ¶

func TS(cmp *mcmp.Component, name string, opts ...ParamOption) *mtime.TS

TS returns an *mtime.TS which will be populated once Populate is run on the Component.