search

kdl-org / kdl

the kdl document language specifications
https://kdl.dev
Other
1.09k stars 61 forks source link

Improvements to string naming consistency #299

Closed Lucretiel closed 1 year ago

Lucretiel commented 1 year ago

This PR modifies string descriptions in SPEC.md to use more consistent language throughout. The motivating use case is the inconsistent use of "string", "quoted string", etc in various places in the spec. For instance, Property reads:

A Property [key] is composed of an Identifier or a String...

While Annotation reads:

Type annotations are written as a set of ( and ) with a single Identifier inside...

And Node reads:

Every node must have a name, which is either a legal Identifier, or a quoted String.

This led me to be briefly unsure if Type Annotations were allowed to contain quoted strings (the grammar specifies that they are). In general there don't seem to be any cases where a Bare Identifier can be used but a Raw or Quoted string can't, and as far as I know there aren't any semantic distinctions between the different string styles, so I've introduced the hierarchy proposed in #264 here and modified relevant parts of the spec to make use of it.

There are no semantic changes to KDL here, as far as I know, but I don't have any opposition to waiting for 2.0.0 or later to merge it. This PR also does not introduce any grammar changes (even to names of things); I didn't want to risk potential semantic changes, and there's already precedent for "drift" between nonterminals and the description (eg, type vs "Annotation").

Happy to entertain bikeshedding on the names here. I have a strong preference for the use of the simpler "Identifier" and "String" as categories, containing the more specifically named string types. The main name I'm unsure about is "Quoted String"; "Escaped String" might make more sense, but I disliked the implication that an "Escaped String" somehow always involves an escape, and liked the general vibe that a "Quoted String" is "basically the quoted string you're used to from other language".

Resolves #264

zkat commented 1 year ago

Thanks! These are some great clarifications, and I'm just gonna merge them, since they don't affect the spec itself at all :)