paramset

Documentation

Overview

Package paramset offers helper functions for creating a new param.PSet. It is expected that you will use the

paramset.NewOrPanic(...)

function which will create a new param.PSet with the standard helper set up. Any errors detected while constructing the PSet will cause the program to panic, this is almost certainly what you want as they constitute coding errors. You would typically pass it a list of param.PSetOptFunc's which can be used, for instance, to add the params to the PSet.

The advantage of using the NewOrPanic method over using the NewOrDie method is that you can more easily write a test of your parameter setting code. You put all the code to generate the PSet in a single method and then call that in a panic-safe wrapper and test that it doesn't panic. This means that any param errors will be found during testing while still ensuring that the program will not run if they are somehow missed.

If you want to handle errors explicitly then the paramset.New(...) will return the constructed PSet and any errors.

Index

• func New(psof ...param.PSetOptFunc) (*param.PSet, error)
• func NewNoHelp(psof ...param.PSetOptFunc) (*param.PSet, error)
• func NewNoHelpNoExit(psof ...param.PSetOptFunc) (*param.PSet, error)
• func NewNoHelpNoExitNoErrRpt(psof ...param.PSetOptFunc) (*param.PSet, error)
• func NewNoHelpNoExitNoErrRptOrPanic(psof ...param.PSetOptFunc) *param.PSet
• func NewNoHelpNoExitOrPanic(psof ...param.PSetOptFunc) *param.PSet
• func NewOrDie(psof ...param.PSetOptFunc) *param.PSet
• func NewOrPanic(psof ...param.PSetOptFunc) *param.PSet

Examples

• NewOrPanic (Simple)

Functions

func New

func New(psof ...param.PSetOptFunc) (*param.PSet, error)

New creates a new PSet with the standard helper set. This is a suitable choice in most cases.

func NewNoHelp

func NewNoHelp(psof ...param.PSetOptFunc) (*param.PSet, error)

NewNoHelp creates a new PSet with the helper set to the noHelp helper which does nothing. In particular it will not add any parameters and so it returns a suitable parameter set for the case where you want to add positional parameters the last of which is terminal. This style of interface is used if you have a positional parameter which will invoke a different command based on the value - see the 'git' or 'go' commands for examples of this CLI interface style. If you are choosing an interface like this you might want to consider having one of the possible parameter values being "help" so that the available options can be listed.

If errors are detected then they will be reported and the program will exit.

func NewNoHelpNoExit

func NewNoHelpNoExit(psof ...param.PSetOptFunc) (*param.PSet, error)

NewNoHelpNoExit returns a paramset and any errors encountered while creating it. It adds no parameters and doesn't provide a Usage message. It does report errors but doesn't exit if Parse errors are seen.

This is only likely to be of any use for testing purposes

func NewNoHelpNoExitNoErrRpt

func NewNoHelpNoExitNoErrRpt(psof ...param.PSetOptFunc) (*param.PSet, error)

NewNoHelpNoExitNoErrRpt returns a paramset and any errors encountered while creating it. It adds no parameters and doesn't provide a Usage message. It doesn't report errors and doesn't exit if Parse errors are seen.

This is only likely to be of any use for testing purposes

func NewNoHelpNoExitNoErrRptOrPanic

func NewNoHelpNoExitNoErrRptOrPanic(psof ...param.PSetOptFunc) *param.PSet

NewNoHelpNoExitNoErrRptOrPanic returns a paramset as per NewNoHelpNoExitNoErrRpt but any error will cause the program to panic.

This is only likely to be of any use for testing purposes

func NewNoHelpNoExitOrPanic

func NewNoHelpNoExitOrPanic(psof ...param.PSetOptFunc) *param.PSet

NewNoHelpNoExitOrPanic returns a paramset as per NewNoHelpNoExit but any error will cause the program to panic.

This is only likely to be of any use for testing purposes

func NewOrDie

func NewOrDie(psof ...param.PSetOptFunc) *param.PSet

NewOrDie creates a new PSet with the standard helper set. It then checks the error returned and if it is not nil it will report the error on stderr and exit with a non-zero exit status. This is a suitable choice unless you want to perform any special error handling.

func NewOrPanic

func NewOrPanic(psof ...param.PSetOptFunc) *param.PSet

NewOrPanic creates a new PSet with the standard helper set. It then checks the error returned and if it is not nil it will panic with the returned error wrapped in an explanatory message. This is a suitable choice if you want to test the parameter generation and still have a simple API in your program.

Example (Simple)

package main

import (
	"github.com/nickwells/check.mod/v2/check"
	"github.com/nickwells/param.mod/v6/param"
	"github.com/nickwells/param.mod/v6/paramset"
	"github.com/nickwells/param.mod/v6/psetter"
)

var (
	thingName string
	action    = "nothing"
)

// addParams will add parameters to the passed ParamSet
func addParams(ps *param.PSet) error {
	// This adds a parameter to the PSet that can be given with either of two
	// names: '-name' or '-n'. The parameter parsing will report an error if
	// the parameter is not given or if the value given is an empty string
	ps.Add("name", psetter.String[string]{
		Value:  &thingName,
		Checks: []check.String{check.StringLength[string](check.ValGT(0))},
	},
		"set the name of the thing to do that other thing to",
		param.AltNames("n"),
		param.Attrs(param.CommandLineOnly|param.MustBeSet),
	)

	// This adds another parameter to the PSet. This can be given with either
	// of '-action' or '-a'. The value given must be one of the allowed
	// values: 'delete', 'copy' or 'nothing'. An error will be reported if
	// the parameter is not seen
	ps.Add("action",
		psetter.Enum[string]{
			Value: &action,
			AllowedVals: psetter.AllowedVals[string]{
				"delete":  "delete the thing",
				"copy":    "copy the thing",
				"nothing": "do nothing",
			},
		},
		"give the action to perform on the thing",
		param.AltNames("a"),
		param.Attrs(param.MustBeSet),
	)

	return nil
}

func main() {
	ps := paramset.NewOrPanic(addParams,
		param.SetProgramDescription(
			"a description of the purpose of the program"))
	ps.Parse()

	// the rest of your program goes here
}