Add 'WIT by Example' section

component-model/examples/wit-section-examples/clocks/monotonic-clock.wit

@@ -0,0 +1,29 @@
+package wasi:[email protected];
+/// WASI Monotonic Clock is a clock API intended to let users measure elapsed
+/// time.
+///
+/// It is intended to be portable at least between Unix-family platforms and
+/// Windows.
+///
+/// A monotonic clock is a clock which has an unspecified initial value, and
+/// successive reads of the clock will produce non-decreasing values.
+interface monotonic-clock {
+
+    /// An instant in time, in nanoseconds. An instant is relative to an
+    /// unspecified initial value, and can only be compared to instances from
+    /// the same monotonic-clock.
+    type instant = u64;
+
+    /// A duration of time, in nanoseconds.
+    type duration = u64;
+
+    /// Read the current value of the clock.
+    ///
+    /// The clock is monotonic, therefore calling this function repeatedly will
+    /// produce a sequence of non-decreasing values.
+    now: func() -> instant;
+
+    /// Query the resolution of the clock. Returns the duration of time
+    /// corresponding to a clock tick.
+    resolution: func() -> duration;
+}

component-model/examples/wit-section-examples/clocks/wall-clock.wit

@@ -0,0 +1,30 @@
+package wasi:clocks;
+/// WASI Wall Clock is a clock API intended to let users query the current
+/// time.
+interface wall-clock {
+    /// A time and date in seconds plus nanoseconds.
+    record datetime {
+        seconds: u64,
+        nanoseconds: u32,
+    }
+
+    /// Read the current value of the clock.
+    ///
+    /// This clock is not monotonic, therefore calling this function repeatedly
+    /// will not necessarily produce a sequence of non-decreasing values.
+    ///
+    /// The returned timestamps represent the number of seconds since
+    /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
+    /// also known as [Unix Time].
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    ///
+    /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+    /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+    now: func() -> datetime;
+
+    /// Query the resolution of the clock.
+    ///
+    /// The nanoseconds field of the output is always less than 1000000000.
+    resolution: func() -> datetime;
+}

component-model/examples/wit-section-examples/clocks/world.wit

@@ -0,0 +1,6 @@
+package wasi:clocks;
+
+world imports {
+    import monotonic-clock;
+    import wall-clock;
+}

component-model/examples/wit-section-examples/filesystems/types.wit

@@ -0,0 +1,94 @@
+package wasi:filesystem;
+interface types {
+    use wasi:clocks/wall-clock.{datetime};
+
+    /// File size or length of a region within a file.
+    type filesize = u64;
+
+    /// The type of a filesystem object referenced by a descriptor.
+    enum descriptor-type {
+        /// The descriptor refers to a directory inode.
+        directory,
+        /// The descriptor refers to a regular file inode.
+        regular-file,
+    }
+
+    /// File attributes.
+    record descriptor-stat {
+        /// File type.
+        %type: descriptor-type,
+        /// File size in bytes.
+        size: filesize,
+        /// Last data access timestamp (optional).
+        data-access-timestamp: option<datetime>,
+    }
+
+    /// Open flags used by `open-at`.
+    flags open-flags {
+        /// Create file if it does not exist, similar to `O_CREAT` in POSIX.
+        create,
+        /// Fail if not a directory, similar to `O_DIRECTORY` in POSIX.
+        directory,
+    }
+
+    /// When setting a timestamp, this gives the value to set it to.
+    variant new-timestamp {
+        /// Leave the timestamp set to its previous value.
+        no-change,
+        /// Set the timestamp to the current time of the system clock associated
+        /// with the filesystem.
+        now,
+        /// Set the timestamp to the given value.
+        timestamp(datetime),
+    }
+
+    /// Error codes returned by functions, similar to `errno` in POSIX.
+    enum error-code {
+        /// Permission denied, similar to `EACCES` in POSIX.
+        access,
+        /// Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX.
+        would-block,
+        /// Connection already in progress, similar to `EALREADY` in POSIX.
+        already,
+        /// Bad descriptor, similar to `EBADF` in POSIX.
+        bad-descriptor,
+        /// Device or resource busy, similar to `EBUSY` in POSIX.
+        busy,
+    }
+
+    /// A descriptor is a reference to a filesystem object, which may be a
+    /// file or directory.
+    resource descriptor {
+        /// Read from a descriptor, without using and updating the descriptor's offset.
+        ///
+        /// This function returns a list of bytes containing the data that was
+        /// read, along with a bool which, when true, indicates that the end of the
+        /// file was reached.
+        read: func(
+            /// The maximum number of bytes to read.
+            length: filesize,
+            /// The offset within the file at which to read.
+            offset: filesize,
+        ) -> result<tuple<list<u8>, bool>, error-code>;
+
+        /// Return the attributes of an open file or directory.
+        stat: func() -> result<descriptor-stat, error-code>;
+
+        /// Adjust the timestamps of a file or directory.
+        set-times-at: func(
+            /// The relative path of the file or directory to operate on.
+            path: string,
+            /// The desired values of the data access timestamp.
+            data-access-timestamp: new-timestamp,
+        ) -> result<_, error-code>;
+
+        /// Open a file or directory.
+        open-at: func(
+            /// The relative path of the object to open.
+            path: string,
+            /// The method by which to open the file.
+            open-flags: open-flags,
+        ) -> result<descriptor, error-code>;
+
+    }
+}

component-model/src/SUMMARY.md

@@ -11,6 +11,7 @@
   - [Interfaces](./design/interfaces.md)
   - [Worlds](./design/worlds.md)
   - [Packages](./design/packages.md)
+- [WIT By Example](./design/wit-example.md)
 - [WIT Reference](./design/wit.md)
 
 # Using WebAssembly Components