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
exportwhich will be ignored - Whitespace around keys will be trimmed
- Keys may be prefixed with
- 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
- Supports JSON escape sequences:
- Single Quotes -
FOO='bar baz'- No escape sequences
- Ends at
' - No whitespace trimming
- Unquoted -
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 ¶
Constants ¶
This section is empty.
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 ¶
Types ¶
type ParseError ¶
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
Source Files