env

README

go-env

Package env provides an env struct field tag to marshal and unmarshal environment variables.

Usage

package main

import (
  "log"

  env "github.com/Netflix/go-env"
)

type Environment struct {
  Home string `env:"HOME"`

  Jenkins struct {
    BuildId     *string `env:"BUILD_ID"`
    BuildNumber int    `env:"BUILD_NUMBER"`
    Ci          bool   `env:"CI"`
  }

  Extras env.EnvSet
}

func main() {
  var environment env.Environment
  es, err := env.UnmarshalFromEnviron(&environment)
  if err != nil {
    log.Fatal(err)
  }
  // Remaining environment variables.
  environment.Extras = es

  // ...

  es, err = env.Marshal(environment)
  if err != nil {
    log.Fatal(err)
  }

  cs := env.ChangeSet{
    "HOME": "/tmp/edgarl",
    "BUILD_ID": nil,
    "BUILD_NUMBER": nil,
  }
  es.Apply(cs)

  environment = env.Environment{}
  err = env.Unmarshal(es, &environment)
  if err != nil {
    log.Fatal(err)
  }

  environment.Extras = es
}

Documentation

Overview

Package env provides an `env` struct field tag to marshal and unmarshal environment variables.

Copyright 2018 Netflix, Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

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.

Index

• Variables
• func EnvSetToEnviron(m EnvSet) []string
• func Unmarshal(es EnvSet, v interface{}) error
• type ChangeSet
• type EnvSet
  • func EnvironToEnvSet(environ []string) (EnvSet, error)
  • func Marshal(v interface{}) (EnvSet, error)
  • func UnmarshalFromEnviron(v interface{}) (EnvSet, error)
  • func (e EnvSet) Apply(cs ChangeSet)

Variables

var (
	// ErrInvalidValue returned when the value passed to Unmarshal is nil or not a
	// pointer to a struct.
	ErrInvalidValue = errors.New("value must be a non-nil pointer to a struct")

	// ErrUnsupportedType returned when a field with tag "env" is unsupported.
	ErrUnsupportedType = errors.New("field is an unsupported type")

	// ErrUnexportedField returned when a field with tag "env" is not exported.
	ErrUnexportedField = errors.New("field must be exported")
)

var (
	// ErrInvalidEnviron returned when environ has an incorrect format.
	ErrInvalidEnviron = errors.New("items in environ must have format key=value")
)

Functions

func EnvSetToEnviron

func EnvSetToEnviron(m EnvSet) []string

EnvSetToEnviron transforms a EnvSet into a slice of strings with the format "key=value".

func Unmarshal

func Unmarshal(es EnvSet, v interface{}) error

Unmarshal parses an EnvSet and stores the result in the value pointed to by v. Fields that are matched in v will be deleted from EnvSet, resulting in an EnvSet with the remaining environment variables. If v is nil or not a pointer to a struct, Unmarshal returns an ErrInvalidValue.

Fields tagged with "env" will have the unmarshalled EnvSet of the matching key from EnvSet. If the tagged field is not exported, Unmarshal returns ErrUnexportedField.

If the field has a type that is unsupported, Unmarshal returns ErrUnsupportedType.

Types

type ChangeSet

type ChangeSet map[string]*string

ChangeSet represents a set of environment variables changes, corresponding to os.Setenv and os.Unsetenv operations.

type EnvSet

type EnvSet map[string]string

EnvSet represents a set of environment variables.

func EnvironToEnvSet

func EnvironToEnvSet(environ []string) (EnvSet, error)

EnvironToEnvSet transforms a slice of string with the format "key=value" into the corresponding EnvSet. If any item in environ does follow the format, EnvironToEnvSet returns ErrInvalidEnviron.

func Marshal

func Marshal(v interface{}) (EnvSet, error)

Marshal returns an EnvSet of v. If v is nil or not a pointer, Marshal returns an ErrInvalidValue.

Marshal uses fmt.Sprintf to transform encountered values to its default string format. Values without the "env" field tag are ignored.

Nested structs are traversed recursively.

func UnmarshalFromEnviron

func UnmarshalFromEnviron(v interface{}) (EnvSet, error)

UnmarshalFromEnviron parses an EnvSet from os.Environ and stores the result in the value pointed to by v. Fields that weren't matched in v are returned in an EnvSet with the remaining environment variables. If v is nil or not a pointer to a struct, UnmarshalFromEnviron returns an ErrInvalidValue.

Fields tagged with "env" will have the unmarshalled EnvSet of the matching key from EnvSet. If the tagged field is not exported, UnmarshalFromEnviron returns ErrUnexportedField.

If the field has a type that is unsupported, UnmarshalFromEnviron returns ErrUnsupportedType.

func (EnvSet) Apply

func (e EnvSet) Apply(cs ChangeSet)

Apply applies a ChangeSet to EnvSet, modifying its contents.