README
¶
go-env
Package env provides an env struct field tag to marshal and unmarshal environment variables.
Usage
package main
import (
"log"
"time"
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"`
}
Node struct {
ConfigCache *string `env:"npm_config_cache,NPM_CONFIG_CACHE"`
}
Extras env.EnvSet
Duration time.Duration `env:"TYPE_DURATION"`
DefaultValue string `env:"MISSING_VAR,default=default_value"`
RequiredValue string `env:"IM_REQUIRED,required=true"`
}
func main() {
var environment 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)
}
home := "/tmp/edgarl"
cs := env.ChangeSet{
"HOME": &home,
"BUILD_ID": nil,
"BUILD_NUMBER": nil,
}
es.Apply(cs)
environment = Environment{}
err = env.Unmarshal(es, &environment)
if err != nil {
log.Fatal(err)
}
environment.Extras = es
}
Custom Marshaler/Unmarshaler
There is limited support for dictating how a field should be marshaled or unmarshaled. The following example shows how you could marshal/unmarshal from JSON
import (
"encoding/json"
"fmt"
"log"
env "github.com/Netflix/go-env"
)
type SomeData struct {
SomeField int `json:"someField"`
}
func (s *SomeData) UnmarshalEnvironmentValue(data string) error {
var tmp SomeData
err := json.Unmarshal([]byte(data), &tmp)
if err != nil {
return err
}
*s = tmp
return nil
}
func (s SomeData) MarshalEnvironmentValue() (string, error) {
bytes, err := json.Marshal(s)
if err != nil {
return "", err
}
return string(bytes), nil
}
type Config struct {
SomeData *SomeData `env:"SOME_DATA"`
}
func main() {
var cfg Config
_, err := env.UnmarshalFromEnviron(&cfg)
if err != nil {
log.Fatal(err)
}
if cfg.SomeData != nil && cfg.SomeData.SomeField == 42 {
fmt.Println("Got 42!")
} else {
fmt.Printf("Got nil or some other value: %v\n", cfg.SomeData)
}
es, err = env.Marshal(cfg)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Got the following: %+v\n", 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 ¶
Constants ¶
This section is empty.
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 ¶
EnvSetToEnviron transforms a EnvSet into a slice of strings with the format "key=value".
func Unmarshal ¶
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 ¶
ChangeSet represents a set of environment variables changes, corresponding to os.Setenv and os.Unsetenv operations.
type EnvSet ¶
EnvSet represents a set of environment variables.
func EnvironToEnvSet ¶
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 ¶
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 ¶
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.
type ErrMissingRequiredValue ¶
type ErrMissingRequiredValue struct {
Value string
}
ErrMissingRequiredValue returned when a field with required=true contains no value or default
func (ErrMissingRequiredValue) Error ¶
func (e ErrMissingRequiredValue) Error() string
type Marshaler ¶
Marshaler is the interface implemented by types that can marshal themselves into valid environment variable values.
type Unmarshaler ¶
Unmarshaler is the interface implemented by types that can unmarshal an environment variable value representation of themselves. The input can be assumed to be the raw string value stored in the environment.
Source Files