env

README

Env

Makes fetching and interpreting environment variables easy and safe.

Being able to provide default values when retrieving environment variables often makes program logic shorter and more readable.

Functions

func Str

func Str(name string, optionalDefault ...string) string

Str does the same as os.Getenv, but allows the user to provide a default value (optional). Only the first optional value is used, if the environment variable value is empty or not set.

func Bool

func Bool(envName string) bool

Bool returns the bool value of the given environment variable name. Returns false if it is not declared or empty.

func Int

func Int(envName string, defaultValue int) int

Int returns the number stored in the environment variable, or the given default value.

func AsBool

func AsBool(s string) bool

AsBool can be used to interpret a string value as either true or false. Examples of true values are "yes" and "1".

func Has

func Has(s string) bool

Has return true if the given environment variable name is non-empty.

DurationSeconds

Takes a default int64 value, for the number of seconds, interprets the environment variable as the number of seconds and returns a time.Duration.

DurationMinutes

Takes a default int64 value, for the number of minutes, interprets the environment variable as the number of seconds and returns a time.Duration.

DurationHours

Takes a default int64 value, for the number of hours, interprets the environment variable as the number of seconds and returns a time.Duration.

Contains

Checks if the given environment variable contains the given string.

Is

Checks if the given environment variable is the given value, with leading and trailing spaces trimmed before comparing both values.

HomeDir

Returns the home directory of the current user, or /tmp if it is not available. /home/$LOGNAME or /home/$USER are returned if $HOME is not set.

ExpandUser

Replaces ~ or $HOME at the start of a string with the home directory of the current user.

File

Does the same as the Str function, but replaces a leading ~ or $HOME with the home directory of the current user.

Dir

Does the same as the Str function, but replaces a leading ~ or $HOME with the home directory of the current user.

Path

Returns the current $PATH as a slice of strings.

Other functions

There are also: Float64, Float32, Uint64, Uint32, Uint16, Uint8, Int64, Int32, Int16 and Int8 functions available.

Example

package main

import (
    "fmt"
    "github.com/xyproto/env"
)

func main() {
    fmt.Println(env.DurationSeconds("REQUEST_TIMEOUT", 1800))
}

Running the above program like this: REQUEST_TIMEOUT=1200 ./main, outputs:

20m0s

Cache

• If Load() is called, then cache is enabled and all environment variables are read from the system.
• The functions offered by this package will then read the values from the cache instead.
• If variables are set with os.Setenv, then Load() can be used to read the environment variables from the system again.
• Unload() can be called to stop using the cache and only rely on os.Setenv and os.Getenv again.
• The Set and Unset functions can be used to both set values with os.Setenv and also modify the cache, so that an additional call to Load() is not needed.

General info

• Version: 1.9.1
• License: BSD-3
• Author: Alexander F. Rødseth <xyproto@archlinux.org>

Documentation

Overview

Package env provides convenience functions for retrieving data from environment variables

Package env provides convenience functions for retrieving data from environment variables

Index

• func AsBool(s string) bool
• func Bool(envName string) bool
• func Contains(envName string, value string) bool
• func Dir(name string, optionalDefault ...string) string
• func DurationHours(envName string, defaultValue int64) time.Duration
• func DurationMinutes(envName string, defaultValue int64) time.Duration
• func DurationSeconds(envName string, defaultValue int64) time.Duration
• func ExpandUser(path string) string
• func File(name string, optionalDefault ...string) string
• func Float32(envName string, defaultValue float32) float32
• func Float64(envName string, defaultValue float64) float64
• func Has(envName string) bool
• func HomeDir() string
• func Int(envName string, defaultValue int) int
• func Int16(envName string, defaultValue int16) int16
• func Int32(envName string, defaultValue int32) int32
• func Int64(envName string, defaultValue int64) int64
• func Int8(envName string, defaultValue int8) int8
• func Is(envName, value string) bool
• func Load()
• func Path() []string
• func Set(name, value string) error
• func Str(name string, optionalDefault ...string) string
• func StrAlt(name1, name2 string, optionalDefault ...string) string
• func UInt16(envName string, defaultValue uint16) uint16
• func UInt32(envName string, defaultValue uint32) uint32
• func UInt64(envName string, defaultValue uint64) uint64
• func UInt8(envName string, defaultValue uint8) uint8
• func Unload()
• func Unset(name string) error

Functions

func AsBool

func AsBool(s string) bool

AsBool can be used to interpret a string value as either true or false. Examples of true values are "yes" and "1".

func Bool

func Bool(envName string) bool

Bool returns the bool value of the given environment variable name. Returns false if it is not declared or empty.

func Contains

func Contains(envName string, value string) bool

Contains checks if the given environment variable contains the given string

func Dir

func Dir(name string, optionalDefault ...string) string

Dir does the same as File

func DurationHours

func DurationHours(envName string, defaultValue int64) time.Duration

DurationHours interprets the environment variable value as hours and returns a time.Duration. The given default number is interpreted as the number of hours.

func DurationMinutes

func DurationMinutes(envName string, defaultValue int64) time.Duration

DurationMinutes interprets the environment variable value as minutes and returns a time.Duration. The given default number is interpreted as the number of minutes.

func DurationSeconds

func DurationSeconds(envName string, defaultValue int64) time.Duration

DurationSeconds interprets the environment variable value as seconds and returns a time.Duration. The given default number is interpreted as the number of seconds.

func ExpandUser

func ExpandUser(path string) string

ExpandUser replaces a leading ~ or $HOME with the path to the home directory of the current user

func File

func File(name string, optionalDefault ...string) string

File does the same as Str, but expands a leading "~" or "$HOME" string to the home directory of the current user.

func Float32

func Float32(envName string, defaultValue float32) float32

Float32 returns the number stored in the environment variable, or the provided default value.

func Float64

func Float64(envName string, defaultValue float64) float64

Float64 returns the number stored in the environment variable, or the provided default value.

func Has

func Has(envName string) bool

Has returns true if the given environment variable name is set and not empty.

func HomeDir

func HomeDir() string

HomeDir returns the path to the home directory of the user, if available. If not available, $LOGNAME or $USER are used to construct a path starting with /home/. If $LOGNAME and $USER are not available, just "/tmp" is returned. The returned string is what the home directory should have been named, if it would have existed. No checks are made for if the directory exists.

func Int

func Int(envName string, defaultValue int) int

Int returns the number stored in the environment variable, or the provided default value.

func Int16

func Int16(envName string, defaultValue int16) int16

Int16 returns the number stored in the environment variable, or the provided default value.

func Int32

func Int32(envName string, defaultValue int32) int32

Int32 returns the number stored in the environment variable, or the provided default value.

func Int64

func Int64(envName string, defaultValue int64) int64

Int64 returns the number stored in the environment variable, or the provided default value.

func Int8

func Int8(envName string, defaultValue int8) int8

Int8 returns the number stored in the environment variable, or the provided default value.

func Is

func Is(envName, value string) bool

Is returns true if the given environment variable is the given string value. The whitespace of both values are trimmed before the comparison.

func Load

func Load()

Load reads all environment variables into the environment map. It also instructs env to use the cache. If a program uses os.Setenv, then Load() should be called after that, in order to read the new values. This function can be used both as an "init and enable cache" function and as a "reload" function.

func Path

func Path() []string

Path returns the elements in the $PATH environment variable

func Set

func Set(name, value string) error

Set calls os.Setenv. If caching is enabled, the value in the environment map is also set and there is no need to call Load() to re-read the environment variables from the system.

func Str

func Str(name string, optionalDefault ...string) string

Str does the same as os.Getenv, but allows the user to provide a default value (optional). Only the first optional argument is used, the rest is discarded.

func StrAlt

func StrAlt(name1, name2 string, optionalDefault ...string) string

StrAlt will return the string value of the first given environment variable name, or, if that is not available, use the string value of the second given environment variable. If none are available, the optional default string is returned.

func UInt16

func UInt16(envName string, defaultValue uint16) uint16

UInt16 returns the number stored in the environment variable, or the provided default value.

func UInt32

func UInt32(envName string, defaultValue uint32) uint32

UInt32 returns the number stored in the environment variable, or the provided default value.

func UInt64

func UInt64(envName string, defaultValue uint64) uint64

UInt64 returns the number stored in the environment variable, or the provided default value.

func UInt8

func UInt8(envName string, defaultValue uint8) uint8

UInt8 returns the number stored in the environment variable, or the provided default value.

func Unload

func Unload()

Unload clears the cache and configures env to not use the cache.

func Unset

func Unset(name string) error

Unset will clear an environment variable by calling os.Setenv(name, ""). The cache entry will also be cleared if useCaching is true.