Representation Hints

[zml2008]

On the quest for perfect round-tripping of configurations, it turns out many configuration formats have multiple ways to represent a single value type. Right now we don't keep track of how the loaded file represented its information, and when writing rely on the underlying libraries to choose how to represent the data. Often the libraries don't make choices that users like.

To resolve this, each configuration node will have to have metadata describing how it should be represented. While some keys may be provided in a common form, the loaders will decide which ones they work with. Unsupported keys must be accepted and ignored -- this provides a place to include node metadata that will not be directly serialized.

Some examples of representation hints are:

• YAML flow style -- block|flow|auto
• JSON: pretty printed or not
• HOCON and YAML strings: One line with escaped newlines, or a block of text?
• TOML: Inline or block syntax
• any format: line spacing between entries? maybe?

Some example of things that may be representation hints:

• a header, because it's not directly part of the node, but maybe not because it is content that is written to the file

Some things that are not representation hints are:

• Comments -> these are part of the node's data

Implementing representation hints provides a path to resolving issues like #96 and #145

Further question: how much would representation hints take away from information that is currently in ConfigurationOptions? While ConfigurationOptions has more global information, some of it could be applicable.