paction

package
v6.1.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2023 License: MIT Imports: 5 Imported by: 11

Documentation

Overview

Package paction collects together useful action functions that can be applied to params. The definition of an ActionFunc is given in package param.

Action functions are called each time a parameter is encountered, after the parameter setter has been called. They are called in the order they are added to the parameter.

Example (Count)

Example_count provides an example of how the paction.Counter might be used. Here we simply use it to check that only one of a pair of parameters has been set but it can be used to check for more complex rules. For instance, if one is set then all must be set or at least one of the set of parameters is set. 

package main

import (
	"fmt"

	"github.com/nickwells/param.mod/v6/paction"
	"github.com/nickwells/param.mod/v6/param"
	"github.com/nickwells/param.mod/v6/paramset"
	"github.com/nickwells/param.mod/v6/psetter"
)

func main() {
	// Declare the parameter values
	var (
		param1 bool
		param2 bool
	)

	// Declare the counter and make the associated action function. These two
	// lines and the extra arguments to the parameter creation are the core
	// of what you have to do
	var paramCounter paction.Counter
	af := (&paramCounter).MakeActionFunc()

	// Create the parameter set ...
	ps, _ := paramset.New()

	// ... and add the parameters. For each parameter we set the function to
	// be called after they have been set to the action function created
	// above. Note that we record the parameter we have created so that we
	// can report the name we gave it below
	p1 := ps.Add("p1", psetter.Bool{Value: &param1},
		"the first flag (only set 1)",
		param.PostAction(af)) // This sets the action function
	p2 := ps.Add("p2", psetter.Bool{Value: &param2},
		"the second flag (only set 1)",
		param.PostAction(af)) // This sets the action function

	// Now parse a set of supplied parameters. We force the arguments for the
	// purposes of the example, typically you would not pass anything and the
	// Parse function will use the command-line arguments.
	ps.Parse([]string{"-p1", "-p2"})

	// Now we can check the counter to see how many different parameters have
	// been set
	if paramCounter.Count() > 1 {
		fmt.Printf("Both of %s and %s have been set:\n",
			p1.Name(), p2.Name())

		// range over the parameters set and report them. Alternatively we
		// could use the SetBy function on the Counter and get a string
		// describing where the parameters were set
		for _, pSource := range paramCounter.ParamsSetAt {
			fmt.Println(pSource)
		}
	}

}

Output:

Both of p1 and p2 have been set:
Param: p1 (at [command line]: Supplied Parameter:1: "-p1")
Param: p2 (at [command line]: Supplied Parameter:2: "-p2")

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendStringVal 

func AppendStringVal(val *[]string, s *string) param.ActionFunc

AppendStringVal returns an ActionFunc that appends the given string to the supplied slice.

This can be used to add a string to a slice if a parameter has been set.

This should be used if you want to apply the value of a string variable at the time the ActionFunc is called rather than when it is first set.

func AppendStrings 

func AppendStrings(val *[]string, s ...string) param.ActionFunc

AppendStrings returns an ActionFunc that appends the given strings to the supplied slice.

This can be used to add a string to a slice if a parameter has been set.

Note that the value of the strings is passed by value and so the value used will be that at the time this is called. This is therefore useful only for setting fixed values; use the AppendStringVal function if you want to apply the value of a string variable at the time the ActionFunc is called.

func ErrReport 

func ErrReport(msg string) param.ActionFunc

ErrReport returns an ActionFunc that will print its argument to the error writer of the PSet (as given by the ErrWriter method).

func ErrReportAndExit 

func ErrReportAndExit(msg string) param.ActionFunc

ErrReportAndExit returns an ActionFunc that will print its argument to the error writer of the PSet (as given by the ErrWriter method). Having printed the message it will exit with status 1.

func Exit 

func Exit(code int) param.ActionFunc

Exit returns an ActionFunc that will exit with the given exit status. This should always be the last ActionFunc as no subsequent ones will be called

func IsACommandLineParam 

func IsACommandLineParam(loc location.L, _ *param.ByName, _ []string) bool

IsACommandLineParam returns true if the parameter has been set through the command line, false otherwise.

func IsAConfigFileParam 

func IsAConfigFileParam(loc location.L, _ *param.ByName, _ []string) bool

IsAConfigFileParam returns true if the parameter has been set through a line in a configuration file, false otherwise.

func IsAnEnvVarParam 

func IsAnEnvVarParam(loc location.L, _ *param.ByName, _ []string) bool

IsAnEnvVarParam returns true if the parameter has been set through an environment variable, false otherwise.

func IsNotACommandLineParam 

func IsNotACommandLineParam(loc location.L, _ *param.ByName, _ []string) bool

IsNotACommandLineParam returns true if the parameter has not been set through the command line, false otherwise.

func IsNotAConfigFileParam 

func IsNotAConfigFileParam(loc location.L, _ *param.ByName, _ []string) bool

IsNotAConfigFileParam returns true if the parameter has not been set through a line in a configuration file, false otherwise.

func IsNotAnEnvVarParam 

func IsNotAnEnvVarParam(loc location.L, _ *param.ByName, _ []string) bool

IsNotAnEnvVarParam returns true if the parameter has not been set through an environment variable, false otherwise.

func Report 

func Report(msg string) param.ActionFunc

Report returns an ActionFunc that will print its argument to the standard writer of the PSet (as given by the StdWriter method).

func ReportAndExit 

func ReportAndExit(msg string) param.ActionFunc

ReportAndExit returns an ActionFunc that will print its argument to the standard writer of the PSet (as given by the StdWriter method). Having printed the message it will exit with status 0.

func SetMapVal 

func SetMapVal[K comparable, V any](m map[K]V, k K, b V) param.ActionFunc

SetMapVal returns an ActionFunc that sets the keyed entry in the map to the given setTo value.

It is advised that the key be supplied as a named const value to avoid mismatches.

This can be used if you want to set some map entry if a parameter has been set. For instance if you are setting some configuration for an operation it implies that you want the operation performed. This saves forcing the user to both specify the configuration and request the operation.

func SetMapValIf 

func SetMapValIf[K comparable, V any](m map[K]V, k K, b V, test ParamTestFunc,
) param.ActionFunc

SetMapValIF returns an ActionFunc that sets the keyed entry in the map to the given setTo value if the supplied test function returns true.

It is advised that the key be supplied as a named const value to avoid mismatches.

This can be used if you want to set some map entry if a parameter has been set. For instance if you are setting some configuration for an operation it implies that you want the operation performed. This saves forcing the user to both specify the configuration and request the operation.

func SetOnceActionFunc 

func SetOnceActionFunc(action SetOnceErrAction) param.ActionFunc

SetOnceActionFunc constructs a local SetOnce value and then makes an ActionFunc to operate on it. The advantage is that the SetOnce value is guaranteed to be unique to the parameter, the disadvantage is that you don't have access to the value if you want to handle it further

func SetVal 

func SetVal[T any](val *T, setTo T) param.ActionFunc

SetVal returns an ActionFunc that sets the val to the given setTo value.

This can be used, for instance, if you want to set some value if a parameter has been set. For instance if you are setting some configuration for an operation it implies that you want the operation performed. This saves forcing the user to both specify the configuration and request the operation.

func SetValIf 

func SetValIf[T any](val *T, setTo T, test ParamTestFunc) param.ActionFunc

SetValIf returns an ActionFunc that sets the val to the given setTo value if the supplied test function returns true.

This can be used, for instance, if you want to set some value if a parameter has been set. For instance if you are setting some configuration for an operation it implies that you want the operation performed. This saves forcing the user to both specify the configuration and request the operation.

Types

type Counter 

type Counter struct {
	ParamCount map[string]int

	ParamsSetAt param.Sources
}

Counter is used to record how many of a collection of params has been set

It can be used to check, among other things, that at least one of a collection has been set or if more than one has been set

func (Counter) Count 

func (c Counter) Count() int

Count returns the count - the number of distinct parameters that have been set

func (*Counter) MakeActionFunc 

func (c *Counter) MakeActionFunc() param.ActionFunc

MakeActionFunc returns a function suitable for passing to the PostAction method of a param.ByName object

func (Counter) SetBy 

func (c Counter) SetBy() string

SetBy returns a string describing all the places that the parameter(s) were set

func (Counter) Total 

func (c Counter) Total() int

Total returns the total number of times the ActionFunction was called

type ParamTestFunc 

type ParamTestFunc func(location.L, *param.ByName, []string) bool

ParamTestFunc represents a function that can be used to test a parameter

type SetOnce 

type SetOnce struct {
	// contains filtered or unexported fields
}

SetOnce is used to record if a parameter has been previously set and take appropriate action if it has.

This can be used if you have a parameter that you want to set in a system- wide config file (owned, for instance, by root) and which the users cannot override. It doesn't make a lot of sense to have this if you don't have a system-wide config file since the user can just change it themselves - it'll be more irritating than anything else.

Note that this is an alternative mechanism to the SetOnlyOnce parameter attribute. It does NOT guarantee that the value won't be set multiple times, only that an error will be returned (if the action value is set to ErrorOnMultipleTries). If the SetOnlyOnce attribute is set on the parameter then this function will only be called the first time the parameter is set and will therefore have no effect.

func (*SetOnce) MakeActionFunc 

func (so *SetOnce) MakeActionFunc(action SetOnceErrAction) param.ActionFunc

MakeActionFunc returns a function suitable for passing to the PostAction method of a param.ByName object. This uses a pre-existing SetOnce value and so it could be set on multiple different parameters but the expected use is to have a separate SetOnce value for each parameter that you want to protect

type SetOnceErrAction 

type SetOnceErrAction int32

SetOnceErrAction records the behaviour to exhibit when the parameter has been set more than once 

const (
	// IgnoreMultipleTries means that no further action beyond recording that
	// the parameter has been set will be taken
	IgnoreMultipleTries SetOnceErrAction = iota
	// ErrorOnMultipleTries means that more than one attempt to set the value
	// will cause an error to be returned by the action function
	ErrorOnMultipleTries
	// ExitOnMultipleTries means that more than one attempt to set the value
	// will cause the program to exit
	ExitOnMultipleTries
)

SetOnceErrAction values

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.