pelletier/go-toml — pull request #21 by eanderton (2014-08-23 00:12:01+00:00)
Title: Element Position Support

So, this change may be a tad controversial. If you want, we can hash out a better way to do all this if the changeset doesn't fit with what you have in mind for go-toml.

The motivation for this change was that there is a real need to be able to trace where a given TOML table, and its associated keys, came from in the source file. With that information, the programmer can inform the user of semantic mistakes made in a given TOML file. As an experiment, I'm using this version of the feature on Grapnel: https://github.com/eanderton/grapnel/blob/master/src/grapnel/rewrite.go#L126 Here, this feature is used to inform the user of where they have made grammatical mistakes in regular expressions and templates in strings, that may be embedded deep within a configuration file.

The first thing I did was modify the parser to record position information from the token stream. This wound up being a parallel structure (PositionMap) that is stored alongside the TomlTree during parsing. After that, I needed a structure to couple those two together for the library user - this became the TomlDocument.

A quirk of the position storage scheme is that it was not possible to modify the TomlTree, nor the storage of key/value data, without invalidating the current API. As a result, it's necessary to use a key's parent TomlTree pointer in order to find the location of that key in the document. The TomlDocument also provides methods to query this position information using string paths, in order to parallel the path navigation available on the TomlTree itself.

----
TomlDocument provides an optional TOML processing path where position
informaiton is stored alongside a TomlTree.
* Added Position struct
* Added TomlDocument struct
* Revised parser to emit position data
* Revised LoadFile() and Load() to use revised parser
* Revised token to use new Position struct
* Added tests for new functionality
* Bugfixed table array duplicate key handling
* Applied gofmt to all code