roundtrip_ini

Decode, structural edit (replace, insert, delete) and encode the INI file format, preserving comments and blank lines.

Humans care about comments and blank lines and are confused when comments disappear or lines change place for no reason.

Module roundtrip_ini is useful when you need to do round trip editing and

• the diff is meant to be presented to a human for review.
• the output is meant to be read or written again by a human.

At the same time, roundtrip_ini acts also as a formatter / pretty-printer, introducing uniformity. Like gofmt, the formatting is not tunable.

Status

Unstable, in development, version 0.x, the API will very likely change in a breaking way.

Conformity and completeness

The INI file is an informal format and reaching conformity or completeness is not a goal of this project.

Usage and examples

The idea is to have two packages:

• Package roundtrip_ini performs high-level decoding, editing and encoding of the INI format, preserving comments and blank lines.
• Package ast performs low-level decoding, editing and encoding of the INI format, preserving comments and blank lines.

One would normally use package roundtrip_ini, reserving package ast to special cases, but currently only package ast is implemented.

• See the examples in ast/example_test.go.
• See the tests.
• See the godoc-ast API documentation for package ast, which has also the runnable examples.

Formatting

• Spurious leading newlines are removed.
• A trailing newline is added if missing.
• Leading and trailing whitespace is removed from section names: [ hello ] becomes [hello].
• Properties are written as foo = 42 (one space around the equal sign).

See TestRoundTripCornerCases and TestRoundTripPrettyPrint for details.

Comments and blank lines

Comments and blank lines are preserved as follows.

• A comment is just above a section title or above a property. A comment can be multi-line.
• Blank lines are just below a section title or below a property.

See the tests for details.

Contributing

Please, before working on a PR, open an issue to discuss your use case.

This helps to better understand the pros and cons of a change and not to waste your time (and mine) developing a feature that for some reason doesn't fit well with the spirit of the project or could be implemented differently.

This is in the spirit of minimalism and talk, then code.

Credits

Thanks to participle, a parser and lexer generator.

License

This code is released under the MIT license, see file LICENSE.