Skip to content

Make File.Section stop adding missing sections, and format the package doc - #431

Merged
unknwon merged 4 commits into
v2from
v2-section-read-only
Nov 11, 2026
Merged

unknwon merged 4 commits into
v2from
v2-section-read-only

Conversation

@unknwon

@unknwon unknwon commented Nov 11, 2026 •

Copy link
Copy Markdown
Member

Two changes for the next beta.

File.Section stops adding missing sections

This matches what #429 did for Section.Key. In v1 and v2.0.0-beta.1, f.Section("server").Key("port").MustInt(8080) added an empty [server] section, so HasSection, Sections and Write saw it after a mere read.

  • For a missing name, Section returns a section that reads as empty and isn't in the file.
  • A change to one of its keys, NewKey, NewBooleanKey, SetComment or ReflectFrom adds it. f.Section(name).Key(key).SetValue(v) works as before.
  • Until it's added, reads and changes through it follow any section of that name the file gains, e.g., from NewSection, Append, Reload or another Section(name) that was changed.
  • SectionWithIndex follows the same rule. With AllowNonUniqueSections, a change adds the section after the last one of its name. Without it, any index returns the section of that name, as before.
  • Reading a missing section writes nothing, so concurrent reads are safe with Locking(false).

Key benchmarks are within noise.

The package doc is formatted

pkg.go.dev showed the overview as five plain paragraphs. It now uses Go doc comment syntax: headings (Loading, Sections and keys, Structs, Writing, Concurrency and errors), [Name] links for every identifier it names, a short loading example, and a list of the outputs Write doesn't check. The text says the same as before, plus a sentence about missing sections and keys. It now lives in its own doc.go, as is usual for a package doc this long.

Tests

  • TestFile_Section gains four subtests: reading doesn't add, each change adds (and a failed NewKey doesn't), a missing section follows the section its file gains, and a missing index of non-unique sections. The first three fail on the old code.
  • A scratch race test, with locking on and off, read missing sections from 8 goroutines and found nothing added. Concurrent changes to five new names added each once.
  • The race suite, lint and a 40-second FuzzStructMapping run pass.
  • The migration guide's Section.Key section now covers File.Section too.

File.Section and SectionWithIndex return a section that reads as empty
for a name, or an index of it, the file doesn't have. A change to one of
its keys, NewKey, NewBooleanKey, SetComment or ReflectFrom adds it. Until
then, reads and changes through it follow any section of that name and
index the file gains, as missing keys do.

Reading a missing section no longer writes to the file, so HasSection,
Sections and Write don't see it, and concurrent reads are safe with
Locking(false).
Split the overview into sections with headings, link the identifiers it
names, show a short loading example, and list the unchecked outputs.
A section SectionWithIndex added for one index no longer becomes the
section a held handle for another index reads and changes. Also list
NewBooleanKey in the File.Section doc, and note in the migration guide
that setting a key only a parent section has no longer adds the child.
@unknwon
unknwon merged commit 0706216 into v2 Nov 11, 2026
7 checks passed
@unknwon
unknwon deleted the v2-section-read-only branch November 11, 2026 18:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant