Skip to content
This repository has been archived by the owner on Aug 17, 2022. It is now read-only.

Commit

Permalink
Improve binding operator table readability
Browse files Browse the repository at this point in the history
  • Loading branch information
Luke Wagner committed Mar 27, 2019
1 parent c07af1d commit 6568e70
Showing 1 changed file with 18 additions and 21 deletions.
39 changes: 18 additions & 21 deletions proposals/webidl-bindings/Explainer.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,32 +168,29 @@ operators** and maps from a **source tuple** of WebAssembly values to a
**destination tuple** of Web IDL values (although currently only one is ever
produced). A sample list of outgoing binding operators:

| Binding Operator                                          | Description |
| :--- | :--- |
| **operator** immediates *children* | |
| **as** webidl-type idx | Takes the `idx`'th wasm value of the source tuple and produces a Web IDL value of `webidl-type`, allowing only trivial conversions (like `i32` to [`long`] or `anyref` to [`any`]). |
| **utf8-str** webidl-type off-idx len-idx | Takes the `off-idx`'th and `len-idx`th wasm values of the source tuple, which must both be `i32`s, as the offset and length, resp., of a UTF-8 string in linear memory and decodes a `webidl-type`, which must be one of [`DOMString`], [`ByteString`] or [`USVString`]. |
| **utf8-cstr** webidl-type off-idx | Like `utf8-str`, but instead of length being explicitly supplied as a wasm value in the source tuple, the length is found by decoding up to the first null code point. |
| **i32-to-enum** webidl-type val-idx | Takes the `val-idx`'th wasm value of the source tuple, which must be an `i32`, as an index into the list of strings specified by `webidl-type`, which must be an [Enumeration]. |
| **view** webidl-type off-idx len-idx | Takes the `off-idx`'th and `len-idx`'th wasm values of the source tuple, which must both be `i32`s, as the offset and length, resp., of a new `webidl-type`, which must be a [Typed Array View]. |
| **dict** webidl-type *out-exprs* | Create a Web IDL `webidl-type` [Dictionary] value using `out-exprs` as the field values (which must line up with `webidl-type` exactly). |
| **bind-export** webidl-type binding func-idx | Takes the `func-idx`'th wasm value of the source tuple, which must be a typed function [`ref`], and applies `binding` to produce a [Callback] value. (See [`BindExport`](#runtime) below.) |
| Operator | Immediates | Children | Description |
| :--- | :--- | :--- | :--- |
| **as** | webidl‑type<br>idx | | Takes the `idx`'th wasm value of the source tuple and produces a Web IDL value of `webidl-type`, allowing only trivial conversions (like `i32` to [`long`] or `anyref` to [`any`]). |
| **utf8‑str** | webidl‑type<br>off‑idx<br>len‑idx | | Takes the `off-idx`'th and `len-idx`th wasm values of the source tuple, which must both be `i32`s, as the offset and length, resp., of a UTF-8 string in linear memory and decodes a `webidl-type`, which must be one of [`DOMString`], [`ByteString`] or [`USVString`]. |
| **utf8‑cstr** | webidl‑type<br>off‑idx | | Like `utf8-str`, but instead of length being explicitly supplied as a wasm value in the source tuple, the length is found by decoding up to the first null code point. |
| **i32‑to‑enum** | webidl‑type<br>val‑idx | | Takes the `val-idx`'th wasm value of the source tuple, which must be an `i32`, as an index into the list of strings specified by `webidl-type`, which must be an [Enumeration]. |
| **view** | webidl‑type<br>off‑idx<br>len‑idx | | Takes the `off-idx`'th and `len-idx`'th wasm values of the source tuple, which must both be `i32`s, as the offset and length, resp., of a new `webidl-type`, which must be a [Typed Array View]. |
| **dict** | webidl‑type | *out‑exprs* | Create a Web IDL `webidl-type` [Dictionary] value using `out-exprs` as the field values (which must line up with `webidl-type` exactly). |
| **bind‑export** | webidl‑type<br>binding<br>func‑idx | | Takes the `func-idx`'th wasm value of the source tuple, which must be a typed function [`ref`], and applies `binding` to produce a [Callback] value. (See [`BindExport`](#runtime) below.) |

An **incoming binding expression** is composed of **incoming binding
operators** and maps from a source tuple of Web IDL values to a **destination
tuple** of WebAssembly values. A sample list of incoming binding operators:


| Binding&nbsp;Operator&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Description |
| :--- | :--- |
| **operator** immediates *children* | |
| **get** idx | Return the `idx`th Web IDL value of the source tuple. |
| **as** wasm-type *in-expr* | Take the result of `in-expr`, which can be any Web IDL value, and produces a wasm value of `wasm-type`, allowing only trivial conversions (like [`long`] to `i32` or [`any`] to `anyref`). |
| **alloc-utf8-str** alloc-func-idx *in-expr* | Take the result of `in-expr`, which must be one of [`DOMString`], [`ByteString`] or [`USVString`], compute the number of bytes necessary to store a UTF-8 encoding of this string, call the `alloc-func-idx`'th function of the receiving instance, passing the number of bytes and using the resulting offset to store the UTF-8 encoding, finally returning the offset and byte-length as two `i32`s (and trapping on OOM). |
| **alloc-buffer** alloc-func-idx *in-expr* | Take the result of `in-expr`, which must be a [BufferSource], call the `alloc-func-idx`'th function of the receiving instance, passing the BufferSource's length and using the resulting offset to store a copy of the BufferSource in linear memory, returning the offset and byte-length as two `i32`s (and trapping on OOM). |
| **enum-to-i32** webidl-type *in-expr* | Take the result of `in-expr`, which must be an [Enumeration] value, and reverse-map this string to the `i32` index of the matching string in the `webidl-type`, which must also be an Enumeration. |
| **field** field-idx *in-expr* | Take the result of `in-expr`, which must be a [Dictionary] value, and return the Web IDL value of the `field-idx`th field. |
| **bind-import** wasm-type binding *in-expr* | Take the result of `in-expr`, which must be a [Callback] value, and apply `binding` to produce a [`funcref`] (or, later, a typed function reference). (See [`BindImport`](#runtime) below.) |
| Operator | Immediates | Children | Description |
| :--- | :--- | :--- | :--- |
| **get** | idx | | Return the `idx`th Web IDL value of the source tuple. |
| **as** | wasm‑type | *in‑expr* | Take the result of `in-expr`, which can be any Web IDL value, and produces a wasm value of `wasm-type`, allowing only trivial conversions (like [`long`] to `i32` or [`any`] to `anyref`). |
| **alloc‑utf8‑str** | alloc‑func‑idx | *in‑expr* | Take the result of `in-expr`, which must be one of [`DOMString`], [`ByteString`] or [`USVString`], compute the number of bytes necessary to store a UTF-8 encoding of this string, call the `alloc-func-idx`'th function of the receiving instance, passing the number of bytes and using the resulting offset to store the UTF-8 encoding, finally returning the offset and byte-length as two `i32`s (and trapping on OOM). |
| **alloc‑buffer** | alloc‑func‑idx | *in‑expr* | Take the result of `in-expr`, which must be a [BufferSource], call the `alloc-func-idx`'th function of the receiving instance, passing the BufferSource's length and using the resulting offset to store a copy of the BufferSource in linear memory, returning the offset and byte-length as two `i32`s (and trapping on OOM). |
| **enum‑to‑i32** | webidl‑type | *in‑expr* | Take the result of `in-expr`, which must be an [Enumeration] value, and reverse-map this string to the `i32` index of the matching string in the `webidl-type`, which must also be an Enumeration. |
| **field** | field‑idx | *in‑expr* | Take the result of `in-expr`, which must be a [Dictionary] value, and return the Web IDL value of the `field-idx`th field. |
| **bind‑import** | wasm‑type<br>binding | *in‑expr* | Take the result of `in-expr`, which must be a [Callback] value, and apply `binding` to produce a [`funcref`] (or, later, a typed function reference). (See [`BindImport`](#runtime) below.) |

For example, building on the previous section's example, a Web IDL value of the
`$Contact` dictionary type could be produced from three WebAssembly `i32`s by
Expand Down

0 comments on commit 6568e70

Please sign in to comment.