From a286c85ff3e4fed3530eb4a85a299478c0552921 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 8 Dec 2023 10:18:46 -0800 Subject: [PATCH 1/8] (Design) Exact Match Selector Options In response to #433 we need to choose a name for the "exact match" selector. This isn't done yet but will serve as a foundation for choosing. --- exploration/exact-match-selector-options.md | 137 ++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 exploration/exact-match-selector-options.md diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md new file mode 100644 index 0000000000..9791d0db11 --- /dev/null +++ b/exploration/exact-match-selector-options.md @@ -0,0 +1,137 @@ +# Design Proposal Template + +Status: **Proposed** + +
+ Metadata +
+
Contributors
+
@aphillips
+
First proposed
+
2023-12-08
+
+
+ +## Objective + +_What is this proposal trying to achieve?_ + +We need to choose a name for the default "exact match" selector function. + +## Background + +_What context is helpful to understand this proposal?_ + +This addresses issue #433 +and issues raised in various design documents, notably +#471 +(about number selection). + +The default selector function is the function used when an implementation +cannot find another selector. +It is also an attribute of selectors, such as `:number` or perhaps `:date` +that need to match specific values. +ICU MF1 has a selector called `com.ibm.icu.text.SelectFormat` +associated with the keyword `select` in the MF1 syntax. + +## Use-Cases + +_What use-cases do we see? Ideally, quote concrete examples._ + +As a developer, I would like to create matches based on arbitrary enumerated string +values in a manner similar to ICU MF1's `SelectFormat`. +This allows me to use an ordinary enum or data values already present in my data +to do pattern selection. + +As a user, I would like to create numeric matches based on a specific value +not just the plural or ordinal category of the value. +This is for cases where the pattern selected is tied to the actual value +rather than just to the grammatical needs of the language. +Consider the different between the messages in: +>``` +>.match {$numChances :number} +>1 {{You have one chance left}} +>one {{You have {$numChances}} chance left}} +>* {{You have {$numChances}} chances left}} +>``` + +As an implementer, I want to create value matches that are not strictly +tied to the string serialization for data types that I know. +> For example, if a date value were serialized as +> `2023-12-08T12:00:00Z[America/Los_Angeles]` and the selector were +> `{$myDate :date dateStyle=long}` **_and_** I want to do select on the +> date value, I might want a match like this: +>``` +>.match {$myDate} +>2023-12-08 {{This only fires on this specific date}} +>* {{This fires some other time}} +>``` +>A different example that makes this clearer might be numbers. +> In the `de-DE` locale, the number `42.3` is usually formatted +> as `42,3`. Consider the message: +> ``` +> .local $myNum = {|42.3| :number minFractionDigits=1} +> .match {$myNum :equals} +> 42.3 {{This always matches} +> * {{This never matches}} +> ``` + +As a user, I want to use a selector name that makes sense and feels natural to write. + +## Requirements + +_What properties does the solution have to manifest to enable the use-cases above?_ + +## Constraints + +_What prior decisions and existing conditions limit the possible design?_ + +## Proposed Design + +_Describe the proposed solution. Consider syntax, formatting, errors, registry, tooling, interchange._ + +## Alternatives Considered + +_What other solutions are available?_ +_How do they compare against the requirements?_ +_What other properties do they have?_ + +### Option A. `:select` + +Pros: +- The same as ICU MF1's keyword. We have implementation experience. + +Cons: +- Somewhat generic name. + +### Option B. `:exact` + +Pros: +- Says what the match does. + +Cons: +- Not super specific? + +### Option C. `:equals` + +Pros: +- Says what the match does. + +Cons: +- Implies object or value equality, which may not be correct in all implementations + or programming languages. + The implications might be confusing to users in those cases. + +### Option D. `:string` + +Pros: +- Clearer about what is being compared than `select` or `exact`: + it's the string value? + +Cons: +- Not clear about + +### Option E. Something else + +It is possible that we haven't landed the best name yet. +If you don't like any of these, what **_do_** you like?!? From 5f7795259f2017d14edede6caea5b86988621865 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 11 Dec 2023 09:00:56 -0800 Subject: [PATCH 2/8] Update exact-match-selector-options.md --- exploration/exact-match-selector-options.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 9791d0db11..21b3f6009f 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -99,7 +99,9 @@ _What other properties do they have?_ ### Option A. `:select` Pros: -- The same as ICU MF1's keyword. We have implementation experience. +- The same as ICU MF1's keyword. Users have implementation experience. + Might fascilitate easier migration from MF1? +- Not overly specific, so can conceptually fit with "non-exact" matching. Cons: - Somewhat generic name. @@ -110,7 +112,9 @@ Pros: - Says what the match does. Cons: -- Not super specific? +- Unclear whether it refers to the serialization form or the imputed value. + There may be some cases where the match depends on options, + such as with `{|42.3| :integer}` and a key `42` ### Option C. `:equals` @@ -129,7 +133,10 @@ Pros: it's the string value? Cons: -- Not clear about +- Might confuse users who are comparing e.g. two numbers or two dates. + In typed languages, the values being compared might not actually be strings. +- Depends on the serialization. + ### Option E. Something else From 0028e87b9b1dbb74ae6546dc06ce09e3399d27f2 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 11 Dec 2023 13:51:41 -0800 Subject: [PATCH 3/8] Update exact-match-selector-options.md --- exploration/exact-match-selector-options.md | 22 ++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 21b3f6009f..da2d74a350 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -1,6 +1,6 @@ # Design Proposal Template -Status: **Proposed** +Status: **Accepted**
Metadata @@ -16,7 +16,7 @@ Status: **Proposed** _What is this proposal trying to achieve?_ -We need to choose a name for the default "exact match" selector function. +We need to choose a name for the selector function used when no other selector is specified. ## Background @@ -27,12 +27,10 @@ and issues raised in various design documents, notably #471 (about number selection). -The default selector function is the function used when an implementation +The exact match selector function is the function used when an implementation cannot find another selector. It is also an attribute of selectors, such as `:number` or perhaps `:date` that need to match specific values. -ICU MF1 has a selector called `com.ibm.icu.text.SelectFormat` -associated with the keyword `select` in the MF1 syntax. ## Use-Cases @@ -86,10 +84,24 @@ _What properties does the solution have to manifest to enable the use-cases abov _What prior decisions and existing conditions limit the possible design?_ +ICU MF1 has a selector called `com.ibm.icu.text.SelectFormat` +associated with the keyword `select` in the MF1 syntax. +Our design should be compatible with this selector when used for the same use case, +but it not constrained to use the same name or terminology. + ## Proposed Design _Describe the proposed solution. Consider syntax, formatting, errors, registry, tooling, interchange._ +The exact match selector is named `:string`. +The exact match selector matches the string literal value of its operand against +any sets of keys in a case-sensitive, encoding-sensitive manner. +No Unicode normalization is performed. + +The `:string` selector is also a verbatim formatting function. +That is, the message "{$var :string}" when formatted contains the resolved string +value of the variable `$var`. + ## Alternatives Considered _What other solutions are available?_ From aa5f9740a5622b9dc094282f38deb48ab0b34ab5 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 11 Dec 2023 13:57:28 -0800 Subject: [PATCH 4/8] Update exact-match-selector-options.md --- exploration/exact-match-selector-options.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index da2d74a350..8dc15c9397 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -98,6 +98,11 @@ The exact match selector matches the string literal value of its operand against any sets of keys in a case-sensitive, encoding-sensitive manner. No Unicode normalization is performed. +> [!NOTE] +> In this context "encoding-sensitive" does not mean "character encoding" +> but rather "sensitive to the sequence of code points used by the string". +> See [Character Model for the World Wide Web: String Matching](https://www.w3.org/TR/charmod-norm) + The `:string` selector is also a verbatim formatting function. That is, the message "{$var :string}" when formatted contains the resolved string value of the variable `$var`. From 7d338a7938f40abfa49d5cd7ff4e30fbfe8b95cd Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 15 Dec 2023 08:23:03 -0800 Subject: [PATCH 5/8] Update exploration/exact-match-selector-options.md --- exploration/exact-match-selector-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 8dc15c9397..4b4c8b99b1 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -16,7 +16,7 @@ Status: **Accepted** _What is this proposal trying to achieve?_ -We need to choose a name for the selector function used when no other selector is specified. +We need to choose a name for the selector function used to match keys to the string value of an operand. ## Background From 63503ef3d8795e2734d52b3a0649f6fe3e642f6f Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 15 Dec 2023 08:29:20 -0800 Subject: [PATCH 6/8] Update exploration/exact-match-selector-options.md Co-authored-by: Eemeli Aro --- exploration/exact-match-selector-options.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 4b4c8b99b1..46caa77e18 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -107,6 +107,9 @@ The `:string` selector is also a verbatim formatting function. That is, the message "{$var :string}" when formatted contains the resolved string value of the variable `$var`. +Other selectors may follow the example of `:number`, +which includes an option `select` that may take a value `exact`. + ## Alternatives Considered _What other solutions are available?_ From 20c5a6f59b6f31a116f15a525c1b6df849b25f3c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sat, 16 Dec 2023 08:51:29 -0800 Subject: [PATCH 7/8] Address comment We require annotations, so the text was inappropriate in the "background" section. Fixed it to be consistent with our policy/syntax/etc. --- exploration/exact-match-selector-options.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 46caa77e18..4a278bf053 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -27,10 +27,12 @@ and issues raised in various design documents, notably #471 (about number selection). -The exact match selector function is the function used when an implementation -cannot find another selector. -It is also an attribute of selectors, such as `:number` or perhaps `:date` -that need to match specific values. +The exact match selector function is an "all-purpose" built-in selector +for use in messages when a more specific selector (such as for numbers or +dates) is not available. +Other selectors, such as `:number` or `:datetime` +that need to match specific values provide similar functionality. +Custom selectors should model their exact-match on this selector. ## Use-Cases From 3ab707e5b3517d16d2edefe2daa9710e97a13724 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 18 Dec 2023 11:11:01 -0800 Subject: [PATCH 8/8] Change exact match selector design to "proposed" --- exploration/exact-match-selector-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/exact-match-selector-options.md b/exploration/exact-match-selector-options.md index 4a278bf053..57bc4f66e3 100644 --- a/exploration/exact-match-selector-options.md +++ b/exploration/exact-match-selector-options.md @@ -1,6 +1,6 @@ # Design Proposal Template -Status: **Accepted** +Status: **Proposed**
Metadata