struct2env

README

struct2env

Convert between go structures to environment variables and back (for structured config <-> shell env)

There are many go packages that are doing environment to go struct config (for instance https://github.com/kelseyhightower/envconfig) but I didn't find one doing the inverse and we needed to set a bunch of environment variables for shell and other tools to get some configuration structured as JSON and Go object, so this was born. For symetry the reverse was also added (history of commit on https://github.com/fortio/dflag/pull/50/commits)

Standalone package with 0 dependencies outside of the go standard library. Developed with go 1.20 but tested with go as old as 1.17 but should works with pretty much any go version, as it only depends on reflection and strconv.

The unit test has a fairly extensive example on how:

type FooConfig struct {
	Foo          string
	Bar          string
	Blah         int `env:"A_SPECIAL_BLAH"`
	ABool        bool
	NotThere     int `env:"-"`
	HTTPServer   string
	IntPointer   *int
	FloatPointer *float64
    // ...
}

Turns into

TST_FOO="a\nfoo with \" quotes and \\ and '"
TST_BAR="42str"
TST_A_SPECIAL_BLAH="42"
TST_A_BOOL=true
TST_HTTP_SERVER="http://localhost:8080"
TST_INT_POINTER="199"

Using

kv, errs := struct2env.StructToEnvVars(foo)
struct2env.ToShellWithPrefix("TST_", kv)

Documentation

Overview

Package env provides conversion from structure to and from environment variables.

It supports converting struct fields to environment variables using field tags, handling different data types, and transforming strings between different case conventions, which is useful for generating or parsing environment variables, JSON tags, or command line flags.

The package also defines several case conversion functions that aid in manipulating strings to fit conventional casing for various programming and configuration contexts. Additionally, it provides functions to serialize structs into slices of key-value pairs where the keys are derived from struct field names transformed to upper snake case by default, or specified explicitly via struct field tags.

It also includes functionality to deserialize environment variables back into struct fields, handling pointers and nested structs appropriately, as well as providing shell-compatible output for environment variable definitions.

The package leverages reflection to dynamically handle arbitrary struct types, and has 0 dependencies.

Index

• func CamelCaseToLowerKebabCase(s string) string
• func CamelCaseToLowerSnakeCase(s string) string
• func CamelCaseToUpperSnakeCase(s string) string
• func SerializeValue(value interface{}) string
• func SetFromEnv(prefix string, s interface{}) []error
• func ShellQuote(input string) string
• func SplitByCase(input string) []string
• func ToShell(kvl []KeyValue) string
• func ToShellWithPrefix(prefix string, kvl []KeyValue) string
• type KeyValue
  • func StructToEnvVars(s interface{}) ([]KeyValue, []error)
  • func (kv KeyValue) String() string

Functions

func CamelCaseToLowerKebabCase

func CamelCaseToLowerKebabCase(s string) string

CamelCaseToLowerKebabCase converts a string from camelCase or CamelCase to lower-kebab-case. Handles cases like HTTPServer -> http-server. Good for command line flags for instance.

func CamelCaseToLowerSnakeCase

func CamelCaseToLowerSnakeCase(s string) string

CamelCaseToLowerSnakeCase converts a string from camelCase or CamelCase to lowe_snake_case. Handles cases like HTTPServer -> http_server. Good for JSON tags for instance.

func CamelCaseToUpperSnakeCase

func CamelCaseToUpperSnakeCase(s string) string

CamelCaseToUpperSnakeCase converts a string from camelCase or CamelCase to UPPER_SNAKE_CASE. Handles cases like HTTPServer -> HTTP_SERVER and httpServer -> HTTP_SERVER. Good for environment variables.

func SerializeValue

func SerializeValue(value interface{}) string

func SetFromEnv

func SetFromEnv(prefix string, s interface{}) []error

func ShellQuote

func ShellQuote(input string) string

Escape characters such as the result string can be embedded as a single argument in a shell fragment e.g for ENV_VAR=<value> such as <value> is safe (no $(cmd...) no ` etc`).

func SplitByCase

func SplitByCase(input string) []string

Split strings into words, using CamelCase/camelCase/CAMELCase rules.

func ToShell

func ToShell(kvl []KeyValue) string

func ToShellWithPrefix

func ToShellWithPrefix(prefix string, kvl []KeyValue) string

This convert the key value pairs to bourne shell syntax (vs newer bash export FOO=bar).

Types

type KeyValue

type KeyValue struct {
	Key         string // Must be safe (is when coming from Go struct names but could be bad with env:).
	QuotedValue string // (Must be) Already quoted/escaped.
}

Intermediate result list from StructToEnvVars(), both the Key and QuotedValue must be shell safe/non adversarial as they are emitted as is by String() with = in between. Using StructToEnvVars produces safe values even with adversarial input (length notwithstanding).

func StructToEnvVars

func StructToEnvVars(s interface{}) ([]KeyValue, []error)

StructToEnvVars converts a struct to a map of environment variables. The struct can have a `env` tag on each field. The tag should be in the format `env:"ENV_VAR_NAME"`. The tag can also be `env:"-"` to exclude the field from the map. If the field is exportable and the tag is missing we'll use the field name converted to UPPER_SNAKE_CASE (using CamelCaseToUpperSnakeCase()) as the environment variable name.

func (KeyValue) String

func (kv KeyValue) String() string