From dd2d5891cb29756c094d35a553e0b17b08728057 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 27 Mar 2024 14:25:34 -0700 Subject: [PATCH 01/15] [DESIGN] Effect of selectors on placeholders Addresses #736, #747 DO NOT REVIEW YET == WORK IN PROGRESS --- exploration/selection-declaration.md | 79 ++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 exploration/selection-declaration.md diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md new file mode 100644 index 0000000000..e271f3dff8 --- /dev/null +++ b/exploration/selection-declaration.md @@ -0,0 +1,79 @@ +# Effect of Selectors on Subsequent Placeholders + +Status: **Proposed** + +
+ Metadata +
+
Contributors
+
@aphillips
+
First proposed
+
2024-03-27
+
Pull Requests
+
#000
+
+
+ +## Objective + +_What is this proposal trying to achieve?_ + +Define what effect (if any) the _annotation_ of a _selector_ has on subsequent _placeholders_ +that access the same _operand_ value. + +## Background + +_What context is helpful to understand this proposal?_ + +In MFv2, we require that all _selectors_ have an _annotation_. + +Ideally, a _selector_ and a _formatter_ for the same _function_ operating on the same _operand_ +use the same options. + +``` +.input {$num :number minimumFractionDigits=2} +.match {$num} +one {{Unreachable in English locale}} +* {{This prints {$num} with two decimal places.}} +``` + +It is tempting to want to write this as a shorthand: + +``` +.match {$num :number minimumFractionDigits=2} +one {{Unreachable...}} +* {{This prints {$num} with two decimal places.}} +``` + +## Use-Cases + +_What use-cases do we see? Ideally, quote concrete examples._ + +**Multiple Selection Conflicts** +If a user writes multiple selectors for the same operand, which one formats the placeholder? + +``` +.match {$num :integer} {$num :number minimumFractionDigits=2} +* * {{What is printed for {$num}?}} + +.match {$num :number minimumFractionDigits=2} {$num :integer} +* * {{What is printed for {$num}?}} +``` + +## 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 they have?_ From 7e4231beb060db828115d83f2577cf9803138863 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 29 Mar 2024 08:09:27 -0700 Subject: [PATCH 02/15] Flesh out background --- exploration/selection-declaration.md | 46 ++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 13 deletions(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index e271f3dff8..bf1b20bca5 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -25,24 +25,41 @@ that access the same _operand_ value. _What context is helpful to understand this proposal?_ -In MFv2, we require that all _selectors_ have an _annotation_. +In MF2, we require that all _selectors_ have an _annotation_. +The purpose of this requirement is to help ensure that a _selector_ on a given _operand_ +is working with the same value as the _formatter_ eventually used for presentation +of that _operand_. +This is needed because the format of a value can have an effect on the grammar used +in the localized _message_. -Ideally, a _selector_ and a _formatter_ for the same _function_ operating on the same _operand_ -use the same options. +For example, in English: + +> You have 1 mile to go. +> You have 1.0 miles to go. + +These messages might be written as: ``` -.input {$num :number minimumFractionDigits=2} -.match {$num} -one {{Unreachable in English locale}} -* {{This prints {$num} with two decimal places.}} +.input {$togo :integer} +.match {$togo} +0 {{You have arrived.}} +one {{You have {$togo} mile to go.}} +* {{You have {$togo} miles to go.}} + +.input {$togo :number minimumFractionDigits=1} +.match {$togo} +0 {{You have arrived.}} +one {{Unreachable in an English locale.}} +* {{You have {$togo} miles to go.}} ``` -It is tempting to want to write this as a shorthand: +It is tempting to want to write these as a shorthand, with the _annotation_ in the _selector_: ``` -.match {$num :number minimumFractionDigits=2} -one {{Unreachable...}} -* {{This prints {$num} with two decimal places.}} +.match {$togo :integer} +0 {{You have arrived.}} +one {{You have {$togo} mile to go.}} +* {{You have {$togo} miles to go.}} ``` ## Use-Cases @@ -54,12 +71,15 @@ If a user writes multiple selectors for the same operand, which one formats the ``` .match {$num :integer} {$num :number minimumFractionDigits=2} -* * {{What is printed for {$num}?}} +* * {{Which selector formats {$num}?}} .match {$num :number minimumFractionDigits=2} {$num :integer} -* * {{What is printed for {$num}?}} +* * {{Which selector formats {$num}?}} ``` +If both formats are needed in the message, how does one reference one or the other? + + ## Requirements _What properties does the solution have to manifest to enable the use-cases above?_ From 976d39d0ecbcf2e825aca431a878681493a1cce5 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Fri, 29 Mar 2024 09:56:17 -0700 Subject: [PATCH 03/15] Add a use case --- exploration/selection-declaration.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index bf1b20bca5..5c3e7c5d9e 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -79,6 +79,16 @@ If a user writes multiple selectors for the same operand, which one formats the If both formats are needed in the message, how does one reference one or the other? +**Selection Different From Format** +We don't support selection on dates in LDML45, but it's easy to conceptualize. +How can a user write a _selector_ that doesn't mess up a _formatter_? + +``` +.input {$d :datetime skeleton=yMMMdjm} +.match {$d :datetime month=numeric} +1 {{Today is {$d} in cold cold January}} +* {{Today is {$d}}} +``` ## Requirements From e6d95556e5ca072e28228e49a2f583c4a89cb25b Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 9 Apr 2024 09:45:41 -0700 Subject: [PATCH 04/15] Adding options and more user stories --- exploration/selection-declaration.md | 134 ++++++++++++++++++++++++++- 1 file changed, 133 insertions(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 5c3e7c5d9e..d9d2e7d648 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -66,6 +66,44 @@ one {{You have {$togo} mile to go.}} _What use-cases do we see? Ideally, quote concrete examples._ +1. As a user, I want my formatting to match my selector. + This is one of the reasons why MF2 requires that selectors be annotated. + When I write a selector, the point is to choose the pattern to use as a template + for formatting the value being selected on. + Mismatches between these are undesirable. + + ``` + .match {$num :number minimumFractionDigits=1} + one {{This case can never happen in an English locale}} + * {{I expect this formats num with one decimal place: {$num}}} + ``` + +2. As a user, I want to use the least amount of MF special syntax possible. +3. As a user, I don't want to repeat formatting, particularly in large selection matrices. + ``` + .match {$num1 :integer} {$num2 :number minimumFractionDigits=1} + 0 0 {{You have {$num1 :integer} ({$num2 :number minimumFractionDigits=1}) wildebeest.}} + 0 one {{You have {$num1 :integer} ({$num2 :number minimumFractionDigits=1}) wildebeest.}} + 0 * {{You have {$num1 :integer} ({$num2 :number minimumFractionDigits=1}) wildebeest.}} + one 0 {{ }} + one one {{ }} + one * {{ }} + // more cases for other locales that use two/few/many + * 0 {{ }} + * one {{ }} + * * {{ }} + ``` + +4. As a user (especially as a translator), I don't want to have to modify + declarations and selectors to keep them in sync. + ``` + .input {$num :number minimumFractionDigits=1} + .match {$num} + * {{Shouldn't have to modify the selector}} + ``` + > Note that this is currently provided for by the spec. + + **Multiple Selection Conflicts** If a user writes multiple selectors for the same operand, which one formats the placeholder? @@ -77,9 +115,15 @@ If a user writes multiple selectors for the same operand, which one formats the * * {{Which selector formats {$num}?}} ``` -If both formats are needed in the message, how does one reference one or the other? +If both formats are needed in the message (presumably they are or why the selector), +how does one reference one or the other? **Selection Different From Format** +If a user wants to separate selection and formatting, +but selectors have a formatting side-effect, +how do I write a selector that doesn't interfere with the formatting of the _same_ operand? +(Note that users could do this using a `.local` declaration to split the operand) + We don't support selection on dates in LDML45, but it's easy to conceptualize. How can a user write a _selector_ that doesn't mess up a _formatter_? @@ -107,3 +151,91 @@ _Describe the proposed solution. Consider syntax, formatting, errors, registry, _What other solutions are available?_ _How do they compare against the requirements?_ _What other properties they have?_ + +#### Do What Comes Last + +In this alternative, selectors override declarations. + +``` +.input {$num :integer} +.match {$num :number minimumFractionDigits=1} +* {{Formats {$num} like 1.0}} +``` + +**Pros** +- ... thinking, thinking... + +**Cons** +- Violates immutability that we've established everywhere else + +#### Declaring Selectors with Immutability + +In this alternative, selectors are treated as declaration-selectors. +That is, an annotation in a selector works like a `.input`. +However, it is an error for the selector to try to modify a previous declaration +(just as it is an error for a declaration to try to modify a previous declaration). +This permits `.match` selectors to be a shorthand when no declarations exist. + +It is also an error for a selector to modify a previous selector + +``` +.match {$num :integer} +* {{Formats {$num} as integer}} + +.input {$num :integer} +.match {$num :number maximumFractionDigits=0} +* {{This message produces a Duplicate Declaration error}} + +.input {$num :integer} {$num :number} +* * {{This message produces a Duplicate Declaration error}} +``` + +**Pros** +- Shorthand version works intuitively with minimal typing + +**Cons** +- Selectors can't provide additional selection-specific options + if the value has already been annotated +- Doesn't allow multiple selection on the same operand, e.g. + ``` + .input {$date :datetime skeleton=yMdjm} + .match {$date :datetime field=month} {{$date ::datetime field=dayOfWeek} + * * {{This message produces a Duplicate Declaration error + even though selection is separate from formatting.}} + ``` + +#### Provide a `#`-like Feature + +(Copy-pasta adapted from @eemeli's proposal in #736) + +Make the `.match` expression also act as implicit declarations accessed by index position: + +``` +.match {$count :number} +one {{You have {$0} apple}} +* {{You have {$0} apples}} +``` + +Assigning values to `$0`, `$1`, ... would not conflict with any input values, +as numbers are invalid `name-start` characters. +That's by design so that we encourage at least _some_ name for each variable; +here that's effectively provided by the `.match` expressions. + +ABNF would be modified: +```diff +-variable = "$" name ++variable = "$" (name / %x30-39) +``` + +...with accompanying spec language making numeric variables resolve to the `.match` selectors in placeholders, +and a data model error otherwise. + +**Pros** +- More ergonomic for most `.input` cases +- Enables representation of many messages without any declarations + +**Cons** +- Confusing that the operand name can't be used in the pattern? + Removes some self-documentation from the pattern. +- Requires the pattern to change if the selectors are modified. +- Limits number of referenceable selectors to 10 (in the current form) From eee707101dc55db6a294fd4ed6f8654fe218faa6 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 9 Apr 2024 09:53:39 -0700 Subject: [PATCH 05/15] Fix example typo --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index d9d2e7d648..46a5da9ee2 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -199,7 +199,7 @@ It is also an error for a selector to modify a previous selector - Doesn't allow multiple selection on the same operand, e.g. ``` .input {$date :datetime skeleton=yMdjm} - .match {$date :datetime field=month} {{$date ::datetime field=dayOfWeek} + .match {$date :datetime field=month} {$date :datetime field=dayOfWeek} * * {{This message produces a Duplicate Declaration error even though selection is separate from formatting.}} ``` From 905a20db6582d45a19a7ec09efde50baf1836cba Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Thu, 11 Apr 2024 11:29:11 -0700 Subject: [PATCH 06/15] Update selection-declaration.md --- exploration/selection-declaration.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 46a5da9ee2..f0000fc64b 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -104,7 +104,7 @@ _What use-cases do we see? Ideally, quote concrete examples._ > Note that this is currently provided for by the spec. -**Multiple Selection Conflicts** +### Multiple Selection Conflicts If a user writes multiple selectors for the same operand, which one formats the placeholder? ``` @@ -118,7 +118,7 @@ If a user writes multiple selectors for the same operand, which one formats the If both formats are needed in the message (presumably they are or why the selector), how does one reference one or the other? -**Selection Different From Format** +### Selection Is Different From Format If a user wants to separate selection and formatting, but selectors have a formatting side-effect, how do I write a selector that doesn't interfere with the formatting of the _same_ operand? @@ -130,7 +130,7 @@ How can a user write a _selector_ that doesn't mess up a _formatter_? ``` .input {$d :datetime skeleton=yMMMdjm} .match {$d :datetime month=numeric} -1 {{Today is {$d} in cold cold January}} +1 {{Today is {$d} in cold cold {$d :datetime month=long}}} * {{Today is {$d}}} ``` @@ -152,9 +152,14 @@ _What other solutions are available?_ _How do they compare against the requirements?_ _What other properties they have?_ -#### Do What Comes Last +#### Allow "Declarative" Selectors with _Mutability_ -In this alternative, selectors override declarations. +In this alternative, selectors are treated as declaration-selectors. +That is, an annotation in a selector works like a `.input`. +This permits `.match` selectors to be a shorthand when no declarations exist. + +It is not an error to overwrite a previous annotation. +Instead the selector's annotation replaces what came before. ``` .input {$num :integer} @@ -163,12 +168,12 @@ In this alternative, selectors override declarations. ``` **Pros** -- ... thinking, thinking... +- Shorthand version works intuitively with minimal typing. **Cons** - Violates immutability that we've established everywhere else -#### Declaring Selectors with Immutability +#### Allow "Declarative" Selectors with _Immutability_ In this alternative, selectors are treated as declaration-selectors. That is, an annotation in a selector works like a `.input`. @@ -176,7 +181,8 @@ However, it is an error for the selector to try to modify a previous declaration (just as it is an error for a declaration to try to modify a previous declaration). This permits `.match` selectors to be a shorthand when no declarations exist. -It is also an error for a selector to modify a previous selector +It is also an error for a selector to modify a previous selector. +This implies that multiple selecton on the same operand is pointless. ``` .match {$num :integer} @@ -192,6 +198,8 @@ It is also an error for a selector to modify a previous selector **Pros** - Shorthand version works intuitively with minimal typing +- Preserves immutability +- Produces an error when users inappropriately annotate some items **Cons** - Selectors can't provide additional selection-specific options From a02cd3d6d6e39705a30a7467adf75a02b9ea71b2 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 16 Apr 2024 11:45:01 -0700 Subject: [PATCH 07/15] Update selection-declaration.md --- exploration/selection-declaration.md | 47 ++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index f0000fc64b..6004658966 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -152,6 +152,53 @@ _What other solutions are available?_ _How do they compare against the requirements?_ _What other properties they have?_ +### Allow both local and input declarative selectors with immutability + +In this alternative, we modify the syntax to allow selectors to +annotate an input variable (as with `.input`) +or assign a local variable (as with `.local`). +Either annotation is immutable and results in a Duplicate Declaration error +if it attempts to annotate a variable previously annotated. + +Example: +``` +.match {$input :function} $local = {$input :function} +* * {{This annotates {$input} and assigns {$local} a value.}} + +.match $local1 = {$input :function} $local2 = {$input :function2} +* * {{This assigns two locals}} + +.input {$input :function} +.local $local = {$input :function} +.match {$input :function} {$local :function} +* * {{This produces two duplicate declaration errors.}} +``` + +The ABNF change looks like: +```abnf +selector = expression / declaration +declaration = s variable [s] "=" [s] expression +``` + +**Pros** +- Shorthand is consistent with the rest of the syntax +- Shorthand version works intuitively with minimal input +- Preserves immutability +- Produces an error when users inappropriately annotate some items + +**Cons** +- Selectors can't provide additional selection-specific options + if the value has already been annotated +- Doesn't allow multiple selection on the same operand, e.g. + ``` + .input {$date :datetime skeleton=yMdjm} + .match {$date :datetime field=month} {$date :datetime field=dayOfWeek} + * * {{This message produces a Duplicate Declaration error + even though selection is separate from formatting.}} + ``` + However, this design does allow for a local variable to be easily created + for the purpose of selection. + #### Allow "Declarative" Selectors with _Mutability_ In this alternative, selectors are treated as declaration-selectors. From 98ff114e80c38913c67e85ca104f6a2df77b1284 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sun, 21 Apr 2024 07:39:05 -0700 Subject: [PATCH 08/15] Update exploration/selection-declaration.md Co-authored-by: Eemeli Aro --- exploration/selection-declaration.md | 31 ++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 6004658966..2bc4a2c6ed 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -259,6 +259,37 @@ This implies that multiple selecton on the same operand is pointless. even though selection is separate from formatting.}} ``` +#### Match on variables instead of expressions + +In this alternative, the `.match` syntax is simplified +to work on variable references rather than expressions: + +``` +.input {$count :number} +.match $count +one {{You have {$count} apple}} +* {{You have {$count} apples}} + +.local $empty = {$theList :isEmpty} +.match $empty +true {{You bought nothing}} +* {{You bought {$theList}!}} +``` + +The ABNF change would look like: +```diff + match-statement = match 1*([s] selector) +-selector = expression ++selector = variable +``` + +**Pros** +- Overall the syntax is simplified. +- Preserves immutability. + +**Cons** +- A separate declaration is required for each selector. + #### Provide a `#`-like Feature (Copy-pasta adapted from @eemeli's proposal in #736) From 191a9085b45ccd405a2b6be08d4304aaa60c3ba4 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Sun, 21 Apr 2024 07:51:42 -0700 Subject: [PATCH 09/15] Update exploration/selection-declaration.md Co-authored-by: Tim Chevalier --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 2bc4a2c6ed..cffb197ed2 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -156,7 +156,7 @@ _What other properties they have?_ In this alternative, we modify the syntax to allow selectors to annotate an input variable (as with `.input`) -or assign a local variable (as with `.local`). +or bind a local variable (as with `.local`). Either annotation is immutable and results in a Duplicate Declaration error if it attempts to annotate a variable previously annotated. From c19bcfaefbc4a5ba47e35ca028cd0e68ee2e7aa5 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 08:04:42 -0700 Subject: [PATCH 10/15] Address comments. --- exploration/selection-declaration.md | 92 +++++++++++++++++++--------- 1 file changed, 62 insertions(+), 30 deletions(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index cffb197ed2..807e6c5d72 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -19,7 +19,7 @@ Status: **Proposed** _What is this proposal trying to achieve?_ Define what effect (if any) the _annotation_ of a _selector_ has on subsequent _placeholders_ -that access the same _operand_ value. +that access the same _variable_. ## Background @@ -103,36 +103,41 @@ _What use-cases do we see? Ideally, quote concrete examples._ ``` > Note that this is currently provided for by the spec. +5. As a user, I want to write multiple selectors for the same operand. + How do I know which one will format the placeholder later? + ``` + .match {$num :integer} {$num :number minimumFractionDigits=2} + * * {{Which selector formats {$num}?}} -### Multiple Selection Conflicts -If a user writes multiple selectors for the same operand, which one formats the placeholder? - -``` -.match {$num :integer} {$num :number minimumFractionDigits=2} -* * {{Which selector formats {$num}?}} + .match {$num :number minimumFractionDigits=2} {$num :integer} + * * {{Which selector formats {$num}?}} + ``` -.match {$num :number minimumFractionDigits=2} {$num :integer} -* * {{Which selector formats {$num}?}} -``` + If both formats are needed in the message (presumably they are or why the selector), + how does one reference one or the other? -If both formats are needed in the message (presumably they are or why the selector), -how does one reference one or the other? -### Selection Is Different From Format -If a user wants to separate selection and formatting, -but selectors have a formatting side-effect, -how do I write a selector that doesn't interfere with the formatting of the _same_ operand? -(Note that users could do this using a `.local` declaration to split the operand) +6. As a user I want to use the same operand for both formatting and selection, + but use different functions or options for each. + I don't want the options used for selection to mess up the formatting. -We don't support selection on dates in LDML45, but it's easy to conceptualize. -How can a user write a _selector_ that doesn't mess up a _formatter_? + For example, while LDML45 doesn't support selection on dates, + it's easy to conceptualize a date selector at odds with the formatter: + ``` + .input {$d :datetime skeleton=yMMMdjm} + .match {$d :datetime month=numeric} + 1 {{Today is {$d} in cold cold {$d :datetime month=long} (trying to select on month)}} + * {{Today is {$d}}} + ``` -``` -.input {$d :datetime skeleton=yMMMdjm} -.match {$d :datetime month=numeric} -1 {{Today is {$d} in cold cold {$d :datetime month=long}}} -* {{Today is {$d}}} -``` + Note that users can achieve this effect using a `.local`: + ``` + .input {$d :datetime skeleton=yMMMdjm} + .local $monthSelect = {$d :datetime month=numeric} + .match {$monthSelect} + 1 {{No problem getting January and formatting {$d}}} + * {{...}} + ``` ## Requirements @@ -152,6 +157,30 @@ _What other solutions are available?_ _How do they compare against the requirements?_ _What other properties they have?_ +### Do nothing + +In this alternative, selectors are independent of declarations. +Selectors also do not affect the resolved value. + +Examples: +``` +.input {$n :integer} +.match {$n :number minimumFractionDigits=2} +* {{Formats '$n' as an integer: {$n}}} + +.match {$n :integer} +* {{If $n==1.2 formats {$n} as 1.2 in en-US}} +``` + +**Pros** +- No changes required. +- `.local` can be used to solve problems with variations in selection and formatting +- Supports multiple selectors on the same operand +**Cons** +- May require the user to annotate the operand for both formatting and selection. +- Can produce a mismatch between formatting and selection, since the operand's formatting + isn't visible to the selector. + ### Allow both local and input declarative selectors with immutability In this alternative, we modify the syntax to allow selectors to @@ -199,11 +228,12 @@ declaration = s variable [s] "=" [s] expression However, this design does allow for a local variable to be easily created for the purpose of selection. -#### Allow "Declarative" Selectors with _Mutability_ +### Allow _immutable_ input declarative selectors In this alternative, selectors are treated as declaration-selectors. That is, an annotation in a selector works like a `.input`. This permits `.match` selectors to be a shorthand when no declarations exist. +The option does not permit local variable declaration. It is not an error to overwrite a previous annotation. Instead the selector's annotation replaces what came before. @@ -220,7 +250,7 @@ Instead the selector's annotation replaces what came before. **Cons** - Violates immutability that we've established everywhere else -#### Allow "Declarative" Selectors with _Immutability_ +### Allow _mutable_ input declarative selectors In this alternative, selectors are treated as declaration-selectors. That is, an annotation in a selector works like a `.input`. @@ -259,10 +289,12 @@ This implies that multiple selecton on the same operand is pointless. even though selection is separate from formatting.}} ``` -#### Match on variables instead of expressions +### Match on variables instead of expressions In this alternative, the `.match` syntax is simplified -to work on variable references rather than expressions: +to work on variable references rather than expressions. +This requires users to declare any selector using a `.input` or `.local` declaration +before writing the `.match`: ``` .input {$count :number} @@ -290,7 +322,7 @@ The ABNF change would look like: **Cons** - A separate declaration is required for each selector. -#### Provide a `#`-like Feature +### Provide a `#`-like Feature (Copy-pasta adapted from @eemeli's proposal in #736) From fc7287edad5b83c8ef827a2d7fc74bb2d195a379 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 08:05:07 -0700 Subject: [PATCH 11/15] Update exploration/selection-declaration.md Co-authored-by: Tim Chevalier --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 807e6c5d72..954813b3a7 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -186,7 +186,7 @@ Examples: In this alternative, we modify the syntax to allow selectors to annotate an input variable (as with `.input`) or bind a local variable (as with `.local`). -Either annotation is immutable and results in a Duplicate Declaration error +Either variable binding is immutable and results in a Duplicate Declaration error if it attempts to annotate a variable previously annotated. Example: From 276d1f8d64ec55554c9bfc01275069fc6d1b604c Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 08:06:15 -0700 Subject: [PATCH 12/15] Update exploration/selection-declaration.md Co-authored-by: Tim Chevalier --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 954813b3a7..ea1d173381 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -217,7 +217,7 @@ declaration = s variable [s] "=" [s] expression **Cons** - Selectors can't provide additional selection-specific options - if the value has already been annotated + if the variable name is already in scope - Doesn't allow multiple selection on the same operand, e.g. ``` .input {$date :datetime skeleton=yMdjm} From 76740a34c1ed3f18debec067cf6e55e68fcd7512 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 08:13:24 -0700 Subject: [PATCH 13/15] Update exploration/selection-declaration.md Co-authored-by: Tim Chevalier --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index ea1d173381..f3ebdcbb83 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -235,7 +235,7 @@ That is, an annotation in a selector works like a `.input`. This permits `.match` selectors to be a shorthand when no declarations exist. The option does not permit local variable declaration. -It is not an error to overwrite a previous annotation. +It is not an error to re-declare a variable that is in scope. Instead the selector's annotation replaces what came before. ``` From cd1ffa6b285e91569805f4d9b91440ccff4ff9ea Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 10:40:21 -0700 Subject: [PATCH 14/15] Update exploration/selection-declaration.md Co-authored-by: Richard Gibson --- exploration/selection-declaration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index f3ebdcbb83..816034d295 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -103,7 +103,7 @@ _What use-cases do we see? Ideally, quote concrete examples._ ``` > Note that this is currently provided for by the spec. -5. As a user, I want to write multiple selectors for the same operand. +5. As a user, I want to write multiple selectors using the same variable with different annotations. How do I know which one will format the placeholder later? ``` .match {$num :integer} {$num :number minimumFractionDigits=2} From d7d095d68f0e1876633afddb3699a4a1007fdcf8 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 24 Apr 2024 11:07:40 -0700 Subject: [PATCH 15/15] Format tweak --- exploration/selection-declaration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/exploration/selection-declaration.md b/exploration/selection-declaration.md index 816034d295..3c33c2445e 100644 --- a/exploration/selection-declaration.md +++ b/exploration/selection-declaration.md @@ -176,6 +176,7 @@ Examples: - No changes required. - `.local` can be used to solve problems with variations in selection and formatting - Supports multiple selectors on the same operand + **Cons** - May require the user to annotate the operand for both formatting and selection. - Can produce a mismatch between formatting and selection, since the operand's formatting