envstruct

README

envstruct

[![slack.cloudfoundry.org][slack-badge]][loggregator-slack]

If you have any questions, or want to get attention for a PR or issue please reach out on the #logging-and-metrics channel in the cloudfoundry slack

envstruct is a simple library for populating values on structs from environment variables.

Usage

Export some environment variables.

$ export HOST_IP="127.0.0.1"
$ export HOST_PORT="443"
$ export PASSWORD="abc123"

Note: The environment variables are case sensitive. The casing of the set environment variable must match the casing in the struct tag.

Write some code. In this example, IP requires that the HOST_IP environment variable is set to non empty value and Port defaults to 80 if HOST_PORT is an empty value. Then we use the envstruct.WriteReport() to print a table with a report of what fields are on the struct, the type, the environment variable where the value is read from, whether or not it is required, and the value. All values are omitted by default, if you wish to display the value for a field you can add report to the env struct tag.

package main

import envstruct "code.cloudfoundry.org/go-envstruct"

type Credentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
}

func (c *Credentials) UnmarshalEnv(data string) error {
	return json.Unmarshal([]byte(data), c)
}

type HostInfo struct {
	Credentials Credentials `env:"CREDENTIALS, required"`
	IP          string      `env:"HOST_IP,     required, report"`
	Port        int         `env:"HOST_PORT,             report"`
}

func main() {
	hi := HostInfo{Port: 80}

	err := envstruct.Load(&hi)
	if err != nil {
		panic(err)
	}

	envstruct.WriteReport(&hi)
}

Run your code and rejoice!

$ go run example/example.go
FIELD NAME:  TYPE:             ENV:         REQUIRED:  VALUE:
Credentials  main.Credentials  CREDENTIALS  true       (OMITTED)
IP           string            HOST_IP      true       10.0.0.1
Port         int               HOST_PORT    false      80
Credentials: {Username:my-user Password:my-password}

Supported Types

• string
• bool (true and 1 results in true value, anything else results in false value)
• int
• int8
• int16
• int32
• int64
• uint
• uint8
• uint16
• uint32
• uint64
• float32
• float64
• complex64
• complex128
• []slice (Slices of any other supported type. Environment variable should have coma separated values)
• time.Duration
• *url.URL
• Struct
• Pointer to Struct
• map[string]string (Environment variable should have comma separated key:value. Keys cannot contain colons and neither key nor value can contain commas. e.g. key_one:value_one, key_two:value_two
• Custom Unmarshaller (see Credentials in example above)

Running Tests

Run tests using ginkgo.

$ go run github.com/onsi/ginkgo/v2/ginkgo -r

Documentation

Index

• Variables
• func Load(t interface{}) error
• func ToEnv(t interface{}) []string
• func WriteReport(t interface{}) error
• type Unmarshaller

Variables

var ReportWriter io.Writer = os.Stderr

ReportWriter struct writing to stderr by default

Functions

func Load

func Load(t interface{}) error

Load will use the `env` tags from a struct to populate the structs values and perform validations.

func ToEnv

func ToEnv(t interface{}) []string

ToEnv will return a slice of strings that can be used with exec.Cmd.Env formatted as `ENVAR_NAME=value` for a given struct.

func WriteReport

func WriteReport(t interface{}) error

WriteReport will take a struct that is setup for envstruct and print out a report containing the struct field name, field type, environment variable for that field, whether or not the field is required and the value of that field. The report is written to `ReportWriter` which defaults to `os.Stderr`. By default all values are omitted. This prevents logging of secrets. To not omit a value, you must add the `report` value in the `env` struct tag.

Types

type Unmarshaller

type Unmarshaller interface {
	UnmarshalEnv(v string) error
}

Unmarshaller is a type which unmarshals itself from an environment variable.