paction

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/v4/param"
	"github.com/nickwells/param.mod/v4/param/paction"
	"github.com/nickwells/param.mod/v4/param/paramset"
	"github.com/nickwells/param.mod/v4/param/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. At:\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. At:
Param: p1 (at supplied parameters:1: -p1)
Param: p2 (at supplied parameters:2: -p2)

Index

• func ErrReport(msg string) param.ActionFunc
• func Exit(code int) param.ActionFunc
• func Report(msg string) param.ActionFunc
• func SetBool(val *bool, setTo bool) param.ActionFunc
• func SetOnceActionFunc(action SetOnceErrAction) param.ActionFunc
• func SetString(val *string, setTo string) param.ActionFunc
• type Counter
  • func (c Counter) Count() int
  • func (c *Counter) MakeActionFunc() param.ActionFunc
  • func (c Counter) SetBy() string
  • func (c Counter) Total() int
• type SetOnce
  • func (so *SetOnce) MakeActionFunc(action SetOnceErrAction) param.ActionFunc
• type SetOnceErrAction

Examples

• Package (Count)

Functions

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 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 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 SetBool

func SetBool(val *bool, setTo bool) param.ActionFunc

SetBool returns an ActionFunc to set the val to the given bool.

This can be used if you want to set some boolean 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 SetString

func SetString(val *string, setTo string) param.ActionFunc

SetString returns an ActionFunc to set the val to the given string.

This can be used if you want to set some string 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 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 for this to have the desired effect you must also set the SetOnlyOnce parameter attribute. This will only audit the multiple attempts and optionally set the error status on the parameter. If you do not set the SetOnlyOnce parameter and you do not have the ExitOnMultipleTries action set then it is possible that the parameter could be set despite this ActionFunc being provided

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