You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: exploration/error-handling.md
+36-62Lines changed: 36 additions & 62 deletions
Original file line number
Diff line number
Diff line change
@@ -77,57 +77,38 @@ However, `java.text.NumberFormat` provide both throwing and non-throwing
77
77
As a MessageFormat implementer, I want to be able to signal errors in an idiomatic way
78
78
for my language and still be conformant with MF2 requirements.
79
79
80
-
## Proposed Design
80
+
## Accepted Design
81
81
82
-
The following spec text is proposed:
82
+
The following design was selected in #830.
83
83
84
-
> A message formatter MUST signal errors required by this specification.
85
-
> It SHOULD provide the specific information for each error reported.
86
-
> A message formatter SHOULD provide a fallback representation of the message.
87
-
>
88
-
> [!NOTE]
89
-
> The fallback representation of a message MAY be provided by a separate API.
90
-
91
-
This solution requires implementations to be able to signal an error occurred,
92
-
which can be accomplished in different ways. Ex:
93
-
94
-
* an API that throws or returns an Error object when encountering an error
95
-
* an API that includes a read/write `ErrorCode` argument
96
-
* two APIs, a permissive one that always returns a best-effort formatted result
97
-
and a stricter one that throws or returns an Error object when encountering an error
98
-
* an API that always returns a best-effort formatted result
99
-
and sets a global `boolean` value
100
-
101
-
This does not give implementations full freedom to return _nothing_ or some other behavior.
102
-
103
-
## Alternatives Considered
84
+
### MUST signal errors and MUST provide fallback
104
85
105
-
### Separate Requirements
86
+
* Implementations MUST provide a mechanism for signaling errors. There is no specific requirement for what form signaling an error takes.
87
+
* Implementations MUST provide a mechanism for getting a fallback representation of a message that produces a formatting or selection error. Note that this can be entirely separate from the first requirement.
88
+
* An implementation is not conformant unless it provides access to both behaviors. It is compliant to do both in a single formatting attempt.
106
89
107
-
The following spec text is proposed:
90
+
> In all cases, when encountering an error,
91
+
> a message formatter MUST be able to signal an error or errors.
92
+
> It MUST also provide the appropriate fallback representation of the _message_ defined
93
+
> in this specification.
108
94
109
-
> When formatting a message with one or more errors:
110
-
> - An implementation MUST provide a way for a user to be informed
111
-
> of the name of at least one of the errors,
112
-
> either directly or via an identifying error code.
113
-
> - An implementation MUST provide a way for a message with one or more
114
-
> _Resolution Errors_ or _Message Function Errors_ to be formatted
115
-
> using a fallback representation.
116
-
>
117
-
> The two above requirements MAY be fulfilled by a single formatting method,
118
-
> or separately by more than one such method.
95
+
This alternative requires that an implementation provide both an error signal
96
+
and a means of accessing a "best-effort" fallback message.
97
+
This slightly relaxes the requirement of "returning" an error
98
+
(to allow a locally-appropriate signal of the error).
119
99
120
-
This alternative ensures that even messages with runtime errors
121
-
can be formatted with the same string representation in all implementations.
100
+
Under this alternative, implementations can be conformant by providing
101
+
two separate formatting methods or functions,
102
+
one of which returns the fallback string and one of which signals the error.
122
103
123
-
Compared to the current spec text,
124
-
the under-specified "informative error" is replaced
125
-
with a more concrete minimum requirement,
126
-
which can be fulfilled with a two-byte error code in very limited environments.
104
+
Similar to the current spec text,
105
+
this alternative requires implementations to provide useful information:
106
+
both a signal that an error occurred and a best effort message.
107
+
A downside to this alternative is that these requirements together assume that
108
+
all implementations will want to pay the cost of constructing a representative mesage
109
+
after the occurrence of an error.
127
110
128
-
The phrase "In all cases" is left out,
129
-
and the ability to fulfill the requirements separately
130
-
rather than at the same time is explicitly called out.
111
+
## Alternatives Considered
131
112
132
113
### Current spec: require information from error(s) and a representative best effort message
is to avoid additionally returning optional error codes when providing best-effort formatted results.
150
131
151
-
### Require a best-effort message value and signaling of an error
132
+
### MUST signal errors and SHOULD provide fallback
152
133
153
-
> In all cases, when encountering an error,
154
-
> a message formatter MUST be able to signal an error or errors.
155
-
> It MUST also provide the appropriate fallback representation of the _message_ defined
156
-
> in this specification.
134
+
* Implementations MUST provide a mechanism for signaling errors. There is no specific requirement for what form signaling an error takes.
135
+
* Implementations SHOULD provide a mechanism for getting a fallback representation of a message that produces a formatting or selection error. Note that this can be entirely separate from the first requirement.
136
+
* Implementations are conformant if they only signal errors.
157
137
158
-
This alternative requires that an implementation provide both an error signal
159
-
and a means of accessing a "best-effort" fallback message.
160
-
This slightly relaxes the requirement of "returning" an error
161
-
(to allow a locally-appropriate signal of the error).
138
+
### SHOULD signal errors and MUST provide fallback
162
139
163
-
Under this alternative, implementations can be conformant by providing
164
-
two separate formatting methods or functions,
165
-
one of which returns the fallback string and one of which signals the error.
140
+
* Implementations SHOULD provide a mechanism for signaling errors. There is no specific requirement for what form signaling an error takes.
141
+
* Implementations MUST provide a mechanism for getting a fallback representation of a message that produces a formatting or selection error. Note that this can be entirely separate from the first requirement.
142
+
* Implementations are conformant if they only provide a fallback representation of a message.
166
143
167
-
Similar to the current spec text,
168
-
this alternative requires implementations to provide useful information:
169
-
both a signal that an error occurred and a best effort message.
170
-
A downside to this alternative is that these requirements together assume that
171
-
all implementations will want to pay the cost of constructing a representative mesage
172
-
after the occurrence of an error.
173
144
174
-
### Allow implementations to determine all details
145
+
### Error handling is not a normative requirement
146
+
147
+
* Implementations are not required by MF2 to signal errors or to provide access to a fallback representation.
148
+
- The specification provides guidance on error conditions; on what error types exist; and what the fallback representation is.
175
149
176
150
> When encountering an error during formatting,
177
151
> a message formatter MAY provide some representation of the message,
0 commit comments