Preserve comments

[Aike Sass]

Hi.

I am looking for a way to preserve comments in an already existing yaml file while modifying this file. Is this possible with snakeYAML?

Thanks,
Aike

[Andrey Somov]

This is against the spec: http://yaml.org/spec/1.1/current.html#id864687

Cheers,
Andrey

[Andrey Somov]

This is against the spec: http://yaml.org/spec/1.1/current.html#id864687

Cheers,
Andrey


On Thursday, March 17, 2016 at 3:48:02 PM UTC+1, Aike Sass wrote:

[Lior Wehrli]

Hi Andrey,

Sorry to bring up this old thread. We have the same requirement as Aike. We would like our YAML processing to honor and human editing of the YAML file, within reason of course.

I've looked into the spec and found this:

At http://yaml.org/spec/1.1/current.html#id864687:
Comments are a presentation detail and must not have any effect on the serialization tree or representation graph. In particular, comments are not associated with a particular node. The usual purpose of a comment is to communicate between the human maintainers of a file. A typical example is comments in a configuration file. Comments may not appear inside scalars, but may be interleaved with such scalars inside collections.

At http://yaml.org/spec/1.1/current.html#presentation%20detail/:
The final output process is presenting the YAML serializations as a character stream in a human-friendly manner. To maximize human readability, YAML offers a rich set of stylistic options which go far beyond the minimal functional needs of simple data storage. Therefore the YAML processor is required to introduce various presentation details when creating the stream, such as the choice of node styles, how to format content, the amount of indentation, which tag handles to use, the node tags to leave unspecified, the set of directives to provide and possibly even what comments to add. While some of this can be done with the help of the application, in general this process should be guided by the preferences of the user.

As far as I can tell, none of the above prohibit that the processor preserves the presentation details it has read in from the source.

Would you consider extending snakeyaml in such a way that the presentation detail are preserved? This can, IMHO, be absolutely transparent to the API of the processor, as mandated by the spec. The importance for me is to preserve the intent of the spec: "The usual purpose of a comment is to communicate between the human maintainers of a file". Similarly, the way a user formats the YAML data (indentation, line breaks and blank linkes) is also part of human-to-human communication. The processor should strive to interfere with this communication as little as possible. At the moment however, de-serialization completely removes all that information. It is inadvisable for example, to use Snakeyaml to process YAML file maintained via a VCS as any minor mutation is very likely to change the document in an unpredictable way and make tracking the meaning of the change very hard.

Cheers,

Lior

[Andrey Somov]

Dear Lior,

please do not mix many things in one message. It makes it very difficult to discuss.

I will only answer the comments and ignore all the other requests. If you want the answer please send another question.

"Comments are a presentation detail and must not have any effect on the serialization tree or representation graph."

Well, the tree/graph is nothing but the Node tree. If the Node is completely unaware of the comments, where the comments should live in ?

If you have an idea how to solve the problem - your contribution is welcome !!!

The main challenge here is not the spec. The challenge is how to make it sound. Both for the public API and the internal implementation.

Feel free to contribute.

Cheers,

Andrey

--
You received this message because you are subscribed to a topic in the Google Groups "SnakeYAML" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/snakeyaml-core/sVJUlqr3k1U/unsubscribe.
To unsubscribe from this group and all its topics, send an email to snakeyaml-core+unsubscribe@googlegroups.com.
To post to this group, send email to snakeyaml-core@googlegroups.com.
Visit this group at https://groups.google.com/group/snakeyaml-core.
For more options, visit https://groups.google.com/d/optout.

[Joachim Durchholz]

On 01.02.2017 21:00, Andrey Somov wrote:
> /"*Comments*/*are a presentation detail
> <http://yaml.org/spec/1.1/current.html#presentation%20detail/> and must

> not have any effect on the serialization tree

> <http://yaml.org/spec/1.1/current.html#serialization/> or representation
> graph <http://yaml.org/spec/1.1/current.html#representation/>.*"

> Well, the tree/graph is nothing but the Node tree. If the Node is
> completely unaware of the comments, where the comments should live in ?
>
> If you have an idea how to solve the problem - your contribution is
> welcome !!!

Idea: store presentation details in a separate data structure.
Essentially a parse tree minus the actual data.
Merging the data back in while serializing would require a new API call,
and likely a new implementation.
Extra challenge: avoid code duplication without affecting performance
for the non-representation-preserving flow. My knee-jerk approach would
be to try subclassing, with the understanding that that road might be
bumpy with (maybe) the occasional chasm to bridge.

No contribution from me.
I see a valid and worthwhile use case (updating manually-written config
files through a program), but I have none of them on my table right now
and too many other for-fun projects.
But maybe the outline above will help somebody get into the right mood
for doing it. If you, I'll be happy, if not, I won't be disappointed :-)

[Lior Wehrli]

Thanks for your responses guys. I will investigate possible solutions with my project and will come back to you (in a separate thread) when I have a more concrete proposal.

Cheers,

Lior