env

Documentation

Index

• Variables
• func Bind[T BindConstraint](i T, key string) error
• func BindMultiple[T BindConstraint](bindings map[T]string) error
• func LookupNoEmpty(key string) (string, bool)
• type BindConstraint
• type ParseError
  • func (err ParseError) As(target any) bool
  • func (err ParseError) Error() string
  • func (err ParseError) Is(target error) bool
  • func (err ParseError) Unwrap() error

Examples

• Bind

Variables

var ErrParse = errors.New("failed to parse")

ErrParse is used in the ParseError type when checking error.Is to be able to identify the error responses from the bind functions.

var ErrUnsupportedType = errors.New("unsupported type")

ErrUnsupportedType is returned when an environment variable target to bind is not supported. For example a custom struct type.

Functions

func Bind

func Bind[T BindConstraint](i T, key string) error

Bind will take a value pointer and depending on its type will try to parse the environment variable, if set and not empty, using the appropriate parsing function.

If the environment variable is not set, is empty, or the function returns an error, the value of the target interface is left unchanged.

Returns an env.ParseError on parsing errors.

Returns a wrapped env.ErrUnsupportedType error if the type of the interface is not supported.

Returns a wrapped env.ErrNotAPointer error if the target interface is not a pointer.

Returns nil otherwise.

Example

package main

import (
	"errors"
	"fmt"
	"os"
	"time"

	"github.com/iver-wharf/wharf-core/v2/pkg/env"
)

func main() {
	os.Setenv("A", "1")
	os.Setenv("B", "2")

	type testType struct {
		A string
		B int
		C time.Duration
	}

	var x testType

	fmt.Printf("Before: A: %q\n", x.A)
	fmt.Printf("Before: B: %d\n", x.B)

	env.Bind(&x.A, "A")
	env.Bind(&x.B, "B")

	fmt.Printf("After: A: %q\n", x.A)
	fmt.Printf("After: B: %d\n", x.B)

	os.Setenv("C", "foo bar")
	err := env.Bind(&x.C, "C")
	fmt.Printf("Parse C: %s (is ErrParse? %t)\n", err, errors.Is(err, env.ErrParse))

}

Output:

Before: A: ""
Before: B: 0
After: A: "1"
After: B: 2
Parse C: env "C"="foo bar": time: invalid duration "foo bar" (is ErrParse? true)

func BindMultiple

func BindMultiple[T BindConstraint](bindings map[T]string) error

BindMultiple updates the Go variables via the pointers with the values of the environment variables, if set and not empty, for each respective pair in the map.

If the environment variable is not set, is empty, or the function returns an error, the value of the respective target interface is left unchanged.

An error is returned if any of the bindings failed to bind.

func LookupNoEmpty

func LookupNoEmpty(key string) (string, bool)

LookupNoEmpty retrieves the value of the environment variable.

Returns ("", false) if the environment variable was empty, or not set. Returns (envVariableValue, true) otherwise.

Types

type BindConstraint

type BindConstraint interface {
	*string | *bool | *int | *int32 | *int64 | *uint | *uint32 | *uint64 |
		*float32 | *float64 | *time.Time | *time.Duration
}

BindConstraint is a generic type constraint of all the types that the Bind function supports.

type ParseError

type ParseError struct {
	EnvKey   string
	EnvValue string
	Err      error
}

ParseError is an error type that unwraps to the internal parsing error obtained.

func (ParseError) As

func (err ParseError) As(target any) bool

As returns true if this error could be unwrapped into the type of the target error.

This method provides compatibility with the errors.As function.

func (ParseError) Error

func (err ParseError) Error() string

Error returns the error string. Makes it compliant with the error interface.

func (ParseError) Is

func (err ParseError) Is(target error) bool

Is returns true if the target error is ErrParse or if the inner actual parsing error is the same error.

This method provides compatibility with the errors.Is function.

func (ParseError) Unwrap

func (err ParseError) Unwrap() error

Unwrap returns the inner actual parsing error, such as the error return value from a strconv function.

This method provides compatibility with the errors.Unwrap function.