Repository navigation
Make File.Section stop adding missing sections, and format the package doc - #431
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes for the next beta.
File.Sectionstops adding missing sectionsThis matches what #429 did for
Section.Key. In v1 andv2.0.0-beta.1,f.Section("server").Key("port").MustInt(8080)added an empty[server]section, soHasSection,SectionsandWritesaw it after a mere read.Sectionreturns a section that reads as empty and isn't in the file.NewKey,NewBooleanKey,SetCommentorReflectFromadds it.f.Section(name).Key(key).SetValue(v)works as before.NewSection,Append,Reloador anotherSection(name)that was changed.SectionWithIndexfollows the same rule. WithAllowNonUniqueSections, a change adds the section after the last one of its name. Without it, any index returns the section of that name, as before.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 outputsWritedoesn't check. The text says the same as before, plus a sentence about missing sections and keys. It now lives in its owndoc.go, as is usual for a package doc this long.Tests
TestFile_Sectiongains four subtests: reading doesn't add, each change adds (and a failedNewKeydoesn'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.FuzzStructMappingrun pass.Section.Keysection now coversFile.Sectiontoo.