Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Improvements to string naming consistency #299

Merged
merged 2 commits into from
Sep 21, 2022

Conversation

Lucretiel
Copy link
Contributor

@Lucretiel Lucretiel commented Sep 20, 2022

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.

  • Identifiers may be:
    • Bare Identifiers, or
    • Strings, which may be:
      • Quoted Strings, or
      • Raw Strings.

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

This PR modifies string descriptions in SPEC.md to use more consistent language throughout, with the primary intention of removing long descriptions like "a property key is either an identifier or a string". There are no semantic changes to KDL here.
@zkat
Copy link
Member

zkat commented Sep 21, 2022

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

@zkat zkat merged commit 0b99021 into kdl-org:main Sep 21, 2022
larsgw pushed a commit that referenced this pull request Oct 2, 2022
This PR modifies string descriptions in SPEC.md to use more consistent language throughout, with the primary intention of removing long descriptions like "a property key is either an identifier or a string". There are no semantic changes to KDL here.
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Inconsistent wording between Annotations, Property Keys, and Node Names
2 participants