From bfb44278504553859bffa510e1d7b8c9a640c1d5 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 3 Jul 2023 21:46:24 +0200 Subject: [PATCH 1/4] Minor formatting fixes --- spec/formatting.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/spec/formatting.md b/spec/formatting.md index 6d956bdc1e..2af964b684 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -49,10 +49,11 @@ At a minimum, it includes: This will be passed on to formatting functions. - Information on the base directionality of the message and its _text_ tokens. - This will be used by strategies for bidirectional isolation. + This will be used by strategies for bidirectional isolation, + and can be used to set the base direction of the _message_ upon display. - A mapping of string identifiers to values, - defining variable values that may be used during _variable resolution_. + defining variable values that are available during _variable resolution_. This is often determined by a user-provided argument of a formatting function call. - The _function registry_, @@ -68,7 +69,7 @@ Implementations MAY include additional fields in their _formatting context_. _Expressions_ are used in _declarations_, _selectors_, and _patterns_. In a _declaration_, the resolved value of the _expression_ is assigned to a _variable_, -which may then be used in other _expressions_. +which is available for use by later _expressions_. As such a _variable_ MAY then be referenced in different ways, implementations SHOULD NOT immediately fully format the value for output. @@ -99,8 +100,10 @@ one of the following is used to resolve the value of the _expression_: depending on the shape of the _operand_. - Else, if the _expression_ has a _function_ _annotation_, its resolved value is defined by _function resolution_. -- Else, the _expression_ has a _reserved_ _annotation_, - and a fallback value is used as its value. +- Else, the _expression_ has a _reserved_ _annotation_. + If the _annotation_ uses a `private-start` character that the implementation supports, + its value is resolved according to the implementation's specification. + Otherwise, a fallback value is used as its value. ### Literal Resolution @@ -174,7 +177,7 @@ the following steps are taken: ### Fallback Resolution -The resolution of an _expression_ may fail in the following cases: +The resolution of an _expression_ MAY fail in the following cases: - A _variable_ _operand_ fails to resolve. - A _function_ _annotation_ fails to resolve. @@ -309,7 +312,7 @@ The method MatchSelectorKeys is determined by the implementation. It takes as arguments a resolved _selector_ value `rv` and a list of string keys `keys`, and returns a list of string keys in preferential order. The returned list must only contain unique elements of the input list `keys`, -and it may be empty. +and it MAY be empty. The most preferred key is first, with the rest sorted by decreasing preference. ### Filter Variants From 9d60067a8f082ddeccd7a6aadb83be3e9617009a Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Tue, 4 Jul 2023 09:25:13 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Addison Phillips --- spec/formatting.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec/formatting.md b/spec/formatting.md index 2af964b684..e29cbdb805 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -311,9 +311,10 @@ Next, using `res`, resolve the preferential order for all message keys: The method MatchSelectorKeys is determined by the implementation. It takes as arguments a resolved _selector_ value `rv` and a list of string keys `keys`, and returns a list of string keys in preferential order. -The returned list must only contain unique elements of the input list `keys`, -and it MAY be empty. -The most preferred key is first, with the rest sorted by decreasing preference. +The returned list MUST contain only unique elements of the input list `keys`. +The returned list MAY be empty. +The most-preferred key is first, +with each successive key appearing in order by decreasing preference. ### Filter Variants From 9c09b5340794002658d3e6c93ee7e547a6990adb Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Thu, 6 Jul 2023 11:51:11 +0300 Subject: [PATCH 3/4] Apply suggestions from code review --- spec/formatting.md | 36 ++++++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/spec/formatting.md b/spec/formatting.md index e29cbdb805..bb1f9dca9f 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -103,7 +103,7 @@ one of the following is used to resolve the value of the _expression_: - Else, the _expression_ has a _reserved_ _annotation_. If the _annotation_ uses a `private-start` character that the implementation supports, its value is resolved according to the implementation's specification. - Otherwise, a fallback value is used as its value. + Else, a Reserved Syntax error is emitted and a fallback value is used as its value. ### Literal Resolution @@ -177,15 +177,15 @@ the following steps are taken: ### Fallback Resolution -The resolution of an _expression_ MAY fail in the following cases: +A **_fallback value_** is the resolved value emitted when an _expression_ cannot be resolved. + +An _expression_ fails to resolve when: - A _variable_ _operand_ fails to resolve. - A _function_ _annotation_ fails to resolve. - The _expression_ has a _reserved_ _annotation_. -In each such case, an error MUST be emitted -and a **_fallback value_** used for the _expression_. -This value depends on the shape of the _expression_: +The _fallback value_ depends on the contents of the _expression_: - _expression_ with _literal_ _operand_: U+007C VERTICAL LINE `|` followed by the value of the Literal, @@ -497,7 +497,7 @@ when * {Other match} ## Formatting After _pattern selection_, -each _text_ and _expression_ part of the selected _pattern_ must be resolved and formatted. +each _text_ and _expression_ part of the selected _pattern_ is resolved and formatted. _Formatting_ is a mostly implementation-defined process, as it depends on the implementation's shape for resolved values @@ -695,7 +695,7 @@ These are divided into the following categories: - **Unresolved Variable errors** occur when a variable reference cannot be resolved. > For example, attempting to format either of the following messages - > must result in an Unresolved Variable error if done within a context that + > would result in an Unresolved Variable error if done within a context that > does not provide for the variable reference `$var` to be successfully resolved: > > ``` @@ -712,7 +712,7 @@ These are divided into the following categories: a reference to a function which cannot be resolved. > For example, attempting to format either of the following messages - > must result in an Unknown Function error if done within a context that + > would result in an Unknown Function error if done within a context that > does not provide for the function `:func` to be successfully resolved: > > ``` @@ -725,6 +725,26 @@ These are divided into the following categories: > when * {The value is not one.} > ``` + - **Reserved Syntax errors** occur when an expression uses syntax reserved for + future standardization, + or for private implementation use that is not supported by the current implementation. + + > For example, attempting to format this message + > would always result in an Reserved Syntax error: + > + > ``` + > {The value is {@horse}.} + > ``` + > + > Attempting to format this message would result in an Reserved Syntax error + > if done within a context that does not support the `^` private use sigil: + > + > ``` + > match {|horse| ^private} + > when 1 {The value is one.} + > when * {The value is not one.} + > ``` + - **Selection errors** occur when message selection fails. - **Selector errors** are failures in the matching of a key to a specific selector. From ea3f6e80538b8740789c9f604e949f64d5e91e03 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Fri, 7 Jul 2023 11:18:41 +0300 Subject: [PATCH 4/4] Apply suggestions from code review --- spec/formatting.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/formatting.md b/spec/formatting.md index bb1f9dca9f..6cc866a688 100644 --- a/spec/formatting.md +++ b/spec/formatting.md @@ -103,7 +103,7 @@ one of the following is used to resolve the value of the _expression_: - Else, the _expression_ has a _reserved_ _annotation_. If the _annotation_ uses a `private-start` character that the implementation supports, its value is resolved according to the implementation's specification. - Else, a Reserved Syntax error is emitted and a fallback value is used as its value. + Else, an Unsupported Expression error is emitted and a fallback value is used as its value. ### Literal Resolution @@ -725,18 +725,18 @@ These are divided into the following categories: > when * {The value is not one.} > ``` - - **Reserved Syntax errors** occur when an expression uses syntax reserved for - future standardization, + - **Unsupported Expression errors** occur when an expression uses + syntax reserved for future standardization, or for private implementation use that is not supported by the current implementation. > For example, attempting to format this message - > would always result in an Reserved Syntax error: + > would always result in an Unsupported Expression error: > > ``` > {The value is {@horse}.} > ``` > - > Attempting to format this message would result in an Reserved Syntax error + > Attempting to format this message would result in an Unsupported Expression error > if done within a context that does not support the `^` private use sigil: > > ```