psetter

ExampleBool_inverted demonstrates the use of a Bool setter with the Invert flag set to true. The standard behaviour will set the value to true when no explicit value is given but with this flag set the value is set to false. Any value given is inverted. This is useful for turning off some default behaviour rather than turning it on as the standard action of this setter would do.

ps := newPSetForTesting() // use paramset.NewOrPanic()

p1 := true

ps.Add("dont-do-this", psetter.Bool{Value: &p1, Invert: true}, "help text")

fmt.Printf("Before parsing    p1: %v\n", p1)
ps.Parse([]string{"-dont-do-this"})
fmt.Printf("After  parsing    p1: %v\n", p1)

Output:

Before parsing    p1: true
After  parsing    p1: false

ExampleBool_standard demonstrates the use of a Bool setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var p1 bool

ps.Add("do-this", psetter.Bool{Value: &p1}, "help text")

fmt.Printf("Before parsing    p1: %v\n", p1)
ps.Parse([]string{"-do-this"})
fmt.Printf("After  parsing    p1: %v\n", p1)

Output:

Before parsing    p1: false
After  parsing    p1: true

ExampleBool_withBadValue demonstrates the use of a Bool setter showing the behaviour when an argument is supplied that cannot be translated into a bool value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

p1 := true

ps.Add("do-this", psetter.Bool{Value: &p1}, "help text")

fmt.Printf("Before parsing    p1: %v\n", p1)
// Parse the arguments. Note that the value after the '=' cannot be
// translated into a bool value.
errMap := ps.Parse([]string{"-do-this=blah"})
// We expect to see an error reported.
logErrs(errMap)
// There was an error with the parameter so the value will be unchanged
fmt.Printf("After  parsing    p1: %v\n", p1)

Output:

Before parsing    p1: true
Errors for: do-this
	: cannot interpret 'blah' as either true or false
At: [command line]: Supplied Parameter:1: "-do-this=blah"
After  parsing    p1: true

ExampleBool_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the bool Value has not been initialised
ps.Add("do-this", psetter.Bool{}, "help text")

Output:

panic
do-this: psetter.Bool Check failed: the Value to be set is nil

ExampleBool_withValue demonstrates the use of a Bool setter showing how the value of the flag can be set to an explicit value by passing the value required after the parameter (following an "=").

ps := newPSetForTesting() // use paramset.NewOrPanic()

p1 := true

ps.Add("do-this", psetter.Bool{Value: &p1}, "help text")

fmt.Printf("Before parsing    p1: %v\n", p1)
ps.Parse([]string{"-do-this=false"})
fmt.Printf("After  parsing    p1: %v\n", p1)

Output:

Before parsing    p1: true
After  parsing    p1: false

ExampleDuration_basic demonstrates the use of a Duration setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var v time.Duration

ps.Add("how-long", psetter.Duration{Value: &v}, "help text")

fmt.Printf("Before parsing    v: %v\n", v)
ps.Parse([]string{"-how-long", "1h"})
fmt.Printf("After  parsing    v: %v\n", v)

Output:

Before parsing    v: 0s
After  parsing    v: 1h0m0s

ExampleDuration_withFailingChecks demonstrates how to specify additional checks for a Duration value and shows the error that you can expect to see if a value is supplied which fails any of the checks. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var v time.Duration

ps.Add("how-long",
	psetter.Duration{
		Value: &v,
		Checks: []check.Duration{
			check.ValGT[time.Duration](2 * time.Hour),
		},
	},
	"help text")

fmt.Printf("Before parsing    v: %v\n", v)
// Parse the arguments. Note that the duration given (1 hour) is less
// than the minimum value given by the check function.
errMap := ps.Parse([]string{"-how-long", "1h"})
// The check will fail so we expect to see errors reported
logErrs(errMap)
// There was an error with the parameter so the value will be unchanged
fmt.Printf("After  parsing    v: %v\n", v)

Output:

Before parsing    v: 0s
Errors for: how-long
	: the value (1h0m0s) must be greater than 2h0m0s
At: [command line]: Supplied Parameter:2: "-how-long" "1h"
After  parsing    v: 0s

ExampleDuration_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the Duration Value has not been
// initialised
ps.Add("how-long", psetter.Duration{}, "help text")

Output:

panic
how-long: psetter.Duration Check failed: the Value to be set is nil

ExampleDuration_withPassingChecks demonstrates how to specify additional checks for a Duration value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var v time.Duration

ps.Add("how-long",
	psetter.Duration{
		Value: &v,
		Checks: []check.Duration{
			check.ValBetween[time.Duration](time.Duration(0), 2*time.Hour),
		},
	},
	"help text")

fmt.Printf("Before parsing    v: %v\n", v)
ps.Parse([]string{"-how-long", "1h"})
fmt.Printf("After  parsing    v: %v\n", v)

Output:

Before parsing    v: 0s
After  parsing    v: 1h0m0s

ExampleEnum_standard demonstrates the use of an Enum setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

s := XOption

ps.Add("my-string",
	psetter.Enum{
		Value: &s,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\ts = %s\n", s)

ps.Parse([]string{"-my-string", "y"})

fmt.Println("After  parsing")
fmt.Printf("\ts = %s\n", s)

Output:

Before parsing
	s = x
After  parsing
	s = y

ExampleEnum_withBadInitialValue demonstrates the behaviour of the package when the initial value is invalid (not in the list of allowed values). Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

s := "z"

// we expect this to panic because the Value has an invalid initial value
ps.Add("my-string",
	psetter.Enum{
		Value: &s,
		AllowedVals: psetter.AllowedVals{ // Note there's no 'z' value
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

Output:

panic
my-string: psetter.Enum Check failed: the initial value (z) is not valid

ExampleEnum_withBadVal demonstrates the behaviour when a value not given in the AllowedValues is passed as a parameter. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

s := XOption

ps.Add("my-string",
	psetter.Enum{
		Value: &s,
		AllowedVals: psetter.AllowedVals{ // Note there's no 'z' value
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\ts = %s\n", s)

// Parse the arguments. We supply a value but note that it is not in the
// list of allowed values.
errMap := ps.Parse([]string{"-my-string", "z"})

// We expect to see an error reported.
logErrs(errMap)

// The value is unchanged due to the error.
fmt.Println("After  parsing")
fmt.Printf("\ts = %s\n", s)

Output:

Before parsing
	s = x
Errors for: my-string
	: value not allowed: "z"
At: [command line]: Supplied Parameter:2: "-my-string" "z"
After  parsing
	s = x

ExampleEnum_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

// we expect this to panic because the Value has not been initialised
ps.Add("my-string",
	psetter.Enum{
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

Output:

panic
my-string: psetter.Enum Check failed: the Value to be set is nil

ExampleEnumList_standard demonstrates the use of an EnumList setter

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

var ss []string

ps.Add("my-list",
	psetter.EnumList{
		Value: &ss,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

ps.Parse([]string{"-my-list", "x,y"})

fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
After  parsing
	ss[0] = "x"
	ss[1] = "y"

ExampleEnumList_withBadVals demonstrates the behaviour when a value not given in the AllowedValues is passed. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

var ss []string

ps.Add("my-list",
	psetter.EnumList{
		Value: &ss,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

// Parse the arguments. We supply a list of strings but note that one of
// them is not in the list of allowed values.
errMap := ps.Parse([]string{"-my-list", "x,z"})

// We expect to see an error reported.
logErrs(errMap)

// The slice of strings is unchanged due to the error.
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
Errors for: my-list
	: value is not allowed: "z"
At: [command line]: Supplied Parameter:2: "-my-list" "x,z"
After  parsing

ExampleEnumList_withFailingChecks demonstrates the behaviour of the package when an invalid value is given. In this case the resulting list is not of the required length. It demonstrates the checks that can be supplied to ensure that the resulting list is as expected. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

var ss []string

ps.Add("my-list",
	psetter.EnumList{
		Value: &ss,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
		Checks: []check.StringSlice{
			check.SliceLength[[]string](check.ValEQ(2)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

// Parse the arguments. We supply a list of strings, each of which is
// allowed. The resulting slice is of the wrong length.
errMap := ps.Parse([]string{"-my-list", "x"})

// We expect to see an error reported.
logErrs(errMap)

// The slice of strings is unchanged due to the error.
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
Errors for: my-list
	: the length of the list (1) is incorrect: the value (1) must equal 2
At: [command line]: Supplied Parameter:2: "-my-list" "x"
After  parsing

ExampleEnumList_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

// we expect this to panic because the list Value has not been initialised
ps.Add("my-list",
	psetter.EnumList{
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

Output:

panic
my-list: psetter.EnumList Check failed: the Value to be set is nil

ExampleEnumList_withPassingChecks demonstrates how you can specify additional checks to be applied to the passed arguments before the value is set.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

var ss []string

ps.Add("my-list",
	psetter.EnumList{
		Value: &ss,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
		Checks: []check.StringSlice{
			check.SliceLength[[]string](check.ValEQ(2)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

ps.Parse([]string{"-my-list", "x,y"})

fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
After  parsing
	ss[0] = "x"
	ss[1] = "y"

ExampleEnumMap_fixingInitialValue demonstrates how an initial value may be changed through the command line. That is, it is possible to change the value of a map entry to false as well as to true.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

m := map[string]bool{"x": true}
keys := []string{XOption, YOption}

ps.Add("my-map",
	psetter.EnumMap{
		Value: &m,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

ps.Parse([]string{"-my-map", "x=false,y"})

fmt.Println("After  parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

Output:

Before parsing
	m[x] = true
After  parsing
	m[x] = false
	m[y] = true

ExampleEnumMap_hiddenMapEntries demonstrates the behaviour of the package when the AllowHiddenMapEntries flag is set. In this case the Value to be set has an entry with a key not in the allowed values but no error is reported. Note that it is not possible to set such a map value as the key will be rejected as invalid.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

m := map[string]bool{"z": true}
keys := []string{XOption, YOption, "z"}

ps.Add("my-map",
	psetter.EnumMap{
		Value: &m,
		AllowedVals: psetter.AllowedVals{ // Note there's no 'z' value
			XOption: "a description of this option",
			YOption: "what this option means",
		},

		// Setting AllowHiddenMapEntries to true prevents the 'z' entry
		// causing an error
		AllowHiddenMapEntries: true,
	}, "help text")

fmt.Println("Before parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

ps.Parse([]string{"-my-map", "y"})

fmt.Println("After  parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

Output:

Before parsing
	m[z] = true
After  parsing
	m[y] = true
	m[z] = true

ExampleEnumMap_standard demonstrates the use of an EnumMap setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

var m map[string]bool
keys := []string{XOption, YOption}

ps.Add("my-map",
	psetter.EnumMap{
		Value: &m,
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

fmt.Println("Before parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

ps.Parse([]string{"-my-map", "x"})

fmt.Println("After  parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

Output:

Before parsing
After  parsing
	m[x] = true

ExampleEnumMap_withBadKey demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has an entry with a key not in the allowed values. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

m := map[string]bool{"z": true}

// we expect this to panic because the map has an entry which is not in
// the allowed values
ps.Add("my-map",
	psetter.EnumMap{
		Value: &m,
		AllowedVals: psetter.AllowedVals{ // Note there's no 'z' value
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

Output:

panic
my-map: psetter.EnumMap Check failed: the map entry with key "z" is invalid - it is not in the allowed values map

ExampleEnumMap_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

const (
	XOption = "x"
	YOption = "y"
)

// we expect this to panic because the map Value has not been initialised
ps.Add("my-map",
	psetter.EnumMap{
		AllowedVals: psetter.AllowedVals{
			XOption: "a description of this option",
			YOption: "what this option means",
		},
	}, "help text")

Output:

panic
my-map: psetter.EnumMap Check failed: the Value to be set is nil

ExampleFloat64_standard demonstrates the use of a Float64 setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var f float64

ps.Add("my-float",
	psetter.Float64{
		Value: &f,
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\tf = %5.3f\n", f)
ps.Parse([]string{"-my-float", "1.23"})
fmt.Println("After  parsing")
fmt.Printf("\tf = %5.3f\n", f)

Output:

Before parsing
	f = 0.000
After  parsing
	f = 1.230

ExampleFloat64_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var f float64

ps.Add("my-float",
	psetter.Float64{
		Value: &f,
		Checks: []check.Float64{
			check.ValGT[float64](5.0),
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\tf = %5.3f\n", f)
// Parse the arguments. We supply a float value but note that it does not
// satisfy the check for this parameter.
errMap := ps.Parse([]string{"-my-float", "1.23"})
// We expect to see an error reported.
logErrs(errMap)
// The float value is unchanged due to the error.
fmt.Println("After  parsing")
fmt.Printf("\tf = %5.3f\n", f)

Output:

Before parsing
	f = 0.000
Errors for: my-float
	: the value (1.23) must be greater than 5
At: [command line]: Supplied Parameter:2: "-my-float" "1.23"
After  parsing
	f = 0.000

ExampleFloat64_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the map Value has not been initialised
ps.Add("my-float", psetter.Float64{}, "help text")

Output:

panic
my-float: psetter.Float64 Check failed: the Value to be set is nil

ExampleFloat64_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var f float64

ps.Add("my-float",
	psetter.Float64{
		Value: &f,
		Checks: []check.Float64{
			check.ValGT[float64](5.0),
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\tf = %5.3f\n", f)
ps.Parse([]string{"-my-float", "6.23"})
fmt.Println("After  parsing")
fmt.Printf("\tf = %5.3f\n", f)

Output:

Before parsing
	f = 0.000
After  parsing
	f = 6.230

ExampleInt64_standard demonstrates the use of a Int64 setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var i int64

ps.Add("my-int",
	psetter.Int64{
		Value: &i,
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\ti = %d\n", i)
ps.Parse([]string{"-my-int", "1"})
fmt.Println("After  parsing")
fmt.Printf("\ti = %d\n", i)

Output:

Before parsing
	i = 0
After  parsing
	i = 1

ExampleInt64_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var i int64

ps.Add("my-int",
	psetter.Int64{
		Value: &i,
		Checks: []check.Int64{
			check.ValGT[int64](5),
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\ti = %d\n", i)
// Parse the arguments. We supply a int value but note that it does not
// satisfy the check for this parameter.
errMap := ps.Parse([]string{"-my-int", "1"})
// We expect to see an error reported.
logErrs(errMap)
// The int value is unchanged due to the error.
fmt.Println("After  parsing")
fmt.Printf("\ti = %d\n", i)

Output:

Before parsing
	i = 0
Errors for: my-int
	: the value (1) must be greater than 5
At: [command line]: Supplied Parameter:2: "-my-int" "1"
After  parsing
	i = 0

ExampleInt64_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the map Value has not been initialised
ps.Add("my-int", psetter.Int64{}, "help text")

Output:

panic
my-int: psetter.Int64 Check failed: the Value to be set is nil

ExampleInt64_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var i int64

ps.Add("my-int",
	psetter.Int64{
		Value: &i,
		Checks: []check.Int64{
			check.ValGT[int64](5),
		},
	}, "help text")

fmt.Println("Before parsing")
fmt.Printf("\ti = %d\n", i)
ps.Parse([]string{"-my-int", "6"})
fmt.Println("After  parsing")
fmt.Printf("\ti = %d\n", i)

Output:

Before parsing
	i = 0
After  parsing
	i = 6

ExampleInt64List_standard demonstrates the use of a Int64List setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

il := []int64{42}

ps.Add("my-ints",
	psetter.Int64List{
		Value: &il,
	}, "help text")

fmt.Println("Before parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}
ps.Parse([]string{"-my-ints", "1,23"})
fmt.Println("After  parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}

Output:

Before parsing
	il[0] = 42
After  parsing
	il[0] = 1
	il[1] = 23

ExampleInt64List_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

il := []int64{42}

ps.Add("my-ints",
	psetter.Int64List{
		Value: &il,
		Checks: []check.Int64Slice{
			check.SliceAll[[]int64, int64](check.ValGT[int64](5)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}
// Parse the arguments. We supply a float value but note that it does not
// satisfy the check for this parameter.
errMap := ps.Parse([]string{"-my-ints", "1,23"})
// We expect to see an error reported.
logErrs(errMap)
// The float value is unchanged due to the error.
fmt.Println("After  parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}

Output:

Before parsing
	il[0] = 42
Errors for: my-ints
	: list entry: 0 (1) does not pass the test: the value (1) must be greater than 5
At: [command line]: Supplied Parameter:2: "-my-ints" "1,23"
After  parsing
	il[0] = 42

ExampleInt64List_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the map Value has not been initialised
ps.Add("my-ints", psetter.Int64List{}, "help text")

Output:

panic
my-ints: psetter.Int64List Check failed: the Value to be set is nil

ExampleInt64List_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

il := []int64{42}

ps.Add("my-ints",
	psetter.Int64List{
		Value: &il,
		Checks: []check.Int64Slice{
			check.SliceAll[[]int64, int64](check.ValGT[int64](5)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}
ps.Parse([]string{"-my-ints", "6,23"})
fmt.Println("After  parsing")
for i, v := range il {
	fmt.Printf("\til[%d] = %d\n", i, v)
}

Output:

Before parsing
	il[0] = 42
After  parsing
	il[0] = 6
	il[1] = 23

ExampleMap_fixingInitialValue demonstrates how an initial value may be changed through the command line. That is, it is possible to change the value of a map entry to false as well as to true.

ps := newPSetForTesting() // use paramset.NewOrPanic()

m := map[string]bool{"x": true}
keys := []string{"x", "y"}

ps.Add("my-map", psetter.Map{Value: &m}, "help text")

fmt.Println("Before parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}
ps.Parse([]string{"-my-map", "x=false,y"})
fmt.Println("After  parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

Output:

Before parsing
	m[x] = true
After  parsing
	m[x] = false
	m[y] = true

ExampleMap_standard demonstrates the use of an Map setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var m map[string]bool
keys := []string{"x", "y"}

ps.Add("my-map", psetter.Map{Value: &m}, "help text")

fmt.Println("Before parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}
ps.Parse([]string{"-my-map", "x"})
fmt.Println("After  parsing")
for _, k := range keys {
	if v, ok := m[k]; ok {
		fmt.Printf("\tm[%s] = %v\n", k, v)
	}
}

Output:

Before parsing
After  parsing
	m[x] = true

ExampleMap_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the map Value has not been initialised
ps.Add("my-map", psetter.Map{}, "help text")

Output:

panic
my-map: psetter.Map Check failed: the Value to be set is nil

ExampleNil_standard demonstrates how you might use a Nil setter. Note that the Nil setter does nothing itself; any effect takes place through associated action functions

ps := newPSetForTesting() // use paramset.NewOrPanic()

var flag1 bool
var flag2 bool

ps.Add("my-param", psetter.Nil{}, "help text",
	param.PostAction(paction.SetVal(&flag1, true)),
	param.PostAction(paction.SetVal(&flag2, true)),
)

fmt.Println("Before parsing")
fmt.Printf("\tflag1 = %v\n", flag1)
fmt.Printf("\tflag2 = %v\n", flag2)
ps.Parse([]string{"-my-param"})
fmt.Println("After  parsing")
fmt.Printf("\tflag1 = %v\n", flag1)
fmt.Printf("\tflag2 = %v\n", flag2)

Output:

Before parsing
	flag1 = false
	flag2 = false
After  parsing
	flag1 = true
	flag2 = true

ExamplePathname_standard demonstrates the use of a Pathname setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var pathname string

ps.Add("my-pathname", psetter.Pathname{Value: &pathname}, "help text")

fmt.Printf("Before parsing    pathname: %q\n", pathname)
ps.Parse([]string{"-my-pathname", "testdata/noSuchFile.go"})
fmt.Printf("After  parsing    pathname: %q\n", pathname)

Output:

Before parsing    pathname: ""
After  parsing    pathname: "testdata/noSuchFile.go"

ExamplePathname_withFailingExpectation demonstrates the use of a Pathname setter which has the Expectation set. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var pathname string

ps.Add("my-pathname",
	psetter.Pathname{
		Value:       &pathname,
		Expectation: filecheck.FileExists(),
	},
	"help text")

fmt.Printf("Before parsing    pathname: %q\n", pathname)
errMap := ps.Parse([]string{"-my-pathname", "testdata/noSuchFile.go"})
// We expect to see an error reported.
logErrs(errMap)
// There was an error with the parameter so the value will be unchanged
fmt.Printf("After  parsing    pathname: %q\n", pathname)

Output:

Before parsing    pathname: ""
Errors for: my-pathname
	: path: "testdata/noSuchFile.go" should exist but doesn't
At: [command line]: Supplied Parameter:2: "-my-pathname" "testdata/noSuchFile.go"
After  parsing    pathname: ""

ExamplePathname_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the bool Value has not been initialised
ps.Add("do-this", psetter.Pathname{}, "help text")

Output:

panic
do-this: psetter.Pathname Check failed: the Value to be set is nil

ExamplePathname_withPassingChecks demonstrates the use of a Pathname setter which has Checks. Note that it also has the Expectation set.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var pathname string

ps.Add("my-pathname",
	psetter.Pathname{
		Value:       &pathname,
		Expectation: filecheck.IsNew(),
		Checks: []check.String{
			check.StringHasSuffix[string](".go"),
		},
	},
	"help text")

fmt.Printf("Before parsing    pathname: %q\n", pathname)
ps.Parse([]string{"-my-pathname", "testdata/noSuchFile.go"})
fmt.Printf("After  parsing    pathname: %q\n", pathname)

Output:

Before parsing    pathname: ""
After  parsing    pathname: "testdata/noSuchFile.go"

ExamplePathname_withPassingExpectation demonstrates the use of a Pathname setter which has the Expectation set.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var pathname string

ps.Add("my-pathname",
	psetter.Pathname{
		Value:       &pathname,
		Expectation: filecheck.IsNew(),
	},
	"help text")

fmt.Printf("Before parsing    pathname: %q\n", pathname)
ps.Parse([]string{"-my-pathname", "testdata/noSuchFile.go"})
fmt.Printf("After  parsing    pathname: %q\n", pathname)

Output:

Before parsing    pathname: ""
After  parsing    pathname: "testdata/noSuchFile.go"

ExamplePathnameListAppender_standard demonstrates the use of a PathnameListAppender

ps := newPSetForTesting() // use paramset.NewOrPanic()

ss := []string{"testdata/pathname/nonesuch.go"}

ps.Add("next",
	psetter.PathnameListAppender{
		Value:       &ss,
		Expectation: filecheck.IsNew(),
		Checks: []check.String{
			check.StringHasSuffix[string](".go"),
		},
	},
	"help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
ps.Parse([]string{"-next", "testdata/pathname/nonesuch2.go"})
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
	ss[0] = "testdata/pathname/nonesuch.go"
After  parsing
	ss[0] = "testdata/pathname/nonesuch.go"
	ss[1] = "testdata/pathname/nonesuch2.go"

ExamplePathnameListAppender_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the list Value has not been initialised
ps.Add("my-list", psetter.PathnameListAppender{}, "help text")

Output:

panic
my-list: psetter.PathnameListAppender Check failed: the Value to be set is nil

ExampleRegexp_standard demonstrates the use of a Regexp setter.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var re *regexp.Regexp

ps.Add("my-re", psetter.Regexp{Value: &re}, "help text")

fmt.Printf("Before parsing    re: ")
if re == nil {
	fmt.Printf(" nil\n")
} else {
	fmt.Printf(" non-nil [%s]\n", re.String())
}
ps.Parse([]string{"-my-re", `.*\.go`})
fmt.Printf("After  parsing    re: ")
if re == nil {
	fmt.Printf(" nil\n")
} else {
	fmt.Printf(" non-nil [%s]\n", re.String())
}

Output:

Before parsing    re:  nil
After  parsing    re:  non-nil [.*\.go]

ExampleRegexp_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the regexp pointer Value has not been
// initialised
ps.Add("do-this", psetter.Regexp{}, "help text")

Output:

panic
do-this: psetter.Regexp Check failed: the Value to be set is nil

ExampleStrList_standard demonstrates the use of a StrList setter

ps := newPSetForTesting() // use paramset.NewOrPanic()

var ss []string

ps.Add("my-list",
	psetter.StrList{
		Value: &ss,
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
ps.Parse([]string{"-my-list", "x,y"})
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
After  parsing
	ss[0] = "x"
	ss[1] = "y"

ExampleStrList_withEditor demonstrates the behaviour of the Editor.

package main

import (
	"errors"
	"fmt"

	"github.com/nickwells/param.mod/v5/param"
	"github.com/nickwells/param.mod/v5/param/psetter"
)

type myEditorStrList struct{}

// Edit switches on the parameter name to reset the parameter value
func (myEditorStrList) Edit(paramName, paramVal string) (string, error) {
	switch paramName {
	case "hello":
		return "Hello, " + paramVal, nil
	case "en":
		return "Hi, " + paramVal, nil
	case "fr":
		return "Bonjour, " + paramVal, nil
	case "es":
		return "Hola, " + paramVal, nil
	case "de":
		return "Guten Tag, " + paramVal, nil
	}
	return "", errors.New("Unknown language: " + paramName)
}

// ExampleStrList_withEditor demonstrates the behaviour of the Editor.
func main() {
	ps := newPSetForTesting() // use paramset.NewOrPanic()

	var ss []string
	var myE myEditorStrList

	ps.Add("hello",
		psetter.StrList{
			Value:  &ss,
			Editor: myE,
		}, "help text",
		param.AltNames("en", "fr", "es", "de"),
	)

	fmt.Println("Before parsing")
	for i, v := range ss {
		fmt.Printf("\tss[%d] = %q\n", i, v)
	}
	ps.Parse([]string{"-fr", "Nick,Pascal,Amelie"})
	fmt.Println("After  parsing")
	for i, v := range ss {
		fmt.Printf("\tss[%d] = %q\n", i, v)
	}
}

Output:

Before parsing
After  parsing
	ss[0] = "Bonjour, Nick"
	ss[1] = "Bonjour, Pascal"
	ss[2] = "Bonjour, Amelie"

ExampleStrList_withFailingChecks demonstrates the behaviour of the package when an invalid value is given. In this case the resulting list is not of the required length. It demonstrates the checks that can be supplied to ensure that the resulting list is as expected. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var ss []string

ps.Add("my-list",
	psetter.StrList{
		Value: &ss,
		Checks: []check.StringSlice{
			check.SliceLength[[]string, string](check.ValEQ(2)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
// Parse the arguments. We supply a list of strings, each of which is
// allowed. The resulting slice is of the wrong length.
errMap := ps.Parse([]string{"-my-list", "x"})
// We expect to see an error reported.
logErrs(errMap)
// The slice of strings is unchanged due to the error.
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
Errors for: my-list
	: the length of the list (1) is incorrect: the value (1) must equal 2
At: [command line]: Supplied Parameter:2: "-my-list" "x"
After  parsing

ExampleStrList_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the list Value has not been initialised
ps.Add("my-list", psetter.StrList{}, "help text")

Output:

panic
my-list: psetter.StrList Check failed: the Value to be set is nil

ExampleStrList_withPassingChecks demonstrates how you can specify additional checks to be applied to the passed arguments before the value is set.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var ss []string

ps.Add("my-list",
	psetter.StrList{
		Value: &ss,
		Checks: []check.StringSlice{
			check.SliceLength[[]string, string](check.ValEQ(2)),
		},
	}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
ps.Parse([]string{"-my-list", "x,y"})
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
After  parsing
	ss[0] = "x"
	ss[1] = "y"

ExampleStrListAppender_standard demonstrates the use of a StrListAppender

ps := newPSetForTesting() // use paramset.NewOrPanic()

ss := []string{"Hello"}

ps.Add("next", psetter.StrListAppender{Value: &ss}, "help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
ps.Parse([]string{"-next", "darkness", "-next", "my old friend"})
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
	ss[0] = "Hello"
After  parsing
	ss[0] = "Hello"
	ss[1] = "darkness"
	ss[2] = "my old friend"

ExampleStrListAppender_withEditor demonstrates the behaviour of the Editor.

package main

import (
	"errors"
	"fmt"

	"github.com/nickwells/param.mod/v5/param"
	"github.com/nickwells/param.mod/v5/param/psetter"
)

type myEditorMult struct{}

// Edit switches on the parameter name to reset the parameter value
func (myEditorMult) Edit(paramName, paramVal string) (string, error) {
	switch paramName {
	case "next":
		return paramVal, nil
	case "next2":
		return paramVal + ", " + paramVal, nil
	case "next3":
		return paramVal + ", " + paramVal + ", " + paramVal, nil
	}
	return "", errors.New("Unexpected parameter: " + paramName)
}

// ExampleStrListAppender_withEditor demonstrates the behaviour of the Editor.
func main() {
	ps := newPSetForTesting() // use paramset.NewOrPanic()

	ss := []string{"Hello"}
	var myE myEditorMult

	ps.Add("next",
		psetter.StrListAppender{
			Value:  &ss,
			Editor: myE,
		}, "help text",
		param.AltNames("next2", "next3"),
	)

	fmt.Println("Before parsing")
	for i, v := range ss {
		fmt.Printf("\tss[%d] = %q\n", i, v)
	}
	ps.Parse([]string{"-next", "darkness", "-next3", "darkness"})
	fmt.Println("After  parsing")
	for i, v := range ss {
		fmt.Printf("\tss[%d] = %q\n", i, v)
	}
}

Output:

Before parsing
	ss[0] = "Hello"
After  parsing
	ss[0] = "Hello"
	ss[1] = "darkness"
	ss[2] = "darkness, darkness, darkness"

ExampleStrListAppender_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

ss := []string{"Hello"}

ps.Add("next",
	psetter.StrListAppender{
		Value: &ss,
		Checks: []check.String{
			check.StringLength[string](check.ValLT(10)),
		},
	},
	"help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
errMap := ps.Parse([]string{"-next", "darkness", "-next", "my old friend"})
// We expect to see an error reported.
logErrs(errMap)
// The value does not include the second parameter due to the error.
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
	ss[0] = "Hello"
Errors for: next
	: the length of the string (13) is incorrect: the value (13) must be less than 10
At: [command line]: Supplied Parameter:4: "-next" "my old friend"
After  parsing
	ss[0] = "Hello"
	ss[1] = "darkness"

ExampleStrListAppender_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

// we expect this to panic because the list Value has not been initialised
ps.Add("my-list", psetter.StrListAppender{}, "help text")

Output:

panic
my-list: psetter.StrListAppender Check failed: the Value to be set is nil

ExampleStrListAppender_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

ss := []string{"Hello"}

ps.Add("next",
	psetter.StrListAppender{
		Value: &ss,
		Checks: []check.String{
			check.StringLength[string](check.ValGT(5)),
		},
	},
	"help text")

fmt.Println("Before parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}
ps.Parse([]string{"-next", "darkness", "-next", "my old friend"})
fmt.Println("After  parsing")
for i, v := range ss {
	fmt.Printf("\tss[%d] = %q\n", i, v)
}

Output:

Before parsing
	ss[0] = "Hello"
After  parsing
	ss[0] = "Hello"
	ss[1] = "darkness"
	ss[2] = "my old friend"

ExampleString_standard demonstrates the use of a String setter

ps := newPSetForTesting() // use paramset.NewOrPanic()

var s string

ps.Add("my-string", psetter.String{Value: &s}, "help text")

fmt.Printf("Before parsing: s = %q\n", s)
ps.Parse([]string{"-my-string", "Hello, World!"})
fmt.Printf("After  parsing: s = %q\n", s)

Output:

Before parsing: s = ""
After  parsing: s = "Hello, World!"

ExampleString_withEditor demonstrates the behaviour of the Editor.

package main

import (
	"errors"
	"fmt"

	"github.com/nickwells/param.mod/v5/param"
	"github.com/nickwells/param.mod/v5/param/psetter"
)

type myEditor struct{}

// Edit switches on the parameter name to reset the parameter value
func (myEditor) Edit(paramName, paramVal string) (string, error) {
	switch paramName {
	case "hello":
		return "Hello, " + paramVal, nil
	case "en":
		return "Hi, " + paramVal, nil
	case "fr":
		return "Bonjour, " + paramVal, nil
	case "es":
		return "Hola, " + paramVal, nil
	case "de":
		return "Guten Tag, " + paramVal, nil
	}
	return "", errors.New("Unknown language: " + paramName)
}

// ExampleString_withEditor demonstrates the behaviour of the Editor.
func main() {
	ps := newPSetForTesting() // use paramset.NewOrPanic()

	var s string
	var myE myEditor

	ps.Add("hello",
		psetter.String{
			Value:  &s,
			Editor: myE,
		}, "help text",
		param.AltNames("en", "fr", "es", "de"),
	)

	fmt.Printf("Before parsing: s = %q\n", s)
	ps.Parse([]string{"-fr", "Nick!"})
	fmt.Printf("After  parsing: s = %q\n", s)
}

Output:

Before parsing: s = ""
After  parsing: s = "Bonjour, Nick!"

ExampleString_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var s string

ps.Add("my-string",
	psetter.String{
		Value: &s,
		Checks: []check.String{
			check.StringLength[string](check.ValGT(5)),
		},
	}, "help text")

fmt.Printf("Before parsing: s = %q\n", s)
// Parse the arguments. Note that the string supplied is too short to
// satisfy the check for this parameter.
errMap := ps.Parse([]string{"-my-string", "Hi!"})
// We expect to see an error reported.
logErrs(errMap)
// The value is unchanged due to the error.
fmt.Printf("After  parsing: s = %q\n", s)

Output:

Before parsing: s = ""
Errors for: my-string
	: the length of the string (3) is incorrect: the value (3) must be greater than 5
At: [command line]: Supplied Parameter:2: "-my-string" "Hi!"
After  parsing: s = ""

ExampleString_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

ps.Add("my-string", psetter.String{}, "help text")

Output:

panic
my-string: psetter.String Check failed: the Value to be set is nil

ExampleString_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var s string

ps.Add("my-string",
	psetter.String{
		Value: &s,
		Checks: []check.String{
			check.StringLength[string](check.ValGT(5)),
		},
	}, "help text")

fmt.Printf("Before parsing: s = %q\n", s)
ps.Parse([]string{"-my-string", "Hello, World!"})
fmt.Printf("After  parsing: s = %q\n", s)

Output:

Before parsing: s = ""
After  parsing: s = "Hello, World!"

ExampleTime_standard demonstrates the use of a Time setter

ps := newPSetForTesting() // use paramset.NewOrPanic()

var t time.Time

ps.Add("my-time", psetter.Time{Value: &t}, "help text")

fmt.Printf("Before parsing: time = %s\n", t.Format("15:04"))
ps.Parse([]string{"-my-time", "2000/Jan/01T15:00:00"})
fmt.Printf("After  parsing: time = %s\n", t.Format("15:04"))

Output:

Before parsing: time = 00:00
After  parsing: time = 15:00

ExampleTime_withFailingChecks demonstrates how to add checks to be applied to the value. Note that there is normally no need to examine the return from ps.Parse as the standard Helper will report any errors and abort the program.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var t time.Time

ps.Add("my-time",
	psetter.Time{
		Value: &t,
		Checks: []check.Time{
			check.TimeIsOnDOW(time.Friday),
		},
	},
	"help text")

fmt.Printf("Before parsing: time = %s\n", t.Weekday())
// Parse the arguments. Note that the time given is not on a Friday.
errMap := ps.Parse([]string{"-my-time", "2020/Apr/25T12:00:00"})
// We expect to see an error reported.
logErrs(errMap)
// The value is unchanged due to the error.
fmt.Printf("After  parsing: time = %s\n", t.Weekday())

Output:

Before parsing: time = Monday
Errors for: my-time
	: the day of the week (Saturday) must be a Friday
At: [command line]: Supplied Parameter:2: "-my-time" "2020/Apr/25T12:00:00"
After  parsing: time = Monday

ExampleTime_withFormat demonstrates the use of a Time setter with a non-default Format value

ps := newPSetForTesting() // use paramset.NewOrPanic()

var t time.Time

ps.Add("my-time",
	psetter.Time{
		Value:  &t,
		Format: psetter.TimeFmtHMS,
	},
	"help text")

fmt.Printf("Before parsing: time = %s\n", t.Format("15:04:05"))
ps.Parse([]string{"-my-time", "15:01:02"})
fmt.Printf("After  parsing: time = %s\n", t.Format("15:04:05"))

Output:

Before parsing: time = 00:00:00
After  parsing: time = 15:01:02

ExampleTime_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

ps.Add("my-time", psetter.Time{}, "help text")

Output:

panic
my-time: psetter.Time Check failed: the Value to be set is nil

ExampleTime_withPassingChecks demonstrates how to add checks to be applied to the value.

ps := newPSetForTesting() // use paramset.NewOrPanic()

var t time.Time

ps.Add("my-time",
	psetter.Time{
		Value: &t,
		Checks: []check.Time{
			check.TimeIsOnDOW(time.Friday),
		},
	},
	"help text")

fmt.Printf("Before parsing: time = %s\n", t.Weekday())
ps.Parse([]string{"-my-time", "2020/Apr/24T12:00:00"})
fmt.Printf("After  parsing: time = %s\n", t.Weekday())

Output:

Before parsing: time = Monday
After  parsing: time = Friday

ExampleTimeLocation_standard demonstrates the use of a TimeLocation setter

ps := newPSetForTesting() // use paramset.NewOrPanic()

var loc *time.Location

ps.Add("location", psetter.TimeLocation{Value: &loc}, "help text")

fmt.Printf("Before parsing   location: %v\n", loc)
ps.Parse([]string{"-location", "Europe/London"})
fmt.Printf("After  parsing   location: %v\n", loc)

Output:

Before parsing   location: UTC
After  parsing   location: Europe/London

ExampleTimeLocation_withNilValue demonstrates the behaviour of the package when an invalid setter is provided. In this case the Value to be set has not been initialised. Note that in production code you should not recover from the panic, instead you should fix the code that caused it.

defer func() { // For test purposes only - do not recover in live code
	if p := recover(); p != nil {
		fmt.Println("panic")
		fmt.Println(p)
	}
}()

ps := newPSetForTesting() // use paramset.NewOrPanic()

ps.Add("location", psetter.TimeLocation{}, "help text")

Output:

panic
location: psetter.TimeLocation Check failed: the Value to be set is nil