From 54cfbf13f2858b4a2baf2f42b44bf71705b05a33 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Thu, 5 Jun 2025 13:58:59 +0200 Subject: [PATCH 1/2] Include :date, :datetime, and :time with style options only --- spec/functions/datetime.md | 81 ++++++++++++++---------------- test/tests/functions/datetime.json | 3 -- 2 files changed, 39 insertions(+), 45 deletions(-) diff --git a/spec/functions/datetime.md b/spec/functions/datetime.md index 9fb2917055..366525372c 100644 --- a/spec/functions/datetime.md +++ b/spec/functions/datetime.md @@ -2,10 +2,6 @@ This subsection describes the _functions_ and _options_ for date/time formatting. -> [!IMPORTANT] -> The _functions_ in this section have a status of **Draft**. -> They are proposed for inclusion in a future release and are not Stable. - > [!NOTE] > Selection based on date/time types is not required by this release of MessageFormat. > Use care when defining implementation-specific _selectors_ based on date/time types. @@ -14,15 +10,14 @@ This subsection describes the _functions_ and _options_ for date/time formatting #### The `:datetime` function -The function `:datetime` is used to format date/time values, including -the ability to compose user-specified combinations of fields. +The function `:datetime` is used to format combined date/time values. If no options are specified, this function defaults to the following: - `{$d :datetime}` is the same as `{$d :datetime dateStyle=medium timeStyle=short}` > [!NOTE] -> The default formatting behavior of `:datetime` is inconsistent with `Intl.DateTimeFormat` +> The formatting behavior of `:datetime` is inconsistent with `Intl.DateTimeFormat` > in JavaScript and with `{d,date}` in ICU MessageFormat 1.0. > This is because, unlike those implementations, `:datetime` is distinct from `:date` and `:time`. @@ -35,52 +30,52 @@ All other _operand_ values produce a _Bad Operand_ error. ##### Options -The `:datetime` function can use either the appropriate _style options_ -or can use a collection of _field options_ (but not both) to control the formatted -output. -_Date/time override options_ can be combined with either _style options_ or _field options_. - -If both _style options_ and _field options_ are specified, -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 _options_. -These are included in the resolved option values of the _expression_, -with _options_ on the _expression_ taking priority over any options of the _operand_. - -> [!NOTE] -> 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 - -**_Style options_** pertain to the overall styling or appearance of the formatted output. - -The following _style options_ are REQUIRED to be available on the function `:datetime`: +The following _options_ are REQUIRED to be available on the function `:datetime`: - `dateStyle` - `full` - `long` - - `medium` + - `medium` (default) - `short` - `timeStyle` - `full` - `long` - `medium` - - `short` + - `short` (default) +- _Date/time override options_ + +`dateStyle` and `timeStyle` are **_style options_** +which pertain to the overall styling or appearance of the formatted output. + +If the _operand_ of the _expression_ is an implementation-defined date/time type, +it can include other option values. +Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, +with _options_ on the _expression_ taking priority over any options of the _operand_. +Any _operand_ options not matching the _Date/time override options_ are ignored. ###### Field Options +> [!IMPORTANT] +> The _field options_ in this section have a status of **Draft**. +> They are proposed for inclusion in a future release and are not Stable. + **_Field options_** describe which fields to include in the formatted output and what format to use for that field. +The `:datetime` function can use either the appropriate _style options_ +or a collection of _field options_ (but not both) to control the formatted +output. +_Date/time override options_ can be combined with either _style options_ or _field options_. + +If both _style options_ and _field options_ are specified, +a _Bad Option_ error is emitted +and a _fallback value_ used as the _resolved value_ of the _expression_. + > [!NOTE] > _Field options_ do not have default values because they are only to be used > to compose the formatter. -The following _field options_ are REQUIRED to be available on the function `:datetime`: +The following _field options_ are available on the function `:datetime`: - `weekday` - `long` @@ -147,9 +142,9 @@ All other _operand_ values produce a _Bad Operand_ error. ##### Options -The function `:date` has these _options_: +The following _options_ are REQUIRED to be available on the function `:date`: -- `style` \[REQUIRED\] +- `style` - `full` - `long` - `medium` (default) @@ -158,8 +153,9 @@ 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_ options matching the `:datetime` _style options_ or _field options_ are ignored, -as is any `style` option. +Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, +with _options_ on the _expression_ taking priority over any options of the _operand_. +Any _operand_ options not matching the _Date/time override options_ are ignored. ##### Resolved Value @@ -187,9 +183,9 @@ All other _operand_ values produce a _Bad Operand_ error. ##### Options -The function `:time` has these _options_: +The following _options_ are REQUIRED to be available on the function `:time`: -- `style` \[REQUIRED\] +- `style` - `full` - `long` - `medium` @@ -198,8 +194,9 @@ 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_ options matching the `:datetime` _style options_ or _field options_ are ignored, -as is any `style` option. +Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, +with _options_ on the _expression_ taking priority over any options of the _operand_. +Any _operand_ options not matching the _Date/time override options_ are ignored. ##### Resolved Value diff --git a/test/tests/functions/datetime.json b/test/tests/functions/datetime.json index 1d45518290..2bb20ffee9 100644 --- a/test/tests/functions/datetime.json +++ b/test/tests/functions/datetime.json @@ -44,9 +44,6 @@ { "src": "{|2006-01-02T15:04:06| :datetime}" }, - { - "src": "{|2006-01-02T15:04:06| :datetime year=numeric month=2-digit}" - }, { "src": "{|2006-01-02T15:04:06| :datetime dateStyle=long}" }, From 38b4bbe9b5cc81a487f7d0b66fef2fd110cf1167 Mon Sep 17 00:00:00 2001 From: Eemeli Aro Date: Mon, 9 Jun 2025 17:16:14 +0300 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Addison Phillips --- spec/functions/datetime.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/functions/datetime.md b/spec/functions/datetime.md index 366525372c..d91618bd6a 100644 --- a/spec/functions/datetime.md +++ b/spec/functions/datetime.md @@ -10,7 +10,7 @@ This subsection describes the _functions_ and _options_ for date/time formatting #### The `:datetime` function -The function `:datetime` is used to format combined date/time values. +The function `:datetime` is used to format both the date and time of a date/time value. If no options are specified, this function defaults to the following: @@ -51,7 +51,7 @@ If the _operand_ of the _expression_ is an implementation-defined date/time type it can include other option values. Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, with _options_ on the _expression_ taking priority over any options of the _operand_. -Any _operand_ options not matching the _Date/time override options_ are ignored. +Any _operand_ options not matching the _date/time override options_ are ignored. ###### Field Options @@ -155,7 +155,7 @@ If the _operand_ of the _expression_ is an implementation-defined date/time type it can include other option values. Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, with _options_ on the _expression_ taking priority over any options of the _operand_. -Any _operand_ options not matching the _Date/time override options_ are ignored. +Any _operand_ options not matching the _date/time override options_ are ignored. ##### Resolved Value @@ -196,7 +196,7 @@ If the _operand_ of the _expression_ is an implementation-defined date/time type it can include other option values. Any _date/time override options_ of the operand are included in the resolved option values of the _expression_, with _options_ on the _expression_ taking priority over any options of the _operand_. -Any _operand_ options not matching the _Date/time override options_ are ignored. +Any _operand_ options not matching the _date/time override options_ are ignored. ##### Resolved Value