osenv

README

OS Environment

This package aims to provide extension of the os.Getenv that supports different types of variable types, and allows to specify a default value, in case the environment variable is missing.

This version is implemented with Go 1.18+ generics. If you need to use the package's functionailty in Go versions prior to 1.18, see below.

There are two versions of the package:

• v2: uses generics, therefore can only be compiled with Go 1.18+ (this version).
• v1: supports Go versions 1.12+.

Go 1.18+ (v2):

import "github.com/rusq/osenv/v2"

Go 1.12+ (v1):

import "github.com/rusq/osenv"

Usage

package main

import (
	"fmt"
	"math"
	"time"

	"github.com/rusq/osenv/v2"
)

func main() {
	fmt.Printf("OSENV_BOOL: %v\n"+
		"OSENV_DURATION: %s\n"+
		"OSENV_FLOAT: %.7f\n"+
		"OSENV_INT: %d\n"+
		"OSENV_INT64: %d\n"+
		"OSENV_STRING: %s\n"+
		"OSENV_TIME: %s\n",

		osenv.Value("OSENV_BOOL", true),
		osenv.Value("OSENV_DURATION", 60*time.Second),
		osenv.Value("OSENV_FLOAT", math.Pi),
		osenv.Value("OSENV_INT", math.MaxInt32),
		osenv.Value("OSENV_INT64", math.MaxInt64),
		osenv.Value("OSENV_STRING", "default string value"),
		osenv.Value("OSENV_TIME", time.Date(2020, 12, 31, 23, 59, 59, 0, time.UTC)),
	)
}

For more examples, refer to package documentation

The package defines a single function that handles all supported types:

• Boolean
• time.Duration
• Float64
• Int
• Int64
• String
• Secret*
• Time

For all of these types, call osenv.Value(...).

* Secret obtains a string from the environment (osenv.Secret). The only difference between Value and Secret, is that Secret unsets the environment variable after getting the value.

Upgrading from v1 to v2

If you were using osenv/v1 before, and upgrading to osenv/v2, follow the instructions in this section.

Replace the call to the function in "From" with the call to the function in "To":

From	To
osenv.Bool	osenv.Value
osenv.Duration	osenv.Value
osenv.Float	osenv.Value
osenv.Int	osenv.Value
osenv.Int64	osenv.Value
osenv.Time	osenv.Value
osenv.String	osenv.Value

Documentation

Overview

Package osenv provides convenient functions to access environment variables.

Copyright 2022 Rustam Gilyazov. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.

Index

• Variables
• func Secret[T SupportedTypes](key string, defavlt T) T
• func Value[T SupportedTypes](key string, defavlt T) T
• type SupportedTypes

Examples

• Secret
• Value

Variables

var TimeFormat = time.RFC3339

TimeFormat specifies the supported time format for Time values. The default value is RFC3339 time format.

Functions

func Secret

func Secret[T SupportedTypes](key string, defavlt T) T

Secret returns the value of the environment variable with the name `key`. If the environment variable with name KEY not found, it returns the `defavlt` value. The environment variable is unset after the value is retrieved.

Example

os.Setenv("SECRET_VALUE", "hidden fact")

fmt.Printf("os.Getenv before: %q\n", os.Getenv("SECRET_VALUE"))

aSecret := Secret("SECRET_VALUE", "xxx")
fmt.Printf("aSecret variable contains: %q\n", aSecret)

fmt.Printf("os.Getenv after: %q\n", os.Getenv("SECRET_VALUE"))

Output:

os.Getenv before: "hidden fact"
aSecret variable contains: "hidden fact"
os.Getenv after: ""

func Value

func Value[T SupportedTypes](key string, defavlt T) T

Example

fmt.Printf("OSENV_BOOL: %v\n"+
	"OSENV_DURATION: %s\n"+
	"OSENV_FLOAT: %.7f\n"+
	"OSENV_INT: %d\n"+
	"OSENV_INT64: %d\n"+
	"OSENV_STRING: %s\n"+
	"OSENV_TIME: %s\n",

	Value("OSENV_BOOL", true),
	Value("OSENV_DURATION", 60*time.Second),
	Value("OSENV_FLOAT", math.Pi),
	Value("OSENV_INT", math.MaxInt32),
	Value("OSENV_INT64", math.MaxInt64),
	Value("OSENV_STRING", "default string value"),
	Value("OSENV_TIME", time.Date(2020, 12, 31, 23, 59, 59, 0, time.UTC)),
)

Output:

OSENV_BOOL: true
OSENV_DURATION: 1m0s
OSENV_FLOAT: 3.1415927
OSENV_INT: 2147483647
OSENV_INT64: 9223372036854775807
OSENV_STRING: default string value
OSENV_TIME: 2020-12-31 23:59:59 +0000 UTC

Types

type SupportedTypes

type SupportedTypes interface {
	bool | float64 | int | int64 | string | time.Duration | time.Time
}

SupportedTypes is the type constraint interface, that lists all currently supported environment variable types.