Issues with handling of comments at the start of files #74
Description
Hi there! I came across your project when looking for a yaml formatter to use in a project and I encountered some unexpected behaviour that might be useful to you.
The project I'm contributing to the yaml is parsed using Ruby, so there are tags in the yaml to help Ruby map yaml to classes. The problems below aren't caused by those tags, but they make small problems more painful than they'd be otherwise (problem 2 below in particular).
Problem 1 - inconsistent handling of comments in files containing multiple yaml documents
If a file contains multiple yaml documents starting with --- then the comments are reordered differently at the start of the file versus elsewhere. This seems to be due to the first --- of the file being prioritised as line 1 of the output.
This file has two documents with a consistent format:
# Set.new([1,2]).to_yaml - first
--- !ruby/object:Set
hash:
1: true
2: true
# Set.new([1,2]).to_yaml - second
--- !ruby/object:Set
hash:
3: true
4: true(Adapted from https://rhnh.net/2011/01/31/yaml-tutorial/ - example shows yaml output from Ruby code)
The formatter introduces differences between the comment positions in the first and subsequent entries:
---
!ruby/object:Set
# Set.new([1,2]).to_yaml - first
hash:
1: true
2: true
# Set.new([1,2]).to_yaml - second
---
!ruby/object:Set
hash:
3: true
4: trueProblem 2 - tags being moved above comments at start of file
In the example above you can see that the first !ruby/object:Set tag is 'pulled' up to the start of the file, above the comment which was originally line 1. This can be an issue if the yaml file starts with a copyright notice (or any other comment that needs to be at the top of the file) because the tag is separated from the yaml and this obscures how the file works.
Original file:
# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Set.new([1,2]).to_yaml - first
--- !ruby/object:Set
hash:
1: true
2: true
# Set.new([1,2]).to_yaml - second
--- !ruby/object:Set
hash:
3: true
4: trueA yamlfmt moves the tag away from the yaml:
---
!ruby/object:Set
# Copyright 2022 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http:#www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# Set.new([1,2]).to_yaml - first
hash:
1: true
2: true
# Set.new([1,2]).to_yaml - second
---
!ruby/object:Set
hash:
3: true
4: trueIdeally (blocks of) comments at the start of a file would be given a special status and would still be the first lines of the file after formatting.
I appreciate you're a sole maintainer and the project is in v0.x.x at the moment, so I'm not expecting a fix in response! However I thought these examples and info about reproducing problems would be helpful to you.
Happy new year! 👋