https://github.com/marco-m/roundtrip_ini

decode, edit and encode the INI file format, preserving comments and blank lines
https://github.com/marco-m/roundtrip_ini

go ini-file parsing roundtrip structural-editing

Last synced: 2 days ago
JSON representation

decode, edit and encode the INI file format, preserving comments and blank lines

• Host: GitHub
• URL: https://github.com/marco-m/roundtrip_ini
• Owner: marco-m
• License: mit
• Created: 2022-06-26T17:30:24.000Z (over 2 years ago)
• Default Branch: master
• Last Pushed: 2023-11-13T21:46:01.000Z (about 1 year ago)
• Last Synced: 2025-01-19T15:07:34.352Z (3 days ago)
• Topics: go, ini-file, parsing, roundtrip, structural-editing
• Language: Go
• Homepage:
• Size: 24.4 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# roundtrip_ini

[![PkgGoDev](https://pkg.go.dev/github.com/marco-m/roundtrip_ini)](https://pkg.go.dev/github.com/marco-m/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](LICENSE).

[godoc-ast]: https://pkg.go.dev/github.com/marco-m/roundtrip_ini/ast

[participle]: https://github.com/alecthomas/participle

[INI file]: https://en.wikipedia.org/wiki/INI_file

[talk, then code]: https://dave.cheney.net/2019/02/18/talk-then-code

[minimalism]: https://www.britannica.com/art/Minimalism