From 79d151ea7623c63176e2bcb6a143c1610dec0f1c Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 17:48:09 -0500 Subject: [PATCH 1/6] feat(md,wit): format WIT and nested code inside markdown files --- .topiary/languages.ncl | 14 ++++++++++++++ .topiary/queries/injections.scm | 8 ++++++++ .../language-support/using-wit-resources/rust.md | 4 ++-- 3 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 .topiary/languages.ncl create mode 100644 .topiary/queries/injections.scm diff --git a/.topiary/languages.ncl b/.topiary/languages.ncl new file mode 100644 index 00000000..525e1426 --- /dev/null +++ b/.topiary/languages.ncl @@ -0,0 +1,14 @@ +{ + languages = { + markdown = { + grammar.source = { + git = { + git = "https://github.com/tree-sitter-grammars/tree-sitter-markdown.git", + rev = "a0a00f817d02412bd92c54d316f164d827b57b5c", + subdir = "tree-sitter-markdown", + }, + }, + queries.injections.source.path = "queries/injections.scm", + }, + }, +} diff --git a/.topiary/queries/injections.scm b/.topiary/queries/injections.scm new file mode 100644 index 00000000..f79c6175 --- /dev/null +++ b/.topiary/queries/injections.scm @@ -0,0 +1,8 @@ +(fenced_code_block + (info_string + (language) @injection.language) @info + (code_fence_content) @injection.content + ; mdBook inline macro + (#not-match? @info ".*(nofmt|rust).*") + (#not-match? @injection.content "\\{\\{\\#include") +) diff --git a/component-model/src/language-support/using-wit-resources/rust.md b/component-model/src/language-support/using-wit-resources/rust.md index c8233136..29de9ccc 100644 --- a/component-model/src/language-support/using-wit-resources/rust.md +++ b/component-model/src/language-support/using-wit-resources/rust.md @@ -4,7 +4,7 @@ ## An example stack-based Reverse Polish Notation (RPN) calculator -In this section, our example resource will be a [Reverse Polish Notation (RPN)](https://en.wikipedia.org/wiki/Reverse_Polish_notation) +In this section, our example resource will be a [Reverse Polish Notation (RPN)](https://en.wikipedia.org/wiki/Reverse_Polish_notation) calculator. (Engineers of a certain vintage will remember this from handheld calculators of the 1970s.) A RPN calculator is a stateful entity: a consumer pushes operands and operations onto a stack @@ -20,7 +20,7 @@ interface types { add, sub, mul, - div + div, } resource engine { From b8d0577493abc4c11ca9b44ef06cba0774d8ac41 Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 17:49:30 -0500 Subject: [PATCH 2/6] test: initial WIT formatting: `topiary fmt ./**/*.wit` --- .../examples/composing-section-examples/http-service.wit | 2 +- .../examples/tutorial/js/string-reverse-upper/component.wit | 1 - .../examples/tutorial/moonbit/adder-with-error/world.wit | 2 +- component-model/examples/tutorial/tinygo/adder/world2.wit | 3 +-- component-model/examples/tutorial/wit/adder/world.wit | 2 +- .../examples/wit-section-examples/clocks/wall-clock.wit | 1 - .../examples/wit-section-examples/filesystems/types.wit | 1 - 7 files changed, 4 insertions(+), 8 deletions(-) diff --git a/component-model/examples/composing-section-examples/http-service.wit b/component-model/examples/composing-section-examples/http-service.wit index b05e6e02..f80efa3f 100644 --- a/component-model/examples/composing-section-examples/http-service.wit +++ b/component-model/examples/composing-section-examples/http-service.wit @@ -1,5 +1,5 @@ package foo:wasi-http-service; world target-world { - include wasi:http/proxy@0.2.3; + include wasi:http/proxy@0.2.3; } diff --git a/component-model/examples/tutorial/js/string-reverse-upper/component.wit b/component-model/examples/tutorial/js/string-reverse-upper/component.wit index 1084e6b0..281cbbe7 100644 --- a/component-model/examples/tutorial/js/string-reverse-upper/component.wit +++ b/component-model/examples/tutorial/js/string-reverse-upper/component.wit @@ -11,6 +11,5 @@ world revup { // :/@ // import example:string-reverse/reverse@0.1.0; - export reversed-upper; } diff --git a/component-model/examples/tutorial/moonbit/adder-with-error/world.wit b/component-model/examples/tutorial/moonbit/adder-with-error/world.wit index b41acc96..d0d7a5b2 100644 --- a/component-model/examples/tutorial/moonbit/adder-with-error/world.wit +++ b/component-model/examples/tutorial/moonbit/adder-with-error/world.wit @@ -2,7 +2,7 @@ package docs:adder@0.1.0; interface add { variant computation-error { - overflow + overflow, } add: func(x: u32, y: u32) -> result; } diff --git a/component-model/examples/tutorial/tinygo/adder/world2.wit b/component-model/examples/tutorial/tinygo/adder/world2.wit index 6c4b9cbc..5d80175c 100644 --- a/component-model/examples/tutorial/tinygo/adder/world2.wit +++ b/component-model/examples/tutorial/tinygo/adder/world2.wit @@ -6,6 +6,5 @@ interface add { world adder { include wasi:cli/imports@0.2.0; - export add; -} \ No newline at end of file +} diff --git a/component-model/examples/tutorial/wit/adder/world.wit b/component-model/examples/tutorial/wit/adder/world.wit index 59a46856..a836a628 100644 --- a/component-model/examples/tutorial/wit/adder/world.wit +++ b/component-model/examples/tutorial/wit/adder/world.wit @@ -6,4 +6,4 @@ interface add { world adder { export add; -} \ No newline at end of file +} diff --git a/component-model/examples/wit-section-examples/clocks/wall-clock.wit b/component-model/examples/wit-section-examples/clocks/wall-clock.wit index 40366987..d39aa1df 100644 --- a/component-model/examples/wit-section-examples/clocks/wall-clock.wit +++ b/component-model/examples/wit-section-examples/clocks/wall-clock.wit @@ -7,6 +7,5 @@ interface wall-clock { seconds: u64, nanoseconds: u32, } - now: func() -> datetime; } diff --git a/component-model/examples/wit-section-examples/filesystems/types.wit b/component-model/examples/wit-section-examples/filesystems/types.wit index cd4866b6..0965d95b 100644 --- a/component-model/examples/wit-section-examples/filesystems/types.wit +++ b/component-model/examples/wit-section-examples/filesystems/types.wit @@ -18,6 +18,5 @@ interface types { open-at: func( path: string, ) -> result; - } } From 6c5c53d20397ded3fe662fb74147ca52e442559f Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 17:56:22 -0500 Subject: [PATCH 3/6] test: intial markdown formatting pass --- component-model/examples/tutorial/README.md | 1 - .../src/composing-and-distributing/distributing.md | 4 ++-- .../building-a-simple-component/moonbit.md | 8 ++++---- .../language-support/building-a-simple-component/rust.md | 8 ++++---- .../importing-and-reusing-components/javascript.md | 2 +- .../importing-and-reusing-components/rust.md | 3 +-- .../src/language-support/using-http-in-components/rust.md | 2 +- 7 files changed, 13 insertions(+), 15 deletions(-) diff --git a/component-model/examples/tutorial/README.md b/component-model/examples/tutorial/README.md index 86f5083e..0f3f789b 100644 --- a/component-model/examples/tutorial/README.md +++ b/component-model/examples/tutorial/README.md @@ -8,7 +8,6 @@ has an `add` operation: ```wit adder package docs:adder@0.1.0; - interface add { add: func(x: u32, y: u32) -> u32; } diff --git a/component-model/src/composing-and-distributing/distributing.md b/component-model/src/composing-and-distributing/distributing.md index 1d9c919a..1f7f090f 100644 --- a/component-model/src/composing-and-distributing/distributing.md +++ b/component-model/src/composing-and-distributing/distributing.md @@ -77,7 +77,7 @@ default_registry = "ghcr.io" [namespace_registries] # Tell wkg that packages with the `wasi` namespace are in an OCI registry # under ghcr.io/webassembly -wasi = { registry = "wasi", metadata = { preferredProtocol = "oci", "oci" = {registry = "ghcr.io", namespacePrefix = "webassembly/" } } } +wasi = { registry = "wasi", metadata = { preferredProtocol = "oci", "oci" = { registry = "ghcr.io", namespacePrefix = "webassembly/" } } } ``` As a more generic example, the following configuration instructs `wkg` to use @@ -89,7 +89,7 @@ default_registry = "ghcr.io" [namespace_registries] # Instruct wkg to use the OCI protocol to fetch packages with the `docs` namespace from ttl.sh/wasm-components -docs = { registry = "docs", metadata = { preferredProtocol = "oci", "oci" = {registry = "ttl.sh", namespacePrefix = "wasm-components/" } } } +docs = { registry = "docs", metadata = { preferredProtocol = "oci", "oci" = { registry = "ttl.sh", namespacePrefix = "wasm-components/" } } } ``` > Note: the registry name can be referenced in the `package_registry_overrides` section of the `wkg` config diff --git a/component-model/src/language-support/building-a-simple-component/moonbit.md b/component-model/src/language-support/building-a-simple-component/moonbit.md index 25ea431b..328eb179 100644 --- a/component-model/src/language-support/building-a-simple-component/moonbit.md +++ b/component-model/src/language-support/building-a-simple-component/moonbit.md @@ -193,12 +193,12 @@ The WIT printed should be similar if not exactly the same as the following: package root:component; world root { - export docs:adder/add@0.1.0; + export docs:adder/add@0.1.0; } package docs:adder@0.1.0 { - interface add { - add: func(x: u32, y: u32) -> u32; - } + interface add { + add: func(x: u32, y: u32) -> u32; + } } ``` diff --git a/component-model/src/language-support/building-a-simple-component/rust.md b/component-model/src/language-support/building-a-simple-component/rust.md index c54dc704..2d9dab82 100644 --- a/component-model/src/language-support/building-a-simple-component/rust.md +++ b/component-model/src/language-support/building-a-simple-component/rust.md @@ -221,12 +221,12 @@ The command above should produce the output below: package root:component; world root { - export docs:adder/add@0.1.0; + export docs:adder/add@0.1.0; } package docs:adder@0.1.0 { - interface add { - add: func(x: u32, y: u32) -> u32; - } + interface add { + add: func(x: u32, y: u32) -> u32; + } } ``` diff --git a/component-model/src/language-support/importing-and-reusing-components/javascript.md b/component-model/src/language-support/importing-and-reusing-components/javascript.md index 13e064d9..f90ae4b4 100644 --- a/component-model/src/language-support/importing-and-reusing-components/javascript.md +++ b/component-model/src/language-support/importing-and-reusing-components/javascript.md @@ -113,7 +113,7 @@ You should see output like the following: package root:component; world root { - export example:string-reverse-upper/reversed-upper@0.1.0; + export example:string-reverse-upper/reversed-upper@0.1.0; } ``` diff --git a/component-model/src/language-support/importing-and-reusing-components/rust.md b/component-model/src/language-support/importing-and-reusing-components/rust.md index fe2a6bc0..b36f20a7 100644 --- a/component-model/src/language-support/importing-and-reusing-components/rust.md +++ b/component-model/src/language-support/importing-and-reusing-components/rust.md @@ -20,7 +20,6 @@ interface calculate { world calculator { import docs:adder/add@0.1.0; - export calculate; } ``` @@ -32,7 +31,7 @@ custom `wkg.toml` to our project: ```toml [overrides] -"docs:adder" = { path = "../adder/wit" } # directory containing the WIT package +"docs:adder" = { path = "../adder/wit" } # directory containing the WIT package ``` After adding this configuration file, when we run `wkg wit fetch`, `wkg` will assume that the package `docs:adder` can be found diff --git a/component-model/src/language-support/using-http-in-components/rust.md b/component-model/src/language-support/using-http-in-components/rust.md index c495923c..1b3dda0d 100644 --- a/component-model/src/language-support/using-http-in-components/rust.md +++ b/component-model/src/language-support/using-http-in-components/rust.md @@ -4,7 +4,7 @@ Add the `wasm32-wasip2` target to the Rust toolchain. -```rust +```console rustup target add wasm32-wasip2 ``` From 969ae33020b9be150c10fac52a96fbee680e32d0 Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 17:58:58 -0500 Subject: [PATCH 4/6] test: markdown formatting callouts --- component-model/src/design/migrating-to-p3.md | 8 ++++---- component-model/src/tutorial.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/component-model/src/design/migrating-to-p3.md b/component-model/src/design/migrating-to-p3.md index 112f29eb..342f01f7 100644 --- a/component-model/src/design/migrating-to-p3.md +++ b/component-model/src/design/migrating-to-p3.md @@ -33,7 +33,7 @@ WASI 0.3 replaces every `wasi:io` resource with a Canonical ABI primitive. The t A WASI 0.2 read call returned a single `input-stream` resource and surfaced terminal errors only as you consumed it. WASI 0.3 splits those concerns: the call returns a `stream` for the data and a `future>` for the outcome, packed into a tuple. -```wit +```wit nofmt // WASI 0.2 (filesystem read) read-via-stream: func(offset: filesize) -> result; @@ -47,7 +47,7 @@ In WASI 0.3, the caller does not have to drain the stream to learn whether the r WASI 0.2 write paths handed a guest some host-owned resource (an `output-stream`) and let the guest push bytes into it. WASI 0.3 inverts that: the guest supplies the data as a `stream` value, and the host returns a `future` that resolves once it has finished consuming the stream. -```wit +```wit nofmt // WASI 0.2: receive an output-stream resource, write into it get-stdout: func() -> output-stream; @@ -59,7 +59,7 @@ write-via-stream: func(data: stream) -> future>; WASI 0.2 modeled operations that could suspend as a `start-foo` / `finish-foo` pair, with a `pollable` for readiness in between. WASI 0.3 collapses each pair into a single call: -```wit +```wit nofmt // WASI 0.2 start-connect: func(network: borrow, remote-address: ip-socket-address) -> result<_, error-code>; finish-connect: func() -> result, error-code>; @@ -77,7 +77,7 @@ The complete per-interface diff lives on [WASI 0.3](https://wasi.dev/releases/wa - **`wasi:io` is gone.** The package has no 0.3.0 release. Every resource it exposed (`pollable`, `input-stream`, `output-stream`) is replaced by a Component Model primitive, per the [concept mapping](#concept-mapping) above. - **`wasi:http` collapses from nine resources to two.** The incoming/outgoing × request/response/body matrix plus `future-trailers`, `future-incoming-response`, and `response-outparam` all become `request` and `response`, with `stream` bodies and a `future` for trailers. The handler is now an `async func`: -```wit +```wit nofmt // WASI 0.2 handle: func(request: incoming-request, response-out: response-outparam); diff --git a/component-model/src/tutorial.md b/component-model/src/tutorial.md index a82c7ee3..c0e66e49 100644 --- a/component-model/src/tutorial.md +++ b/component-model/src/tutorial.md @@ -42,9 +42,9 @@ These files can be found in the component book repository in the [`examples/tuto world adder { export add; } -``` + ``` -```wit + ```wit // wit/calculator/world.wit package docs:calculator@0.1.0; @@ -142,7 +142,7 @@ default_registry = "ghcr.io" [namespace_registries] # Tell wkg that the component-book WITs can be found at ghcr.io/bytecodealliance/docs -docs = { registry = "docs", metadata = { preferredProtocol = "oci", "oci" = {registry = "ghcr.io", namespacePrefix = "bytecodealliance/" } } } +docs = { registry = "docs", metadata = { preferredProtocol = "oci", "oci" = { registry = "ghcr.io", namespacePrefix = "bytecodealliance/" } } } ``` > [!NOTE] From 39e62fcb38ac648414b816290c47cf592adcb9ca Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 18:13:00 -0500 Subject: [PATCH 5/6] test: `topiary fmt component-model/src/language-support/using-wit-resources/rust.md --skip-stage host --skip-language rust` --- .topiary/languages.ncl | 1 + .../using-wit-resources/rust.md | 30 +++++++++---------- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/.topiary/languages.ncl b/.topiary/languages.ncl index 525e1426..461d4883 100644 --- a/.topiary/languages.ncl +++ b/.topiary/languages.ncl @@ -10,5 +10,6 @@ }, queries.injections.source.path = "queries/injections.scm", }, + wit.indent = " ", # 4 spaces }, } diff --git a/component-model/src/language-support/using-wit-resources/rust.md b/component-model/src/language-support/using-wit-resources/rust.md index 29de9ccc..de4cfa65 100644 --- a/component-model/src/language-support/using-wit-resources/rust.md +++ b/component-model/src/language-support/using-wit-resources/rust.md @@ -16,23 +16,23 @@ In WIT, the resource looks like the following: package docs:rpn@0.1.0; interface types { - enum operation { - add, - sub, - mul, - div, - } - - resource engine { - constructor(); - push-operand: func(operand: u32); - push-operation: func(operation: operation); - execute: func() -> u32; - } + enum operation { + add, + sub, + mul, + div, + } + + resource engine { + constructor(); + push-operand: func(operand: u32); + push-operation: func(operation: operation); + execute: func() -> u32; + } } world calculator { - export types; + export types; } ``` @@ -131,7 +131,7 @@ To use the calculator engine in another component, that component must import th package docs:rpn-cmd; world app { - import docs:rpn/types@0.1.0; + import docs:rpn/types@0.1.0; } ``` From d184976167810347e163d8915610bcf9624a83a6 Mon Sep 17 00:00:00 2001 From: Mikhail Katychev Date: Tue, 6 Oct 2026 18:26:21 -0500 Subject: [PATCH 6/6] fix(md,wit): handle remainder of `nofmt` codeblocks --- .../examples/example-host/README.md | 4 +- component-model/examples/tutorial/README.md | 18 +-- component-model/src/design/async.md | 20 +-- component-model/src/design/wit-example.md | 26 ++-- component-model/src/design/wit.md | 125 +++++++++--------- .../building-a-simple-component/moonbit.md | 8 +- .../building-a-simple-component/rust.md | 8 +- .../javascript.md | 2 +- .../creating-runnable-components/rust.md | 12 +- .../javascript.md | 2 +- .../importing-and-reusing-components/rust.md | 6 +- component-model/src/tutorial.md | 18 +-- component-model/src/using-wit-resources.md | 38 +++--- 13 files changed, 145 insertions(+), 142 deletions(-) diff --git a/component-model/examples/example-host/README.md b/component-model/examples/example-host/README.md index 67e543ef..177470cc 100644 --- a/component-model/examples/example-host/README.md +++ b/component-model/examples/example-host/README.md @@ -9,11 +9,11 @@ The `adder` world exports an interface called `add` which defines an function th package docs:adder@0.1.0; interface add { - add: func(x: u32, y: u32) -> u32; + add: func(x: u32, y: u32) -> u32; } world adder { - export add; + export add; } ``` diff --git a/component-model/examples/tutorial/README.md b/component-model/examples/tutorial/README.md index 0f3f789b..b046d61b 100644 --- a/component-model/examples/tutorial/README.md +++ b/component-model/examples/tutorial/README.md @@ -9,11 +9,11 @@ has an `add` operation: package docs:adder@0.1.0; interface add { - add: func(x: u32, y: u32) -> u32; + add: func(x: u32, y: u32) -> u32; } world adder { - export add; + export add; } ``` @@ -21,19 +21,19 @@ world adder { package docs:calculator@0.1.0; interface calculate { - enum op { - add, - } - eval-expression: func(op: op, x: u32, y: u32) -> u32; + enum op { + add, + } + eval-expression: func(op: op, x: u32, y: u32) -> u32; } world calculator { - export calculate; - import docs:adder/add; + export calculate; + import docs:adder/add; } world app { - import calculate; + import calculate; } ``` diff --git a/component-model/src/design/async.md b/component-model/src/design/async.md index 9ec67c1a..b8593bc1 100644 --- a/component-model/src/design/async.md +++ b/component-model/src/design/async.md @@ -1,15 +1,15 @@ # Native Async with WASI 0.3 WASI 0.3 adds new Canonical ABI primitives to the Component Model that enable async functionality. Components that target WASI 0.3 can use the new features in their WIT files: -* `async func` +* `async func` * `stream` * `future` These new types let interfaces express asynchronous operations that compose across component boundaries. -For migration mechanics (e.g., how a WASI 0.2 component maps onto these primitives) see [Migrating from WASI 0.2 to WASI 0.3](./migrating-to-p3.md). +For migration mechanics (e.g., how a WASI 0.2 component maps onto these primitives) see [Migrating from WASI 0.2 to WASI 0.3](./migrating-to-p3.md). -For a closer look at the WASI 0.3 release, including a full per-interface diff, see [WASI 0.3](https://wasi.dev/releases/wasi-p3) on WASI.dev. +For a closer look at the WASI 0.3 release, including a full per-interface diff, see [WASI 0.3](https://wasi.dev/releases/wasi-p3) on WASI.dev. This page focuses on the Component Model concepts themselves. @@ -22,7 +22,7 @@ The Component Model's Canonical ABI defines how typed values cross component bou That arrangement holds up for two-party interactions, but it falters once components are composed in a chain. If a component awaits work that another component delegates further, the readiness signal has to travel back up the chain. When readiness is expressed as a resource scoped to a single component, the intermediate component is stuck running an event loop purely to forward the wake-up to its caller; the runtime cannot help, because the resource doesn't live in a place the runtime can reach across. This is sometimes called the **sandwich problem**: an async vocabulary that describes a single hop just fine but cannot propagate readiness past one. -Native async primitives help close this expressivity gap. With updated Component ABI mechanics that enable `async func`, `stream`, and `future` available at the WIT level, scheduling and wake-up propagation become the runtime's job rather than any individual component's. +Native async primitives help close this expressivity gap. With updated Component ABI mechanics that enable `async func`, `stream`, and `future` available at the WIT level, scheduling and wake-up propagation become the runtime's job rather than any individual component's. Components can pass futures and streams along without keeping their own event loops running to relay readiness, as was necessary with WASI 0.2. @@ -41,21 +41,21 @@ Code generated from the WIT picks up each language's natural async idiom: `async ### Streams (`stream`) -A typed, asynchronous channel for a sequence of `T` values. Crucially, `stream` is a Canonical ABI *value*, not a resource (as opposed to WASI 0.2) -- it can be returned from a call, accepted as a parameter, and handed from one component to another without giving up ownership of the underlying buffer. +A typed, asynchronous channel for a sequence of `T` values. Crucially, `stream` is a Canonical ABI *value*, not a resource (as opposed to WASI 0.2) -- it can be returned from a call, accepted as a parameter, and handed from one component to another without giving up ownership of the underlying buffer. The same value can also be passed straight through one or more intermediate components without those components having to relay any wake-ups. -```wit +```wit nofmt read-via-stream: func() -> tuple, future>>; ``` ### Futures (`future`) -A typed handle for a single value that will become available later. Like `stream`, `future` is a value rather than a resource, so it crosses component boundaries the same way a primitive does. +A typed handle for a single value that will become available later. Like `stream`, `future` is a value rather than a resource, so it crosses component boundaries the same way a primitive does. Note that synchronous functions which return `future`s *cannot* block; the caller can await the result when it needs it. -```wit +```wit nofmt write-via-stream: func(data: stream) -> future>; ``` @@ -65,7 +65,7 @@ write-via-stream: func(data: stream) -> future>; Reads return both a data channel and a completion handle, packed into a tuple ([`read-via-stream`](https://github.com/WebAssembly/wasi-filesystem/blob/main/wit/types.wit#L308) in `wasi-filesystem`): -```wit +```wit nofmt read-via-stream: func() -> tuple, future>>; ``` @@ -75,7 +75,7 @@ The two halves are independent. The caller can consume the stream eagerly, sampl Writes use the symmetric shape: the guest supplies the data as a `stream` parameter, and the host returns a `future` that resolves once it has consumed the stream. Stdout, stderr, filesystem writes, and TCP sends all follow this shape ([`write-via-stream`](https://github.com/WebAssembly/wasi-filesystem/blob/main/wit/types.wit#L320) in `wasi-filesystem`): -```wit +```wit nofmt write-via-stream: func(data: stream) -> future>; ``` diff --git a/component-model/src/design/wit-example.md b/component-model/src/design/wit-example.md index 07f09e43..3a5d2195 100644 --- a/component-model/src/design/wit-example.md +++ b/component-model/src/design/wit-example.md @@ -53,7 +53,7 @@ In this case, declarations are _type declarations_ or _function declarations_. _Record types_ are one of the possible types that can be declared in WIT. -```wit +```wit nofmt record datetime { seconds: u64, nanoseconds: u32, @@ -78,7 +78,7 @@ an unsigned 32-bit integer. The following declares a function named `now`: -```wit +```wit nofmt now: func() -> datetime; ``` @@ -116,7 +116,7 @@ Let's look at some WIT features used in this interface. ### Enums -```wit +```wit nofmt enum error-code { access, bad-descriptor, @@ -145,7 +145,7 @@ Let's look at the method declarations one at a time: #### Reading from files -```wit +```wit nofmt read: func( length: filesize, offset: filesize, @@ -189,7 +189,7 @@ The `open-at()` method is a constructor, which we know because it returns a `descriptor` when it doesn't fail (remember that these methods are attached to the resource type `descriptor`): -```wit +```wit nofmt open-at: func( path: string, ) -> result; @@ -215,7 +215,7 @@ The runtime owns the scheduling; the guest sees an ordinary call and the host se package wasi-example:cli; interface run { - run: async func() -> result; + run: async func() -> result; } ``` @@ -229,8 +229,8 @@ Reading from standard input pairs a `stream` with a `future`: ```wit interface stdin { - use types.{error-code}; - read-via-stream: func() -> tuple, future>>; + use types.{error-code}; + read-via-stream: func() -> tuple, future>>; } ``` @@ -254,8 +254,8 @@ and the host returns a `future` that resolves once the bytes are consumed: ```wit interface stdout { - use types.{error-code}; - write-via-stream: func(data: stream) -> future>; + use types.{error-code}; + write-via-stream: func(data: stream) -> future>; } ``` @@ -269,9 +269,9 @@ The `command` world below imports the I/O interfaces and exports `run`: ```wit world command { - import stdin; - import stdout; - export run; + import stdin; + import stdout; + export run; } ``` diff --git a/component-model/src/design/wit.md b/component-model/src/design/wit.md index df203233..dbd0f987 100644 --- a/component-model/src/design/wit.md +++ b/component-model/src/design/wit.md @@ -64,7 +64,7 @@ WIT defines special comment formats for documentation: For example: -```wit +```wit nofmt /// Prints "hello". print-hello: func(); @@ -124,7 +124,7 @@ WIT defines the following primitive types: `list` for any type `T` denotes an ordered sequence of values of type `T`. `T` can be any type, built-in or user-defined: -```wit +```wit nofmt list // byte buffer list // a list of customers ``` @@ -138,7 +138,7 @@ This is similar to Rust `Vec`, or Java `List`. For example, a lookup function might return an option in order to allow for the possibility that the lookup key wasn't found: -```wit +```wit nofmt option ``` @@ -158,7 +158,7 @@ For example, a HTTP request function might return a result, with the success case (the `T` type) representing a HTTP response, and the error case (the `E` type) representing the various kinds of error that might occur: -```wit +```wit nofmt result ``` @@ -174,7 +174,7 @@ For example, a `print` function could return an error code if it fails, but has nothing to return if it succeeds. In this case, you can omit the corresponding type as follows: -```wit +```wit nofmt result // no data associated with the error case result<_, u32> // no data associated with the success case result // no data associated with either case @@ -189,7 +189,7 @@ A `tuple` type is an ordered _fixed-length_ sequence of values of specified type It is similar to a [_record_](#records), except that the fields are identified by indices instead of by names. -```wit +```wit nofmt tuple // An integer and a string tuple // An integer, then a string, then an integer ``` @@ -204,7 +204,7 @@ a `stream` delivers values incrementally: the producer pushes elements as they become available, and the consumer receives them as they arrive. -```wit +```wit nofmt stream // a stream of bytes stream // a stream of records ``` @@ -230,7 +230,7 @@ that will become available later. A function returning a `future` does not block on the value being produced; the caller awaits the future when it needs the value. -```wit +```wit nofmt future // a future that will resolve to a u32 future> // a future that will resolve to either a response or an error ``` @@ -256,7 +256,7 @@ A record instance contains a value for every field. Field types can be built-in or user-defined. The syntax is as follows: -```wit +```wit nofmt record customer { id: u64, name: string, @@ -280,7 +280,7 @@ An instance of a variant type matches exactly one case. Cases are separated by commas. The syntax is as follows: -```wit +```wit nofmt variant allowed-destinations { none, any, @@ -303,7 +303,7 @@ and enforce the correct data shape for each tag. An `enum` type is a variant type where none of the cases have associated data: -```wit +```wit nofmt enum color { hot-pink, lime-green, @@ -335,7 +335,7 @@ For example, we could model a blob (binary large object) as a resource. The following WIT defines the `blob` resource type, which contains a constructor, two methods, and a static function: -```wit +```wit nofmt resource blob { constructor(init: list); write: func(bytes: list); @@ -362,7 +362,7 @@ and a constructor can be rewritten to a function that returns a value owned by the caller. For example, the `blob` resource [above](#resources) could be approximated as: -```wit +```wit nofmt resource blob; blob-constructor: func(bytes: list) -> blob; blob-write: func(self: borrow, bytes: list); @@ -387,7 +387,7 @@ or returning without transferring ownership to another function.) A `flags` type is a set of named booleans. -```wit +```wit nofmt flags allowed-methods { get, post, @@ -404,7 +404,7 @@ flags allowed-methods { You can define a new type alias using `type ... = ...`. Type aliases are useful for giving shorter or more meaningful names to types: -```wit +```wit nofmt type buffer = list; type http-result = result; ``` @@ -414,7 +414,7 @@ type http-result = result; A function is defined by a name and a function type. As with record fields, the name is separated from the type by a colon: -```wit +```wit nofmt do-nothing: func(); ``` @@ -422,7 +422,7 @@ The function type is the keyword `func`, followed by a parenthesised, comma-separated list of parameters (names and types). If the function returns a value, this is expressed as an arrow symbol (`->`) followed by the return type: -```wit +```wit nofmt // This function does not return a value print: func(message: string); @@ -434,7 +434,7 @@ lookup: func(store: kv-store, key: string) -> option; To express a function that returns multiple values, you can use any compound type (such as [tuples](#tuple) or [records](#record)). -```wit +```wit nofmt get-customers-paged: func(cont: continuation-token) -> tuple, continuation-token>; ``` @@ -445,7 +445,7 @@ or can be declared as an import or export in a [world](#worlds). A function can be declared `async`, indicating that the call may suspend before producing its result: -```wit +```wit nofmt // An async function returning a result handle: async func(request: request) -> result; ``` @@ -464,14 +464,13 @@ enclosed in braces and introduced with the `interface` keyword: ```wit interface canvas { - type canvas-id = u64; - - record point { - x: u32, - y: u32, - } + type canvas-id = u64; - draw-line: func(canvas: canvas-id, from: point, to: point); + record point { + x: u32, + y: u32, + } + draw-line: func(canvas: canvas-id, from: point, to: point); } ``` @@ -486,17 +485,17 @@ The interface can then refer to the types named in the `use`. ```wit interface types { - type dimension = u32; - record point { - x: dimension, - y: dimension, - } + type dimension = u32; + record point { + x: dimension, + y: dimension, + } } interface canvas { - use types.{dimension, point}; - type canvas-id = u64; - draw-line: func(canvas: canvas-id, from: point, to: point, thickness: dimension); + use types.{dimension, point}; + type canvas-id = u64; + draw-line: func(canvas: canvas-id, from: point, to: point, thickness: dimension); } ``` @@ -519,22 +518,22 @@ Imports describe the interfaces or functions that a component depends on. ```wit interface printer { - print: func(text: string); + print: func(text: string); } interface error-reporter { - report-error: func(error-message: string); + report-error: func(error-message: string); } world multi-function-device { - // The component implements the `printer` interface - export printer; + // The component implements the `printer` interface + export printer; - // The component implements the `scan` function - export scan: func() -> list; + // The component implements the `scan` function + export scan: func() -> list; - // The component needs to be supplied with an `error-reporter` - import error-reporter; + // The component needs to be supplied with an `error-reporter` + import error-reporter; } ``` @@ -555,8 +554,8 @@ you can use `package/name` syntax: ```wit world http-proxy { - export wasi:http/incoming-handler; - import wasi:http/outgoing-handler; + export wasi:http/incoming-handler; + import wasi:http/outgoing-handler; } ``` @@ -573,9 +572,9 @@ Interfaces can be declared inline in a world: ```wit world toy { - export example: interface { - do-nothing: func(); - } + export example: interface { + do-nothing: func(); + } } ``` @@ -587,12 +586,12 @@ and import all that world's imports. ```wit world glow-in-the-dark-multi-function-device { - // The component provides all the same exports, and depends on - // all the same imports, as a `multi-function-device`... - include multi-function-device; + // The component provides all the same exports, and depends on + // all the same imports, as a `multi-function-device`... + include multi-function-device; - // ...but also exports a function to make it glow in the dark - export glow: func(brightness: u8); + // ...but also exports a function to make it glow in the dark + export glow: func(brightness: u8); } ``` @@ -602,7 +601,7 @@ As with `use` directives, you can `include` worlds from other packages. A package is a set of interfaces and worlds, potentially defined across multiple files in the same directory. -Each WIT file is associated with one package, +Each WIT file is associated with one package, which is declared either directly in that file or in a peer file in the same directory. To declare a package, use the `package` directive to specify the package ID. @@ -624,28 +623,32 @@ the package IDs must all match each other. ```wit // types.wit interface types { - record request { /* ... */ } - record response { /* ... */ } + record request { + id: usize /* ... */ + } + record response { + id: usize /* ... */ + } } // incoming.wit interface incoming-handler { - use types.{request, response}; - // ... + use types.{request, response}; + // ... } // outgoing.wit interface outgoing-handler { - use types.{request, response}; - // ... + use types.{request, response}; + // ... } // http.wit package documentation:http@1.0.0; world proxy { - export incoming-handler; - import outgoing-handler; + export incoming-handler; + import outgoing-handler; } ``` diff --git a/component-model/src/language-support/building-a-simple-component/moonbit.md b/component-model/src/language-support/building-a-simple-component/moonbit.md index 328eb179..6b0d1eb2 100644 --- a/component-model/src/language-support/building-a-simple-component/moonbit.md +++ b/component-model/src/language-support/building-a-simple-component/moonbit.md @@ -193,12 +193,12 @@ The WIT printed should be similar if not exactly the same as the following: package root:component; world root { - export docs:adder/add@0.1.0; + export docs:adder/add@0.1.0; } package docs:adder@0.1.0 { - interface add { - add: func(x: u32, y: u32) -> u32; - } + interface add { + add: func(x: u32, y: u32) -> u32; + } } ``` diff --git a/component-model/src/language-support/building-a-simple-component/rust.md b/component-model/src/language-support/building-a-simple-component/rust.md index 2d9dab82..21d1f421 100644 --- a/component-model/src/language-support/building-a-simple-component/rust.md +++ b/component-model/src/language-support/building-a-simple-component/rust.md @@ -221,12 +221,12 @@ The command above should produce the output below: package root:component; world root { - export docs:adder/add@0.1.0; + export docs:adder/add@0.1.0; } package docs:adder@0.1.0 { - interface add { - add: func(x: u32, y: u32) -> u32; - } + interface add { + add: func(x: u32, y: u32) -> u32; + } } ``` diff --git a/component-model/src/language-support/creating-runnable-components/javascript.md b/component-model/src/language-support/creating-runnable-components/javascript.md index 6055a24e..f83563cf 100644 --- a/component-model/src/language-support/creating-runnable-components/javascript.md +++ b/component-model/src/language-support/creating-runnable-components/javascript.md @@ -23,6 +23,6 @@ The above component can be made recognizable as "runnable" to `wasi:cli`-aware t package runnable:js-component; world component { - export wasi:cli/run@0.2.4; + export wasi:cli/run@0.2.4; } ``` diff --git a/component-model/src/language-support/creating-runnable-components/rust.md b/component-model/src/language-support/creating-runnable-components/rust.md index 88cbaeb0..6dcedb2b 100644 --- a/component-model/src/language-support/creating-runnable-components/rust.md +++ b/component-model/src/language-support/creating-runnable-components/rust.md @@ -127,12 +127,12 @@ contents to `runnable-example/wit/component.wit`: package example:runnable; interface greet { - greet: func(name: string) -> string; + greet: func(name: string) -> string; } world greeter { - export greet; - export wasi:cli/run@0.2.7; + export greet; + export wasi:cli/run@0.2.7; } ``` {{#endtab }} @@ -141,12 +141,12 @@ world greeter { package example:runnable; interface greet { - greet: func(name: string) -> string; + greet: func(name: string) -> string; } world greeter { - export greet; - export wasi:cli/run@0.3.0-rc-2026-03-15; + export greet; + export wasi:cli/run@0.3.0-rc-2026-03-15; } ``` diff --git a/component-model/src/language-support/importing-and-reusing-components/javascript.md b/component-model/src/language-support/importing-and-reusing-components/javascript.md index f90ae4b4..fe1ce47d 100644 --- a/component-model/src/language-support/importing-and-reusing-components/javascript.md +++ b/component-model/src/language-support/importing-and-reusing-components/javascript.md @@ -113,7 +113,7 @@ You should see output like the following: package root:component; world root { - export example:string-reverse-upper/reversed-upper@0.1.0; + export example:string-reverse-upper/reversed-upper@0.1.0; } ``` diff --git a/component-model/src/language-support/importing-and-reusing-components/rust.md b/component-model/src/language-support/importing-and-reusing-components/rust.md index b36f20a7..cd1da533 100644 --- a/component-model/src/language-support/importing-and-reusing-components/rust.md +++ b/component-model/src/language-support/importing-and-reusing-components/rust.md @@ -15,12 +15,12 @@ that component in a calculator component. Here is a partial example world for a package docs:calculator; interface calculate { - eval-expression: func(expr: string) -> u32; + eval-expression: func(expr: string) -> u32; } world calculator { - import docs:adder/add@0.1.0; - export calculate; + import docs:adder/add@0.1.0; + export calculate; } ``` diff --git a/component-model/src/tutorial.md b/component-model/src/tutorial.md index c0e66e49..7682eee7 100644 --- a/component-model/src/tutorial.md +++ b/component-model/src/tutorial.md @@ -36,11 +36,11 @@ These files can be found in the component book repository in the [`examples/tuto package docs:adder@0.1.0; interface add { - add: func(x: u32, y: u32) -> u32; + add: func(x: u32, y: u32) -> u32; } world adder { - export add; + export add; } ``` @@ -49,19 +49,19 @@ These files can be found in the component book repository in the [`examples/tuto package docs:calculator@0.1.0; interface calculate { - enum op { - add, - } - eval-expression: func(op: op, x: u32, y: u32) -> u32; + enum op { + add, + } + eval-expression: func(op: op, x: u32, y: u32) -> u32; } world calculator { - export calculate; - import docs:adder/add@0.1.0; + export calculate; + import docs:adder/add@0.1.0; } world app { - import calculate; + import calculate; } ``` diff --git a/component-model/src/using-wit-resources.md b/component-model/src/using-wit-resources.md index f857d726..7464641d 100644 --- a/component-model/src/using-wit-resources.md +++ b/component-model/src/using-wit-resources.md @@ -11,28 +11,28 @@ An example of a resource: package docs:calc-resource@0.1.0; interface types { - enum operation { - add, - sub, - mul, - div, - } - - variant execute-error { - divide-by-zero, - unexpected(string), - } - - resource stack-calculator { - constructor(); - push-operand: func(operand: u32); - push-operation: func(operation: operation); - execute: func() -> result; - } + enum operation { + add, + sub, + mul, + div, + } + + variant execute-error { + divide-by-zero, + unexpected(string), + } + + resource stack-calculator { + constructor(); + push-operand: func(operand: u32); + push-operation: func(operation: operation); + execute: func() -> result; + } } world calculator { - export types; + export types; } ```