Skip to content
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.

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

Add <when> to help select the right <match> #558

Closed
wants to merge 7 commits into from
Closed
Show file tree
Hide file tree
Changes from 3 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
15 changes: 13 additions & 2 deletions spec/registry.dtd
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
position (open|close|standalone) "standalone"
>

<!ELEMENT matchSignature (input?,option*,match*,override*)>
<!ELEMENT matchSignature (input?,option*,override*,when*,matches?)>

<!ELEMENT input EMPTY>
<!ATTLIST input
Expand All @@ -37,11 +37,22 @@
readonly (true|false) "false"
>

<!ELEMENT matches (match*)>
<!ATTLIST matches
href CDATA #IMPLIED
validationRule IDREF #IMPLIED
>

<!ELEMENT match EMPTY>
<!ATTLIST match
locales NMTOKENS #IMPLIED
values NMTOKENS #IMPLIED
validationRule IDREF #IMPLIED
>

<!ELEMENT when (when*,matches?)>
<!ATTLIST when
option NMTOKEN #REQUIRED
values NMTOKENS #REQUIRED
>

<!ELEMENT override (input?,option*)>
Expand Down
67 changes: 51 additions & 16 deletions spec/registry.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,33 @@ the corresponding input and options rules.
If multiple `<override>` elements would match the current locale,
only the first one is used.

Matching-function signatures additionally include one or more `<match>` elements
to define the keys against which they can match when used as selectors.
### Variant Key Matches

Matching-function signatures can include `<matches>` and `<when>` elements
eemeli marked this conversation as resolved.
Show resolved Hide resolved
defining the variant keys matched by the selector.

Each `<matches>` MAY contain either one or more `<match>` elements, or an `href` attribute.
eemeli marked this conversation as resolved.
Show resolved Hide resolved
If an `href` attribute is set, its URL value MUST resolve to an XML document
with a root `<matches>` element with no `href` attribute,
Copy link
Member

Choose a reason for hiding this comment

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

Why not permit chaining?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Because we've no reason to, and this way we can rely on the external matches XML to resolve all of its dependencies completely.

Copy link
Member

Choose a reason for hiding this comment

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

So there are no cases in which part of a <matches> tree in the external XML refers to (say) CLDR data? Once you've implemented resolving an external file, it's just a question of recursion, no?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

So there are no cases in which part of a <matches> tree in the external XML refers to (say) CLDR data?

Correct. A <matches> can only contain <match> elements, which may only have locales and values attributes, and are otherwise empty. So there's no space for recursion.

which will then replace the current `<matches>` element for all later processing.
If `<matches>` contains any child elements, its `href` attribute is ignored.
Otherwise, if `<matches>` contains an `href` attribute, its `validationRule` attribute is ignored.
eemeli marked this conversation as resolved.
Show resolved Hide resolved

The `<match>` element whose `locales` best matches the current locale
using resource item [lookup](https://unicode.org/reports/tr35/#Lookup) from LDML is used.
An element with no `locales` attribute is the default
(and is considered equivalent to the `root` locale).

As the available keys may depend on option values,
eemeli marked this conversation as resolved.
Show resolved Hide resolved
`<when>` elements can be used to select an appropriate `<matches>` element for selection.
If the resolved or default value of a selector option
corresponding to the `<when>` `option` attribute
is included in its list of `values`,
its contents are considered before any and all later `<when>` and `<matches>` elements.
If a `<matches>` element within a `<when>` has a `<match>` for the current locale,
later `<matches>` elements outside that `<when>` are not considered.
eemeli marked this conversation as resolved.
Show resolved Hide resolved

### Function Aliases

Functions may also include `<alias>` definitions,
which provide shorthands for commonly used option baskets.
Expand Down Expand Up @@ -104,15 +129,25 @@ For the sake of brevity, only `locales="en"` is considered.

<matchSignature>
<input validationRule="anyNumber"/>
<option name="type" values="cardinal ordinal"/>
<option name="select" values="plural ordinal" default="plural"/>
<option name="minimumIntegerDigits" validationRule="positiveInteger"/>
<option name="minimumFractionDigits" validationRule="positiveInteger"/>
<option name="maximumFractionDigits" validationRule="positiveInteger"/>
<option name="minimumSignificantDigits" validationRule="positiveInteger"/>
<option name="maximumSignificantDigits" validationRule="positiveInteger"/>
<!-- Since this applies to both cardinal and ordinal, all plural options are valid. -->
<match locales="en" values="one two few other" validationRule="anyNumber"/>
<match values="zero one two few many other" validationRule="anyNumber"/>
<when option="select" values="plural">
<matches validationRule="anyNumber">
<match locales="en" values="one other"/>
</matches>
</when>
<when option="select" values="ordinal">
<matches validationRule="anyNumber">
<match locales="en" values="one two few other"/>
</matches>
</when>
<matches validationRule="anyNumber">
<match values="zero one two few many other"/>
</matches>
</matchSignature>

<formatSignature>
Expand Down Expand Up @@ -144,18 +179,18 @@ Given the above description, the `:number` function is defined to work both in a
```

Furthermore,
`:number`'s `<matchSignature>` contains two `<match>` elements
`:number`'s `<matchSignature>` contains multiple `<matches>` and `<when>` elements
which allow the validation of variant keys.
The element whose `locales` best matches the current locale
using resource item [lookup](https://unicode.org/reports/tr35/#Lookup) from LDML is used.
An element with no `locales` attribute is the default
(and is considered equivalent to the `root` locale).

- `<match locales="en" values="one two few other" .../>` can be used in locales like `en` and `en-GB`
to validate the `when other` variant by verifying that the `other` key is present
in the list of enumarated values: `one other`.
- `<match ... validationRule="anyNumber"/>` can be used to valide the `when 1` variant
by testing the `1` key against the `anyNumber` regular expression defined in the registry file.
- `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be plural
to validate that only `one`, `other` or numeric keys are used for variants.
Comment on lines +185 to +187
Copy link
Member

Choose a reason for hiding this comment

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

I think we might want to make these into examples. And I think we might want to avoid "validate that only". Perhaps:

Suggested change
- `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be plural
to validate that only `one`, `other` or numeric keys are used for variants.
> For example,
> `<when option="select" values="plural"><matches><match locales="en" values="one other" ... />`
> could be used when validating translations for locales such as `en` and `en-GB`
> to check that variant keys `one` and `other` have been provided
> (in addition to any numeric keys).

- `<when option="select" values="ordinal"><matches><match locales="en" values="one two few other" ... />`
can be used in locales like `en` and `en-GB` if the selection type is known to be ordinal
to validate that only `one`, `two`, `few`, `other` or numeric keys are used for variants.
- `<matches validationRule="anyNumber"><match values="zero one two few many other"/>` can be used
for all locales and selection types, validating that variant keys are either numeric
or use one of the plural category identifiers.

---

Expand Down