-
-
Notifications
You must be signed in to change notification settings - Fork 36
Implement changes to date/time functions #648
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
6a829f5
2d04a8f
74474e2
fc14878
9bf73c7
7b3c4bc
03b2548
9f158d9
308dd1d
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -33,6 +33,9 @@ Therefore, addition to this list requires a higher level of rigor. | |
|
||
### Numbers | ||
|
||
> [!IMPORTANT] | ||
> This section is replaced by the design for number selection | ||
|
||
Function name: `:number` | ||
|
||
Aliases: | ||
|
@@ -86,6 +89,11 @@ If no options are specified, each of the functions defaults to the following: | |
> Pattern selection based on date/time values is a complex topic and no support for this | ||
> is required in this release. | ||
|
||
> [!NOTE] | ||
> The default formatting behavior of `:datetime` is inconsistent with `Intl.DateTimeFormat` | ||
> in JavaScript and with `{d,date}` in MessageFormat v1. | ||
> This is because, unlike those implementations, `:datetime` is distinct from `:date` and `:time`. | ||
|
||
#### Operands | ||
|
||
The _operand_ of a date/time function is either | ||
|
@@ -109,7 +117,7 @@ For more information, see [Working with Timezones](https://w3c.github.io/timezon | |
> 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". | ||
> an _Operand Mismatch Error_ at runtime. | ||
|
||
> [!NOTE] | ||
> String values passed as variables in the _formatting context_'s | ||
|
@@ -133,20 +141,15 @@ For more information, see [Working with Timezones](https://w3c.github.io/timezon | |
|
||
#### Options | ||
|
||
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 | ||
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. | ||
|
||
If both are specified, an _Invalid Expression_ error MUST be emitted | ||
and a _fallback value_ used as the resolved value of the _expression_. | ||
|
||
##### Style Options | ||
|
||
The function `:datetime` has these function-specific _style_ options. | ||
- `dateStyle` | ||
- `full` | ||
|
@@ -164,27 +167,28 @@ The function `:date` has these function-specific _style_ options: | |
- `full` | ||
- `long` | ||
- `medium` | ||
- `short` | ||
- `short` (default) | ||
|
||
The function `:time` has these function-specific _style_ options: | ||
- `style` | ||
- `full` | ||
- `long` | ||
- `medium` | ||
- `short` | ||
- `short` (default) | ||
|
||
The _field_ options are defined as follows: | ||
##### Field Options | ||
|
||
All functions have the following option: | ||
- `timeZoneName` | ||
- `long` | ||
- `short` | ||
- `shortOffset` | ||
- `longOffset` | ||
- `shortGeneric` | ||
- `longGeneric` | ||
Field options describe which fields to include in the formatted output | ||
and what format to use for that field. | ||
Only those fields specified in the _annotation_ appear in the formatted output. | ||
Comment on lines
+181
to
+183
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. One of the features of semantic skeleta is preventing nonsensical skeletons like "hours and seconds" without minutes. Mapping from standard skeleta to semantic skeleta may fill in some of those missing fields. Even now, fields such as hour cycle and era may appear even if not in the skeleton. Therefore, it would be better to remove the second sentence giving any guarantees about which fields appear in the formatted output. |
||
|
||
> [!NOTE] | ||
> Field options do not have default values because they are only to be used | ||
> to compose the formatter. | ||
|
||
The functions `:datetime` and `:date` have the following options: | ||
The _field_ options are defined as follows: | ||
|
||
The function `:datetime` has the following options: | ||
- `weekday` | ||
- `long` | ||
- `short` | ||
|
@@ -205,8 +209,6 @@ The functions `:datetime` and `:date` have the following options: | |
- `day` | ||
- `numeric` | ||
- `2-digit` | ||
|
||
The functions `:datetime` and `:time` have the following options: | ||
- `hour` | ||
- `numeric` | ||
- `2-digit` | ||
|
@@ -225,6 +227,27 @@ The functions `:datetime` and `:time` have the following options: | |
- `h12` | ||
- `h23` | ||
- `h24` | ||
- `timeZoneName` | ||
- `long` | ||
- `short` | ||
- `shortOffset` | ||
- `longOffset` | ||
- `shortGeneric` | ||
- `longGeneric` | ||
|
||
> [!NOTE] | ||
> The following options do not have default values because they are only to be used | ||
> as overrides for locale-and-value dependent implementation-defined defaults. | ||
|
||
The followind date/time options are *not* part of the default registry. | ||
Implementations SHOULD avoid creating options that conflict with these, but | ||
are encouraged to track development of these options during Tech Preview: | ||
- `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) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. not having the timezone setting will make it difficult to test in server environments where the 'default' is not used. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I agree, even in the case where the implementation provides a message-context API for setting the time zone. The argument is that you "ought" to use a Temporal type with real time zone support--which I don't disagree that one should do that. But there are lots of applications that can't or systems that do not provide anything but an incremental time value and need to set the time zone. Not providing an option to set that seems problematic. On the other hand, these specific options will likely enter Tech Preview as "RGI" and we'll get feedback from users. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The system or locale time zone should never be implicitly used; I would suggest formatting with "GMT+?" if the time zone is not specified but the format requires a time zone. The correct way to pass in a time zone is to use a ZonedDateTime type or similar. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Shane has a good point. This is a bit like currencies with numbers; the input should include both, and if you don't have an input timezone, then the assumption is UTC. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Yes, if the format requires a time zone and one is not available. Although that generally means a floating time value such as
The input should include both, absolutely. However, there are plenty of For these sorts of incremental time values, the ability to say:
... is sometimes useful. I even have ample implementation experience of zoned values needing to be floated or re-zoned for display purposes. Doing this in Amazon's message formatter was easy to explain and worked effectively, although in our case we passed the time zone via the formatting context and it applied to the whole message, not to specific fields. Note that there are no options for "floating" a time value for display (that is, turning an
I do not agree. It means that simple messages never display local time when using old-fashioned time value like
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah, I think we're aligned but let me clarify. The system time zone can be used when localizing a timestamp (absolute time / instant). Ideally that happens outside of MF because MF shouldn't be in the business of date arithmetic. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. MF is definitely not in the anything arithmetic business 😄 but our functions can sometimes be. What I have in mind here is that users be able (but not required) to pass a time zone when they need the underlying formatter to do one of the following:
As noted, this could be done in the formatting context, but an application might need to do any of these for a specific expression field:
Notice that in all three cases you want the value and the target time zone and the desired operation can be determined through reflection. Re-floating a time value isn't generally necessary in the formatter unless what you want to do is get rid of the time zone name in the display.
As above: ideally yes. The option is for a non-ideal world. One downside to the above: the option can take a value and the value can be an argument. But the value can't be null/empty. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. One of the challenges with
Due to interoperability concerns, I do think MF2 should specify the data flow. I'm in full alignment that MF2 shouldn't specify output formats, but it should specify the flow of information so that two different implementations produce semantically equivalent output. |
||
- valid identifier per [BCP175](https://www.rfc-editor.org/rfc/rfc6557) | ||
|
||
|
||
#### Selection | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Above: there is no
timezoneOffset
field. Remove?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
timezoneOffset
is a field in XMLSchema's various specified literal representations, not our spec.