envs

README

envs - Reads configuration from various environments

Copyright (c) 2022, 2023, Geert JM Vanderkelen

The Go envs package offers functionality to read environment variables from the OS or dot-env files.

Overview

Environment Variables can be used, among other things, to configure applications. This package offers functionality to read such environment into a Go struct with special field tags.

Quick Start

For example, you want to read variables from the environment where the Go application runs to identify the user and her home directory. This can be easily achieved using Go's os.Getenv, but using this package, it would be like this:

package main

import (
	"fmt"

	"github.com/golistic/envs"
)

type UserEnv struct {
	Username string `envVar:"USER"`
	HomeDir  string `envVar:"HOME"`
	Avatar   string `envVar:"AVATAR" default:"🐣"`
}

func main() {
	userEnv := &UserEnv{}
	if err := envs.OSEnviron(userEnv); err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Printf("Username: %s\n", userEnv.Username)
		fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
	}
}

The above would output something similar too:

Username: alice
HomeDir : /Users/alice
Avatar  : 🐣

The AVATAR environment variables was not available, so the default was used.

Supported Go Types

We currently support the following types (also pointer values):

• string
• numeric
  • int, int8, int16, int32, int64
  • empty mean 0 (zero)
• bool
  • true, t, 1, on, enabled
  • false, f, 0, off, disabled
  • empty means false
• time.Duration
  • a Go duration as string, for example, 2d5m
  • empty means 0s

Naked Variables

Naked variables are those without value and equal sign, for example:

# naked!
TCP_PORT

When the destination struct has the field reading TCP_PORT as pointer value, for example, *int16, it will be nil. However, if type would be int16, a syntax error is shown.

Supported Environments

We support the following environments:

• Operating System (OS) environment using Go's os.Environ
• .env files using rules from
  • the dotenv project, for NodeJS projects
  • the djanto-dotenv project, for Django projects

Operating System (OS) environment

Reading the Operating System (OS) environment is the most common way of getting the application's configuration.

See Quick Start for an example.

NodeJS projects

Reading an .env (dotenv) file from a NodeJS project is done using the rules defined by the dotenv package.

Note: variable expansion not yet supported.

Example:

package main

import (
	"fmt"

	"github.com/golistic/envs"
)

type UserEnv struct {
	Username string `envVar:"USER"`
	HomeDir  string `envVar:"HOME"`
	Avatar   string `envVar:"AVATAR" default:"🐣"`
}

func main() {
	userEnv := &UserEnv{}
	if err := envs.NodeJSDotEnvFromFile(userEnv, ".env"); err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Printf("Username: %s\n", userEnv.Username)
		fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
		fmt.Printf("Avatar  : %s\n", userEnv.Avatar)
	}
}

Django projects

Reading an .env (dotenv) file from a Django project is done using the rules defined by the django-dotenv module.

Note: variable expansion not yet supported.

Example code is very similar to the NodeJS one, but using the function envs.DjangoDotEnvFromFile instead.

License

Distributed under the MIT license. See LICENSE.txt for more information.

Documentation

Index

• func DjangoDotEnv(dest any, r io.Reader) error
• func DjangoDotEnvFromFile(dest any, path string) error
• func NodeJSDotEnv(dest any, r io.Reader) error
• func NodeJSDotEnvFromFile(dest any, path string) error
• func OSEnviron(dest any) error
• type ErrReadingFile
  • func (err *ErrReadingFile) Error() string
• type ErrSyntax
  • func (err *ErrSyntax) Error() string

Examples

• NodeJSDotEnvFromFile
• OSEnviron

Functions

func DjangoDotEnv

func DjangoDotEnv(dest any, r io.Reader) error

DjangoDotEnv reads environment variables from r and stores them in struct dest according to the rules defined by the django-dotenv project https://github.com/jpadilla/django-dotenv/blob/master/dotenv.py. The variables are stored and available within the dest struct.

func DjangoDotEnvFromFile

func DjangoDotEnvFromFile(dest any, path string) error

DjangoDotEnvFromFile reads environment variables from a file with path and stores them in struct dest. See DjangoDotEnv() for further details.

func NodeJSDotEnv

func NodeJSDotEnv(dest any, r io.Reader) error

NodeJSDotEnv reads environment variables from a file typically called `.env` according to the rules defined by the NPM package https://www.npmjs.com/package/dotenv.

func NodeJSDotEnvFromFile

func NodeJSDotEnvFromFile(dest any, path string) error

NodeJSDotEnvFromFile reads environment variables from a file with path and stores them in struct dest. See NodeJSDotEnv() for further details.

Example

package main

import (
	"fmt"
	"path"

	"github.com/golistic/envs"
)

type UserEnv struct {
	Username string `envVar:"USER"`
	HomeDir  string `envVar:"HOME"`
	Avatar   string `envVar:"AVATAR" default:"🐣"`
}

func main() {
	userEnv := &UserEnv{}

	p := path.Join(".", "_test_data", "js.example.env")
	if err := envs.NodeJSDotEnvFromFile(userEnv, p); err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Printf("Username: %s\n", userEnv.Username)
		fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
		fmt.Printf("Avatar  : %s\n", userEnv.Avatar)
	}

}

Output:

Username: alice
HomeDir : /home/alice
Avatar  : 🙂️

func OSEnviron

func OSEnviron(dest any) error

OSEnviron gets variables from the operating system's environment and stores the values in the struct dest.

This function uses Go's os.Environ.

Panics when dest is non-pointer, nil, or not a struct.

Example

package main

import (
	"fmt"
	"os"

	"github.com/golistic/envs"
)

type UserEnv struct {
	Username string `envVar:"USER"`
	HomeDir  string `envVar:"HOME"`
	Avatar   string `envVar:"AVATAR" default:"🐣"`
}

func main() {
	userEnv := &UserEnv{}

	// we have to set the following so test is deterministic
	_ = os.Setenv("USER", "alice")
	_ = os.Setenv("HOME", "/Users/alice")

	if err := envs.OSEnviron(userEnv); err != nil {
		fmt.Println("Error:", err)
	} else {
		fmt.Printf("Username: %s\n", userEnv.Username)
		fmt.Printf("HomeDir : %s\n", userEnv.HomeDir)
		fmt.Printf("Avatar  : %s\n", userEnv.Avatar)
	}

}

Output:

Username: alice
HomeDir : /Users/alice
Avatar  : 🐣

Types

type ErrReadingFile

type ErrReadingFile struct {
	FilePath string
	Err      error
}

func (*ErrReadingFile) Error

func (err *ErrReadingFile) Error() string

type ErrSyntax

type ErrSyntax struct {
	Line   int
	EnvVar string
	Reason string
}

func (*ErrSyntax) Error

func (err *ErrSyntax) Error() string