param

package
v3.6.0 Latest Latest
Warning

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

 Go to latest Published: Feb 18, 2020 License: MIT Imports: 15 Imported by: 3

Documentation

Overview

Package param is used for setting the starting parameters for an application. It allows developers to define parameters in their packages and then in main() they can call Parse and command line parameters will be compared against the defined parameters and the corresponding values will be set.

You can add parameters to the set of params to be checked with the Add function and you can add alternative names with AltName which returns an option function that will add the alternative name to the set of ways that a parameter can be referenced. Similarly the GroupName function allows you to group related parameters together so that they will be reported together in the usage message.

The way to use this package is to create a PSet and then to add parameters to it and when you've set all the parameters you want, you call Parse on the PSet. You can create a PSet with the NewSet function but it is more convenient to use the convenience function from the paramset package: 

paramset.NewOrDie(...)

as this will automatically set the mandatory helper to the Standard helper. This will provide a common set of parameters that give a consistent interface to your command line tools. The standard parameters also give access to many useful features that will make your command line tools easy to use.

When adding a new parameter you need to choose the Setter that you want it to use. The psetter package provides a lot of standard ones but you can write your own if you have a package where you want to instantiate a parameter that is not covered by the standard setters.

Optionally you can choose to provide actions to be performed once the parameter has been seen. The paction package provides some standard actions but you can write your own. These can be useful to set parameters where if one is set it implies that another should take a certain value. Actions can also be used to record how many of a group of parameters have been set so that you could, for instance, check that only one of a group of mutually exclusive parameters has been set.

Similarly you can specify final functions to be run after all parameter processing is complete but before Parse returns to the caller. These final functions can check that the parameters have been set correctly. For instance you can use these final functions to make sure that a sensible combination of parameters has been set.

Example (SetDirectly)

Example_setDirectly shows how to use the param package. It is generally advisable to have the parameter setting grouped into separate functions (see the typicalUse example) but in order to show the use of the param funcs we have added the new parameters in line after constructing the new PSet.

Note that the parameter names are given without any leading dashes. This is because they can be passed on the command line or through parameter files or environment variables where the leading dash is not used. 

package main

import (
	"fmt"

	"github.com/nickwells/param.mod/v3/param"
	"github.com/nickwells/param.mod/v3/param/paramset"
	"github.com/nickwells/param.mod/v3/param/psetter"
)

func main() {
	var example1 bool
	var example2 int64

	ps := paramset.NewOrDie()
	ps.SetProgramDescription("what this program does")

	ps.Add("example1",
		psetter.Bool{Value: &example1},
		"here is where you would describe the parameter",
		// optional additional settings
		param.AltName("e1"))

	ps.Add("example2",
		psetter.Int64{Value: &example2},
		"the description of the parameter",
		// optional additional settings
		param.AltName("e2"))

	fmt.Println("example1:", example1)
	fmt.Println("example2:", example2)

	// For the purposes of the example we are passing the parameters in as a
	// slice. In practice you would almost always pass nothing in which case
	// Parse will use the command line arguments.
	ps.Parse([]string{
		"-e1",            // this uses the alternative name for the parameter
		"-example2", "3", // this parameter expects a following value
	})
	fmt.Println("example1:", example1)
	fmt.Println("example2:", example2)

}

Output:

example1: false
example2: 0
example1: true
example2: 3
Example (TypicalUse)

Example_typicalUse shows how you would typically use the param package. Construct the PSet, adding any parameters through AddParam functions either from the main package or else package specific parameter setters. Set some description of the program. Then just call Parse with no parameters so that it will use the command line parameters 

package main

import (
	"github.com/nickwells/param.mod/v3/param"
	"github.com/nickwells/param.mod/v3/param/paramset"
	"github.com/nickwells/param.mod/v3/param/psetter"
)

// Example_typicalUse shows how you would typically use the param
// package. Construct the PSet, adding any parameters through AddParam
// functions either from the main package or else package specific parameter
// setters. Set some description of the program. Then just call Parse with no
// parameters so that it will use the command line parameters
func main() {
	ps := paramset.NewOrDie(
		tuAddParams1,
		tuAddParams2,
		param.SetProgramDescription("what this program does"))
	ps.Parse()
}

const tuExampleGroupName = "my-groupname"

var tuExample1 bool
var tuExample2 int64

// tuAddParams1 will add the "example1" parameter to the PSet
func tuAddParams1(ps *param.PSet) error {
	// we must set the group description before we can use the group name.
	// Parameters which don't explicitly set the group name are put in the
	// pre-declared "cmd" group
	ps.SetGroupDescription(tuExampleGroupName,
		"The parameters for my command")

	ps.Add("example1",
		psetter.Bool{Value: &tuExample1},
		"here is where you would describe the parameter",
		param.AltName("e1"),
		param.GroupName(tuExampleGroupName))

	return nil
}

// tuAddParams2 will add the "example2" parameter to the PSet
func tuAddParams2(ps *param.PSet) error {
	// add the example2 parameter to the set. Note that we don't set any
	// groupname and so this will be in the default group for the command
	// ("cmd")
	ps.Add("example2",
		psetter.Int64{Value: &tuExample2},
		"the description of the parameter",
		param.AltName("e2"))

	return nil
}

Output:
Example (WithEnvVar)

Example_withEnvVar shows how to use the param package using environment variables to set the parameter values 

package main

import (
	"fmt"
	"os"

	"github.com/nickwells/param.mod/v3/param"
	"github.com/nickwells/param.mod/v3/param/paramset"
	"github.com/nickwells/param.mod/v3/param/psetter"
)

// Example_withEnvVar shows how to use the param package using environment
// variables to set the parameter values
func main() {
	wevExample1 = false
	wevExample2 = 0

	ps := paramset.NewOrDie(
		wevAddParams1,
		wevAddParams2,
		param.SetProgramDescription("what this program does"))
	ps.SetEnvPrefix("GOLEM_PARAM_TEST_")
	ps.AddEnvPrefix("golem_param_test2_")

	os.Setenv("GOLEM_PARAM_TEST_"+"example1", "")
	os.Setenv("golem_param_test2_"+"example2", "3")

	fmt.Println("example1:", wevExample1)
	fmt.Println("example2:", wevExample2)
	// For the purposes of the example we are passing a slice of
	// strings. This is just to prevent the Parse func from setting any
	// values (and complaining about invalid parameters) from the command
	// line (the os.Args slice).
	ps.Parse([]string{})
	fmt.Println("example1:", wevExample1)
	fmt.Println("example2:", wevExample2)

}

const wevExampleGroupName = "groupname"

var wevExample1 bool
var wevExample2 int64

// wevAddParams1 will set the "example1" parameter in the PSet
func wevAddParams1(ps *param.PSet) error {
	ps.SetGroupDescription(wevExampleGroupName,
		"The parameters for my command")

	ps.Add("example1",
		psetter.Bool{Value: &wevExample1},
		"here is where you would describe the parameter",
		param.AltName("e1"),
		param.GroupName(wevExampleGroupName))

	return nil
}

// wevAddParams2 will set the "example2" parameter in the PSet
func wevAddParams2(ps *param.PSet) error {
	ps.Add("example2",
		psetter.Int64{Value: &wevExample2},
		"the description of the parameter",
		param.AltName("e2"),
		param.GroupName(wevExampleGroupName))

	return nil
}

Output:

example1: false
example2: 0
example1: true
example2: 3

Index

Examples

Constants

View Source 
const DfltGroupName = "cmd"

DfltGroupName is the parameter group name that a parameter will have if no explicit group name is given. It is expected that parameters specific to the command will be in this group.

View Source 
const DfltProgName = "PROGRAM NAME UNKNOWN"

DfltProgName is the program name that will be returned if Parse has not yet been called

View Source 
const DfltTerminalParam = "--"

DfltTerminalParam is the default value of the parameter that will stop command-line parameters from being processed. Any parameters found after this value will be available through the Remainder() func. This default value can be overridden through the SetTerminalParam func

Variables

This section is empty.

Functions

func ConfigFileActionFunc 

func ConfigFileActionFunc(loc location.L, p *ByName, paramVals []string) error

ConfigFileActionFunc can be called as an action func and will take the second entry in the paramVals (which is expected to exist) as the name of a config file from which to take parameters.

func ConvertEnvVarNameToParamName 

func ConvertEnvVarNameToParamName(name string) string

ConvertEnvVarNameToParamName converts an environment variable name to a parameter name. Any environment variable prefix (as added by AddEnvPrefix) should have been stripped off first. It should have the opposite effect to the ConvertParamNameToEnvVarName function

func ConvertParamNameToEnvVarName 

func ConvertParamNameToEnvVarName(name string) string

ConvertParamNameToEnvVarName converts a parameter name to a valid environment variable name. Note that in order to be recognised it will need to be prefixed by a recognised environment variable prefix as added by AddEnvPrefix. It should have the opposite effect to the ConvertEnvVarNameToParamName function

func DontExitOnParamSetupErr 

func DontExitOnParamSetupErr(ps *PSet) error

DontExitOnParamSetupErr turns off the standard behaviour of exiting if an error is detected while initialising the param set. The error is reported in either case

func GroupNameCheck added in v3.0.1 

func GroupNameCheck(name string) error

GroupNameCheck checks that the group name is valid and returns an error if not

func SetAsTerminal 

func SetAsTerminal(bp *ByPos) error

SetAsTerminal is a function which can be passed as a PosOptFunc. It sets the flag on the positional parameter indicating that it is terminal. Only the last positional parameter can be terminal; this is checked separately later.

Types

type AVM 

type AVM struct{ AllowedVals AValMap }

AVM is a mixin type that can be embedded in a Setter to provide an allowed values map for the Setter. It provides an implementation for the AllowedValuesMap method of the interface

func (AVM) AllowedValuesMap 

func (a AVM) AllowedValuesMap() AValMap

AllowedValuesMap returns the map of allowed values. Use this if your setter has a map of allowed values.

func (AVM) ValueAllowed 

func (a AVM) ValueAllowed(val string) bool

ValueAllowed returns true if the passed value is a key in the allowed values map

func (AVM) ValueMapOK 

func (a AVM) ValueMapOK() error

ValueMapOK returns any error that the OK method on the allowed values map returns

type AValMap 

type AValMap map[string]string

AValMap - this maps allowed values for an enumerated parameter to explanatory text. It forms part of the usage documentation of the program and will appear when the -help parameter is given by the user. It is also used to validate a supplied parameter.

func (AValMap) OK 

func (av AValMap) OK() error

OK returns a nil error if the map is "good" or an error with an explanation of the problem otherwise.

A map is "good" if it has more than one entry. A set of allowed values with one or fewer entries is obviously a mistake: if no entries are valid then the parameter can never be set correctly and if it only has a single entry then the current (initial) value is the only allowed value and so there is no need for a parameter as no alternative can ever be allowed.

func (AValMap) String 

func (av AValMap) String() string

String returns a string documenting the entries in the map - each entry is on a separate line

type ActionFunc 

type ActionFunc func(loc location.L, p *ByName, paramValues []string) error

ActionFunc is the type of a function to be called when the ByName parameter is encountered.

loc gives details on where the param was seen, this includes a description of the source (for instance "command line")

param is the parameter which was matched.

paramValues will have one or possibly two entries: the name used to match the param and (possibly) the value string.

type Attributes 

type Attributes int32

Attributes holds the attributes of the ByName parameter 

const (
	// CommandLineOnly means that the parameter can only be set on the
	// command line. Note that this also includes being set through values
	// passed to the Parse func as a slice of strings. You might want to set
	// this attribute on parameters which would always be different between
	// command invocations or where setting it would make the program
	// terminate. For instance, it is set on the standard help attributes as
	// setting these in a configuration file would never allow the program to
	// execute.
	CommandLineOnly Attributes = 1 << iota
	// MustBeSet means that the parameter must be given - it cannot be
	// omitted
	MustBeSet
	// SetOnlyOnce means that only the first time it is set will have any
	// effect and any subsequent attempts to set it will be ignored. You can
	// control the behaviour when multiple attempts are made through a
	// SetterFunc (see the SetOnce type in the paction package). You might
	// want to set this on a parameter that you want to set for all users in
	// a global configuration file that only the system administrator can
	// edit. This would allow you to set a system-wide policy.
	SetOnlyOnce
	// DontShowInStdUsage means that the parameter name will be suppressed
	// when the usage message is printed unless the expanded usage message
	// has been requested
	DontShowInStdUsage
)

Attributes values

type ByName 

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

ByName represents a parameter which is set by matching a name - it includes details such as: the primary name; any alternate names by which it can be set; the name of the group to which it belongs; the action to take when it is observed (typically setting a value); the description (used in the help message); the place(s) where it has been set - the last one takes precedence and the attributes

func (ByName) AllowedValues 

func (p ByName) AllowedValues() string

AllowedValues returns a description of the values that the ByName parameter can accept

func (ByName) AllowedValuesMap 

func (p ByName) AllowedValuesMap() AValMap

AllowedValuesMap returns the map (which may be nil) of values to descriptions for the values that the ByName parameter can accept

func (ByName) AltNames 

func (p ByName) AltNames() []string

AltNames returns a copy of the alternative names of the ByName parameter

func (ByName) AttrIsSet 

func (p ByName) AttrIsSet(attr Attributes) bool

AttrIsSet will return true if the supplied attribute is set on the param. Multiple attributes may be given in which case they must all be set

func (ByName) Description 

func (p ByName) Description() string

Description returns the description of the ByName parameter

func (ByName) ErrWriter 

func (p ByName) ErrWriter() io.Writer

ErrWriter returns the error writer of the PSet that this parameter belongs to

func (ByName) GroupName 

func (p ByName) GroupName() string

GroupName returns the groupName of the ByName parameter

func (*ByName) HasBeenSet 

func (p *ByName) HasBeenSet() bool

HasBeenSet will return true if the parameter has been set.

func (ByName) InitialValue 

func (p ByName) InitialValue() string

InitialValue returns the initialValue of the ByName parameter

func (ByName) Name 

func (p ByName) Name() string

Name returns the name of the ByName parameter

func (ByName) PSet added in v3.3.0 

func (p ByName) PSet() *PSet

PSet returns the parameter set to which the ByName parameter belongs

func (ByName) SetterType added in v3.6.0 

func (p ByName) SetterType() string

SetterType returns the name of the Setter type that the ByName parameter uses

func (ByName) StdWriter 

func (p ByName) StdWriter() io.Writer

StdWriter returns the standard writer of the PSet that this parameter belongs to

func (ByName) ValueReq 

func (p ByName) ValueReq() ValueReq

ValueReq returns the value requirements for the ByName parameter.

func (ByName) WhereSet 

func (p ByName) WhereSet() []string

WhereSet returns a copy of the list of places where the ByName parameter has been set

type ByPos 

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

ByPos represents a positional parameter. There are numerous strict rules about how this can be used. A positional parameter will only be checked on the command line (or a slice of strings); it cannot be set by an environment variable or in a config file. There must be enough command line arguments for all the positional parameters to be set. Only the last parameter can be a terminal parameter (a terminal parameter ends the parsing and returns). Having a parameter as a terminal parameter will allow different parameter sets to be used depending on the value of the positional parameter.

func (ByPos) AllowedValues added in v3.3.0 

func (p ByPos) AllowedValues() string

AllowedValues returns a description of the values that the ByPos parameter can accept

func (ByPos) AllowedValuesMap added in v3.3.0 

func (p ByPos) AllowedValuesMap() AValMap

AllowedValuesMap returns the map (which may be nil) of values to descriptions for the values that the ByPos parameter can accept

func (ByPos) Description 

func (bp ByPos) Description() string

Description returns the parameter description

func (ByPos) ErrWriter 

func (bp ByPos) ErrWriter() io.Writer

ErrWriter returns the error writer of the PSet that this parameter belongs to

func (ByPos) InitialValue added in v3.3.0 

func (p ByPos) InitialValue() string

InitialValue returns the initialValue of the ByPos parameter

func (ByPos) IsTerminal 

func (bp ByPos) IsTerminal() bool

IsTerminal returns true if the ByPos parameter is marked as terminal

func (ByPos) Name 

func (bp ByPos) Name() string

Name returns the parameter name

func (ByPos) StdWriter 

func (bp ByPos) StdWriter() io.Writer

StdWriter returns the standard writer of the PSet that this parameter belongs to

type ConfigFileDetails 

type ConfigFileDetails struct {
	Name         string
	CfConstraint filecheck.Exists
	// contains filtered or unexported fields
}

ConfigFileDetails records the details of a configuration file. Specifically its name and details about whether or not it must exist

func (ConfigFileDetails) ParamsMustExist added in v3.1.0 

func (cfd ConfigFileDetails) ParamsMustExist() bool

ParamsMustExist will return true if the existence rule for the file is set to paramMustExist, that is, if the file should only contain valid parameters

func (ConfigFileDetails) String 

func (cfd ConfigFileDetails) String() string

String returns a string describing the ConfigFileDetails

type ErrMap 

type ErrMap map[string][]error

ErrMap is the type used to store the errors recorded when parsing the parameters. Each map entry represents a parameter for which errors were detected; all the errors for that parameter are stored in a slice. Errors not related to any individual parameter are stored in the map entry with a key of an empty string.

type Example added in v3.5.0 

type Example struct {
	Ex   string
	Desc string
}

Example records a sample usage and a description for the "Examples" section of the help message

type FinalCheckFunc 

type FinalCheckFunc func() error

FinalCheckFunc is the type of a function to be called after all the parameters have been set

type Group 

type Group struct {
	Name        string
	Desc        string
	Params      []*ByName
	HiddenCount int
	ConfigFiles []ConfigFileDetails
	// contains filtered or unexported fields
}

Group holds details about a group of parameters

func (Group) AllParamsHidden 

func (g Group) AllParamsHidden() bool

AllParamsHidden returns true if all the parameters are marked as not to be shown in the standard usage message, false otherwise

func (*Group) SetHiddenCount 

func (g *Group) SetHiddenCount() int

SetHiddenCount counts how many params have the DontShowInStdUsage attribute set and records this in the HiddenCount field. It also returns the value

type Helper 

type Helper interface {
	ProcessArgs(ps *PSet)
	ErrorHandler(w io.Writer, name string, errMap ErrMap)
	Help(ps *PSet, messages ...string)
	AddParams(ps *PSet)
}

Helper is the interface that a helper object must implement. It should supply a set of default parameters to be added by the AddParams func and a func (called ProcessArgs) to be called after the parsing is complete which will operate on the default parameter values. There should be a Help func for reporting a help message and an error handler for reporting errors.

type NilAVM 

type NilAVM struct{}

NilAVM is a mixin type that can be embedded in a Setter to provide a default implementation for the AllowedValuesMap method of the interface

func (NilAVM) AllowedValuesMap 

func (_ NilAVM) AllowedValuesMap() AValMap

AllowedValuesMap returns a nil map of allowed values - unless your setter has a map of allowed values you should probably use this

type NullRemHandler 

type NullRemHandler struct{}

NullRemHandler is a type which can be set as a remainder handler if you wish to perform the remainder handling yourself after the parsing is complete.

func (NullRemHandler) HandleRemainder 

func (rh NullRemHandler) HandleRemainder(ps *PSet, loc *location.L)

HandleRemainder does nothing, specifically it doesn't call the helper's ErrorHandler (which by default will terminate the program). If you set this as the RemHandler for the PSet then you will have to handle the remaining arguments after the program has been called by calling the Remainder method on the PSet.

type OptFunc 

type OptFunc func(p *ByName) error

OptFunc is the type of a option func used to set various flags etc on a parameter.

func AltName 

func AltName(altName string) OptFunc

AltName will attach an alternative name to the parameter. It will return an error if the alternative name has already been used

func Attrs 

func Attrs(attrs Attributes) OptFunc

Attrs returns an OptFunc which will set the attributes of the parameter to the passed value.

func GroupName 

func GroupName(name string) OptFunc

GroupName will set the parameter group name for the parameter. The group name is stripped of any leading or trailing white space and it is checked for validity; an error is returned if it is not valid. A parameter group can be used to collect related parameters together, this grouping will be reflected when the usage message is displayed

func PostAction 

func PostAction(action ActionFunc) OptFunc

PostAction will return an option function which will add an action function to the list of functions to be called after the value has been set.

type PSet 

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

PSet represents a collection of parameters to be parsed together. A program will typically only have one PSet but having this makes it easier to retain control. You would create the PSet in main using the paramset.New func which will automatically set the standard help member. This lets you know precisely which parameters have been enabled before calling Parse

func NewSet 

func NewSet(psof ...PSetOptFunc) (*PSet, error)

NewSet creates a new PSet with the various maps and slices initialised. Generally you would be better off creating a PSet through the paramset.New function which will automatically set the default helper

func (*PSet) Add 

func (ps *PSet) Add(name string,
	setter Setter,
	desc string,
	opts ...OptFunc) *ByName

Add will add a new named parameter to the set that will be recognised. The setter defines the function that should be performed when the parameter is processed and will typically be a parameter setter from the psetter package that will set the value of an associated variable.

Any leading or trailing spaces are silently removed. Add will panic if the parameter has already been used. Add will also panic if the name doesn't start with a letter or if it contains any other character than a letter, a digit or a dash.

Various other features of the parameter can be set by the OptFuncs which may be passed after the description.

Example

ExamplePSet_Add shows the usage of the Add method of the PSet. This is used to add new parameters into the set. 

package main

import (
	"fmt"

	"github.com/nickwells/param.mod/v3/param"
	"github.com/nickwells/param.mod/v3/param/paramset"
	"github.com/nickwells/param.mod/v3/param/psetter"
)

func main() {
	ps, _ := paramset.New()

	// we declare f here for the purposes of the example but typically it
	// would be declared in package scope somewhere or in the main() func
	var f float64

	p := ps.Add(
		"param-name",
		psetter.Float64{Value: &f},
		"a parameter description",
		param.GroupName("test.group"),
		param.Attrs(param.DontShowInStdUsage))

	fmt.Printf("%3.1f\n", f)
	fmt.Printf("group name: %s\n", p.GroupName())
	fmt.Printf("param name: %s\n", p.Name())
	fmt.Printf("CommandLineOnly: %t\n", p.AttrIsSet(param.CommandLineOnly))
	fmt.Printf("MustBeSet: %t\n", p.AttrIsSet(param.MustBeSet))
	fmt.Printf("SetOnlyOnce: %t\n", p.AttrIsSet(param.SetOnlyOnce))
	fmt.Printf("DontShowInStdUsage: %t\n", p.AttrIsSet(param.DontShowInStdUsage))

}

Output:

0.0
group name: test.group
param name: param-name
CommandLineOnly: false
MustBeSet: false
SetOnlyOnce: false
DontShowInStdUsage: true

func (*PSet) AddByPos 

func (ps *PSet) AddByPos(name string,
	setter Setter,
	desc string,
	opts ...PosOptFunc) *ByPos

AddByPos will add a new positional parameter to the set of parameters. The setter defines the function that should be performed when the parameter is processed and will typically be a parameter setter from the paramSetter package that will set the value of an associated variable

Various other features of the parameter can be set by the OptFuncs which may be passed after the description.

Unlike with the ByName parameter the name given here is purely for documentation purposes and should be a very short value just used as a hint at the intended purpose. The name should be expanded and explained by the description.

func (*PSet) AddConfigFile 

func (ps *PSet) AddConfigFile(fName string, c filecheck.Exists)

AddConfigFile adds an additional config file which will also be checked for existence and read from. Files are processed in the order they are added.

This can be used to set a system-wide config file and a per-user config file that can be used to provide personal preferences.

func (*PSet) AddConfigFileStrict added in v3.1.0 

func (ps *PSet) AddConfigFileStrict(fName string, c filecheck.Exists)

AddConfigFileStrict behaves as for AddConfigFile except that parameters given in the file must exist for the given program. This is suitable for program-specific config files where it can be expected that any parameter given in the config file will exist and so it should be reported as an error if it does not.

func (*PSet) AddEnvPrefix 

func (ps *PSet) AddEnvPrefix(prefix string)

AddEnvPrefix adds a new prefix to the list of environment variable prefixes. If the new prefix is empty or a substring of any of the existing prefixes or vice versa then it panics

func (*PSet) AddExample added in v3.5.0 

func (ps *PSet) AddExample(ex, desc string)

AddExample adds an example to the set of examples on the PSet. Note that there is no validation of the given example

func (*PSet) AddFinalCheck 

func (ps *PSet) AddFinalCheck(fcf FinalCheckFunc)

AddFinalCheck will add a function to the list of functions to be called after all the parameters have been set. Note that multiple functions can be set and they will be called in the order that they are added. Each function should return an error (or nil) to be added to the list of errors detected. All the checks will be called even if one of them returns an error

func (*PSet) AddGroup 

func (ps *PSet) AddGroup(name, desc string)

AddGroup will add a new param group to the PSet and set the descriptive text. It will panic if the description has already been set - this is to ensure that the group name is distinct. This description is shown when the usage message is printed. If the short-form description is chosen then the group name is shown instead so it's worth making it a useful value.

A suggested standard for group names is to have parameters specific to a command in a group called 'cmd'. This is the default group name if none is set explicitly.

Or for parameters specific to a package to use the package name prefixed with 

'pkg.'

for instance: 'pkg.param'

If you have several groups for the same package or command then you can add an additional suffix after a separating dash.

for instance: 'cmd-formatting' or 'pkg.param-help'

The group name will have any leading and trailing spaces deleted before use.

func (*PSet) AddGroupConfigFile 

func (ps *PSet) AddGroupConfigFile(gName, fName string, c filecheck.Exists)

AddGroupConfigFile adds an additional config file for the named group.

func (*PSet) AddReference added in v3.5.0 

func (ps *PSet) AddReference(name, desc string)

AddReference adds a reference to the set of references on the PSet

func (*PSet) AreSet 

func (ps *PSet) AreSet() bool

AreSet will return true if Parse has been called or false otherwise

func (*PSet) ConfigFiles 

func (ps *PSet) ConfigFiles() []ConfigFileDetails

ConfigFiles returns a copy of the current config file details.

func (*PSet) ConfigFilesForGroup 

func (ps *PSet) ConfigFilesForGroup(gName string) []ConfigFileDetails

ConfigFilesForGroup returns a copy of the current config file details for the given group name.

func (*PSet) CountByPosParams 

func (ps *PSet) CountByPosParams() int

CountByPosParams will return the number of positional parameters

func (*PSet) EnvPrefixes 

func (ps *PSet) EnvPrefixes() []string

EnvPrefixes returns a copy of the current environment prefixes

func (*PSet) ErrWriter 

func (ps *PSet) ErrWriter() io.Writer

ErrWriter returns the current value of the ErrWriter to which error messages should be written

func (PSet) Errors 

func (ps PSet) Errors() ErrMap

Errors returns the map of errors for the param set

func (*PSet) Examples added in v3.5.0 

func (ps *PSet) Examples() []Example

Examples returns a copy of the current set of examples.

func (PSet) GetGroupByName added in v3.6.0 

func (ps PSet) GetGroupByName(name string) *Group

GetGroupByName returns a pointer to the details for the named Group. If the name is not recognised then the pointer will be nil

func (*PSet) GetGroupDesc 

func (ps *PSet) GetGroupDesc(grpName string) string

GetGroupDesc returns the description for the named group or the empty string if the group does not exist.

func (*PSet) GetGroups 

func (ps *PSet) GetGroups() []*Group

GetGroups returns a slice of Groups sorted by group name. Each Group element has a slice of ByName parameters and these are sorted by the primary parameter name.

func (*PSet) GetParamByName 

func (ps *PSet) GetParamByName(name string) (p *ByName, err error)

GetParamByName will return the named parameter if it can be found. The error will be set if not

func (*PSet) GetParamByPos 

func (ps *PSet) GetParamByPos(idx int) (p *ByPos, err error)

GetParamByPos will return the positional parameter if it exists. The error will be set if not.

func (PSet) HasAltSources added in v3.3.0 

func (ps PSet) HasAltSources() bool

HasAltSources returns true if there are any alternative sources (configuration files, either general or group-specific, or environment variable prefixes) false otherwise

func (PSet) HasEnvPrefixes added in v3.6.0 

func (ps PSet) HasEnvPrefixes() bool

HasEnvPrefixes returns true if there are any environment variable prefixes for this program, false otherwise

func (*PSet) HasExamples added in v3.5.0 

func (ps *PSet) HasExamples() bool

HasExamples returns true if the PSet has any entries in the set of examples

func (PSet) HasGlobalConfigFiles added in v3.6.0 

func (ps PSet) HasGlobalConfigFiles() bool

HasGlobalConfigFiles returns true if there are any non-group-specific config files for this program, false otherwise

func (*PSet) HasGroupName 

func (ps *PSet) HasGroupName(grpName string) bool

HasGroupName returns true if the PSet has a group with the given name, false otherwise

func (*PSet) HasReferences added in v3.5.0 

func (ps *PSet) HasReferences() bool

HasReferences returns true if the PSet has any references

func (*PSet) Help 

func (ps *PSet) Help(message ...string)

Help will call the helper's Help function

func (*PSet) Parse 

func (ps *PSet) Parse(args ...[]string) ErrMap

Parse will initialise the parameter values

It will first look in the configuration files (if any filenames have been set using the SetConfigFile function).

Next it will look in the environment (if any environment prefix strings have been set using the SetEnvPrefix function).

Lastly it will process the command line arguments.

It takes zero or more arguments each of which is a slice of strings. If no arguments are given then it uses the command line parameters (excluding the first which is used to set the program name). If any argument is passed then all the slices are concatenated together and that is parsed.

It will return a map of errors: parameter name to a non-empty slice of error messages. In order to make sensible use of this the report-errors and exit-on-errors flags should be turned off - there are functions which allow the caller to do this (or they can be set through the command-line flags) but they should be called before Parse is called. The default behaviour is to report any errors and exit. This means that you can sensibly ignore the return value unless you want to handle the errors yourself.

Finally it will process any remaining parameters - these are any parameters following a positional parameter that has been marked as terminal or any parameters following the terminal parameter (which is "--" by default). If no trailing arguments are expected and no handler has been set for handling them then the default handler is called which will record an error and call the helper.ErrorHandler method.

func (*PSet) ProgBaseName added in v3.6.0 

func (ps *PSet) ProgBaseName() string

ProgBaseName returns the base name of the program - the program name with any leading directories stripped off. Note that this should be called only after the arguments are already parsed - before that it will only give the default value

func (*PSet) ProgDesc 

func (ps *PSet) ProgDesc() string

ProgDesc returns the program description

func (*PSet) ProgName 

func (ps *PSet) ProgName() string

ProgName returns the name of the program - the value of the zeroth argument. Note that this should be called only after the arguments are already parsed - before that it will only give the default value

func (*PSet) References added in v3.5.0 

func (ps *PSet) References() []Reference

References returns a copy of the current set of references.

func (*PSet) Remainder 

func (ps *PSet) Remainder() []string

Remainder returns any arguments that come after the terminal parameter. Note this may be a nil slice if all the parameters have been processed.

func (*PSet) SetConfigFile 

func (ps *PSet) SetConfigFile(fName string, c filecheck.Exists)

SetConfigFile will set the list of config files from which to read parameter values to just the value given. If it is used with the AddConfigFile method below then it should be the first method called.

The config file name may start with ~/ to refer to the home directory of the user.

The config file should contain parameter names and values separated by an equals sign. Any surrounding space around the parameter name and value are stripped off. For instance the following lines will have the same effect of setting the value of the myParam attribute to 42: 

myParam  = 42
myParam=42

The parameter name can be preceded by a comma-separated list of program names and a slash in which case the parameter will only be applied when the config file is being parsed by one of the listed programs. The match is applied to the basename of the program (the part after the last pathname separator). This is particularly useful if there is a config file which is shared amongst a number of different programs. It could also be used to give different default behaviour when a given program has several different names (one binary with different names linked to it). As for the parameter name and value any surrounding whitespace is stripped from the program name before comparison. For instance: 

myProg/myProgParam = 99

Parameters which don't take a value should appear on a line on their own, without an equals character following. As with parameters which take a value any surrounding white space is removed and ignored.

Since a parameter file might be shared between several programs, a parameter in a config file which is not found in the set of parameters for that program is not reported as an error as it might be targeted at a different program. This is not the case for parameters which are marked as being for specific programs by having a list of program names before the parameter name. Similarly for parameters in files which are for a particular parameter group, the parameter must be recognised or else it is reported as an error.

The config file supports the features of a file parsed by the fileparse.FP such as comments and include files.

func (*PSet) SetConfigFileStrict added in v3.1.0 

func (ps *PSet) SetConfigFileStrict(fName string, c filecheck.Exists)

SetConfigFileStrict behaves as for SetConfigFile except that parameters given in the file must exist for the given program. This is suitable for program-specific config files where it can be expected that any parameter given in the config file will exist and so it should be reported as an error if it does not.

func (*PSet) SetEnvPrefix 

func (ps *PSet) SetEnvPrefix(prefix string)

SetEnvPrefix will set the prefix for environment variables that are to be considered as potential parameters. This prefix is stripped from the name and any underscores are replaced with dashes before the environment variable name is passed on for matching against parameters

func (*PSet) SetGroupConfigFile 

func (ps *PSet) SetGroupConfigFile(gName, fName string, c filecheck.Exists)

SetGroupConfigFile sets the config file for the named group. Group config files have several constraints: the parameters in the file must only be for the named group and it is an error if any parameter in the file is not recognised.

Additionally, the param group must already exist.

func (*PSet) SetGroupDescription deprecated 

func (ps *PSet) SetGroupDescription(name, desc string)

SetGroupDescription will call AddGroup

Deprecated: use AddGroup

func (*PSet) SetNamedRemHandler added in v3.4.0 

func (ps *PSet) SetNamedRemHandler(rh RemHandler, name string) error

SetNamedRemHandler calls SetRemHandler to set the remainder handler and if that succeeds it will set the text to be used for the remaining arguments. This name will be used in the help message

func (*PSet) SetProgramDescription 

func (ps *PSet) SetProgramDescription(desc string)

SetProgramDescription sets the program description

func (*PSet) SetRemHandler 

func (ps *PSet) SetRemHandler(rh RemHandler) error

SetRemHandler sets the value of the remainder handler to be used by the parameter set. Note that the handler must be set and so you cannot pass nil. The default behaviour is for an error to be reported if there are any unprocessed parameters. If you expect additional arguments after either a terminal positional parameter or after an explicit end-of-parameters parameter (by default '--') then you have two choices. You can set the remainder handler to the NullRemHandler and process the remainder yourself in the body of the program. Alternatively you can pass a RemHandler that will handle the remainder in the Parse method.

func (*PSet) SetTerminalParam 

func (ps *PSet) SetTerminalParam(s string)

SetTerminalParam sets the value of the parameter that is used to terminate the processing of parameters. This can be used to override the default value which is set to DfltTerminalParam

func (*PSet) StdWriter 

func (ps *PSet) StdWriter() io.Writer

StdWriter returns the current value of the StdWriter to which standard messages should be written

func (*PSet) TerminalParam 

func (ps *PSet) TerminalParam() string

TerminalParam will return the current value of the terminal parameter.

func (*PSet) TrailingParamsExpected added in v3.4.0 

func (ps *PSet) TrailingParamsExpected() bool

TrailingParamsExpected returns true if a remainder handler has been set successfully and false otherwise

func (*PSet) TrailingParamsName added in v3.4.0 

func (ps *PSet) TrailingParamsName() string

TrailingParamsName returns the name that has been given to the trailing parameters (if any)

func (*PSet) UnusedParams 

func (ps *PSet) UnusedParams() map[string][]string

UnusedParams returns a copy of the map of unused parameter names. The map associates a parameter name with a slice of strings which records where the parameter has been set. Unused parameters are always from config files or environment variables; unrecognised parameters given on the command line are reported as errors.

type PSetOptFunc 

type PSetOptFunc func(ps *PSet) error

PSetOptFunc is the type of a function that can be passed to NewSet. These functions can be used to set optional behaviour on the parameter set.

func SetErrWriter 

func SetErrWriter(w io.Writer) PSetOptFunc

SetErrWriter returns a PSetOptFunc which can be passed to NewSet. It sets the Writer to which error messages are written

func SetHelper 

func SetHelper(h Helper) PSetOptFunc

SetHelper returns a PSetOptFunc which can be passed to NewSet. This sets the value of the helper to be used by the parameter set and adds the parameters that the helper needs. Note that the helper must be set and so you must pass some such function. To avoid lots of duplicate code there are sensible defaults which can be used in the param/paramset package.

This can only be set once and this will return an error if the helper has already been set

func SetProgramDescription 

func SetProgramDescription(desc string) PSetOptFunc

SetProgramDescription returns a PSetOptFunc which can be passed to NewSet. It will set the program description

func SetStdWriter 

func SetStdWriter(w io.Writer) PSetOptFunc

SetStdWriter returns a PSetOptFunc which can be passed to NewSet. It sets the Writer to which standard messages are written

type PosOptFunc 

type PosOptFunc func(bp *ByPos) error

PosOptFunc is the type of a option func used to set various flags on a positional parameter

type Reference added in v3.5.0 

type Reference struct {
	Name string
	Desc string
}

Reference records a name and a description for the "See Also" section of the help message

type RemHandler 

type RemHandler interface {
	HandleRemainder(ps *PSet, loc *location.L)
}

RemHandler describes how the remaining parameters should be handled. These are the parameters that remain after either a terminal positional parameter or else a terminal parameter (by default this is "--")

The HandleRemainder func is for specifying how to handle any remaining arguments after the standard parsing has been completed. It takes as an argument the PSet on which Parse has been called. The remaining parameters can be retrieved for further processing through the Remainder method on that PSet. The second argument to HandleRemainder is the location that the previous parser reached in the parameters it had been passed.

A typical way of using this mechanism might be to select a new pre-created PSet (or create a new one on the fly) based on the settings of any previous parameters by the previous Parse call. Then Parse can be called on the new PSet passing the remaining arguments given by the Remainder method on the original PSet. This would be a typical use case where a terminal positional parameter has been used; several common commands such as git and go itself use a similar style of command invocation.

In the case where a terminal parameter is given and there is a following list of parameters it is more likely that the extra parameters are not intended as flags to control the operation of the program. In this case the remaining parameters might be taken as a list of values to be processed and a different HandleRemainder function would be appropriate.

type Setter 

type Setter interface {
	Set(string) error
	SetWithVal(string, string) error
	ValueReq() ValueReq
	AllowedValues() string
	AllowedValuesMap() AValMap
	CurrentValue() string
	CheckSetter(name string)
}

Setter is the interface that wraps the necessary methods for a paramSetter

Each paramSetter must implement these methods

Set takes the name of the parameter and no value. If the value requirements are such that an argument is not needed then this can set the value or do whatever the paramSetter is supposed to do. Otherwise it should return an error.

SetWithVal takes the name of the parameter and the associated value. If the value requirements are such that an argument is needed or is optional then this can set the value or do whatever the paramSetter is supposed to do. Otherwise it should return an error.

ValueReq returns the ValueReq for the parameter: one of Mandatory, Optional or None.

AllowedValues returns a string documenting the parameters that a parameter value can take. A function generating a help message should call both this and the AllowedValuesMap method and ignore any nil map returned.

AllowedValuesMap returns a map of allowed values to descriptions. This will return nil if the parameter does not have an associated map of values. A function generating a help message should call both this and the AllowedValues method and ignore any nil map returned.

CurrentValue returns a string showing the current value of the parameter. It is called before any arguments have been parsed in order to get the initial value for use in help messages.

CheckSetter is called to ensure that the setter has been correctly created, for instance that the pointer to the value is not nil or, if the pointer is to a map, that the map being pointed at has been created. Correct behaviour of this func would be to panic if the setter has not been properly set up.

When creating your own Setter implementation you may find it useful to use one of the ValueReq types as an embedded type.So, for instance, if your Setter must have a following value then you can embed the param.ValueReqMandatory struct in your struct and this will provide correct ValueReq and Set methods. Similarly if your Setter must not have a following value embed the param.ValueReqNone struct and it will provide correct ValueReq and SetWithVal methods. For examples of how this is done see any of the Setter instances in the psetter package.

Likewise the NilAVM type can be embedded in a Setter implementation and it will provide a default AllowedValuesMap method which will return a nil map.

type Source 

type Source struct {
	From      string
	Loc       location.L
	ParamVals []string
	Param     *ByName
}

Source records where a parameter has been set

func (Source) Desc 

func (pSrc Source) Desc() string

Desc describes where the param was set

func (Source) String 

func (pSrc Source) String() string

String formats a Source into a string

type Sources 

type Sources []Source

Sources is a slice of Source

func (Sources) String 

func (pSrcs Sources) String() string

String formats a slice of Sources into a String

type ValueReq 

type ValueReq int

ValueReq encodes whether or not a value is required after a parameter 

const (
	Mandatory ValueReq = iota
	Optional
	None
)

Mandatory means that a value must follow the parameter.

Optional means that a value may follow the parameter but need not in which case the default value will be used.

None means that a value must not follow the parameter.

func (ValueReq) String 

func (i ValueReq) String() string

type ValueReqMandatory 

type ValueReqMandatory struct{}

ValueReqMandatory is a mixin type that can be embedded in a Setter to provide suitable default values for a Setter where the parameter must have a value following it.

func (ValueReqMandatory) Set 

func (v ValueReqMandatory) Set(name string) error

Set returns an error because if the value is Mandatory then a value must follow the parameter for this setter

func (ValueReqMandatory) ValueReq 

func (v ValueReqMandatory) ValueReq() ValueReq

ValueReq returns the Mandatory value of the ValueReq type to indicate that a value must follow the parameter for this setter

type ValueReqNone 

type ValueReqNone struct{}

ValueReqNone is a mixin type that can be embedded in a Setter to provide suitable default values for a Setter where the parameter must not have a following value.

func (ValueReqNone) SetWithVal 

func (v ValueReqNone) SetWithVal(name, _ string) error

SetWithVal returns an error because if the value is None then a value must not follow the parameter for this setter

func (ValueReqNone) ValueReq 

func (v ValueReqNone) ValueReq() ValueReq

ValueReq returns the None value of the ValueReq type to indicate that a value must not follow the parameter for this setter

type ValueReqOptional 

type ValueReqOptional struct{}

ValueReqOptional is a mixin type that can be embedded in a Setter to provide suitable default values for a Setter where the following parameter is optional.

func (ValueReqOptional) ValueReq 

func (v ValueReqOptional) ValueReq() ValueReq

ValueReq returns the Optional value of the ValueReq type to indicate that a value must follow the parameter for this setter

Source Files

View all Source files

Directories

Path Synopsis
Package paction collects together useful action functions that can be applied to params.
 Package paction collects together useful action functions that can be applied to params.
Package paramset offers helper functions for creating a new param.PSet.
 Package paramset offers helper functions for creating a new param.PSet.
Package phelp provides the standard help parameter handling which includes printing the standard help message and any error reporting.
 Package phelp provides the standard help parameter handling which includes printing the standard help message and any error reporting.
Package psetter contains a collection of useful types that can be used to set parameter values of a program.
 Package psetter contains a collection of useful types that can be used to set parameter values of a program.

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.