Skip to content

Commit

Permalink
Release v1.0.0-rc.3
Browse files Browse the repository at this point in the history
  • Loading branch information
@pradyunsg
pradyunsg committed Oct 7, 2020
1 parent 46995ba commit 3b66213
Showing 1 changed file with 1 addition and 1 deletion.
2 changes: 1 addition & 1 deletion CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# TOML Changelog

## unreleased
## 1.0.0-rc.3 / 2020-10-07

* Clarify that comments and newlines are allowed before commas in arrays.
* Mark the ABNF as canonical, and reference it from the text specification.
Expand Down

8 comments on commit 3b66213

@Torxed
Copy link

@Torxed Torxed commented on 3b66213 Oct 11, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarify that comments and newlines are allowed before commas in arrays.

I read this as comments are allowed before commas in array, such as these two examples:

obj  = ["a value", "second value" # Here is a comment, "last value"]
obj2 = [
    "a value",
    "second value" # Here is a comment,
    "last value"
]

I presume this is not the case? But the wording in the release note threw me off for a while - unless it is allowed, which seams weird as it doesn't make sense to have a comment mid-definition of something (meaning, after the defining statement but before the end of that statement).

@eksortso
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was thought that newlines after comments were obvious. A comment always extends to the end of the line. The commas that the change refers to come after the newline, like this:

obj2 = [
    "a value"
    ,"second value" # Here is a comment
    ,"last value"
]

Originally the changelog said "comments with newlines". It was changed because newlines alone, without comments, are also permitted before commas in arrays. So both comments with their newlines, and newlines on their own, are allowed before commas in arrays.

@Torxed
Copy link

@Torxed Torxed commented on 3b66213 Oct 12, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Newlines after comments are obvious to me too, it's the placement of the comma that boggled me.
I did not see any wording prohibiting the above example I showed, which is essentially what you showed @eksortso - but with a different placement of the comma.
Which makes parsing a living nightmare if it's a valid option. Although treating , as another new-line object would be a possible but would feel hacky.

The more I try to parse TOML (for fun), the more I realize that the language emphasizes easy to read over easy to ... parse with machines.

Depending on what is and was isn't allowed, I would probably strengthen the release note wording, making sure that what I wrote is not mistaken as allowed if it's not supposed to be.

@eksortso
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's true that readability is more important than easy parsing. But we did spell out the fine details in the ABNF document. Make your parser equivalent to that, and you're good to go.

@ChristianSi
Copy link
Contributor

@ChristianSi ChristianSi commented on 3b66213 Oct 12, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Torxed You do realize that every comment extends to the end of the line, don't you? You can't place a comma AFTER a comment WITHIN the same line, since it will simple become a part of the comment.

But now you can place a comma after a comment in the NEXT line, as @eksortso shows in his example. That wasn't allowed until this release, which was likely an accident and never a deliberate design decision.

@Torxed
Copy link

@Torxed Torxed commented on 3b66213 Oct 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ChristianSi I get that from reading https://toml.io/en/v1.0.0-rc.3#comment, I just felt that the commit message added double standards to where and how the comment could be placed/written. It was a very minor remark, I did not mean to cause a lot of ruckus.

@eksortso
Copy link
Contributor

@eksortso eksortso commented on 3b66213 Oct 12, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No problem, we appreciate the feedback. This helps us catch rough edges that we missed or hadn't noticed before.

The commit messages are part of the standard's development process, but they're not part of the standard itself. Those messages can afford to be a little imprecise, so long as we get the details straight on toml.io and in toml.md and toml.abnf. Likewise, the changelog provides an "at-a-glance" view of changes to a spec, but for the details, check the actual specification documents. If those are imprecise or unclear, feel free to suggest changes.

@Torxed
Copy link

@Torxed Torxed commented on 3b66213 Oct 12, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@eksortso Will do! Cheers for the quick responses.

Please sign in to comment.