Define _option value_ and _digit size option_ (#1039)

* Define _option value_ and _digit size option_

* Apply suggestions from code review

Co-authored-by: Addison Phillips <[email protected]>

* Apply suggestions from code review

---------

Co-authored-by: Addison Phillips <[email protected]>

Author: eemeli

spec/errors.md

@@ -347,13 +347,13 @@ for that specific _function_.
 #### Bad Option
 
 A **_<dfn>Bad Option</dfn>_** error is an error that occurs when there is
-an implementation-defined error with an _option_ or its value.
+an implementation-defined error with an _option_ or an _option value_.
 These might include:
 - A required _option_ is missing.
 - Mutually exclusive _options_ are supplied.
-- An _option_ value provided to a _function_ during _function resolution_
+- An _option value_ provided to a _function_ during _function resolution_
    does not match one of the implementation-defined types or values for that _function_;
-   or in which the literal _option_ value does not have the required format
+   or in which the _string value_ of an _option_ does not have the required format
    and thus cannot be processed into one of the expected
    implementation-defined types for that specific _function_.
 
@@ -386,5 +386,5 @@ does not match the expected implementation-defined format.
 #### Unsupported Operation
 
 A **_<dfn>Unsupported Operation</dfn>_** error is an implementation-specific error
-that occurs when a given _option_, _option_ value, _operand_ value, or some combination
+that occurs when a given _option_, _option value_, _operand_, or some combination
 of these are incompatible or not supported by a given _function_ or its _function handler_.

spec/formatting.md

@@ -137,17 +137,12 @@ as well as a flag to indicate whether
 its formatted representation requires isolation
 from the surrounding text.
 
-For each _option_ value, the _resolved value_ MUST indicate if the value
+For each _option value_, the _resolved value_ MUST indicate if the value
 was directly set with a _literal_, as opposed to being resolved from a _variable_.
 This is to allow _functions handlers_ to require specific _options_ to be set using _literals_.
 
 > For example, the _default functions_ `:number` and `:integer` require that the _option_
-> `select` be set with a _literal_ (`plural`, `ordinal`, or `exact`). 
-> Allowing a _variable_ in this _option_ would produce a _message_ that 
-> is impossible to translate because the set of _keys_ is tied to the _selector_ chosen.
-
-> [!NOTE]
-> Such information is irrelevant for _resolved values_ not used as the value of an _option_.
+> `select` be set with a _literal_ _option value_ (`plural`, `ordinal`, or `exact`). 
 
 The form that _resolved values_ take is implementation-dependent,
 and different implementations MAY choose to perform different levels of resolution.
@@ -177,7 +172,7 @@ and different implementations MAY choose to perform different levels of resoluti
 >   calling the `selectKeys(keys)` method of its _resolved value_
 >   did not emit an error.
 > - Using a _variable_, the _resolved value_ of an _expression_
->   could be used as an _operand_ or _option_ value if
+>   could be used as an _operand_ or _option value_ if
 >   calling the `getValue()` method of its _resolved value_ did not emit an error.
 >   In this use case, the `resolvedOptions()` method could also
 >   provide a set of option values that could be taken into account by the called function.
@@ -246,8 +241,7 @@ Its _resolved value_ is defined by _literal resolution_.
 the character sequence of the _text_ or _literal_
 after any character escape has been converted to the escaped character.
 
-When a _literal_ is used as an _operand_
-or on the right-hand side of an _option_,
+When a _literal_ is used as an _operand_ or as an _option value_,
 the formatting function MUST treat its _resolved value_ the same
 whether its value was originally a _quoted literal_ or an _unquoted literal_.
 
@@ -329,15 +323,15 @@ the following steps are taken:
    - The resolved mapping of _options_.
    - If the _expression_ includes an _operand_, its _resolved value_.
 
-   The form that resolved _operand_ and _option_ values take is implementation-defined.
+   The form that resolved _operand_ and _option values_ take is implementation-defined.
 
    An implementation MAY pass additional arguments to the _function handler_,
    as long as reasonable precautions are taken to keep the function interface
    simple and minimal, and avoid introducing potential security vulnerabilities.
 
 6. If the call succeeds,
    resolve the value of the _expression_ as the result of that function call.
-   The value MUST NOT be marked as a literal option value.
+   The value MUST NOT be marked as a _literal_ _option value_.
 
    If the call fails or does not return a valid value,
    emit the appropriate _Message Function Error_ for the failure.
@@ -363,7 +357,7 @@ An implementation MAY allow custom functions to be defined by users.
 Implementations that provide a means for defining custom functions
 MUST provide a means for _function handlers_
 to return _resolved values_ that contain enough information
-to be used as _operands_ or _option_ values in subsequent _expressions_.
+to be used as _operands_ or _option values_ in subsequent _expressions_.
 
 The _resolved value_ returned by a _function handler_
 MAY be different from the value of the _operand_ of the _function_.
@@ -399,12 +393,12 @@ For each _option_:
 1. Let `res` be a new empty mapping.
 1. For each _option_:
    1. Let `id` be the string value of the _identifier_ of the _option_.
-   1. Let `rv` be the _resolved value_ of the _option_ value.
+   1. Let `rv` be the _resolved value_ of the _option value_.
    1. If `rv` is a _fallback value_:
       1. If supported, emit a _Bad Option_ error.
    1. Else:
-      1. If the _option_ value consists of a _literal_:
-         1. Mark `rv` as a literal option value.
+      1. If the _option value_ consists of a _literal_:
+         1. Mark `rv` as a _literal_ _option value_.
       1. Set `res[id]` to be `rv`.
 1. Return `res`.
 
@@ -428,7 +422,7 @@ The _resolved value_ of _markup_ includes the following fields:
 
 - The type of the markup: open, standalone, or close
 - The _identifier_ of the _markup_
-- The resolved _options_ values after _option resolution_.
+- The resolved mapping of _options_ after _option resolution_.
 
 If the resolved mapping of _options_ includes any _`u:` options_
 supported by the implementation, process them as specified.
@@ -440,8 +434,8 @@ The resolution of _markup_ MUST always succeed.
 
 A **_<dfn>fallback value</dfn>_** is the _resolved value_ for
 an _expression_ or _variable_ when that _expression_ or _variable_ fails to resolve.
-It contains a string representation that is used for its formatting,
-and no option values.
+It contains a string representation that is used for its formatting.
+All _options_ are removed.
 
 The _resolved value_ of _text_, _literal_, and _markup_ MUST NOT be a _fallback value_.
 
@@ -453,7 +447,7 @@ An _expression_ fails to resolve when:
 
 - A _variable_ used as its _operand_ resolves to a _fallback value_.
   Note that an _expression_ does not necessarily fail to resolve
-  if an _option_ resolves with a _fallback value_.
+  if an _option value_ resolves with a _fallback value_.
 - No _function handler_ is found for a _function_ _identifier_.
 - Calling a _function handler_ fails or does not return a valid value.
 

spec/functions/README.md

@@ -25,11 +25,11 @@ emit an _Unknown Function_ error for that _function_'s _identifier_.
 To _accept_ an _option_ means that a _function handler_ MUST NOT
 emit a _Bad Option_ error for that _option_'s _identifier_ when used with the _function_
 it is defined for
-and MUST NOT emit a _Bad Option_ error for any of the _option_ values
+and MUST NOT emit a _Bad Option_ error for any of the _option values_
 defined for that _option_.
 Accepting a _function_ or its _options_ does not mean that a particular output is produced.
 Implementations MAY emit an _Unsupported Operation_ error for _options_
-or _option_ values that they cannot support.
+or _option values_ that they cannot support.
 
 _Functions_ can define _options_. 
 An _option_ can be REQUIRED or RECOMMENDED.
@@ -54,11 +54,11 @@ by any version of this specification for _default functions_.
 Such _options_ MUST use an implementation-specific _namespace_.
 
 Implementations MAY _accept_, for _options_ defined in this specification,
-_option_ values which are not defined in this specification.
+_option values_ which are not defined in this specification.
 However, such values might become defined with a different meaning in the future,
 including with a different, incompatible name
 or using an incompatible value space.
-Supporting implementation-specific _option_ values for _default functions_ is NOT RECOMMENDED.
+Supporting implementation-specific _option values_ for _default functions_ is NOT RECOMMENDED.
 
 Implementations MAY _accept_, for _operands_ or _options_ defined in this specification,
 values with implementation-defined types.
@@ -71,11 +71,11 @@ Such values can be useful to users in cases where local usage and support exists
 > - A Java implementation might _accept_ a `java.time.chrono.Chronology` object
 >   as a value for the _date/time override option_ `calendar`
 
-Future versions of this specification MAY define additional _options_ and _option_ values,
+Future versions of this specification MAY define additional _options_ and _option values_,
 subject to the rules in the [Stability Policy](#stability-policy),
 for _functions_ found in this specification.
 As implementations are permitted to ignore _options_ that they do not support,
-it is possible to write _messages_ using _options_ not defined below
+it is possible to write _messages_ using _options_ not defined here
 which currently format with no error, but which could produce errors
 when formatted with a later edition of this specification.
 Therefore, using _options_ not explicitly defined here is NOT RECOMMENDED.

spec/functions/datetime.md

@@ -45,20 +45,20 @@ a _Bad Option_ error is emitted
 and a _fallback value_ used as the _resolved value_ of the _expression_.
 
 If the _operand_ of the _expression_ is an implementation-defined date/time type,
-it can include _style options_, _field options_, or other option values.
+it can include _style options_, _field options_, or other _options_.
 These are included in the resolved option values of the _expression_,
-with _options_ on the _expression_ taking priority over any option values of the _operand_.
+with _options_ on the _expression_ taking priority over any options of the _operand_.
 
 > [!NOTE]
-> The names of _options_ and their _values_ were derived from the
+> The names of _options_ and their _option values_ were derived from the
 > [options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#description)
 > in JavaScript's `Intl.DateTimeFormat`.
 
 ###### Style Options
 
 **_<dfn>Style options</dfn>_** pertain to the overall styling or appearance of the formatted output.
 
-The function `:datetime` has these _style options_.
+The following _style options_ are REQUIRED to be available on the function `:datetime`:
 
 - `dateStyle`
   - `full`
@@ -80,7 +80,7 @@ and what format to use for that field.
 > _Field options_ do not have default values because they are only to be used
 > to compose the formatter.
 
-The function `:datetime` has the following _field options_:
+The following _field options_ are REQUIRED to be available on the function `:datetime`:
 
 - `weekday`
   - `long`
@@ -149,7 +149,7 @@ All other _operand_ values produce a _Bad Operand_ error.
 
 The function `:date` has these _options_:
 
-- `style`
+- `style` \[REQUIRED\]
   - `full`
   - `long`
   - `medium` (default)
@@ -158,7 +158,7 @@ The function `:date` has these _options_:
 
 If the _operand_ of the _expression_ is an implementation-defined date/time type,
 it can include other option values.
-Any _operand_ option values matching the `:datetime` _style options_ or _field options_ are ignored,
+Any _operand_ options matching the `:datetime` _style options_ or _field options_ are ignored,
 as is any `style` option.
 
 ##### Resolved Value
@@ -168,7 +168,7 @@ is implementation-defined.
 
 An implementation MAY emit a _Bad Operand_ or _Bad Option_ error (as appropriate)
 when a _variable_ annotated directly or indirectly by a `:date` _annotation_
-is used as an _operand_ or an _option_ value.
+is used as an _operand_ or an _option value_.
 
 #### The `:time` function
 
@@ -189,7 +189,7 @@ All other _operand_ values produce a _Bad Operand_ error.
 
 The function `:time` has these _options_:
 
-- `style`
+- `style` \[REQUIRED\]
   - `full`
   - `long`
   - `medium`
@@ -198,7 +198,7 @@ The function `:time` has these _options_:
 
 If the _operand_ of the _expression_ is an implementation-defined date/time type,
 it can include other option values.
-Any _operand_ option values matching the `:datetime` _style options_ or _field options_ are ignored,
+Any _operand_ options matching the `:datetime` _style options_ or _field options_ are ignored,
 as is any `style` option.
 
 ##### Resolved Value
@@ -208,7 +208,7 @@ is implementation-defined.
 
 An implementation MAY emit a _Bad Operand_ or _Bad Option_ error (as appropriate)
 when a _variable_ annotated directly or indirectly by a `:time` _annotation_
-is used as an _operand_ or an _option_ value.
+is used as an _operand_ or an _option value_.
 
 #### Date and Time Operands
 
@@ -271,20 +271,7 @@ or embedded in an implementation-defined date/time _operand_ value.
 > These _options_ do not have default values because they are only to be used
 > as overrides for locale-and-value dependent implementation-defined defaults.
 
-The following _option_ and its values are REQUIRED to be available on
-the functions `:datetime` and `:time`:
-
-- `hour12`
-  - `true`
-  - `false`
-
-The following _option_ and its values are RECOMMENDED to be available on
-the functions `:datetime`, `:date`, and `:time`.
-
-- `calendar`
-  - valid [Unicode Calendar Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCalendarIdentifier)
-
-The following _option_ and its values are REQUIRED to be available on
+The following _option_ is REQUIRED to be available on
 the functions `:datetime`, `:date`, and `:time`.
 
 - `timeZone`
@@ -300,3 +287,16 @@ the functions `:datetime`, `:date`, and `:time`.
 > into a [floating](https://www.w3.org/TR/timezone/#floating) time value
 > (sometimes called a _plain_ or _local_ time value) by removing
 > the association with a specific time zone.
+
+The following _option_ is REQUIRED to be available on
+the functions `:datetime` and `:time`:
+
+- `hour12`
+  - `true`
+  - `false`
+
+The following _option_ is RECOMMENDED to be available on
+the functions `:datetime`, `:date`, and `:time`.
+
+- `calendar`
+  - valid [Unicode Calendar Identifier](https://unicode.org/reports/tr35/tr35.html#UnicodeCalendarIdentifier)