param

package
v2.3.0 Latest Latest
Warning

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

 Go to latest Published: May 19, 2019 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 New 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.New 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.

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 valuu. 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.

Example (SetByFunc)

Example_setByFunc shows how to use the param package with param setting functions passed to the paramset.New method. These set the same parameters as in the setDirectly example. Because the parameters being set are external to the Example function we have defined them outside the function so that they are visible to the AddParams... funcs. 

package main

import (
	"fmt"

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

func main() {
	ValExample1 = false
	ValExample2 = 0

	ps, _ := paramset.New(
		AddParams1,
		AddParams2,
		param.SetProgramDescription("what this program does"))

	fmt.Println("example1:", ValExample1)
	fmt.Println("example2:", ValExample2)
	// 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
		},
		[]string{
			"-example2", "3", // this parameter expects a following value
		},
	)
	fmt.Println("example1:", ValExample1)
	fmt.Println("example2:", ValExample2)

}

const exampleGroupName = "groupname"

var ValExample1 bool
var ValExample2 int64

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

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

	return nil
}

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

	return nil
}

Output:

example1: false
example2: 0
example1: true
example2: 3
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 setByFunc 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/v2/param"
	"github.com/nickwells/param.mod/v2/param/paramset"
	"github.com/nickwells/param.mod/v2/param/psetter"
)

func main() {
	var example1 bool
	var example2 int64

	ps, _ := paramset.New()
	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/v2/param"
	"github.com/nickwells/param.mod/v2/param/paramset"
	"github.com/nickwells/param.mod/v2/param/psetter"
)

func main() {
	ps, _ := paramset.New(
		AddParams1,
		AddParams2,
		param.SetProgramDescription("what this program does"))
	ps.Parse()
}

const exampleGroupName = "groupname"

var ValExample1 bool
var ValExample2 int64

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

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

	return nil
}

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

	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/v2/param"
	"github.com/nickwells/param.mod/v2/param/paramset"
	"github.com/nickwells/param.mod/v2/param/psetter"
)

func main() {
	ValExample1 = false
	ValExample2 = 0

	ps, _ := paramset.New(
		AddParams1,
		AddParams2,
		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:", ValExample1)
	fmt.Println("example2:", ValExample2)
	// 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..
	ps.Parse([]string{})
	fmt.Println("example1:", ValExample1)
	fmt.Println("example2:", ValExample2)

}

const exampleGroupName = "groupname"

var ValExample1 bool
var ValExample2 int64

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

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

	return nil
}

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

	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 added in v2.2.0 

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

ConfigFileActionFunc can be called as an action func and will take the second entry in the paramValues (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 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 ActionFunc 

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

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

source is the descriptive name for the set of values from which the parameter has been set such as "command line".

loc gives more detail on where the param was seen.

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
	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)
	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) 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) 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) 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) 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
}

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

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

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/v2/param"
	"github.com/nickwells/param.mod/v2/param/paramset"
	"github.com/nickwells/param.mod/v2/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) 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) 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) 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 added in v2.1.0 

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

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 program name and a slash in which case the parameter will only be applied when the config file is being parsed by that program. 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 a specific program by having the program name 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) 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) 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) 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 behavioiur 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 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
	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

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.

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(_ 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(_, _ 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.