Skip to content

Define reserved identifiers #1038

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Define reserved identifiers #1038

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 7 additions & 8 deletions spec/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,20 +110,19 @@ defined for _default functions_.
> differences in implementation or changes to locale data
> (such as due to the release of new CLDR versions).

Updates to this specification will only reserve, define, or require
_function_ _identifiers_ and _function_ _option_ _identifiers_
which satisfy either of the following two requirements:
**_<dfn>Reserved identifiers</dfn>_** are those that satisfy at least one of the following conditions:

- Includes no _namespace_,
and has a _name_ consisting of characters in the ranges a-z, A-Z, and 0-9,
and the characters U+002E FULL STOP `.`, U+002D HYPHEN-MINUS `-`, and U+005F LOW LINE `_`.
- Uses a _namespace_ consisting of a single character in the ranges a-z and A-Z.

Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

Text flows much better if we add another definition:

Suggested change
**_<dfn>Custom identifiers</dfn>_** are all those identifiers that are not _reserved identifiers_:

Copy link
Member

@aphillips aphillips Feb 21, 2025

Choose a reason for hiding this comment

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

This stuff seems to belong better in syntax.md than in the body of the stability policy. We have a whole section about names and identifiers there and that's where most readers would expect to find definitions like these. Then the stability policy can focus on it's job of forbidding/permitting certain things found in the specification

Copy link
Collaborator Author

@eemeli eemeli Feb 21, 2025

Choose a reason for hiding this comment

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

I agree with Addison. Defining reserved identifier here makes sense, but going beyond that would be a bit much.

Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

I agree, in the sense that "Includes no namespace,
and has a name consisting of characters in the ranges a-z, A-Z, and 0-9,
and the characters U+002E FULL STOP ., U+002D HYPHEN-MINUS -, and U+005F LOW LINE _." should never have been just in the body; it should have had a syntax definition.

That is, I think we need to define the 'reserved identifiers' and the 'custom identifiers', and ideally they would be in the abnf and not here.

Copy link
Collaborator Author

@eemeli eemeli Feb 21, 2025

Choose a reason for hiding this comment

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

The message.abnf only includes rules that are required for the definition of the message rule. We already have some ABNF rules sprinkled elsewhere in the spec:

  • currency_code
  • number-literal
  • digit-size-option
  • integer
  • u-locale-option

Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

ok, makes sense.

All other _identifiers_ in these categories are reserved for the use of implementations or users.
Updates to this specification will only reserve, define, or require _reserved identifiers_.
All _identifiers_ other than _reserved identifiers_ are available for the use of implementations or users.
Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

Suggested change
All _identifiers_ other than _reserved identifiers_ are available for the use of implementations or users.
All _custom identifiers_ are available for the use of implementations or users.


> [!IMPORTANT]
> Implementation-defined or user-defined _functions_ and _function_ _options_
> SHOULD use a _namespace_ as part of their _identifiers_
> to help avoid collisions with other implementations.
> [!NOTE]
> Implementers and users are strongly advised to namespace all _identifiers_ used in custom _functions_,
Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

Suggested change
> Implementers and users are strongly advised to namespace all _identifiers_ used in custom _functions_,
> Implementers and users are strongly advised to only use _custom identifiers_ in custom _functions_,

Copy link
Member

@aphillips aphillips Feb 21, 2025

Choose a reason for hiding this comment

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

This changes the meaning. There are two things going on here:

  • Non-default functions should use a namespace. <- this is not normative but is good advice

They can omit the namespace by choosing names that include non-reserved identifier characters too, so separately:

  • Non-default functions should use custom identifiers

We also have to be careful to say that we mean for the function name.

{$foo :custom:function option=|option has a 'reserved' identifier which we want to encourage|}

> _options_ to _default functions_, _attributes_, and _markup_.
Comment on lines +123 to +125
Copy link
Member

@aphillips aphillips Feb 21, 2025

Choose a reason for hiding this comment

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

This is a normative change, since it removes a normative SHOULD (albeit to function authors and which cannot be tested). Why not keep the normative level intact? We can do a wording change, if desired.

I'm not sure about "markup", since we don't define markup.

We could make it a bit tighter:

Suggested change
> [!NOTE]
> Implementers and users are strongly advised to namespace all _identifiers_ used in custom _functions_,
> _options_ to _default functions_, _attributes_, and _markup_.
> [!NOTE]
> Use a namespace for all _identifiers_ defined by an implementation
> or in the _names_ of custom _functions_, _attributes_, or _markup_ defined by users.

Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

The fuzziness of 'implementation' and 'user' gets in the way here. I read 'custom' as 'not defined by this spec. I read 'users' as 'users of an implementation', including that implementation's custom functions, etc.

Copy link
Collaborator Author

@eemeli eemeli Feb 21, 2025

Choose a reason for hiding this comment

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

Given that the SHOULD is effectively untestable, I don't think changing it to "strongly advised" is that significant a change.

I'd be fine with leaving un-namespaced markup as explicitly not reserved.

Copy link
Member

@macchiati macchiati Feb 21, 2025

Choose a reason for hiding this comment

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

I'd be fine with leaving un-namespaced markup as explicitly not reserved.

I disagree: we currently don't define any standard markup, but we could in the future (same with attributes). So the same principles for functions and attributes apply.


Future versions of this specification will not introduce changes
to the data model that would result in a data model representation
Expand Down