jonasi / go-envparse

Minimal environment variable parser for Go

go-envparse

A minimal Go environment variable parser. It's intended to be used to parse .env style files similar to godotenv or rubydotenv, but perform minimal allocations, handle more complex quoting, and be better tested.

Parsing a line does 2 allocations regardless of line length or complexity.

The parser supports JSON strings which allows for cross-language/platform encoding of arbitrarily complex data.

For example if you are parsing environment variables from a templated file, the template can JSON encode data that may contain newlines:

FOO={{ some_template_function | toJSON }}

...would be templated to:

FOO="The template value\nmay have included\nsome newlines!\n\ud83d\udd25"

...and envparse.Parse() would return:

map[string]string{
	"FOO": "The template value\nmay have included\nsome newlines!\n🔥",
}

Minimal

The following common features are intentionaly missing:

• Full shell quoting semantics
• Full shell escape sequence support
  • Only JSON escape sequences are supported (see below)
• Variable interpolation
  • Use Go's os.Expand on the parsed values
• Anything YAML related
  • No

However, comments, unquoted, single quoted, and double quoted text may all be used within a single value:

SOME_KEY = normal unquoted \text 'plus single quoted\' "\"double quoted " # EOL

...parses to:

map[string]string{
	"SOME_KEY": `normal unquoted \text plus single quoted\ "double quoted `
}

(Note the trailing space inside the double quote is kept, but the space between the final " and # is trimmed.)

Format

• Keys should be of the form: [A-Za-z_][A-Za-z0-9_]?
  • Keys may be prefixed with export which will be ignored
  • Whitespace around keys will be trimmed
• Values should be valid ASCII or UTF-8 encoded.
• Newlines are always treated as delimiters, so newlines within values must be escaped.
• Values may use one of more quoting styles:
  • Unquoted - FOO=bar baz
    • No escape sequences
    • Ends at #, ", ', or newline
    • Preceeding and trailing whitespace will be trimmed
  • Double Quotes - FOO="bar baz"
    • Supports JSON escape sequences: \uXXXX, \r, \n, \t, \\, and \"
    • Ends at unescaped "
    • No whitespace trimming
  • Single Quotes - FOO='bar baz'
    • No escape sequences
    • Ends at '
    • No whitespace trimming

See envparse_test.go for examples of valid and invalid data.