From 6f6663333698fd98c5d140cfca09968466c27f42 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Mon, 5 Feb 2024 16:29:39 -0800 Subject: [PATCH 1/7] Describe date/time formatting functions and options Based on the 2024-02-05 teleconference discussion, describe the date/time formatting functions in a manner similar to the number selection design document. --- .../default-registry-and-mf1-compatibility.md | 144 ++++++++++++++---- 1 file changed, 115 insertions(+), 29 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index 2083655ead..abf2c25e70 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -63,37 +63,123 @@ Options: (When no default is given, the default depends on the locale or implementation) -### Dates and Times - -Function name: `:datetime` - -Aliases: -- `:date` (with `style=...` option corresponding to `:datetime dateStyle=...`) -- `:time` (with `style=...` option corresponding to `:datetime timeStyle=...`) +--- -Operand: "iso8601" - -Options: -- `dateStyle` (`full` `long` `medium` `short`) -- `timeStyle` (`full` `long` `medium` `short`) -- `calendar` (buddhist chinese coptic dangi ethioaa ethiopic gregory hebrew indian islamic islamic-umalqura - islamic-tbla islamic-civil islamic-rgsa iso8601 japanese persian roc) -- `numberingSystem` (arab arabext bali beng deva fullwide gujr guru hanidec khmr knda laoo latn - limb mlym mong mymr orya tamldec telu thai tibt) -- `timezone` (tzid) -- `hourCycle` (`h11` `h12` `h23` `h24`) -- `weekday` (`long` `short` `narrow`) -- `era` (`long` `short` `narrow`) -- `year` (`numeric` `2-digit`) -- `month` (`numeric` `2-digit` `long` `short` `narrow`) -- `day` (`numeric` `2-digit`) -- `hour` (`numeric` `2-digit`) -- `minute` (`numeric` `2-digit`) -- `second` (`numeric` `2-digit`) -- `fractionalSecondDigits` (`1`, `2`, `3`) -- `timeZoneName` (`long` `short` `shortOffset` `longOffset` `shortGeneric` `longGeneric`) +### Dates and Times -(When no default is given, the default depends on the locale or implementation) +This subsection describes the functions and options for date/time formatting. + +#### Functions + +Dates and times have the following functions: + +- `:datetime` + - defaults to `dateStyle=short timeStyle=short` +- `:date` + - defaults to `dateStyle=short` + - Does not permit any of these options: + - `timeStyle` + - `hour` + - `minute` + - `second` + - `fractionalSecondDigits` + - `hourCycle` +- `:time` + - defaults to `timeStyle=short` + - Does not permit any of these options: + - `dateStyle` + - `weekday` + - `era` + - `year` + - `month` + - `day` + +#### Operands + +> [!IMPORTANT] +> The list of serializations needs more work. + +The operand of a date/time function is either a literal that any of the serializations +defined by RFC3339 or SEDATE and which is parsed by the +implementation into an implementation defined date/time type; +or any implementation-defined date/time types. + +#### Options + +The following options provide high-level control over date/time formats: +- `dateStyle` + - `full` + - `long` + - `medium` + - `short` (default) +- `timeStyle` + - `full` + - `long` + - `medium` + - `short` (default) +- `calendar` (default is locale-specific) + - valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier) +- `numberingSystem` (default is locale-specific) + - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) +- `timezone` (default is system default time zone or UTC) + - valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557) +- `hourCycle` (default is locale-specific) + - `h11` + - `h12` + - `h23` + - `h24` + +The following options are used to construct date/time formats in a manner analogous to skeletons. +They do not have default values because the value must be specified. +- `weekday` + - `long` + - `short` + - `narrow` +- `era` + - `long` + - `short` + - `narrow` +- `year` + - `numeric` + - `2-digit` +- `month` + - `numeric` + - `2-digit` + - `long` + - `short` + - `narrow` +- `day` + - `numeric` + - `2-digit` +- `hour` + - `numeric` + - `2-digit` +- `minute` + - `numeric` + - `2-digit` +- `second` + - `numeric` + - `2-digit` +- `fractionalSecondDigits` + - `1` + - `2` + - `3` +- `timeZoneName` + - `long` + - `short` + - `shortOffset` + - `longOffset` + - `shortGeneric` + - `longGeneric` + +#### Selection + +Selection based on date/time types is not required by MFv2. +Implementations should use care when defining selectors based on date/time types. +The types of queries found in implementations such as `java.time.TemporalAccessor` +are complex and user expectations may be inconsistent with good I18N practices. + +--- ### Strings From e9c2fb706d5fd0d16616f214f9413527e03ebcdf Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 6 Feb 2024 06:19:29 -0800 Subject: [PATCH 2/7] Improve operands --- .../default-registry-and-mf1-compatibility.md | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index abf2c25e70..eb0ce16a79 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -96,13 +96,27 @@ Dates and times have the following functions: #### Operands -> [!IMPORTANT] -> The list of serializations needs more work. - -The operand of a date/time function is either a literal that any of the serializations -defined by RFC3339 or SEDATE and which is parsed by the -implementation into an implementation defined date/time type; -or any implementation-defined date/time types. +The operand of a date/time function is either +an implementation-defined date/time type (passed in as an argument) +or a literal that can be parsed to an implementation-defined date/time type. + +Date/time literals are required to be an XMLSchema +[dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime), +[time](https://www.w3.org/TR/xmlschema11-2/#time), +or [date](https://www.w3.org/TR/xmlschema11-2/#date). +The `timezoneOffset` of each of these formats is optional. +When the offset is not present, conversion to incremental time types is required +to treat the offset identically to UTC. +Conversion of such values to floating time types +(such as Java's `java.time.LocalDateTime`) should omit time zone. +For more information, see [Working with Timezones](https://w3c.github.io/timezone). + +> [!NOTE] +> True time zone support in serializations is expected to coincide with the adoption +> of Temporal in JavaScript. +> The form of these serializations is known and is a de facto standard. +> Support for these extensions is expected to be required in the post-tech preview. +> See: https://datatracker.ietf.org/doc/draft-ietf-sedate-datetime-extended/ #### Options From 9ba4250e8f64bc9b707728c20effd00cb3c4404e Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 6 Feb 2024 10:07:42 -0800 Subject: [PATCH 3/7] Update exploration/default-registry-and-mf1-compatibility.md Co-authored-by: Eemeli Aro --- exploration/default-registry-and-mf1-compatibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index eb0ce16a79..d663c83d37 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -135,7 +135,7 @@ The following options provide high-level control over date/time formats: - valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier) - `numberingSystem` (default is locale-specific) - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) -- `timezone` (default is system default time zone or UTC) +- `timeZone` (default is system default time zone or UTC) - valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557) - `hourCycle` (default is locale-specific) - `h11` From c742372ac5858df1ae9e2936e53411358583c5ab Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 6 Feb 2024 10:08:21 -0800 Subject: [PATCH 4/7] Update exploration/default-registry-and-mf1-compatibility.md Co-authored-by: Eemeli Aro --- exploration/default-registry-and-mf1-compatibility.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index d663c83d37..7626bae8cf 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -125,12 +125,12 @@ The following options provide high-level control over date/time formats: - `full` - `long` - `medium` - - `short` (default) + - `short` - `timeStyle` - `full` - `long` - `medium` - - `short` (default) + - `short` - `calendar` (default is locale-specific) - valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier) - `numberingSystem` (default is locale-specific) From c76d552fcc1cf59a8ec216d95fde38f47611c058 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 6 Feb 2024 16:50:04 -0800 Subject: [PATCH 5/7] Address comments about date operands --- .../default-registry-and-mf1-compatibility.md | 37 ++++++++++++++----- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index 7626bae8cf..22f867cd74 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -98,19 +98,38 @@ Dates and times have the following functions: The operand of a date/time function is either an implementation-defined date/time type (passed in as an argument) -or a literal that can be parsed to an implementation-defined date/time type. +or a _date/time literal value_, as defined below. + +A **_date/time literal value_** is a non-empty string consisting of +one of the following: +- an XMLSchema 1.1 [dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime) +- an XMLSchema 1.1 [time](https://www.w3.org/TR/xmlschema11-2/#time) +- an XMLSchema 1.1 [date](https://www.w3.org/TR/xmlschema11-2/#date) -Date/time literals are required to be an XMLSchema -[dateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime), -[time](https://www.w3.org/TR/xmlschema11-2/#time), -or [date](https://www.w3.org/TR/xmlschema11-2/#date). The `timezoneOffset` of each of these formats is optional. -When the offset is not present, conversion to incremental time types is required -to treat the offset identically to UTC. -Conversion of such values to floating time types -(such as Java's `java.time.LocalDateTime`) should omit time zone. +When the offset is not present, implementations should use a floating time type +(such as Java's `java.time.LocalDateTime`) to represent the time value. For more information, see [Working with Timezones](https://w3c.github.io/timezone). +> [!IMPORTANT] +> The [ABNF](./spec/message.abnf) and [syntax](./spec/syntax.md) of MFv2 +> do not formally define date/time literals. +> This means that a _message_ can be syntactically valid but produce +> runtime errors due to what amounts to a "type mismatch". + +> [!NOTE] +> String values passed as variables in the _formatting context_'s +> _input mapping_ can be formatted as date/time values as long as their +> contents are date/time literals. +> +> For example, if the value of the variable `now` were the string +> `2024-02-06T16:40:00Z`, it would behave identically to the local +> variable in this example: +> ``` +> .local $example = {|2024-02-06T16:40:00Z| :datetime} +> {{{$now :datetime} == {$example}}} +> ``` + > [!NOTE] > True time zone support in serializations is expected to coincide with the adoption > of Temporal in JavaScript. From 40c6f0e63e8c6c753cd20905ba216ab14d0c8c5b Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 6 Feb 2024 17:14:53 -0800 Subject: [PATCH 6/7] Address @eemeli's comments Here I have tried to be more rigorous in describing the functions and their options. Note that we as a group still need to agree to this design. --- .../default-registry-and-mf1-compatibility.md | 100 +++++++++++------- 1 file changed, 60 insertions(+), 40 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index 22f867cd74..2223d80043 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -71,28 +71,20 @@ This subsection describes the functions and options for date/time formatting. #### Functions -Dates and times have the following functions: +Functions for formatting [date/time values](#operands) in the default registry are: - `:datetime` - - defaults to `dateStyle=short timeStyle=short` - `:date` - - defaults to `dateStyle=short` - - Does not permit any of these options: - - `timeStyle` - - `hour` - - `minute` - - `second` - - `fractionalSecondDigits` - - `hourCycle` - `:time` - - defaults to `timeStyle=short` - - Does not permit any of these options: - - `dateStyle` - - `weekday` - - `era` - - `year` - - `month` - - `day` + +If no options are specified, each of the functions defaults to the following: +- `{$d :datetime}` is the same as `{$d :datetime dateStyle=short timeStyle=short}` +- `{$d :date}` is the same as `{$d :date style=short}` +- `{$t :time}` is the same as `{$t :time style=short}` + +> [!NOTE] +> Pattern selection based on date/time values is a complex topic and no support for this +> is required in this release. #### Operands @@ -139,7 +131,21 @@ For more information, see [Working with Timezones](https://w3c.github.io/timezon #### Options -The following options provide high-level control over date/time formats: +All date/time functions support the following options, which +provide high-level control over date/time formats: +- `calendar` (default is locale-specific) + - valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier) +- `numberingSystem` (default is locale-specific) + - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) +- `timeZone` (default is system default time zone or UTC) + - valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557) + +In addition to the above high-level options, a function can use either the appropriate +_style_ options for that function +or can use a collection of _field options_ (but not both) to control the formatted +output. + +The function `:datetime` has these function-specific _style_ options. - `dateStyle` - `full` - `long` @@ -150,20 +156,33 @@ The following options provide high-level control over date/time formats: - `long` - `medium` - `short` -- `calendar` (default is locale-specific) - - valid [Unicode Calendar Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeCalendarIdentifier) -- `numberingSystem` (default is locale-specific) - - valid [Unicode Number System Identifier](https://cldr-smoke.unicode.org/spec/main/ldml/tr35.html#UnicodeNumberSystemIdentifier) -- `timeZone` (default is system default time zone or UTC) - - valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557) -- `hourCycle` (default is locale-specific) - - `h11` - - `h12` - - `h23` - - `h24` - -The following options are used to construct date/time formats in a manner analogous to skeletons. -They do not have default values because the value must be specified. + +The function `:date` has these function-specific _style_ options: +- `style` + - `full` + - `long` + - `medium` + - `short` + +The function `:time` has these function-specific _style_ options: +- `style` + - `full` + - `long` + - `medium` + - `short` + +The _field_ options are defined as follows: + +All functions have the following option: +- `timeZoneName` + - `long` + - `short` + - `shortOffset` + - `longOffset` + - `shortGeneric` + - `longGeneric` + +The functions `:datetime` and `:date` have the following options: - `weekday` - `long` - `short` @@ -184,6 +203,8 @@ They do not have default values because the value must be specified. - `day` - `numeric` - `2-digit` + +The functions `:datetime` and `:time` have the following options: - `hour` - `numeric` - `2-digit` @@ -197,13 +218,12 @@ They do not have default values because the value must be specified. - `1` - `2` - `3` -- `timeZoneName` - - `long` - - `short` - - `shortOffset` - - `longOffset` - - `shortGeneric` - - `longGeneric` +- `hourCycle` (default is locale-specific) + - `h11` + - `h12` + - `h23` + - `h24` + #### Selection From a577655ee7552ca74e14e702a3ff9a00080cae3e Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Wed, 7 Feb 2024 08:15:12 -0800 Subject: [PATCH 7/7] Tweak operand section formatting --- exploration/default-registry-and-mf1-compatibility.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/exploration/default-registry-and-mf1-compatibility.md b/exploration/default-registry-and-mf1-compatibility.md index 2223d80043..d8f1b4518f 100644 --- a/exploration/default-registry-and-mf1-compatibility.md +++ b/exploration/default-registry-and-mf1-compatibility.md @@ -88,9 +88,11 @@ If no options are specified, each of the functions defaults to the following: #### Operands -The operand of a date/time function is either +The _operand_ of a date/time function is either an implementation-defined date/time type (passed in as an argument) or a _date/time literal value_, as defined below. +All other _operand_ values produce a _Selection Error_ when evaluated for selection +or a _Formatting Error_ when formatting the value. A **_date/time literal value_** is a non-empty string consisting of one of the following: @@ -104,7 +106,7 @@ When the offset is not present, implementations should use a floating time type For more information, see [Working with Timezones](https://w3c.github.io/timezone). > [!IMPORTANT] -> The [ABNF](./spec/message.abnf) and [syntax](./spec/syntax.md) of MFv2 +> The [ABNF](/main/spec/message.abnf) and [syntax](/main/spec/syntax.md) of MFv2 > do not formally define date/time literals. > This means that a _message_ can be syntactically valid but produce > runtime errors due to what amounts to a "type mismatch".