Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit f111102

Browse files
eemeliaphillipsgibson042
authored
Refactor errors, adding section for Message Function Errors (#774)
* Refactor errors, adding section for Message Function Errors * Apply suggestions from code review Co-authored-by: Addison Phillips <[email protected]> * Apply suggestions from code review * Drop exemplary text from Formatting Error description * Drop "Bad Expression", add SHOULD for letting functions pick their error * Use "appropriate" rather than "a" for Message Function Errors Co-authored-by: Addison Phillips <[email protected]> * Apply suggestions from code review Co-authored-by: Richard Gibson <[email protected]> Co-authored-by: Addison Phillips <[email protected]> * Apply suggestions from code review Co-authored-by: Addison Phillips <[email protected]> * Drop Selection & Formatting erorrs, add Bad Selector & Bad Variant Key * Apply suggestions from code review Co-authored-by: Addison Phillips <[email protected]> --------- Co-authored-by: Addison Phillips <[email protected]> Co-authored-by: Richard Gibson <[email protected]>
1 parent 7cdea8e commit f111102

File tree

4 files changed

+107
-75
lines changed

4 files changed

+107
-75
lines changed

‎spec/README.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,7 @@
1515
1. [Syntax Errors](errors.md#syntax-errors)
1616
1. [Data Model Errors](errors.md#data-model-errors)
1717
1. [Resolution Errors](errors.md#resolution-errors)
18-
1. [Selection Errors](errors.md#selection-errors)
19-
1. [Formatting Errors](errors.md#formatting-errors)
18+
1. [Message Function Errors](errors.md#message-function-errors)
2019
1. [Registry](registry.md)
2120
1. [`registry.dtd`](registry.dtd)
2221
1. [Formatting](formatting.md)

‎spec/errors.md

Lines changed: 91 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -16,12 +16,13 @@ and MUST be emitted as soon as possible.
1616
The other error categories are only emitted during formatting,
1717
but it might be possible to detect them with validation tools.
1818

19-
During selection, an _expression_ handler MUST only emit _Resolution Errors_ and _Selection Errors_.
20-
During formatting, an _expression_ handler MUST only emit _Resolution Errors_ and _Formatting Errors_.
19+
During selection and formatting,
20+
_expression_ handlers MUST only emit _Message Function Errors_.
2121

22-
_Resolution Errors_ and _Formatting Errors_ in _expressions_ that are not used
23-
in _pattern selection_ or _formatting_ MAY be ignored,
24-
as they do not affect the output of the formatter.
22+
Implementations do not have to check for or emit _Resolution Errors_
23+
or _Message Function Errors_ in _expressions_ that are not otherwise used by the _message_,
24+
such as _placeholders_ in unselected _patterns_
25+
or _declarations_ that are never referenced during _formatting_.
2526

2627
In all cases, when encountering a runtime error,
2728
a message formatter MUST provide some representation of the message.
@@ -34,7 +35,7 @@ SHOULD prioritise _Syntax Errors_ and _Data Model Errors_ over others.
3435

3536
When an error occurs within a _selector_,
3637
the _selector_ MUST NOT match any _variant_ _key_ other than the catch-all `*`
37-
and a _Resolution Error_ or a _Selection Error_ MUST be emitted.
38+
and a _Resolution Error_ or a _Message Function Error_ MUST be emitted.
3839

3940
## Syntax Errors
4041

@@ -242,34 +243,6 @@ or for private implementation use that is not supported by the current implement
242243
> * {{The value is not one.}}
243244
> ```
244245
245-
### Invalid Expression
246-
247-
An **_<dfn>Invalid Expression</dfn>_** error occurs when a _message_ includes an _expression_
248-
whose implementation-defined internal requirements produce an error during _function resolution_
249-
or when a _function_ returns a value (such as `null`) that the implementation does not support.
250-
251-
An **_<dfn>Operand Mismatch Error</dfn>_** is an _Invalid Expression_ error that occurs when
252-
an _operand_ provided to a _function_ during _function resolution_ does not match one of the
253-
expected implementation-defined types for that function;
254-
or in which a literal _operand_ value does not have the required format
255-
and thus cannot be processed into one of the expected implementation-defined types
256-
for that specific _function_.
257-
258-
> For example, the following _message_ produces an _Operand Mismatch Error_
259-
> (a type of _Invalid Expression_ error)
260-
> because the literal `|horse|` does not match the production `number-literal`,
261-
> which is a requirement of the function `:number` for its operand:
262-
> ```
263-
> .local $horse = {horse :number}
264-
> {{You have a {$horse}.}}
265-
> ```
266-
> The following _message_ might produce an _Invalid Expression_ error if the
267-
> the function `:function` threw an exception or otherwise emitted an error
268-
> rather than returning a valid value:
269-
>```
270-
> {{This has an invalid expression {$var :function} because it has a bug in it.}}
271-
>```
272-
273246
### Unsupported Statement
274247
275248
An **_<dfn>Unsupported Statement</dfn>_** error occurs when a message includes a _reserved statement_.
@@ -282,42 +255,41 @@ An **_<dfn>Unsupported Statement</dfn>_** error occurs when a message includes a
282255
> {{The message body}}
283256
> ```
284257
285-
## Selection Errors
258+
### Bad Selector
286259
287-
**_<dfn>Selection Errors</dfn>_** occur when message selection fails.
260+
A **_<dfn>Bad Selector</dfn>_** error occurs when a message includes a _selector_
261+
with a resolved value which does not support selection.
288262
289-
> For example, attempting to format either of the following messages
290-
> might result in a _Selection Error_ if done within a context that
291-
> uses a `:number` selector function which requires its input to be numeric:
292-
>
293-
> ```
294-
> .match {|horse| :number}
295-
> 1 {{The value is one.}}
296-
> * {{The value is not one.}}
297-
> ```
263+
> For example, attempting to format this message
264+
> would result in a _Bad Selector_ error:
298265
>
299266
> ```
300-
> .local $sel = {|horse| :number}
301-
> .match {$sel}
302-
> 1 {{The value is one.}}
303-
> * {{The value is not one.}}
267+
> .local $day = {|2024-05-01| :date}
268+
> .match {$day}
269+
> * {{The due date is {$day}}}
304270
> ```
305271
306-
## Formatting Errors
272+
## Message Function Errors
273+
274+
A **_<dfn>Message Function Error</dfn>_** is any error that occurs
275+
when calling a message function implementation
276+
or which depends on validation associated with a specific function.
307277
308-
**_<dfn>Formatting Errors</dfn>_** occur during the formatting of a resolved value,
309-
for example when encountering a value with an unsupported type
310-
or an internally inconsistent set of options.
278+
Implementations SHOULD provide a way for _functions_ to emit
279+
(or cause to be emitted) any of the types of error defined in this section.
280+
Implementations MAY also provide implementation-defined _Message Function Error_ types.
311281
312282
> For example, attempting to format any of the following messages
313-
> might result in a _Formatting Error_ if done within a context that
283+
> might result in a _Message Function Error_ if done within a context that
314284
>
315-
> 1. provides for the variable reference `$user` to resolve to
285+
> 1. Provides for the variable reference `$user` to resolve to
316286
> an object `{ name: 'Kat', id: 1234 }`,
317-
> 2. provides for the variable reference `$field` to resolve to
287+
> 2. Provides for the variable reference `$field` to resolve to
318288
> a string `'address'`, and
319-
> 3. uses a `:get` formatting function which requires its argument to be an object and
320-
> an option `field` to be provided with a string value,
289+
> 3. Uses a `:get` message function which requires its argument to be an object and
290+
> an option `field` to be provided with a string value.
291+
>
292+
> The exact type of _Message Function Error_ is determined by the message function implementation.
321293
>
322294
> ```
323295
> Hello, {horse :get field=name}!
@@ -336,3 +308,64 @@ or an internally inconsistent set of options.
336308
> Your {$field} is {$id :get field=$field}
337309
> ```
338310
311+
### Bad Operand
312+
313+
A **_<dfn>Bad Operand</dfn>_** error is any error that occurs due to the content or format of the _operand_,
314+
such as when the _operand_ provided to a _function_ during _function resolution_ does not match one of the
315+
expected implementation-defined types for that function;
316+
or in which a literal _operand_ value does not have the required format
317+
and thus cannot be processed into one of the expected implementation-defined types
318+
for that specific _function_.
319+
320+
> For example, the following _messages_ each produce a _Bad Operand_ error
321+
> because the literal `|horse|` does not match the `number-literal` production,
322+
> which is a requirement of the function `:number` for its operand:
323+
>
324+
> ```
325+
> .local $horse = {|horse| :number}
326+
> {{You have a {$horse}.}}
327+
> ```
328+
>
329+
> ```
330+
> .match {|horse| :number}
331+
> 1 {{The value is one.}}
332+
> * {{The value is not one.}}
333+
> ```
334+
335+
### Bad Option
336+
337+
A **_<dfn>Bad Option</dfn>_** error is an error that occurs when there is
338+
an implementation-defined error with an _option_ or its value.
339+
These might include:
340+
- A required _option_ is missing.
341+
- Mutually exclusive _options_ are supplied.
342+
- An _option_ value provided to a _function_ during _function resolution_
343+
does not match one of the implementation-defined types or values for that _function_;
344+
or in which the literal _option_ value does not have the required format
345+
and thus cannot be processed into one of the expected
346+
implementation-defined types for that specific _function_.
347+
348+
> For example, the following _message_ might produce a _Bad Option_ error
349+
> because the literal `foo` does not match the production `digit-size-option`,
350+
> which is a requirement of the function `:number` for its `minimumFractionDigits` _option_:
351+
>
352+
> ```
353+
> The answer is {42 :number minimumFractionDigits=foo}.
354+
> ```
355+
356+
### Bad Variant Key
357+
358+
A **_<dfn>Bad Variant Key</dfn>_** error is an error that occurs when a _variant_ _key_
359+
does not match the expected implementation-defined format.
360+
361+
> For example, the following _message_ produces a _Bad Variant Key_ error
362+
> because `horse` is not a recognized plural category and
363+
> does not match the `number-literal` production,
364+
> which is a requirement of the `:number` function:
365+
>
366+
> ```
367+
> .match {42 :number}
368+
> 1 {{The value is one.}}
369+
> horse {{The value is a horse.}}
370+
> * {{The value is not one.}}
371+
> ```

‎spec/formatting.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -250,8 +250,8 @@ the following steps are taken:
250250
argument type `T` and return type `U`
251251
for implementations of functions
252252
such that `U` can be coerced to `T`.
253-
Implementations of a _function_ SHOULD emit an
254-
_Invalid Expression_ error for _operands_ whose resolved value
253+
Implementations of a _function_ SHOULD emit a
254+
_Bad Operand_ error for _operands_ whose resolved value
255255
or type is not supported.
256256
257257
> [!NOTE]
@@ -307,13 +307,13 @@ the following steps are taken:
307307
resolve the value of the _expression_ as the result of that function call.
308308
309309
If the call fails or does not return a valid value,
310-
emit a _Invalid Expression_ error.
310+
emit the appropriate _Message Function Error_ for the failure.
311311
312312
Implementations MAY provide a mechanism for the _function_ to provide
313313
additional detail about internal failures.
314314
Specifically, if the cause of the failure was that the datatype, value, or format of the
315315
_operand_ did not match that expected by the _function_,
316-
the _function_ might cause an _Operand Mismatch Error_ to be emitted.
316+
the _function_ might cause a _Bad Operand_ error to be emitted.
317317
318318
In all failure cases, use the _fallback value_ for the _expression_ as the resolved value.
319319
@@ -519,7 +519,7 @@ First, resolve the values of each _selector_:
519519
1. Else:
520520
1. Let `nomatch` be a resolved value for which selection always fails.
521521
1. Append `nomatch` as the last element of the list `res`.
522-
1. Emit a _Selection Error_.
522+
1. Emit a _Bad Selector_ error.
523523
524524
The form of the resolved values is determined by each implementation,
525525
along with the manner of determining their support for selection.
@@ -735,7 +735,7 @@ each _text_ and _placeholder_ part of the selected _pattern_ is resolved and for
735735
736736
Resolved values cannot always be formatted by a given implementation.
737737
When such an error occurs during _formatting_,
738-
an implementation SHOULD emit a _Formatting Error_ and produce a
738+
an implementation SHOULD emit an appropriate _Message Function Error_ and produce a
739739
_fallback value_ for the _placeholder_ that produced the error.
740740
A formatting function MAY substitute a value to use instead of a _fallback value_.
741741

‎spec/registry.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,7 @@ The function `:string` provides string selection and formatting.
297297
The _operand_ of `:string` is either any implementation-defined type
298298
that is a string or for which conversion to a string is supported,
299299
or any _literal_ value.
300-
All other values produce an _Invalid Expression_ error.
300+
All other values produce a _Bad Operand_ error.
301301
302302
> For example, in Java, implementations of the `java.lang.CharSequence` interface
303303
> (such as `java.lang.String` or `java.lang.StringBuilder`),
@@ -609,7 +609,7 @@ The _function_ `:integer` performs selection as described in [Number Selection](
609609
610610
The _operand_ of a number function is either an implementation-defined type or
611611
a literal whose contents match the `number-literal` production in the [ABNF](/spec/message.abnf).
612-
All other values produce an _Invalid Expression_ error.
612+
All other values produce a _Bad Operand_ error.
613613
614614
> For example, in Java, any subclass of `java.lang.Number` plus the primitive
615615
> types (`byte`, `short`, `int`, `long`, `float`, `double`, etc.)
@@ -684,7 +684,7 @@ numeric selectors perform as described below.
684684
1. Else if `key` is one of the keywords `zero`, `one`, `two`, `few`, `many`, or `other`, then
685685
1. If `key` and `keyword` consist of the same sequence of Unicode code points, then
686686
1. Append `key` as the last element of the list `resultKeyword`.
687-
1. Else, emit a _Selection Error_.
687+
1. Else, emit a _Bad Variant Key_ error.
688688
1. Return a new list whose elements are the concatenation of the elements (in order) of `resultExact` followed by the elements (in order) of `resultKeyword`.
689689
690690
> [!NOTE]
@@ -785,15 +785,15 @@ If no options are specified, this function defaults to the following:
785785
The _operand_ of the `:datetime` function is either
786786
an implementation-defined date/time type
787787
or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
788-
All other _operand_ values produce an _Invalid Expression_ error.
788+
All other _operand_ values produce a _Bad Operand_ error.
789789
790790
#### Options
791791
792792
The `:datetime` function can use either the appropriate _style options_
793793
or can use a collection of _field options_ (but not both) to control the formatted
794794
output.
795795
796-
If both are specified, an _Invalid Expression_ error MUST be emitted
796+
If both are specified, a _Bad Option_ error MUST be emitted
797797
and a _fallback value_ used as the resolved value of the _expression_.
798798
799799
> [!NOTE]
@@ -910,7 +910,7 @@ If no options are specified, this function defaults to the following:
910910
The _operand_ of the `:date` function is either
911911
an implementation-defined date/time type
912912
or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
913-
All other _operand_ values produce an _Invalid Expression_ error.
913+
All other _operand_ values produce a _Bad Operand_ error.
914914
915915
#### Options
916916
@@ -933,7 +933,7 @@ If no options are specified, this function defaults to the following:
933933
The _operand_ of the `:time` function is either
934934
an implementation-defined date/time type
935935
or a _date/time literal value_, as defined in [Date and Time Operand](#date-and-time-operands).
936-
All other _operand_ values produce an _Invalid Expression_ error.
936+
All other _operand_ values produce a _Bad Operand_ error.
937937
938938
#### Options
939939
@@ -950,7 +950,7 @@ The function `:time` has these _options_:
950950
The _operand_ of a date/time function is either
951951
an implementation-defined date/time type
952952
or a _date/time literal value_, as defined below.
953-
All other _operand_ values produce an _Invalid Expression_ error.
953+
All other _operand_ values produce a _Bad Operand_ error.
954954
955955
A **_<dfn>date/time literal value</dfn>_** is a non-empty string consisting of an ISO 8601 date,
956956
or an ISO 8601 datetime optionally followed by a timezone offset.
@@ -972,7 +972,7 @@ For more information, see [Working with Timezones](https://w3c.github.io/timezon
972972
> The [ABNF](/spec/message.abnf) and [syntax](/spec/syntax.md) of MF2
973973
> do not formally define date/time literals.
974974
> This means that a _message_ can be syntactically valid but produce
975-
> an _Operand Mismatch Error_ at runtime.
975+
> a _Bad Operand_ error at runtime.
976976
977977
> [!NOTE]
978978
> String values passed as variables in the _formatting context_'s

0 commit comments

Comments
 (0)