# go-envparse

**Repository Path**: mirrors_hashicorp/go-envparse

## Basic Information

- **Project Name**: go-envparse
- **Description**: Minimal environment variable parser for Go
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2025-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

[![Run CI Tests](https://github.com/hashicorp/go-envparse/actions/workflows/ci.yaml/badge.svg)](https://github.com/hashicorp/go-envparse/actions/workflows/ci.yaml)
[![Go Reference](https://pkg.go.dev/badge/github.com/hashicorp/go-envparse.svg)](https://pkg.go.dev/github.com/hashicorp/go-envparse)

# go-envparse

A minimal Go environment variable parser. It's intended to be used to parse
`.env` style files similar to [godotenv](https://github.com/joho/godotenv) or
[rubydotenv](https://github.com/bkeepers/dotenv), 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:

```go
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](https://golang.org/pkg/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:

```go
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.