From 4c5d1ef773c69211bd26cd157666a19896e0b7a5 Mon Sep 17 00:00:00 2001 From: Colin D Murphy Date: Fri, 14 Jun 2024 09:42:29 -0400 Subject: [PATCH] Add timezone back in. (#61) * Add timezone back in. Update README with markdown generation step. * Add `@unstable` feature gates for `timezone` * Update wit/world.wit --------- Co-authored-by: Yosh Co-authored-by: Dan Gohman --- .github/workflows/main.yml | 4 ++- README.md | 11 +++++++ imports.md | 66 ++++++++++++++++++++++++++++++++++++++ wit/timezone.wit | 55 +++++++++++++++++++++++++++++++ wit/world.wit | 2 ++ 5 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 wit/timezone.wit diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index abb15ec..58d8a1f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,4 +18,6 @@ jobs: ./wit-deps lock git add -N wit/deps git diff --exit-code - - uses: WebAssembly/wit-abi-up-to-date@v20 + - uses: WebAssembly/wit-abi-up-to-date@v21 + with: + features: clocks-timezone diff --git a/README.md b/README.md index 1690e32..49b40b9 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ WASI clocks must have at least two complete independent implementations. - [[Alternative 2]](#alternative-2) - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) - [References & acknowledgements](#references--acknowledgements) +- [Development](#development) ### Introduction @@ -132,3 +133,13 @@ Many thanks for valuable feedback and advice from: - [Person 1] - [Person 2] - [etc.] + +### Development + +#### Generating imports.md + +The file `imports.md` is generated using [wit-bindgen](https://github.com/bytecodealliance/wit-bindgen). + +```bash +wit-bindgen markdown wit --html-in-md --features clocks-timezone +``` diff --git a/imports.md b/imports.md index ec3bedd..b1fefd7 100644 --- a/imports.md +++ b/imports.md @@ -5,6 +5,7 @@
  • interface wasi:io/poll@0.2.0
  • interface wasi:clocks/monotonic-clock@0.2.0
  • interface wasi:clocks/wall-clock@0.2.0
    • +
  • interface wasi:clocks/timezone@0.2.0
    • @@ -158,3 +159,68 @@ also known as Unix Time.
  • datetime
    • +

    Import interface wasi:clocks/timezone@0.2.0

    +
    +

    Types

    +

    type datetime

    +

    datetime

    +

    +#### `record timezone-display` +

    Information useful for displaying the timezone of a specific datetime.

    +

    This information may vary within a single timezone to reflect daylight +saving time adjustments.

    +
    Record Fields
    +
      +
    • +

      utc-offset: s32

      +

      The number of seconds difference between UTC time and the local +time of the timezone. +

      The returned value will always be less than 86400 which is the +number of seconds in a day (246060).

      +

      In implementations that do not expose an actual time zone, this +should return 0.

      +
      • +
    • +

      name: string

      +

      The abbreviated name of the timezone to display to a user. The name +`UTC` indicates Coordinated Universal Time. Otherwise, this should +reference local standards for the name of the time zone. +

      In implementations that do not expose an actual time zone, this +should be the string UTC.

      +

      In time zones that do not have an applicable name, a formatted +representation of the UTC offset may be returned, such as -04:00.

      +
      • +
    • +

      in-daylight-saving-time: bool

      +

      Whether daylight saving time is active. +

      In implementations that do not expose an actual time zone, this +should return false.

      +
      • +
    +
    +

    Functions

    +

    display: func

    +

    Return information needed to display the given datetime. This includes +the UTC offset, the time zone name, and a flag indicating whether +daylight saving time is active.

    +

    If the timezone cannot be determined for the given datetime, return a +timezone-display for UTC with a utc-offset of 0 and no daylight +saving time.

    +
    Params
    + +
    Return values
    + +

    utc-offset: func

    +

    The same as display, but only return the UTC offset.

    +
    Params
    + +
    Return values
    +
      +
    • s32
      • +
    diff --git a/wit/timezone.wit b/wit/timezone.wit new file mode 100644 index 0000000..3c28688 --- /dev/null +++ b/wit/timezone.wit @@ -0,0 +1,55 @@ +package wasi:clocks@0.2.0; + +@unstable(feature = clocks-timezone) +interface timezone { + @unstable(feature = clocks-timezone) + use wall-clock.{datetime}; + + /// Return information needed to display the given `datetime`. This includes + /// the UTC offset, the time zone name, and a flag indicating whether + /// daylight saving time is active. + /// + /// If the timezone cannot be determined for the given `datetime`, return a + /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight + /// saving time. + @unstable(feature = clocks-timezone) + display: func(when: datetime) -> timezone-display; + + /// The same as `display`, but only return the UTC offset. + @unstable(feature = clocks-timezone) + utc-offset: func(when: datetime) -> s32; + + /// Information useful for displaying the timezone of a specific `datetime`. + /// + /// This information may vary within a single `timezone` to reflect daylight + /// saving time adjustments. + @unstable(feature = clocks-timezone) + record timezone-display { + /// The number of seconds difference between UTC time and the local + /// time of the timezone. + /// + /// The returned value will always be less than 86400 which is the + /// number of seconds in a day (24*60*60). + /// + /// In implementations that do not expose an actual time zone, this + /// should return 0. + utc-offset: s32, + + /// The abbreviated name of the timezone to display to a user. The name + /// `UTC` indicates Coordinated Universal Time. Otherwise, this should + /// reference local standards for the name of the time zone. + /// + /// In implementations that do not expose an actual time zone, this + /// should be the string `UTC`. + /// + /// In time zones that do not have an applicable name, a formatted + /// representation of the UTC offset may be returned, such as `-04:00`. + name: string, + + /// Whether daylight saving time is active. + /// + /// In implementations that do not expose an actual time zone, this + /// should return false. + in-daylight-saving-time: bool, + } +} diff --git a/wit/world.wit b/wit/world.wit index c022457..b76a005 100644 --- a/wit/world.wit +++ b/wit/world.wit @@ -3,4 +3,6 @@ package wasi:clocks@0.2.0; world imports { import monotonic-clock; import wall-clock; + @unstable(feature = clocks-timezone) + import timezone; }