How the dotenv library sees a file line by line: the Entry type, the six Kind values, and how to walk every entry, comments and blanks included.
On this page
- What an entry is
- Before you start
- Step 1 — Know the six kinds
- Step 2 — Read an entry's fields
- Step 3 — Walk every entry
- Step 4 — Print a kind
- Try it
- Pitfalls
- Related
A parsed File is a list of entries in file order. An entry is one logical unit: a pair (which can span several physical lines when a quoted value runs on), a comment line, a blank line, or a line the parser does not recognise. Nothing is dropped, which is why an untouched file renders back byte for byte.
The accessors in reading.md (Get, Keys, Map and the rest) only see active pairs. Walk f.Entries() when you need the rest of the file: a linter that flags disabled settings or unrecognised lines, a tool that reports "DB_USER is disabled" rather than "DB_USER is missing", or a renderer that shows comments next to values.
go get github.com/ubgo/dotenvYou need a *dotenv.File from Open, Parse or ParseReader (see reading.md).
Kind is a closed set: the parser produces nothing else.
| Kind | String() |
A line that produces it | Active? | Key |
Value |
|---|---|---|---|---|---|
KindPair |
pair |
PORT=8080, PORT: 8080, export PORT=8080 |
yes | set | decoded value |
KindComment |
comment |
# a note (first non-space character is #, and the body is not a pair) |
no | empty | empty |
KindBlank |
blank |
an empty or whitespace-only line | no | empty | empty |
KindOther |
other |
not a setting!, MY KEY=value — anything not recognised |
no | empty | empty |
KindDisabledPair |
disabled-pair |
# DEBUG=true — a comment whose body parses as a pair on one line (a : pair only when its value is one token; see Pitfalls) |
no | set | decoded value |
KindInherited |
inherited |
export AWS_REGION or HOME — a name with no delimiter and no value |
no | set | empty |
"Active" means Get, Has, Count, Keys, Pairs and Map see it. Only KindPair is active.
Here is each kind from the exact line that produces it:
// ExampleKind shows the exact line that produces each of the six kinds.
func ExampleKind() {
lines := []string{
"PORT=8080", // a pair
"# a note", // a comment
"", // a blank line
"not a setting!", // unrecognised, kept verbatim
"# DEBUG=true", // a commented-out setting
"export AWS_REGION", // a name with no value: inherited
}
f := dotenv.Parse(strings.Join(lines, "\n") + "\n")
for _, e := range f.Entries() {
fmt.Printf("%-13s %q\n", e.Kind, e.Raw[0])
}
// Output:
// pair "PORT=8080"
// comment "# a note"
// blank ""
// other "not a setting!"
// disabled-pair "# DEBUG=true"
// inherited "export AWS_REGION"
}What each kind is for:
KindPairis a setting. A key may contain letters, digits,_,.,-,[and](Docker Compose's set), and the delimiter may be=or:. Theexportprefix and the delimiter are kept when you edit the value.KindCommentis prose, kept verbatim.KindBlankis kept verbatim, whitespace included.KindOtheris a line the parser does not understand. It is preserved rather than rejected, so one stray line never makes a file unopenable. The cost is that a malformed pair is invisible toGetand friends instead of reported; see Pitfalls.KindDisabledPairis a setting somebody turned off. A line commented out by hand and one commented out byUnsetparse the same way, with one exception for an unquoted:value containing a space (see Pitfalls).f.Disabled()lists them andf.Restore(key)turns one back on (see editing.md).KindInheritedis the Compose way to say "take this variable from the process environment". The library records the name but never reads the environment;f.Inherited()lists the names so your program can decide.
Example: ExampleKind.
Entry has four exported fields:
| Field | Type | Holds |
|---|---|---|
Kind |
Kind |
which of the six kinds this is |
Raw |
[]string |
the exact physical lines, without line terminators (a CRLF file keeps its \r); one element per line, several for a multi-line value |
Key |
string |
the variable name, for KindPair, KindDisabledPair and KindInherited; empty otherwise |
Value |
string |
the decoded value, for KindPair and KindDisabledPair: quotes stripped, escapes interpreted, lines of a multi-line value joined with \n; empty otherwise |
Value is raw in the expansion sense: ${REF} is not resolved. Everything else the library needs to edit an entry without disturbing it (the export prefix, spacing, the delimiter, the inline comment, the quote style, the comment marker of a disabled pair) is kept in unexported fields.
// ExampleEntry shows the four exported fields. Raw keeps the exact physical
// lines (a multi-line value spans several), Value is the decoded value with
// quotes stripped and lines joined by \n.
func ExampleEntry() {
const content = "export CERT=\"line one\nline two\" # pem\n# DEBUG='true'\n"
f := dotenv.Parse(content)
for _, e := range f.Entries() {
fmt.Println("Kind: ", e.Kind)
fmt.Printf("Raw: %q\n", e.Raw)
fmt.Printf("Key: %q\n", e.Key)
fmt.Printf("Value: %q\n", e.Value)
}
// Output:
// Kind: pair
// Raw: ["export CERT=\"line one" "line two\" # pem"]
// Key: "CERT"
// Value: "line one\nline two"
// Kind: disabled-pair
// Raw: ["# DEBUG='true'"]
// Key: "DEBUG"
// Value: "true"
}Treat entries from Entries() as read-only. The slice and the entries are the file's own, not copies; change the file through Set, Unset, Restore, Append and Insert* so Raw stays in step with Key and Value (see editing.md).
Example: ExampleEntry.
f.Entries() returns every entry in file order. Switch on Kind to handle each one.
// ExampleFile_Entries walks every entry in file order, comments and blanks
// included. This is the view for tools that inspect structure, such as a
// linter that flags disabled settings or unrecognised lines.
func ExampleFile_Entries() {
const content = `# database
DB_HOST=localhost
# DB_USER=admin
HOME
not a setting
`
f := dotenv.Parse(content)
for _, e := range f.Entries() {
switch e.Kind {
case dotenv.KindPair:
fmt.Printf("%-13s %s=%s\n", e.Kind, e.Key, e.Value)
case dotenv.KindDisabledPair:
fmt.Printf("%-13s %s (off, would be %s)\n", e.Kind, e.Key, e.Value)
case dotenv.KindInherited:
fmt.Printf("%-13s %s (from the environment)\n", e.Kind, e.Key)
default:
fmt.Printf("%-13s %q\n", e.Kind, e.Raw[0])
}
}
// Output:
// comment "# database"
// pair DB_HOST=localhost
// disabled-pair DB_USER (off, would be admin)
// blank ""
// inherited HOME (from the environment)
// other "not a setting"
}For a quick count of one kind you do not need to walk: f.Disabled() returns the disabled pairs as []Pair, and f.Inherited() returns the inherited names, both in file order.
Example: ExampleFile_Entries.
Kind implements fmt.Stringer, so %s, %v and fmt.Println print its name instead of an integer. That keeps logs and test failures readable. A value outside the six kinds prints as Kind(n).
// ExampleKind_String prints a Kind as a name, which is what %s, %v and a log
// line show. A value outside the six kinds prints as Kind(n).
func ExampleKind_String() {
kinds := []dotenv.Kind{
dotenv.KindPair,
dotenv.KindComment,
dotenv.KindBlank,
dotenv.KindOther,
dotenv.KindDisabledPair,
dotenv.KindInherited,
dotenv.Kind(42),
}
for _, k := range kinds {
fmt.Println(k)
}
// Output:
// pair
// comment
// blank
// other
// disabled-pair
// inherited
// Kind(42)
}Example: ExampleKind_String.
Every snippet on this page is an Example function in example_read_test.go, so go test checks each printed line against its // Output: block. From the repository root:
go test -run '^Example(Kind|Kind_pitfalls|Kind_String|Entry|File_Entries)$' -v .=== RUN ExampleFile_Entries
--- PASS: ExampleFile_Entries (0.00s)
=== RUN ExampleKind
--- PASS: ExampleKind (0.00s)
=== RUN ExampleKind_pitfalls
--- PASS: ExampleKind_pitfalls (0.00s)
=== RUN ExampleKind_String
--- PASS: ExampleKind_String (0.00s)
=== RUN ExampleEntry
--- PASS: ExampleEntry (0.00s)
PASS
ok github.com/ubgo/dotenv 0.010s
Each of these lines is parsed as documented, and each still renders back byte for byte. They are surprising only if you expect a different reading.
// ExampleKind_pitfalls shows lines that parse as something other than what a
// reader might expect. Each is the documented behaviour, and each line still
// renders back byte for byte.
func ExampleKind_pitfalls() {
const content = `# TODO=fix this
# Note: rotate monthly
# Owner: alice
# http://example.com
http://example.com
MY KEY=value
`
f := dotenv.Parse(content)
for _, e := range f.Entries() {
fmt.Printf("%-13s key=%q value=%q\n", e.Kind, e.Key, e.Value)
}
fmt.Println("round trip:", f.Render() == content)
// Output:
// disabled-pair key="TODO" value="fix this"
// comment key="" value=""
// disabled-pair key="Owner" value="alice"
// comment key="" value=""
// pair key="http" value="//example.com"
// other key="" value=""
// round trip: true
}- Prose shaped like an assignment is a disabled setting.
# TODO=fix thisbecomesKindDisabledPairwith keyTODO. This is deliberate: a human skimming the file reads it the same way. It shows up inf.Disabled(), andf.Restore("TODO")would turn it into a live pair. - A commented colon line is a setting only when its value is one token.
KEY: valueis a pair, but a colon is also ordinary punctuation, so inside a comment the:form counts as a disabled pair only when the value is quoted or a single word, and does not start with//.# Note: rotate monthly(a sentence after the colon) and# http://example.com(a URL) are comments;# KEY: value,# KEY:value,# KEY: "a b"and# DB_URL: postgres://db/appare disabled pairs. The=form is not judged this way, which is why# TODO=fix thisabove is still a setting. Two consequences follow. A one-word heading such as# Owner: alicestill reads as a disabled pair. And an unquoted colon value with a space,KEY: two words, cannot be told apart from prose: afterUnset,Saveand a reload it is a plain comment thatRestorecannot find (within oneFile,UnsetthenRestorestill works). Quote such a value, or write it with=, if it must survive being commented out. In library v0.1.1 and earlier, every commented colon line was a disabled pair, soRestore("Note")could turn a sentence into a live key. - A bare URL line is a pair.
http://example.comon its own line parses as keyhttp, value//example.com. Docker Compose reads it the same way, so the library does not special-case it (pinned byTestColonDelimiter). - A key with a space is not an error.
MY KEY=valueisKindOther: kept, but invisible toGet,KeysandMap. If you want strict parsing, walkEntries()and treatKindOtheras an error yourself. - A commented-out multi-line value is several comments. Only a disabled pair whose quote closes on the same line is
KindDisabledPair;# KEY="onefollowed by# two"is twoKindCommententries, so it cannot be restored from a re-read file. KindInheritedis never resolved.HOMEhas aKeybut noValue, and a${HOME}reference to it expands to""like any unset variable. Applyos.LookupEnvoverf.Inherited()if you want Compose's behaviour.RawandValuediffer for quoted and multi-line values. Compare againstValuefor the setting, againstRawfor the bytes in the file.
Example: ExampleKind_pitfalls.
- reading.md —
Read,Open,Parseand the read accessors. - editing.md —
Unset,Restore,Disabled,Inheritedand the entry constructors. - syntax.md — every quoting, comment and escape rule.
- Feature index — every library feature with its guide and example.
- Examples:
example_read_test.go.