Skip to content
Merged
Changes from 5 commits
Commits
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
49 changes: 43 additions & 6 deletions spec/registry.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,48 @@
# MessageFormat 2.0 Default Function Registry

This section describes the functions for which each implementation MUST provide
a _function handler_ to be conformant with this specification.

Implementations MAY implement additional _functions_ or additional _options_.
In particular, implementations are encouraged to provide feedback on proposed
_options_ and their values.
This section defines the **standard** _functions_ which are REQUIRED for conformance with this specification,
along with **optional** _functions_ that SHOULD be implemented to support
additional functionality.

To **_<dfn>accept</dfn>_** a function means that an implementation MUST NOT
emit an _Unknown Function_ error for that _function_'s _identifier_.
To _accept_ an option means that an implementation MUST NOT
emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_
it is defined for
and MUST NOT emit a _Bad Option_ error for any of the _option_ values
(both **standard** and **optional**)
defined for that _option_.
Accepting a _function_ or its _options_ does not mean that a particular output is produced.

_Functions_ can define _options_.
An _option_ can be **standard** or **optional**.

Implementations MUST _accept_ each **standard** _function_ and
MUST _accept_ all _options_ and _option_ values defined as **standard** for those _functions_.

Implementations SHOULD _accept_ each **optional** _function_.
For each such _function_, the implementation MUST accept all _options_ and _option_ values
listed as **standard** for that _function_.

Implementations SHOULD _accept_ _options_ and _option_ values that are marked as **optional**.

Implementations MAY _accept_ _functions_ not defined in this specification.
Functions not defined by any version of this specification MUST use an implementation-defined _namespace_.
In addition, implementations SHOULD provide mechanisms for users to
register and use user-defined _functions_ and their associated _functional handlers_.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Would this not mean that any user-defined function "MUST use an implementation-defined namespace"? That seems rather arbitrary.

I do not think that we ought to place any such restrictions on user-defined functions.

Copy link
Member Author

Choose a reason for hiding this comment

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

So... SHOULD use an implementation defined namespace, right?

Copy link
Collaborator

Choose a reason for hiding this comment

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

That's weird too; the namespace used by a user-defined function should be entirely user-definable, and we should continue to allow for user functions using no namespace at all.

Copy link
Member Author

Choose a reason for hiding this comment

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

Functions not defined by any version of this specification SHOULD use an implementation-defined or user-defined namespace.

Does that fix it? (I added or user-defined)

I agree with you that impls/users can do whatever they want, but we should provide guidance not to use un-namespaced functions that we don't define.

Copy link
Member Author

Choose a reason for hiding this comment

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

(mutated the text: have a look)


Implementations MAY implement additional _options_ not defined here.
Such _options_ MUST use an implementation-specific _namespace_.

Implementations MAY _accept_ additional _option_ values for _options_ defined here,
although care needs to be exercised to ensure interoperability
and to avoid collisions with future standardization.
There is no namespace mechanism for _option_ values,
however, the [stability policy](#stability-policy) for this specification
Copy link
Member

Choose a reason for hiding this comment

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

I don't see that the stability policy that this points to only allows a-z, A-Z, and 0-9 in option values. Does that mean we couldn't have a standard future function option that took fairly liberal string options like prefex=|β/γ| ?

Copy link
Member Author

@aphillips aphillips Nov 8, 2024

Choose a reason for hiding this comment

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

The stability policy says specifically:

Updates to this specification will only reserve, define, or require function names or function option names consisting of characters in the ranges a-z, A-Z, and 0-9. All other names in these categories are reserved for the use of implementations or users.

String option values can include wide ranging literals. This is meant to restrict enumerated keywords. Note too that the restriction is to option/function names, not values. We should probably consider amending this policy in an appropriate way. I will add an issue and agenda item to that effect.

Copy link
Collaborator

Choose a reason for hiding this comment

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

For clarity, we should probably update the stability policy text to refer to "identifiers" rather than "names" in that phrase.

permits only the ranges a-z, A-Z, and 0-9 in _option_ values.
Implementation-defined values SHOULD use a distinguishing character
or character sequence, such as by prefixing with a `_` U+005F LOW LINE,
to ensure that they don't collide with future standardization.
Copy link
Collaborator

Choose a reason for hiding this comment

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

If this is desirable, then we should update the stability policy to ensure that future standardization won't be able to use a _ in option values.

Copy link
Member Author

Choose a reason for hiding this comment

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

Agreed. I will make a PR for that.

Copy link
Collaborator

Choose a reason for hiding this comment

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

See #929.


> [!NOTE]
> The [Stability Policy](/spec#stability-policy) allows for updates to
Expand Down