env

README

go-kit/lists - Env Module

• About this module
• Installation
• Usage
• Code of Conduct
• Working Language
• Support and Feedback
• How to Contribute
• Licensing

The env module provides a set of tools to manage environment variables in Go.

About this module

This module complements the os module of the standard library by providing additional functionality like environment variable parsing and default value handling.

Installation

To install, run:

go get github.com/lvlcn-t/go-kit/env

And import the package in your code:

import "github.com/lvlcn-t/go-kit/env"

Usage

The documentation for this module can be found on pkg.go.dev.

To see how to use this module, you can check the examples directory of the repository.

Code of Conduct

This project has adopted the Contributor Covenant in version 2.1 as our code of conduct. Please see the details in our CODE_OF_CONDUCT.md. All contributors must abide by the code of conduct.

Working Language

We decided to apply English as the primary project language.

Consequently, all content will be made available primarily in English. We also ask all interested people to use English as the preferred language to create issues, in their code (comments, documentation, etc.) and when you send requests to us. The application itself and all end-user facing content will be made available in other languages as needed.

Support and Feedback

The following channels are available for discussions, feedback, and support requests:

Type	Channel
Issues

How to Contribute

Contribution and feedback is encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines. By participating in this project, you agree to abide by its Code of Conduct at all times.

Licensing

Copyright (c) 2024 lvlcn-t.

Licensed under the MIT (the "License"); you may not use this file except in compliance with the License.

You may obtain a copy of the License at https://www.mit.edu/~amini/LICENSE.md.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an " AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the LICENSE for the specific language governing permissions and limitations under the License.

Documentation

Index

• func GetWithFallback[T any](key string, defaultValue T, converter ...Converter[T]) T
• func MustGet[T any](key string, converter ...Converter[T]) T
• type Converter
• type OptionalVariable
• type RequiredVariable
• type TypedVariable
• type Variable
  • func Get[T any](key string) Variable[T]

Functions

func GetWithFallback

func GetWithFallback[T any](key string, defaultValue T, converter ...Converter[T]) T

GetWithFallback retrieves an environment variable and tries to convert it to the desired type. If the environment variable is not set or the conversion fails, it returns the provided default value.

Example:

// Get the environment variable "MY_VAR" as a string.
// If the variable is not set or an error occurs, return "default".
value := env.GetWithFallback("MY_VAR", "default")

// Get the environment variable "MY_VAR" as an integer.
// If the variable is not set or an error occurs, return 42.
value := env.GetWithFallback("MY_VAR", 42)

// Get the environment variable "MY_VAR" as a [time.Duration] using a custom converter.
// If the variable is not set or an error occurs, return 5 * time.Second.
value := env.GetWithFallback("MY_VAR", 5*time.Second, time.ParseDuration)

func MustGet

func MustGet[T any](key string, converter ...Converter[T]) T

MustGet retrieves an environment variable and tries to convert it to the desired type. If the environment variable is not set or the conversion fails, it panics.

Example:

// Get the environment variable "MY_VAR" as a string and panic if an error occurs.
value := env.MustGet[string]("MY_VAR")

// Get the environment variable "MY_VAR" as an integer and panic if an error occurs.
value := env.MustGet[int]("MY_VAR")

// Get the environment variable "MY_VAR" as a [time.Duration] using a custom converter and panic if an error occurs.
value := env.MustGet[time.Duration]("MY_VAR", time.ParseDuration)

Types

type Converter

type Converter[T any] func(string) (T, error)

Converter is a function that converts a string to a desired type.

type OptionalVariable

type OptionalVariable[T any] interface{ TypedVariable[T] }

OptionalVariable represents an optional environment variable.

It always returns a valid value, either the value of the environment variable or the fallback value if the environment variable is not set or an error occurs.

type RequiredVariable

type RequiredVariable[T any] interface{ TypedVariable[T] }

RequiredVariable represents a required environment variable.

The environment variable must be set and always be a valid value.

type TypedVariable

type TypedVariable[T any] interface {
	// Convert sets a custom converter function to convert the string value of the environment variable to type T.
	// If no converter is set, it tries to resolve a default converter based on the type T.
	//
	// Default converters are available for the following types:
	//  - string
	//  - int, int8, int16, int32, int64
	//  - uint, uint8, uint16, uint32, uint64, uintptr
	//  - float32, float64
	//  - complex64, complex128
	//  - bool
	//
	// If no default converter is available, a custom converter must be provided otherwise the environment variable value cannot be retrieved.
	Convert(converter Converter[T]) TypedVariable[T]
	// Value retrieves the environment variable value.
	//
	// If the environment variable is not set or an error occurs, it either returns preconditioned values and an error or panics if the die flag is set.
	Value() (T, error)
	// Raw retrieves the environment variable value as a string without converting it to type T.
	//
	// If the environment variable is not set or an error occurs, it returns the zero value of type T and the error.
	Raw() (string, error)
}

TypedVariable represents a typed environment variable.

type Variable

type Variable[T any] interface {
	// OrDie sets the die flag to panic if the environment variable is not set or an error occurs.
	OrDie() RequiredVariable[T]
	// WithFallback sets the default value to be used if the environment variable is not set or an error occurs.
	WithFallback(defaultValue T) OptionalVariable[T]
	// NoFallback flags the environment variable builder to not use a fallback value.
	// If the environment variable is not set or an error occurs, it returns the zero value of type T and the error.
	NoFallback() RequiredVariable[T]
}

Variable represents a builder for an environment variable of type T.

The variable can be required or optional. Required variables must be set, while optional variables have a fallback value.

func Get

func Get[T any](key string) Variable[T]

Get returns a Variable for the provided key. You can then use the builder to set fallback values, converters, and more.

The type T must be a valid type for an environment variable. Panics if T is an invalid type for an environment variable.

Example:

// Get the environment variable "MY_VAR" as a string and panic if an error occurs.
value, _ := env.Get[string]("MY_VAR").OrDie().Value()

// Get the environment variable "MY_VAR" as an integer.
// If the variable is not set or an error occurs, return 42.
value, _ := env.Get[int]("MY_VAR").WithFallback(42).Value()

// Get the environment variable "MY_VAR" as a [time.Duration] using a custom converter.
// If the variable is not set or an error occurs, return 5 * time.Second.
value, _ := env.Get[time.Duration]("MY_VAR").WithFallback(5*time.Second).Convert(time.ParseDuration).Value()

// Get the environment variable "MY_VAR" as a boolean.
// If the variable is not set or an error occurs, return the error.
value, err := env.Get[bool]("MY_VAR").NoFallback().Value()