envparse

README

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 intentionally 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.

Documentation

Overview

Package envparse is a minimal environment variable parser. It handles empty lines, comments, single quotes, double quotes, and JSON escape sequences.

Non-empty or comment lines should be of the form:

KEY=value

While extraneous characters are discouraged, an "export" prefix, preceding whitespace, and trailing whitespace are all removed:

KEY = This is ok! # Parses to {"KEY": "This is ok!"}
KEY2= Also ok.    # Parses to {"KEY2": "Also ok."}
export FOO=bar    # Parses to {"FOO": "bar"}

Index

• Variables
• func Parse(r io.Reader) (map[string]string, error)
• type ParseError
  • func (e *ParseError) Error() string

Variables

var (
	ErrMissingSeparator = fmt.Errorf("missing =")
	ErrEmptyKey         = fmt.Errorf("empty key")
	ErrUnmatchedDouble  = fmt.Errorf(`unmatched "`)
	ErrUnmatchedSingle  = fmt.Errorf("unmatched '")
	ErrIncompleteEscape = fmt.Errorf("incomplete escape sequence")
	ErrIncompleteHex    = fmt.Errorf("incomplete hex sequence")
	ErrIncompleteSur    = fmt.Errorf("incomplete Unicode surrogate pair")
	ErrMultibyteEscape  = fmt.Errorf("multibyte characters disallowed in escape sequences")
)

Functions

func Parse

func Parse(r io.Reader) (map[string]string, error)

Parse environment variables from an io.Reader into a map or return a ParseError.

Types

type ParseError

type ParseError struct {
	Line int
	Err  error
}

ParseError is returned whenever the Parse function encounters an error. It includes the line number and underlying error.

func (*ParseError) Error

func (e *ParseError) Error() string