env

package module
v0.0.0-...-3a91f46 Latest Latest
Warning

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

 Go to latest Published: Nov 23, 2024 License: BSD-3-Clause Imports: 11 Imported by: 0

README

env

This is a copy of the flag package adapted to work with environment variables.

Use this package to:

  • Define different environment variables, their default value, and description.
  • Define different environments, e.g. one set of environment variables for each subcommand.
  • Get a description of the environment variables defined using the -h/--help command line flag parsing behavior.
  • Get a description of the environment variables defined by setting HELP or H.
  • Add support for your types to be used as environment variables.

Documentation

Overview

TODO(edoput): top-level Usage function missing TODO(edoput): boolValue: IsBoolVar can be removed?

Index

Constants

This section is empty.

Variables

View Source 
var Environment = NewEnvSet(os.Args[0], ExitOnError)

Environment is the default set of environment values, parsed from os.GetEnv. The top-leve functions such as BoolVar, Bool, and so on are wrappers for the methods of Environment.

View Source 
var ErrHelp = errors.New("env: help requested")

ErrHelp is the error returned if the HELP or H environment variable is set but no such variable is defined.

Functions

func Bool 

func Bool(name string, value bool, description string) *bool

Bool defines a bool environment variable with specified name, default value, and description string. The return value is the address of a bool variable that stores the value of the environment variable.

func BoolFunc 

func BoolFunc(name, description string, fn func(string) error)

BoolFunc defines an environment variable with the specified name and description string without requiring values. Each time the variable name is seen, fn is called with the associated value. If fn returns a non-nil error, it will be treated as a parsing error.

func BoolVar 

func BoolVar(p *bool, name string, value bool, description string)

BoolVar defines a bool environment variable with specified name, default value, and description string. The argument p points to a bool variable in which to store the value of the environment variable.

func Duration 

func Duration(name string, value time.Duration, description string) *time.Duration

Duration defines a time.Duration environment variable with specified name, default value, and description string. The return value is the address of a time.Duration variable that stores the value of the variable. The environment variable accepts a value acceptable to time.ParseDuration.

func DurationVar 

func DurationVar(p *time.Duration, name string, value time.Duration, description string)

DurationVar defines a time.Duration environment variable with specified name, default value, and description string. The argument p points to a time.Duration variable in which to store the value of the variable. The environment variable accepts a value acceptable to time.ParseDuration.

func Float64 

func Float64(name string, value float64, description string) *float64

Float64 defines a float64 environment variable with specified name, default value, and description string. The return value is the address of a float64 variable that stores the value of the variable.

func Float64Var 

func Float64Var(p *float64, name string, value float64, description string)

Float64Var defines a float64 environment variable with specified name, default value, and description string. The argument p points to a float64 variable in which to store the value of the variable.

func Func 

func Func(name, description string, fn func(string) error)

Func defines an environment variable with the specified name and description string. Each time the variable name is seen, fn is called with the associated value. If fn returns a non-nil error, it will be treated as a parsing error.

func Int 

func Int(name string, value int, description string) *int

Int defines an int environment variable with specified name, default value, and description string. The return value is the address of an int variable that stores the value of the variable.

func Int64 

func Int64(name string, value int64, description string) *int64

Int64 defines an int64 environment variable with specified name, default value, and description string. The return value is the address of an int64 variable that stores the value of the variable.

func Int64Var 

func Int64Var(p *int64, name string, value int64, description string)

Int64Var defines an int64 environment variable with specified name, default value, and description string. The argument p points to an int64 variable in which to store the value of the variable.

func IntVar 

func IntVar(p *int, name string, value int, description string)

IntVar defines an int environment variable with specified name, default value, and description string. The argument p points to an int variable in which to store the value of the variable. 

func Link(f *flag.FlagSet, e *EnvSet)

Link associates EnvSet e to FlagSet f. Error messages when parsing command line flags will also print out the description of the environment variables expected.

func Parse 

func Parse()

Parse parses the environment values from os.Environ. Must be called after all variables are defined and before variables are accessed by the program.

func PrintDefaults 

func PrintDefaults()

PrintDefaults print, to standard error, unless configured otherwise, the default values of all defined environment variables. For an integer valued variable x, the default output has the form

x int 

description-message-for-x (default: 7)

The description message will appear on a separate line. The parenthetical default is omitted if the default is the zero value for the type. The listed type, here int, can be changed by placing a back-quoted name in the variable's description string; the first such item in the message is taken to be a parameter name to show in the message and the back quotes are stripped from the message when displayed. For instance, given 

env.String("I", "", "search `directory` for include files")

the output will be

I directory 

search directory for include files.

To change the destination for variable messages, call Environment.SetOutput.

func String 

func String(name string, value string, description string) *string

String defines a string environment variable with specified name, default value, and description string. The return value is the address of a string variable that stores the value of the variable.

func StringVar 

func StringVar(p *string, name string, value string, description string)

StringVar defines a string environment variable with specified name, default value, and description string. The argument p points to a string variable in which to store the value of the variable.

func TextVar 

func TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextUnmarshaler, description string)

TextVar defines an environment variable with a specified name, default value, and description string. The argument p must be a pointer to a variable that will hold the value of the variable, and p must implement encoding.TextUnmarshaler. If the environment variable is used, the environment variable's value will be passed to p's UnmarshalText method. The type of the default value must be the same as the type of p.

func Uint 

func Uint(name string, value uint, description string) *uint

Uint defines a uint environment variable with specified name, default value, and description string. The return value is the address of a uint variable that stores the value of the variable.

func Uint64 

func Uint64(name string, value uint64, description string) *uint64

Uint64 defines a uint64 environment variable with specified name, default value, and description string. The return value is the address of a uint64 variable that stores the value of the variable.

func Uint64Var 

func Uint64Var(p *uint64, name string, value uint64, description string)

Uint64Var defines a uint64 environment variable with specified name, default value, and description string. The argument p points to a uint64 variable in which to store the value of the variable.

func UintVar 

func UintVar(p *uint, name string, value uint, description string)

UintVar defines a uint environment variable with specified name, default value, and description string. The argument p points to a uint variable in which to store the value of the variable.

func UnquoteUsage 

func UnquoteUsage(spec *Spec) (name string, description string)

UnquoteUsage extracts a back-quoted name from the usage string for an environment variable and returns it and the un-quoted usage. Given "a `name` to show" it returns ("name", "a name to show"). If there are no back quotes, the name is an educated guess of the type of the variables's value.

func Var 

func Var(value Value, name string, description string)

Var defines an environment variable with the specified name and description string. The type and value of the variable are represented by the first argument, of type Value, which typically holds a user-defined implementation of Value. For instance, the caller could create an environment variable that turns a comma-separated string into a slice of strings by giving the slice the methods of Value; in particular, [Set] would decompose the comma-separated string into the slice.

func Visit 

func Visit(fn func(*Spec))

Visit visits the variables in lexicographical order, calling fn for each. It visits only those that have been set.

func VisitAll 

func VisitAll(fn func(*Spec))

VisitAll visits the variables in lexicographical order, calling fn for each. It visits all, even those not set.

Types

type EnvSet 

type EnvSet struct {
	// Usage is the function called when an error occur while parsing environment variables.
	// The field is a function (not a method) that may be changed to point to a
	// custom error handler. What happens after Usage is called depends on the
	// ErrorHandling setting; this defaults to ExitOnError, which exits the program
	// after calling Usage.
	Usage func()
	// contains filtered or unexported fields
}

A EnvSet represents a set of defined environment variables. The zero value of a EnvSet has no name.

Var name must be unique within an EnvSet. An attempt to define a variable whose name is already in use will cause a panic.

func NewEnvSet 

func NewEnvSet(name string, errorHandling ErrorHandling) *EnvSet

NewEnvSet returns a new, empty environment variables set with the specified name and error handling property. If the name is not empty, it will be printed in the default message and in error messages.

func (*EnvSet) Bool 

func (e *EnvSet) Bool(name string, value bool, description string) *bool

Bool defines a bool environment variable with specified name, default value, and description string. The return value is the address of a bool variable that stores the value of the environment variable.

func (*EnvSet) BoolFunc 

func (e *EnvSet) BoolFunc(name, description string, fn func(string) error)

BoolFunc defines an environment variable with the specified name and description string without requiring values. Each time the variable name is seen, fn is called with the associated value. If fn returns a non-nil error, it will be treated as a parsing error.

func (*EnvSet) BoolVar 

func (e *EnvSet) BoolVar(p *bool, name string, value bool, description string)

BoolVar defines a bool environment variable with specified name, default value, and description string. The argument p points to a bool variable in which to store the value of the environment variable.

func (*EnvSet) Duration 

func (e *EnvSet) Duration(name string, value time.Duration, description string) *time.Duration

Duration defines a time.Duration environment variable with specified name, default value, and description string. The return value is the address of a time.Duration variable that stores the value of the variable. The environment variable accepts a value acceptable to time.ParseDuration.

func (*EnvSet) DurationVar 

func (e *EnvSet) DurationVar(p *time.Duration, name string, value time.Duration, description string)

DurationVar defines a time.Duration environment variable with specified name, default value, and description string. The argument p points to a time.Duration variable in which to store the value of the variable. The environment variable accepts a value acceptable to time.ParseDuration.

func (*EnvSet) ErrorHandling 

func (e *EnvSet) ErrorHandling() ErrorHandling

ErrorHandling returns the error handling behavior of the variable set.

func (*EnvSet) Float64 

func (e *EnvSet) Float64(name string, value float64, description string) *float64

Float64 defines a float64 environment variable with specified name, default value, and description string. The return value is the address of a float64 variable that stores the value of the variable.

func (*EnvSet) Float64Var 

func (e *EnvSet) Float64Var(p *float64, name string, value float64, description string)

Float64Var defines a float64 environment variable with specified name, default value, and description string. The argument p points to a float64 variable in which to store the value of the variable.

func (*EnvSet) Func 

func (e *EnvSet) Func(name, description string, fn func(string) error)

Func defines an environment variable with the specified name and description string. Each time the variable name is seen, fn is called with the associated value. If fn returns a non-nil error, it will be treated as a parsing error.

func (*EnvSet) Init 

func (e *EnvSet) Init(name string, errorHandling ErrorHandling)

Init sets the name and error handling property for an environment variable set. By default, the zero EnvSet uses an empty name and the ContinueOnError error handling policy.

func (*EnvSet) Int 

func (e *EnvSet) Int(name string, value int, description string) *int

Int defines an int environment variable with specified name, default value, and description string. The return value is the address of an int variable that stores the value of the variable.

func (*EnvSet) Int64 

func (e *EnvSet) Int64(name string, value int64, description string) *int64

Int64 defines an int64 environment variable with specified name, default value, and description string. The return value is the address of an int64 variable that stores the value of the variable.

func (*EnvSet) Int64Var 

func (e *EnvSet) Int64Var(p *int64, name string, value int64, description string)

Int64Var defines an int64 environment variable with specified name, default value, and description string. The argument p points to an int64 variable in which to store the value of the variable.

func (*EnvSet) IntVar 

func (e *EnvSet) IntVar(p *int, name string, value int, description string)

IntVar defines an int environment variable with specified name, default value, and description string. The argument p points to an int variable in which to store the value of the environment variable.

func (*EnvSet) Name 

func (e *EnvSet) Name() string

Name returns the name of the environment set.

func (*EnvSet) Output 

func (e *EnvSet) Output() io.Writer

Output returns the destination for description and errro messages. os.Stderr is returned if output was not set or was set to nil.

func (*EnvSet) Parse 

func (e *EnvSet) Parse(environment []string) error

Parse parses variables definitions from the environment list. Must be called after all variables in the EnvSet are defined and before the variables are accessed by the program. The return value will be ErrHelp if HELP or H were set but not defined.

func (*EnvSet) PrintDefaults 

func (e *EnvSet) PrintDefaults()

PrintDefaults print, to standard error unless configured otherwise, the default values of all defined environment variables in the set. See the documentation for the global function PrintDefaults for more information.

func (*EnvSet) SetOutput 

func (e *EnvSet) SetOutput(output io.Writer)

SetOutput sets the destination for usage and error messages. If output is nil, os.Stderr is used.

func (*EnvSet) String 

func (e *EnvSet) String(name string, value string, description string) *string

String defines a string environment variable with specified name, default value, and description string. The return value is the address of a string variable that stores the value of the variable.

func (*EnvSet) StringVar 

func (e *EnvSet) StringVar(p *string, name string, value string, description string)

StringVar defines a string environment variable with specified name, default value, and description string. The argument p points to a string variable in which to store the value of the variable.

func (*EnvSet) TextVar 

func (e *EnvSet) TextVar(p encoding.TextUnmarshaler, name string, value encoding.TextUnmarshaler, description string)

TextVar defines a environment variable with a specified name, default value, and description string. The argument p must be a pointer to a variable that will hold the value of the variable, and p must implement encoding.TextUnmarshaler. If the environment variable is used, the environment variable's value will be passed to p's UnmarshalText method. The type of the default value must be the same as the type of p.

func (*EnvSet) Uint 

func (e *EnvSet) Uint(name string, value uint, description string) *uint

Uint defines a uint environment variable with specified name, default value, and description string. The return value is the address of a uint variable that stores the value of the variable.

func (*EnvSet) Uint64 

func (e *EnvSet) Uint64(name string, value uint64, description string) *uint64

Uint64 defines a uint64 environment variable with specified name, default value, and description string. The return value is the address of a uint64 variable that stores the value of the variable.

func (*EnvSet) Uint64Var 

func (e *EnvSet) Uint64Var(p *uint64, name string, value uint64, description string)

Uint64Var defines a uint64 environment variable with specified name, default value, and description string. The argument p points to a uint64 variable in which to store the value of the variable.

func (*EnvSet) UintVar 

func (e *EnvSet) UintVar(p *uint, name string, value uint, description string)

UintVar defines a uint environment variable with specified name, default value, and description string. The argument p points to a uint variable in which to store the value of the variable.

func (*EnvSet) Var 

func (e *EnvSet) Var(value Value, name string, description string)

Var defines an environment variable with the specified name and description string. They type and value of the variable are represented by the first argument, of type Value, which typically holds a user-defined implementation of Value. For instance, the caller could create an environment variable that turns a comma-separated string into a slice of strings by giving the slice the methods of Value; in particular, [Set] would decompose the comma-separated string into the slice.

func (*EnvSet) Visit 

func (e *EnvSet) Visit(fn func(*Spec))

Visit visits the variables in lexicographical order, calling fn for each. It visits only those that have been set.

func (*EnvSet) VisitAll 

func (e *EnvSet) VisitAll(fn func(*Spec))

VisitAll visits the variables in lexicographical order, calling fn for each. It visits all, even those not set.

type ErrorHandling 

type ErrorHandling int

ErrorHandling defines how EnvSet.Parse behaves if the parse fails. 

const (
	ContinueOnError ErrorHandling = iota // returns a descriptive error
	ExitOnError                          // Call os.Exit(2)
	PanicOnError                         // Call panic with a descriptive error
)

These constants cause EnvSet.Parse to behave as described if the parse fails.

type Spec 

type Spec struct {
	Name        string // name as it appears in environment
	Description string // short description
	Value       Value  // value as set
	DefValue    string // default value (as text); for description message
}

A Spec represents the state of an environment variable.

type Value 

type Value interface {
	String() string
	Set(string) error
	Get() any
}

Value is the interface to the dynamic value stored in a Spec. (The default value is represented as a string.)

Set is called once, in declaration order, for each variable present. The env package may call the String method with a zero-valued receiver, such as a nil pointer.

Get allows the contents of Value to be retrieved.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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