Skip to content

Change the "pattern selection" text #388

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 9 commits into from
Jun 19, 2023
Merged

Change the "pattern selection" text #388

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c38c453
Change the "pattern selection" text
aphillips Jun 5, 2023
3bbe62e
Address comment and make terminology consistent
aphillips Jun 6, 2023
e9bbbe1
Update formatting.md
aphillips Jun 6, 2023
9f16d58
Fix grammatical agreement problem.
aphillips Jun 6, 2023
401b751
Update spec/formatting.md
aphillips Jun 6, 2023
98ec37f
Update spec/formatting.md
aphillips Jun 6, 2023
b910a65
Update spec/formatting.md
aphillips Jun 6, 2023
6620ecf
Update spec/formatting.md
aphillips Jun 6, 2023
dcd424c
Update spec/formatting.md
aphillips Jun 6, 2023
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
56 changes: 31 additions & 25 deletions spec/formatting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,33 +31,39 @@ refer to a local variable that's defined after it in the message.

## Pattern Selection

When formatting a message with one or more _selectors_,
the _pattern_ of one of the _variants_ must be selected for formatting.

When a message has a single _selector_,
an implementation-defined method compares each key to the _selector_
and determines which of the keys match, and in what order of preference.
The list of keys passed to this implementation-defined method
does not include the catch-all key `*`.
The catch-all key `*` is treated as a match for any _selector_,
but with the lowest possible preference.

In a message with more than one _selector_,
the number of keys in each _variant_ **_must_** equal the number of _selectors_.
These correspond to _selectors_ by position.
The same implementation-defined method as above is used to compare
the corresponding key of each _variant_ to its _selector_,
to determine which of the keys match, and in what order of preference.
In order to select a single _variant_,
the full list of _variants_ will need to be filtered and sorted.
First, each _variant_ with a key that does not match its _selector_ is left out.
Then, the remaining _variants_ are sorted lexicographically by key preference,
with earlier _selectors_ having higher priority than later ones.
Finally, the highest-sorted _variant_ is selected.
When a _message_ contains a _match_ statement with one or more _expressions_,
the implementation needs to determine which _variant_ will be used
to provide the _pattern_ for the formatting operation.
This is done by ordering and filtering the available _variant_ statements according to their _key_ values
and selecting the first one.

The number of _keys_ in each _variant_ **_MUST_** equal the number of _expressions_ in the _selectors_.
Copy link
Collaborator

Choose a reason for hiding this comment

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

The styling we have in the readme for normative key words doesn't quite match this:

message-format-wg/spec/README.md

Lines 62 to 64 in 0a8281c

The key words `MAY`, `MUST`, `MUST NOT`, `OPTIONAL`, `RECOMMENDED`,
`SHOULD`, and `SHOULD NOT` in this document are to be interpreted as
described in BCP 14 [RFC2119] [RFC8174].

I don't really mind what we use, as long as we're consistent.


Each _key_ corresponds to an _expression_ in the _selectors_ by its position in the _variant_.

> For example, in this message:
> ```
> match {:one} {:two} {:three}
> when 1 2 3 { ... }
> ```
> The first _key_ `1` corresponds to the first _expression_ in the _selectors_ (`{:one}`),
> the second _key_ `2` to the second _expression_ (`{:two}`),
> and the third _key_ `3` to the third _expression_ (`{:three}`).

To determine which _variant_ best matches a given set of inputs,
each _selector_ is used in turn to order and filter the list of _variants_.

Each _variant_ with a _key_ that does not match its corresponding _selector expression_
is omitted from the list of _variants_.
The remaining _variants_ are sorted according to the _expression_'s _key_-ordering preference.
Earlier _expressions_ in the _selector_'s list of _expressions_ have a higher priority than later ones.

When all of the _selector expressions_ have been processed,
the earliest-sorted _variant_ in the remaining list of _variants_ is selected.

This selection method is defined in more detail below.
An implementation MAY use any pattern selection method,
as long as its observable behaviour matches the results of the method defined here.
An implementation **_MAY_** use any pattern selection method,
as long as its observable behavior matches the results of the method defined here.

### Resolve Selectors

Expand Down