Documentation
¶
Overview ¶
Package envvar implements utilities for processing environment variables. There are three representations of environment variables:
- []"key=value" # hard to get and set, used by standard Go packages
- map[key]value # simple to get and set, nicest syntax
- *envvar.Vars # simple to get and set, also tracks deltas
The slice form (1) is used by standard Go packages, presumably since it's similar to the underlying OS representation. The map form (2) is convenient to use, and has native Go map syntax. The Vars form (3) is also convenient to use, and tracks deltas when mutations are performed.
This package provides utilities to easily use and convert between the three representations.
Empty keys are invalid and silently skipped in operations over all representations.
Index ¶
- func AppendUniqueToken(value, separator, token string) string
- func CopyMap(from map[string]string) map[string]string
- func CopySlice(from []string) []string
- func FilterToken(tokens []string, target string) []string
- func JoinKeyValue(key, value string) string
- func JoinTokens(tokens []string, separator string) string
- func MapToSlice(from map[string]string) []string
- func MergeMaps(maps ...map[string]string) map[string]string
- func MergeSlices(slices ...[]string) []string
- func PrependUniqueToken(value, separator, token string) string
- func SliceToMap(from []string) map[string]string
- func SortByKey(vars []string)
- func SplitKeyValue(kv string) (string, string)
- func SplitTokens(value, separator string) []string
- func UniqueTokens(tokens []string) []string
- type Vars
- func (x *Vars) Base() map[string]string
- func (x *Vars) Contains(key string) bool
- func (x *Vars) Delete(keys ...string)
- func (x *Vars) Deltas() map[string]*string
- func (x *Vars) Get(key string) string
- func (x *Vars) GetTokens(key, separator string) []string
- func (x *Vars) Set(key, value string)
- func (x *Vars) SetTokens(key string, tokens []string, separator string)
- func (x *Vars) ToMap() map[string]string
- func (x *Vars) ToSlice() []string
- func (x *Vars) UpdateOS() error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendUniqueToken ¶
AppendUniqueToken appends token to value, which is separated by separator, and removes all empty and duplicate tokens. Returns a string where token only occurs once, and is last.
func CopySlice ¶
CopySlice returns a copy of from, with empty keys dropped, and ordered by key. If the same key appears more than once the last one "wins"; the value is set based on the last slice element containing that key.
func FilterToken ¶
FilterToken returns a new slice containing tokens that are not empty or match the target, and in the same relative order as the original slice.
func JoinKeyValue ¶
JoinKeyValue joins key and value into a single string "key=value".
func JoinTokens ¶
JoinTokens is like strings.Join(tokens, separator), but also filters out empty tokens.
func MapToSlice ¶
MapToSlice converts from the map to the slice representation. The returned slice is in sorted order.
func MergeMaps ¶
MergeMaps merges together maps, and returns a new map with the merged result. If the same key appears in more than one input map, the last one "wins"; the value is set based on the last map containing that key.
As a result of its semantics, MergeMaps called with a single map returns a copy of the map, with empty keys dropped.
func MergeSlices ¶
MergeSlices merges together slices, and returns a new slice with the merged result. If the same key appears more than once in a single input slice, or in more than one input slice, the last one "wins"; the value is set based on the last slice element in the last slice containing that key.
As a result of its semantics, MergeSlices called with a single slice returns a copy of the slice, with empty keys dropped.
func PrependUniqueToken ¶
PrependUniqueToken prepends token to value, which is separated by separator, removing all empty and duplicate tokens. Returns a string where token only occurs once, and is first.
func SliceToMap ¶
SliceToMap converts from the slice to the map representation. If the same key appears more than once, the last one "wins"; the value is set based on the last slice element containing that key.
func SortByKey ¶
func SortByKey(vars []string)
SortByKey sorts vars into ascending key order, where vars is expected to be in the []"key=value" slice representation.
func SplitKeyValue ¶
SplitKeyValue splits kv into its key and value components. The format of kv is "key=value"; the split is performed on the first '=' character.
func SplitTokens ¶
SplitTokens is like strings.Split(value, separator), but also filters out empty tokens. Thus SplitTokens("", ":") returns a nil slice, unlike strings.SplitTokens which returns a slice with a single empty string.
func UniqueTokens ¶
UniqueTokens returns a new slice containing tokens that are not empty or duplicated, and in the same relative order as the original slice.
Types ¶
type Vars ¶
type Vars struct {
// contains filtered or unexported fields
}
Vars is a mutable set of environment variables that tracks deltas.
Vars are initialized with a base environment, and may be mutated with calls to Set and SetTokens. The resulting environment is retrieved with calls to ToMap and ToSlice.
Mutations are tracked separately from the base environment; call Deltas to retrieve only the environment variables that have been changed.
The zero Vars has an empty environment, and supports all methods.
func VarsFromMap ¶
VarsFromMap returns a new Vars initialized from the given base map.
func VarsFromOS ¶
func VarsFromOS() *Vars
VarsFromOS returns a new Vars initialized from os.Environ.
func VarsFromSlice ¶
VarsFromSlice returns a new Vars initialized from the given base slice.
func (*Vars) Base ¶
Base returns a copy of the original base environment.
Mutating the returned map does not affect x.
func (*Vars) Delete ¶
Delete removes the given keys. Subsequent calls to Contains on each key will return false.
func (*Vars) Deltas ¶
Deltas returns the set of variables that have been mutated after initialization.
If the last mutation for key K was Set or SetTokens, map[K] contains a non-nil pointer to the last value that was set. If the last mutation for key K was Delete, map[K] contains a nil pointer.
Mutating the returned map does not affect x.
func (*Vars) Get ¶
Get returns the value associated with key. Returns "" if the key doesn't exist, or if the key has an empty value. Use Contains to test for existence.
func (*Vars) SetTokens ¶
SetTokens is a convenience that calls x.Set(key, JoinTokens(tokens, separator)).
func (*Vars) ToMap ¶
ToMap returns the map representation of the current set of variables.
Mutating the returned map does not affect x.
Source Files