Skip to content

Clarify that .match selectors are not declarations #750

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

Merged
merged 2 commits into from
Mar 25, 2024
Merged

Clarify that .match selectors are not declarations #750

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be0b553
Clarify that .match selectors are not declarations
eemeli Mar 25, 2024
f1c48cd
Apply suggestions from code review
eemeli Mar 25, 2024
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
20 changes: 15 additions & 5 deletions spec/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -489,6 +489,15 @@ Earlier _selectors_ in the _matcher_'s list of _selectors_ have a higher priorit
When all of the _selectors_ have been processed,
the earliest-sorted _variant_ in the remaining list of _variants_ is selected.

> [!NOTE]
> A _selector_ is not a _declaration_.
> Even when the same _function_ can be used for both formatting and selection
> of a given _operand_
> the _annotation_ that appears in a _selector_ has no effect on subsequent
> _selectors_ nor on the formatting used in _placeholders_.
Comment on lines +492 to +497
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
> [!NOTE]
> A _selector_ is not a _declaration_.
> Even when the same _function_ can be used for both formatting and selection
> of a given _operand_
> the _annotation_ that appears in a _selector_ has no effect on subsequent
> _selectors_ nor on the formatting used in _placeholders_.
> [!NOTE]
> _Expressions_, including _expressions_ that appear as _selectors_,
> have no side effects and are not _declarations_.
> That is, they do not introduce or override _variable_ names.
> This means that the _annotation_ of a _variable_ in a _selector_
> does not change what is bound to the _variable_,
> even if the same _function_ can be used for both formatting and selection
> of a given _operand_.
> The meaning of a _variable_ reference that occurs within a _variant_
> depends only on the explicit or implicit _declaration_ of that _variable_.

Just a suggestion. I think this text is difficult to understand outside the context of the discussions we've been having, and without an example. The same might be true of my suggested text. I guess if it's confusing, people will ask about it during the tech preview feedback period.

Copy link
Member

Choose a reason for hiding this comment

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

The right hand size of a .local is an expression, so your suggestion might be confusing from that respect?

Copy link
Collaborator

Choose a reason for hiding this comment

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

Doesn't seem like it to me. An expression is not a declaration; it can appear in a declaration, but not every term that an expression can appear in is a declaration. ("Term" = "subtree of the data model".)

Alternately, the text could begin with something like "Only a .local or an .input declaration can change the meaning of a variable." Though this isn't quite true, as free variables introduce what we call "implicit declarations" someplace. A .match can't contain declarations (not even implicit declarations, since the only place where an "implicit declaration" makes sense is in a context where further names can be introduced) so it's clear from that that nothing within a .match changes the meaning of any variable name.

Every phrasing I can think of is made more complicated by implicit declarations, though.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I find this suggested text harder to parse than the current succinct text.

We already have the whole surrounding formatting.md which effectively says that same thing that the note does; this is intended to clarify the situation wrt. selectors specifically, and going into details and explanations here doesn't really help with that.

Copy link
Member

Choose a reason for hiding this comment

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

@catamorphism Would you object to my merging the text as is? We're definitely coming back to the whole "resolved value" space later 😄

Copy link
Collaborator

Choose a reason for hiding this comment

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

@aphillips I don't object!

Copy link
Member

Choose a reason for hiding this comment

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

Thanks. Merging now... the end of the 45 train is coming 🚄

> To use the same value for selection and formatting,
> set its value with a `.input` or `.local` _declaration_.

This selection method is defined in more detail below.
An implementation MAY use any pattern selection method,
as long as its observable behavior matches the results of the method defined here.
Expand Down Expand Up @@ -692,10 +701,11 @@ and an `en` (English) locale,
the pattern selection proceeds as follows for this message:

```
.match {$count :number}
one {{Category match}}
1 {{Exact match}}
* {{Other match}}
.input {$count :number}
.match {$count}
one {{Category match for {$count}}}
1 {{Exact match for {$count}}}
* {{Other match for {$count}}}
```

1. For the selector:<br>
Expand All @@ -716,7 +726,7 @@ one {{Category match}}
This is then sorted as:<br>
« ( 0, `1` ), ( 1, `one` ), ( 2, `*` ) »<br>

4. The pattern `Exact match` of the most preferred `1` variant is selected.
4. The pattern `Exact match for {$count}` of the most preferred `1` variant is selected.

## Formatting

Expand Down
7 changes: 5 additions & 2 deletions spec/syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,7 +369,8 @@ match-statement = match 1*([s] selector)
> A _message_ with a _matcher_:
>
> ```
> .match {$count :number}
> .input {$count :number}
> .match {$count}
> one {{You have {$count} notification.}}
> * {{You have {$count} notifications.}}
> ```
Expand Down Expand Up @@ -408,7 +409,9 @@ There MAY be any number of additional _selectors_.
> A message with two _selectors_:
>
> ```
> .match {$numLikes :number} {$numShares :number}
> .input {$numLikes :integer}
> .input {$numShares :integer}
> .match {$numLikes} {$numShares}
> 0 0 {{Your item has no likes and has not been shared.}}
> 0 one {{Your item has no likes and has been shared {$numShares} time.}}
> 0 * {{Your item has no likes and has been shared {$numShares} times.}}
Expand Down