ini-grinder/readme.md

51 lines
2.3 KiB
Markdown

# INI Gusher
Unsatisfied with the INI parsing tools provided by third-parties in the Golang ecosystem, INI Gusher aims to solve parsing and saving of INI files as simply as possible.
```go
var parser = ini.NewParser(modInfoFile)
for entry, parsed := parser.Parse(); parsed; entry, parsed = parser.Parse() {
var myValue = myValueMap[entry.Section]
switch entry.Key {
case "format":
myValue.Format = entry.Value
case "source":
myValue.Source = entry.Value
case "version":
myValue.Version = entry.Value
}
myValueMap[entry.Section] = myValue
}
if err := parser.Err(); err != nil {
return err
}
```
INI files are read into the program and parsed lazily at the key-value pair level from a Go `io.Reader` stream. This allows INI files to be read in, parsed, and decoded into a native data type with as few data transforms as possible while still retaining genercisim under the majority of use-cases.
## Design Goals
As with Golang itself, INI Gusher is fairly opinionated; The API uses incremental streaming of a file from the file-system and into the program with the goal of avoiding unnecessary data transforms. As such, it makes some assumptions about the textual encoding and how you would want to interact with it.
* The programmer would prefer to store the parsed data in a native data structure over any sort of document object model.
* Semi-colon (`;`) and hash (`#`) comments are supported but ignored by the parser.
* An INI file contains only sections, standalone keys, and key-value pairs as parsable values.
* Unquoted keys may only use alphanumerics of any case.
* Unquoted values may only use alphanumerics of any case and whitespace is only acknowledged if it is between them.
* Keys and values may be surrounded in double-quotes (`"`) to preseve trailing whitespace and allow all characters.
* Sections allow all characters between their opening and closing braces (`"[]"`).
* Whitespace is ignored everywhere else.
* The default section is an empty string (`""`).
If the above design goals suit your use-case then INI Gusher is for you.
## What is Up with the Name?
Most Golang libraries use some sort of word starting with "G" in their name and this was my attempt to follow the styleguide laid out before me.