html-to-markdown 2.25.1 → 2.26.2

data/rust-vendor/wit-bindgen-0.46.0/src/lib.rs

@@ -1,881 +0,0 @@
-//! Bindings generation support for Rust with the Component Model.
-//!
-//! This crate is a bindings generator for [WIT] and the [Component Model].
-//! Users are likely interested in the [`generate!`] macro which actually
-//! generates bindings. Otherwise this crate provides any runtime support
-//! necessary for the macro-generated code.
-//!
-//! [WIT]: https://component-model.bytecodealliance.org/design/wit.html
-//! [Component Model]: https://component-model.bytecodealliance.org/
-
-#![no_std]
-
-#[cfg(not(feature = "rustc-dep-of-std"))]
-extern crate alloc;
-#[cfg(feature = "std")]
-extern crate std;
-
-/// Generate bindings for an input WIT document.
-///
-/// This macro is the bread-and-butter of the `wit-bindgen` crate. The macro
-/// here will parse [WIT] as input and generate Rust bindings to work with the
-/// `world` that's specified in the [WIT]. For a primer on WIT see [this
-/// documentation][WIT] and for a primer on worlds see [here][worlds].
-///
-/// [WIT]: https://component-model.bytecodealliance.org/design/wit.html
-/// [worlds]: https://component-model.bytecodealliance.org/design/worlds.html
-///
-/// This macro takes as input a [WIT package] as well as a [`world`][worlds]
-/// within that package. It will then generate a Rust function for all `import`s
-/// into the world. If there are any `export`s then a Rust `trait` will be
-/// generated for you to implement. The macro additionally takes a number of
-/// configuration parameters documented below as well.
-///
-/// Basic invocation of the macro can look like:
-///
-/// ```
-/// use wit_bindgen::generate;
-/// # macro_rules! generate { ($($t:tt)*) => () }
-///
-/// generate!();
-/// ```
-///
-/// This will parse a WIT package in the `wit` folder adjacent to your project's
-/// `Cargo.toml` file. Within this WIT package there must be precisely one
-/// `world` and that world will be the one that has bindings generated for it.
-/// All other options remain at their default values (more on this below).
-///
-/// If your WIT package has more than one `world`, or if you want to select a
-/// world from the dependencies, you can specify a world explicitly:
-///
-/// ```
-/// use wit_bindgen::generate;
-/// # macro_rules! generate { ($($t:tt)*) => () }
-///
-/// generate!("my-world");
-/// generate!("wasi:cli/imports");
-/// ```
-///
-/// This form of the macro takes a single string as an argument which is a
-/// "world specifier" to select which world is being generated. As a single
-/// string, such as `"my-world"`, this selects the world named `my-world` in the
-/// package being parsed in the `wit` folder. The longer form specification
-/// `"wasi:cli/imports"` indicates that the `wasi:cli` package, located in the
-/// `wit/deps` folder, will have a world named `imports` and those bindings will
-/// be generated.
-///
-/// If your WIT package is located in a different directory than one called
-/// `wit` then it can be specified with the `in` keyword:
-///
-/// ```
-/// use wit_bindgen::generate;
-/// # macro_rules! generate { ($($t:tt)*) => () }
-///
-/// generate!(in "./my/other/path/to/wit");
-/// generate!("a-world" in "../path/to/wit");
-/// ```
-///
-/// The full-form of the macro, however, takes a braced structure which is a
-/// "bag of options":
-///
-/// ```
-/// use wit_bindgen::generate;
-/// # macro_rules! generate { ($($t:tt)*) => () }
-///
-/// generate!({
-///     world: "my-world",
-///     path: "../path/to/wit",
-///     // ...
-/// });
-/// ```
-///
-/// For documentation on each option, see below.
-///
-/// ## Exploring generated bindings
-///
-/// Once bindings have been generated they can be explored via a number of means
-/// to see what was generated:
-///
-/// * Using `cargo doc` should render all of the generated bindings in addition
-///   to the original comments in the WIT format itself.
-/// * If your IDE supports `rust-analyzer` code completion should be available
-///   to explore and see types.
-/// * The `wit-bindgen` CLI tool, packaged as `wit-bindgen-cli` on crates.io,
-///   can be executed the same as the `generate!` macro and the output can be
-///   read.
-/// * If you're seeing an error, `WIT_BINDGEN_DEBUG=1` can help debug what's
-///   happening (more on this below) by emitting macro output to a file.
-/// * This documentation can be consulted for various constructs as well.
-///
-/// Currently browsing generated code may have road bumps on the way. If you run
-/// into issues or have idea of how to improve the situation please [file an
-/// issue].
-///
-/// [file an issue]: https://github.com/bytecodealliance/wit-bindgen/issues/new
-///
-/// ## Namespacing
-///
-/// In WIT, worlds can import and export `interface`s, functions, and types. Each
-/// `interface` can either be "anonymous" and only named within the context of a
-/// `world` or it can have a "package ID" associated with it. Names in Rust take
-/// into account all the names associated with a WIT `interface`. For example
-/// the package ID `foo:bar/baz` would create a `mod foo` which contains a `mod
-/// bar` which contains a `mod baz`.
-///
-/// WIT imports and exports are additionally separated into their own
-/// namespaces. Imports are generated at the level of the `generate!` macro
-/// where exports are generated under an `exports` namespace.
-///
-/// ## Imports
-///
-/// Imports into a `world` can be types, resources, functions, and interfaces.
-/// Each of these is bound as a Rust type, function, or module. The intent is
-/// that the WIT interfaces map to what is roughly idiomatic Rust for the given
-/// interface.
-///
-/// ### Imports: Top-level functions and types
-///
-/// Imports at the top-level of a world are generated directly where the
-/// `generate!` macro is invoked.
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r"
-///         package a:b;
-///
-///         world the-world {
-///             record fahrenheit {
-///                 degrees: f32,
-///             }
-///
-///             import what-temperature-is-it: func() -> fahrenheit;
-///
-///             record celsius {
-///                 degrees: f32,
-///             }
-///
-///             import convert-to-celsius: func(a: fahrenheit) -> celsius;
-///         }
-///     ",
-/// });
-///
-/// fn test() {
-///     let current_temp = what_temperature_is_it();
-///     println!("current temp in fahrenheit is {}", current_temp.degrees);
-///     let in_celsius: Celsius = convert_to_celsius(current_temp);
-///     println!("current temp in celsius is {}", in_celsius.degrees);
-/// }
-/// ```
-///
-/// ### Imports: Interfaces
-///
-/// Interfaces are placed into submodules where the `generate!` macro is
-/// invoked and are namespaced based on their identifiers.
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r"
-///         package my:test;
-///
-///         interface logging {
-///             enum level {
-///                 debug,
-///                 info,
-///                 error,
-///             }
-///             log: func(level: level, msg: string);
-///         }
-///
-///         world the-world {
-///             import logging;
-///             import global-logger: interface {
-///                 use logging.{level};
-///
-///                 set-current-level: func(level: level);
-///                 get-current-level: func() -> level;
-///             }
-///         }
-///     ",
-/// });
-///
-/// // `my` and `test` are from `package my:test;` and `logging` is for the
-/// // interfac name.
-/// use my::test::logging::Level;
-///
-/// fn test() {
-///     let current_level = global_logger::get_current_level();
-///     println!("current logging level is {current_level:?}");
-///     global_logger::set_current_level(Level::Error);
-///
-///     my::test::logging::log(Level::Info, "Hello there!");
-/// }
-/// #
-/// # fn main() {}
-/// ```
-///
-/// ### Imports: Resources
-///
-/// Imported resources generate a type named after the name of the resource.
-/// This type is then used both for borrows as `&T` as well as via ownership as
-/// `T`. Resource methods are bound as methods on the type `T`.
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         interface logger {
-///             enum level {
-///                 debug,
-///                 info,
-///                 error,
-///             }
-///
-///             resource logger {
-///                 constructor(destination: string);
-///                 log: func(level: level, msg: string);
-///             }
-///         }
-///
-///         // Note that while this world does not textually import the above
-///         // `logger` interface it is a transitive dependency via the `use`
-///         // statement so the "elaborated world" imports the logger.
-///         world the-world {
-///             use logger.{logger};
-///
-///             import get-global-logger: func() -> logger;
-///         }
-///     "#,
-/// });
-///
-/// use my::test::logger::Level;
-///
-/// fn test() {
-///     let logger = get_global_logger();
-///     logger.log(Level::Debug, "This is a global message");
-///
-///     let logger2 = Logger::new("/tmp/other.log");
-///     logger2.log(Level::Info, "This is not a global message");
-/// }
-/// #
-/// # fn main() {}
-/// ```
-///
-/// Note in the above example the lack of import of `Logger`. The `use`
-/// statement imported the `Logger` type, an alias of it, from the `logger`
-/// interface into `the-world`. This generated a Rust `type` alias so `Logger`
-/// was available at the top-level.
-///
-/// ## Exports: Basic Usage
-///
-/// A WIT world can not only `import` functionality but can additionally
-/// `export` functionality as well. An `export` represents a contract that the
-/// Rust program must implement to be able to work correctly. The `generate!`
-/// macro's goal is to take care of all the low-level and ABI details for you,
-/// so the end result is that `generate!`, for exports, will generate Rust
-/// `trait`s that you must implement.
-///
-/// A minimal example of this is:
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         world my-world {
-///             export hello: func();
-///         }
-///     "#,
-/// });
-///
-/// struct MyComponent;
-///
-/// impl Guest for MyComponent {
-///     fn hello() {}
-/// }
-///
-/// export!(MyComponent);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// Here the `Guest` trait was generated by the `generate!` macro and represents
-/// the functions at the top-level of `my-world`, in this case the function
-/// `hello`. A custom type, here called `MyComponent`, is created and the trait
-/// is implemented for that type.
-///
-/// Additionally a macro is generated by `generate!` (macros generating macros)
-/// called `export!`. The `export!` macro is given a component that implements
-/// the export `trait`s and then it will itself generate all necessary
-/// `#[unsafe(no_mangle)]` functions to implement the ABI required.
-///
-/// ## Exports: Multiple Interfaces
-///
-/// Each `interface` in WIT will generate a `trait` that must be implemented in
-/// addition to the top-level `trait` for the world. All traits are named
-/// `Guest` here and are namespaced appropriately in modules:
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         interface a {
-///             func-in-a: func();
-///             second-func-in-a: func();
-///         }
-///
-///         world my-world {
-///             export a;
-///             export b: interface {
-///                 func-in-b: func();
-///             }
-///             export c: func();
-///         }
-///     "#,
-/// });
-///
-/// struct MyComponent;
-///
-/// impl Guest for MyComponent {
-///     fn c() {}
-/// }
-///
-/// impl exports::my::test::a::Guest for MyComponent {
-///     fn func_in_a() {}
-///     fn second_func_in_a() {}
-/// }
-///
-/// impl exports::b::Guest for MyComponent {
-///     fn func_in_b() {}
-/// }
-///
-/// export!(MyComponent);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// Here note that there were three `Guest` traits generated for each of the
-/// three groups: two interfaces and one `world`. Also note that traits (and
-/// types) for exports are namespaced in an `exports` module.
-///
-/// Note that when the top-level `world` does not have any exported functions,
-/// or if an interface does not have any functions, then no `trait` is
-/// generated:
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         interface a {
-///             type my-type = u32;
-///         }
-///
-///         world my-world {
-///             export b: interface {
-///                 use a.{my-type};
-///
-///                 foo: func() -> my-type;
-///             }
-///         }
-///     "#,
-/// });
-///
-/// struct MyComponent;
-///
-/// impl exports::b::Guest for MyComponent {
-///     fn foo() -> u32 {
-///         42
-///     }
-/// }
-///
-/// export!(MyComponent);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// ## Exports: Resources
-///
-/// Exporting a resource is significantly different than importing a resource.
-/// A component defining a resource can create new resources of that type at any
-/// time, for example. Additionally resources can be "dereferenced" into their
-/// underlying values within the component.
-///
-/// Owned resources have a custom type generated and borrowed resources are
-/// generated with a type of the same name suffixed with `Borrow<'_>`, such as
-/// `MyResource` and `MyResourceBorrow<'_>`.
-///
-/// Like `interface`s the methods and functions used with a `resource` are
-/// packaged up into a `trait`.
-///
-/// Specifying a custom resource type is done with an associated type on the
-/// corresponding trait for the resource's containing interface/world:
-///
-/// ```
-/// use wit_bindgen::generate;
-/// use std::cell::{RefCell, Cell};
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         interface logging {
-///             enum level {
-///                 debug,
-///                 info,
-///                 error,
-///             }
-///
-///             resource logger {
-///                 constructor(level: level);
-///                 log: func(level: level, msg: string);
-///                 level: func() -> level;
-///                 set-level: func(level: level);
-///             }
-///         }
-///
-///         world my-world {
-///             export logging;
-///         }
-///     "#,
-/// });
-///
-/// use exports::my::test::logging::{Guest, GuestLogger, Level};
-///
-/// struct MyComponent;
-///
-/// // Note that the `logging` interface has no methods of its own but a trait
-/// // is required to be implemented here to specify the type of `Logger`.
-/// impl Guest for MyComponent {
-///     type Logger = MyLogger;
-/// }
-///
-/// struct MyLogger {
-///     level: Cell<Level>,
-///     contents: RefCell<String>,
-/// }
-///
-/// impl GuestLogger for MyLogger {
-///     fn new(level: Level) -> MyLogger {
-///         MyLogger {
-///             level: Cell::new(level),
-///             contents: RefCell::new(String::new()),
-///         }
-///     }
-///
-///     fn log(&self, level: Level, msg: String) {
-///         if level as u32 <= self.level.get() as u32 {
-///             self.contents.borrow_mut().push_str(&msg);
-///             self.contents.borrow_mut().push_str("\n");
-///         }
-///     }
-///
-///     fn level(&self) -> Level {
-///         self.level.get()
-///     }
-///
-///     fn set_level(&self, level: Level) {
-///         self.level.set(level);
-///     }
-/// }
-///
-/// export!(MyComponent);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// It's important to note that resources in Rust do not get `&mut self` as
-/// methods, but instead are required to be defined with `&self`. This requires
-/// the use of interior mutability such as `Cell` and `RefCell` above from the
-/// `std::cell` module.
-///
-/// ## Exports: The `export!` macro
-///
-/// Components are created by having exported WebAssembly functions with
-/// specific names, and these functions are not created when `generate!` is
-/// invoked. Instead these functions are created afterwards once you've defined
-/// your own type an implemented the various `trait`s for it. The
-/// `#[unsafe(no_mangle)]` functions that will become the component are created
-/// with the generated `export!` macro.
-///
-/// Each call to `generate!` will itself generate a macro called `export!`.
-/// The macro's first argument is the name of a type that implements the traits
-/// generated:
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     inline: r#"
-///         package my:test;
-///
-///         world my-world {
-/// #           export hello: func();
-///             // ...
-///         }
-///     "#,
-/// });
-///
-/// struct MyComponent;
-///
-/// impl Guest for MyComponent {
-/// #   fn hello() {}
-///     // ...
-/// }
-///
-/// export!(MyComponent);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// This argument is a Rust type which implements the `Guest` traits generated
-/// by `generate!`. Note that all `Guest` traits must be implemented for the
-/// type provided or an error will be generated.
-///
-/// This macro additionally accepts a second argument. The macro itself needs to
-/// be able to find the module where the `generate!` macro itself was originally
-/// invoked. Currently that can't be done automatically so a path to where
-/// `generate!` was provided can also be passed to the macro. By default, the
-/// argument is set to `self`:
-///
-/// ```
-/// use wit_bindgen::generate;
-///
-/// generate!({
-///     // ...
-/// #   inline: r#"
-/// #       package my:test;
-/// #
-/// #       world my-world {
-/// #           export hello: func();
-/// #           // ...
-/// #       }
-/// #   "#,
-/// });
-/// #
-/// # struct MyComponent;
-/// #
-/// # impl Guest for MyComponent {
-/// #   fn hello() {}
-/// #     // ...
-/// # }
-/// #
-/// export!(MyComponent with_types_in self);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// This indicates that the current module, referred to with `self`, is the one
-/// which had the `generate!` macro expanded.
-///
-/// If, however, the `generate!` macro was run in a different module then that
-/// must be configured:
-///
-/// ```
-/// mod bindings {
-///     wit_bindgen::generate!({
-///         // ...
-/// #   inline: r#"
-/// #       package my:test;
-/// #
-/// #       world my-world {
-/// #           export hello: func();
-/// #           // ...
-/// #       }
-/// #   "#,
-///     });
-/// }
-/// #
-/// # struct MyComponent;
-/// #
-/// # impl bindings::Guest for MyComponent {
-/// #   fn hello() {}
-/// #     // ...
-/// # }
-/// #
-/// bindings::export!(MyComponent with_types_in bindings);
-/// #
-/// # fn main() {}
-/// ```
-///
-/// ## Debugging output to `generate!`
-///
-/// While `wit-bindgen` is tested to the best of our ability there are
-/// inevitably bugs and issues that arise. These can range from bad error
-/// messages to misconfigured invocations to bugs in the macro itself. To assist
-/// with debugging these situations the macro recognizes an environment
-/// variable:
-///
-/// ```shell
-/// export WIT_BINDGEN_DEBUG=1
-/// ```
-///
-/// When set the macro will emit the result of expansion to a file and then
-/// `include!` that file. Any error messages generated by `rustc` should then
-/// point to the generated file and allow you to open it up, read it, and
-/// inspect it. This can often provide better context to the error than rustc
-/// provides by default with macros.
-///
-/// It is not recommended to set this environment variable by default as it will
-/// cause excessive rebuilds of Cargo projects. It's recommended to only use it
-/// as necessary to debug issues.
-///
-/// ## Options to `generate!`
-///
-/// The full list of options that can be passed to the `generate!` macro are as
-/// follows. Note that there are no required options, they all have default
-/// values.
-///
-///
-/// ```
-/// use wit_bindgen::generate;
-/// # macro_rules! generate { ($($t:tt)*) => () }
-///
-/// generate!({
-///     // The name of the world that bindings are being generated for. If this
-///     // is not specified then it's required that the package selected
-///     // below has a single `world` in it.
-///     world: "my-world",
-///
-///     // Path to parse WIT and its dependencies from. Defaults to the `wit`
-///     // folder adjacent to your `Cargo.toml`.
-///     //
-///     // This parameter also supports the form of a list, such as:
-///     // ["../path/to/wit1", "../path/to/wit2"]
-///     // Usually used in testing, our test suite may want to generate code
-///     // from wit files located in multiple paths within a single mod, and we
-///     // don't want to copy these files again. Currently these locations must
-///     // be ordered, as later paths can't contain dependencies on earlier
-///     // paths. This restriction may be lifted in the future.
-///     path: "../path/to/wit",
-///
-///     // Enables passing "inline WIT". If specified this is the default
-///     // package that a world is selected from. Any dependencies that this
-///     // inline WIT refers to must be defined in the `path` option above.
-///     //
-///     // By default this is not specified.
-///     inline: "
-///         world my-world {
-///             import wasi:cli/imports;
-///
-///             export my-run: func()
-///         }
-///     ",
-///
-///     // Additional traits to derive for all defined types. Note that not all
-///     // types may be able to implement these traits, such as resources.
-///     //
-///     // By default this set is empty.
-///     additional_derives: [PartialEq, Eq, Hash, Clone],
-///
-///     // When generating bindings for interfaces that are not defined in the
-///     // same package as `world`, this option can be used to either generate
-///     // those bindings or point to already generated bindings.
-///     // For example, if your world refers to WASI types then the `wasi` crate
-///     // already has generated bindings for all WASI types and structures. In this
-///     // situation the key `with` here can be used to use those types
-///     // elsewhere rather than regenerating types.
-///     // If for example your world refers to some type and you want to use
-///     // your own custom implementation of that type then you can specify
-///     // that here as well. There is a requirement on the remapped (custom)
-///     // type to have the same internal structure and identical to what would
-///     // wit-bindgen generate (including alignment, etc.), since
-///     // lifting/lowering uses its fields directly.
-///     //
-///     // If, however, your world refers to interfaces for which you don't have
-///     // already generated bindings then you can use the special `generate` value
-///     // to have those bindings generated.
-///     //
-///     // The `with` key here works for interfaces and individual types.
-///     //
-///     // When an interface or type is specified here no bindings will be
-///     // generated at all. It's assumed bindings are fully generated
-///     // somewhere else. This is an indicator that any further references to types
-///     // defined in these interfaces should use the upstream paths specified
-///     // here instead.
-///     //
-///     // Any unused keys in this map are considered an error.
-///     with: {
-///         "wasi:io/poll": wasi::io::poll,
-///         "some:package/my-interface": generate,
-///         "some:package/my-interface/my-type": my_crate::types::MyType,
-///     },
-///
-///     // Indicates that all interfaces not present in `with` should be assumed
-///     // to be marked with `generate`.
-///     generate_all,
-///
-///     // An optional list of function names to skip generating bindings for.
-///     // This is only applicable to imports and the name specified is the name
-///     // of the function.
-///     skip: ["foo", "bar", "baz"],
-///
-///     // Configuration of how Rust types are generated.
-///     //
-///     // This option will change how WIT types are mapped to Rust types. There
-///     // are a number of ways this can be done depending on the context. For
-///     // example a Rust `&str` is suitable to pass to an imported function but
-///     // an exported function receives a `String`. These both represent the
-///     // WIT type `string`, however.
-///     //
-///     // Type generation becomes extra-significant when aggregates come into
-///     // play (such as a WIT `record` or `variant`), especially when the
-///     // aggregate is used both in an imported function and exported one.
-///     //
-///     // There are three modes of ownership, documented here, but only one
-///     // can be specified.
-///     //
-///     // The default mode is "Owning" meaning that all Rust types will by
-///     // default contain their owned containers. For example a `record` with
-///     // a `string` will map to a Rust `struct` containing a `String`. This
-///     // maximizes the chance that types can be shared between imports and
-///     // exports but can come at a cost where calling an import may require
-///     // more allocations than necessary.
-///     ownership: Owning,
-///
-///     // Specifies an alternative name for the `export!` macro generated for
-///     // any exports this world has.
-///     //
-///     // Defaults to "export"
-///     export_macro_name: "export",
-///
-///     // Indicates whether the `export!` macro is `pub` or just `pub(crate)`.
-///     //
-///     // This defaults to `false`.
-///     pub_export_macro: false,
-///
-///     // The second mode of ownership is "Borrowing". This mode then
-///     // additionally has a boolean flag indicating whether duplicate types
-///     // should be generated if necessary.
-///     //
-///     // This mode will prefer using borrowed values in Rust to represent WIT
-///     // values where possible. For example if the argument to an imported
-///     // function is a record-with-a-string then in Rust that will generate a
-///     // `struct` with a lifetime parameter storing `&'a str`.
-///     //
-///     // The `duplicate_if_necessary` flag will cause duplicate types to be
-///     // generated when a WIT type is used both in an import and export. In
-///     // this situation one will be called `FooParam` and one will be called
-///     // `FooResult` (where `foo` is the WIT name).
-///     //
-///     // It's generally recommended to not turn this on unless performance
-///     // requires it. Even if so, please feel free to open an issue on the
-///     // `wit-bindgen` repository to help improve the default "Owning" use
-///     // case above if possible.
-///     ownership: Borrowing { duplicate_if_necessary: false },
-///
-///     // The generated `export!` macro, if any, will by default look for
-///     // generated types adjacent to where the `export!` macro is invoked
-///     // through the `self` module. This option can be used to change the
-///     // defaults to look somewhere else instead.
-///     default_bindings_module: "path::to::bindings",
-///
-///     // This will suffix the custom section containing component type
-///     // information with the specified string. This is not required by
-///     // default but if the same world is generated in two different locations
-///     // in the crate then one bindings generation location will need this
-///     // suffix to avoid having the custom sections corrupt each other.
-///     type_section_suffix: "suffix",
-///
-///     // Configures the path to the `wit-bindgen` crate itself. By default
-///     // this is `wit_bindgen` assuming that your crate depends on the
-///     // `wit-bindgen` crate itself.
-///     runtime_path: "path::to::wit_bindgen",
-///
-///     // Configure where the `bitflags` crate is located. By default this
-///     // is `wit_bindgen::bitflags` which already reexports `bitflags` for
-///     // you.
-///     bitflags_path: "path::to::bitflags",
-///
-///     // Indicates that instead of `&str` and `String` the `&[u8]` and
-///     // `Vec<u8>` types should be used. Only intended for cases where
-///     // compiled size is of the utmost concern as this can avoid pulling in
-///     // UTF-8 validation.
-///     raw_strings,
-///
-///     // Emits `#[cfg(feature = "std")]` around `impl Error for ... {}` blocks
-///     // for generated types. This is a niche option that is only here to
-///     // support the standard library itself depending on this crate one day.
-///     std_feature,
-///
-///     // Disable a workaround to force wasm constructors to be run only once
-///     // when exported functions are called.
-///     disable_run_ctors_once_workaround: false,
-///
-///     // Whether to generate unused `record`, `enum`, `variant` types.
-///     // By default, they will not be generated unless they are used as input
-///     // or return value of a function.
-///     generate_unused_types: false,
-///
-///     // A list of "features" which correspond to WIT features to activate
-///     // when parsing WIT files. This enables `@unstable` annotations showing
-///     // up and having bindings generated for them.
-///     //
-///     // By default this is an empty list.
-///     features: ["foo", "bar", "baz"],
-///
-///     // Disables generation of a `#[used]` static to try harder to get the
-///     // custom section describing WIT types linked into the binary when
-///     // used in library-like situations. This is `false` by default with
-///     // `#[used]` statics being emitted.
-///     disable_custom_section_link_helpers: false,
-///
-///     // Write generated code to a .rs file, which allows the compiler to
-///     // emit more useful diagnostics for errors in the generated code.  This
-///     // is primarily useful for `wit-bindgen` developers.
-///     //
-///     // This does the same thing as setting `WIT_BINDGEN_DEBUG=1`, except
-///     // that it can be used on a more fine-grained basis (i.e. it only affects
-///     // the specific `generate!` call where it is used.
-///     debug: true,
-///
-///     // Generate async import and/or export bindings.
-///     //
-///     // The resulting bindings will use the component model
-///     // [async ABI](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Async.md).
-///     //
-///     // If this option is not provided then the WIT's source annotation will
-///     // be used instead.
-///     async: true,    // all bindings are async
-///     async: false,   // all bindings are sync
-///     // With an array per-function configuration can be specified. A leading
-///     // '-' will disable async for that particular function.
-///     async: [
-///         "wasi:http/types@0.3.0-draft#[static]body.finish",
-///         "import:wasi:http/handler@0.3.0-draft#handle",
-///         "-export:wasi:http/handler@0.3.0-draft#handle",
-///         "all",
-///     ],
-/// });
-/// ```
-///
-/// [WIT package]: https://component-model.bytecodealliance.org/design/packages.html
-#[cfg(feature = "macros")]
-pub use wit_bindgen_rust_macro::generate;
-
-#[cfg(docsrs)]
-pub mod examples;
-
-#[doc(hidden)]
-pub mod rt;
-
-#[cfg(feature = "async")]
-pub use rt::async_support::{
-    backpressure_dec, backpressure_inc, backpressure_set, block_on, spawn, yield_async,
-    yield_blocking, AbiBuffer, FutureRead, FutureReader, FutureWrite, FutureWriteCancel,
-    FutureWriteError, FutureWriter, StreamRead, StreamReader, StreamResult, StreamWrite,
-    StreamWriter,
-};