Two families of edit methods do different jobs. Pick the family first, then the method.
On this page: Decision table · If X, use Y · Turning a setting off · Writing the result · Pitfalls · Related
| Family | Methods | Semantics | Use for | Guide | Example |
|---|---|---|---|---|---|
| Upsert | Set, SetAfter, SetBefore |
one active entry per key: an existing key is updated in place (its last occurrence), a new key is added | editing a file people maintain | editing, steps 1-2 | ExampleFile_Set, ExampleFile_SetAfter |
| Literal | Append, InsertAfter, InsertBefore with NewPair, NewComment, NewBlank |
places exactly the entries you pass, duplicates included | generating a file or a section | editing, steps 7-8 | ExampleFile_Append, ExampleFile_InsertAfter |
The difference in one line: on A=1, Set("A", "2") leaves one entry, Append(NewPair("A", "2")) leaves two, and the last one wins (ExampleFile_Append_vsSet).
- If you change a value that may or may not exist, use
Set. It returnscreated=truewhen it appended a new line. Setting the value a key already has is a true no-op: the bytes do not change (ExampleFile_Set_noop). - If a new key belongs next to related keys, use
SetAfter(anchor, key, value)orSetBefore. A missing anchor returnsErrAnchorNotFoundand changes nothing; an existing key is updated where it is and never moved (ExampleFile_SetAfter_anchorNotFound). - If you generate content with comments and blank lines, build entries with the constructors and place them with
Append(end of file) orInsertAfter/InsertBefore(next to an anchor, as one block). - If you copy entries from another file, pass entries from its
Entries()toAppendorInsert*: an attached entry is copied verbatim, byte for byte (ExampleFile_Append_verbatim). - If you derive one environment from another, use
Clone, thenSetwhat differs, thenSaveAs. References stay references, so derived values follow your edit (ExampleFile_Clone). Do not rebuild the file fromExpandedMap(): that bakes every reference (ExampleFile_Clone_baked). - If you want to pin one value on purpose, read it with
GetExpandedandSetthe result. It no longer follows its source.
| Goal | Call | Result | Undo | Example |
|---|---|---|---|---|
| Turn it off, keep it in the file | Unset(key, false) |
every line of the entry commented out | Restore(key), byte-identical |
ExampleFile_Unset, ExampleFile_Restore |
| Remove it | Unset(key, true) |
the entry is deleted | none; set it again | ExampleFile_Unset |
| See what is turned off | Disabled() |
every commented-out setting, as Pair values |
— | ExampleFile_Disabled |
Prefer Unset(key, false) for anything a person might want back: the comment above it stays attached, and the change is one line in a diff.
| Call | Writes to | Mode | Guide | Example |
|---|---|---|---|---|
Save() |
f.Path |
an existing file keeps its mode; a new file is 0600 |
saving, step 1 | ExampleFile_Save, ExampleFile_Save_mode |
SaveAs(path) |
path; f.Path is not changed |
an existing destination keeps its mode; a new one gets the source file's mode | saving, step 4 | ExampleFile_SaveAs |
Render() |
nothing; returns the bytes as a string | — | saving | ExampleParse |
Both save calls write a temp file at 0600 and rename it over the destination, so a reader never sees a half-written file.
Seton a key that is only disabled appends a new active line; the commented-out one stays. To turn the original back on, callRestoreinstead.Setre-renders the value. It keeps theexportprefix, indentation, spacing on both sides of the delimiter (A = 1becomesA = 2), the=or:delimiter and any inline comment, and it picks the quoting for the new value (ExampleFile_Set_quoting).Setstores a value literally.Set("P", "a$b")writesP='a$b', soGetExpandedgivesa$bback, before and after a reload. The one exception is a value holding both a'and a backtick: no literal quote is left, so it is double-quoted and its$stays a reference (ExampleFile_Set_dollar). In library v0.1.1 and earlier, the$was written bare and read back as a reference.Setcannot write a reference.Set("URL", "${HOST}/v1")stores the text${HOST}/v1, not a reference toHOST. To write a reference,Appenda parsed line:f.Append(dotenv.Parse("URL=${HOST}/v1\n").Entries()[0])(ExampleFile_Append_verbatim).- Duplicates: every method targets the last occurrence, because it is the one a consumer sees.
Restorealso picks the last disabled entry, which may not be the oneUnsetjust created. - Appending after an unterminated quote puts the new lines inside that value. The source was already malformed (
ExampleFile_Append_unterminatedQuote).