Pick the entry point by two questions: where the content comes from, and whether you will write it back.
On this page: Decision table · If X, use Y · Which accessor · Pitfalls · Related
| Entry point | Input | Missing file | Values come back | Can Save |
Guide | Example |
|---|---|---|---|---|---|---|
Read(path, opts...) |
a path | error | expanded, as a map[string]string |
no (you get a map, not a file) | reading, step 1 | ExampleRead |
Open(path, opts...) |
a path | empty *File, no error; Existed() is false |
raw (Get) or expanded (GetExpanded) |
yes, to Path; creates the file at 0600 |
reading, step 2 | ExampleOpen, ExampleOpen_missing |
Parse(content, opts...) |
a string | not applicable; never fails | raw or expanded | only with SaveAs, or after you set f.Path |
reading, step 3 | ExampleParse |
ParseReader(r, opts...) |
any io.Reader |
not applicable; returns the reader's error | raw or expanded | only with SaveAs, or after you set f.Path |
reading, step 3 | ExampleParseReader |
All four take the same options (WithEscapes, WithLookup, WithPlugin and the rest), so the choice of entry point never limits which features you can use.
- If your program only consumes configuration, use
Read. It isOpenfollowed byExpandedMap: one call, references resolved, comments and disabled lines skipped, duplicates collapsed to the last one. - If the file must exist (a service that cannot start without it), use
Read: a missing file is an error. WithOpen, checkf.Existed()yourself. - If you will edit and save, use
Open. Values stay raw, so saving never flattens a${reference}into a copy of its target. - If you are creating a file that may not exist yet, use
Open. A missing file opens empty, andSavecreates it with mode0600. - If the content is already in memory (an embedded fixture, a test input, a value from a secret store), use
Parse. - If the content arrives as a stream (an HTTP body, a pipe, an archive member), or the file is large, use
ParseReaderrather thanio.ReadAll+Parse: it skips one full copy of the content. It still holds the whole file in memory; nothing here streams. - If you need comments, blank lines or disabled settings, any entry point except
Readgives you a*File; walkf.Entries().
| Question | Accessor | Duplicates | Disabled lines | Example |
|---|---|---|---|---|
| What is on disk for this key? | f.Get(key) |
last wins | ignored | ExampleFile_Get |
| What does a consumer see? | f.GetExpanded(key) |
last wins | ignored | ExampleFile_GetExpanded |
| Is the key active? | f.Has(key) |
— | ignored (a disabled key is not active) | ExampleFile_Has |
| Is the key duplicated? | f.Count(key) |
counted | ignored | ExampleFile_Count |
| Which keys are set? | f.Keys() |
once each, file order | ignored | ExampleFile_Keys |
| Every active assignment, in order? | f.Pairs() |
all kept | ignored | ExampleFile_Pairs |
| The effective values, raw? | f.Map() |
last wins | ignored | ExampleFile_Map |
| The effective values, expanded? | f.ExpandedMap() |
last wins | ignored | ExampleFile_ExpandedMap |
| Which settings are turned off? | f.Disabled() |
all kept | only these | ExampleFile_Disabled |
| Which names are inherited from the environment? | f.Inherited() |
— | — | ExampleFile_Inherited |
| Every line, including comments? | f.Entries() |
all kept | included, as KindDisabledPair |
ExampleFile_Entries |
| Did the file exist, with which mode and path? | f.Existed(), f.Mode(), f.Path |
— | — | ExampleFile_Existed |
ReadandOpendiffer on a missing file.Readfails;Opensucceeds with an empty file. Code that switches from one to the other changes its error behaviour.Readstops at the first expansion error. One${VAR:?message}that is unset fails the whole call, with a*RequiredError. That is deliberate: a half-expanded map would hide which values are trustworthy. See expansion, step 8.ExpandedMap(and soRead) expands only the line that wins for each key. An overridden duplicate holding a failing${VAR:?…}is skipped, the same answerGetExpandedgives; Compose would fail on it. In library v0.1.1 and earlier the overridden line was expanded too and failed the call.- A parsed file has no path.
Saveon a file fromParseorParseReaderreturns an error until you setf.Path, or callSaveAs(path)(ExampleFile_Save_noPath). - Nothing here reads
os.Environ. Name-only lines such asHOMEare listed byInherited()but never resolved, and a${VAR}the file does not define expands to""unless you installWithLookup(os.LookupEnv). - Prose comments with
=read as disabled settings.# TODO=fixappears inDisabled(). The:form counts only when its value is one token, so# Note: rotate monthlyand# http://example.comstay comments, while# Owner: aliceis still a disabled setting (ExampleKind_pitfalls).