html-to-markdown 2.24.4 → 2.24.6

data/rust-vendor/wit-component/src/printing.rs

@@ -0,0 +1,1485 @@
+use anyhow::{Result, anyhow, bail};
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::fmt::Display;
+use std::mem;
+use std::ops::Deref;
+use wit_parser::*;
+
+// NB: keep in sync with `crates/wit-parser/src/ast/lex.rs`
+const PRINT_F32_F64_DEFAULT: bool = true;
+
+/// A utility for printing WebAssembly interface definitions to a string.
+pub struct WitPrinter<O: Output = OutputToString> {
+    /// Visitor that holds the WIT document being printed.
+    pub output: O,
+
+    // Count of how many items in this current block have been printed to print
+    // a blank line between each item, but not the first item.
+    any_items: bool,
+
+    // Whether to print doc comments.
+    emit_docs: bool,
+
+    print_f32_f64: bool,
+}
+
+impl Default for WitPrinter {
+    fn default() -> Self {
+        Self::new(OutputToString::default())
+    }
+}
+
+impl<O: Output> WitPrinter<O> {
+    /// Craete new instance.
+    pub fn new(output: O) -> Self {
+        Self {
+            output,
+            any_items: false,
+            emit_docs: true,
+            print_f32_f64: match std::env::var("WIT_REQUIRE_F32_F64") {
+                Ok(s) => s == "1",
+                Err(_) => PRINT_F32_F64_DEFAULT,
+            },
+        }
+    }
+
+    /// Prints the specified `pkg` which is located in `resolve` to `O`.
+    ///
+    /// The `nested` list of packages are other packages to include at the end
+    /// of the output in `package ... { ... }` syntax.
+    pub fn print(&mut self, resolve: &Resolve, pkg: PackageId, nested: &[PackageId]) -> Result<()> {
+        self.print_package(resolve, pkg, true)?;
+        for (i, pkg_id) in nested.iter().enumerate() {
+            if i > 0 {
+                self.output.newline();
+                self.output.newline();
+            }
+            self.print_package(resolve, *pkg_id, false)?;
+        }
+        Ok(())
+    }
+
+    /// Configure whether doc comments will be printed.
+    ///
+    /// Defaults to true.
+    pub fn emit_docs(&mut self, enabled: bool) -> &mut Self {
+        self.emit_docs = enabled;
+        self
+    }
+
+    /// Prints the specified `pkg`.
+    ///
+    /// If `is_main` is not set, nested package notation is used.
+    pub fn print_package(
+        &mut self,
+        resolve: &Resolve,
+        pkg: PackageId,
+        is_main: bool,
+    ) -> Result<()> {
+        let pkg = &resolve.packages[pkg];
+        self.print_package_outer(pkg)?;
+
+        if is_main {
+            self.output.semicolon();
+            self.output.newline();
+        } else {
+            self.output.indent_start();
+        }
+
+        for (name, id) in pkg.interfaces.iter() {
+            self.print_interface_outer(resolve, *id, name)?;
+            self.output.indent_start();
+            self.print_interface(resolve, *id)?;
+            self.output.indent_end();
+            if is_main {
+                self.output.newline();
+            }
+        }
+
+        for (name, id) in pkg.worlds.iter() {
+            self.print_docs(&resolve.worlds[*id].docs);
+            self.print_stability(&resolve.worlds[*id].stability);
+            self.output.keyword("world");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::WorldDeclaration);
+            self.output.indent_start();
+            self.print_world(resolve, *id)?;
+            self.output.indent_end();
+        }
+        if !is_main {
+            self.output.indent_end();
+        }
+        Ok(())
+    }
+
+    /// Print the specified package without its content.
+    /// Does not print the semicolon nor starts the indentation.
+    pub fn print_package_outer(&mut self, pkg: &Package) -> Result<()> {
+        self.print_docs(&pkg.docs);
+        self.output.keyword("package");
+        self.output.str(" ");
+        self.print_name_type(&pkg.name.namespace, TypeKind::NamespaceDeclaration);
+        self.output.str(":");
+        self.print_name_type(&pkg.name.name, TypeKind::PackageNameDeclaration);
+        if let Some(version) = &pkg.name.version {
+            self.print_name_type(&format!("@{version}"), TypeKind::VersionDeclaration);
+        }
+        Ok(())
+    }
+
+    fn new_item(&mut self) {
+        if self.any_items {
+            self.output.newline();
+        }
+        self.any_items = true;
+    }
+
+    /// Print the given WebAssembly interface without its content.
+    /// Does not print the semicolon nor starts the indentation.
+    pub fn print_interface_outer(
+        &mut self,
+        resolve: &Resolve,
+        id: InterfaceId,
+        name: &str,
+    ) -> Result<()> {
+        self.print_docs(&resolve.interfaces[id].docs);
+        self.print_stability(&resolve.interfaces[id].stability);
+        self.output.keyword("interface");
+        self.output.str(" ");
+        self.print_name_type(name, TypeKind::InterfaceDeclaration);
+        Ok(())
+    }
+
+    /// Print the inner content of a given WebAssembly interface.
+    pub fn print_interface(&mut self, resolve: &Resolve, id: InterfaceId) -> Result<()> {
+        let prev_items = mem::replace(&mut self.any_items, false);
+        let interface = &resolve.interfaces[id];
+
+        let mut resource_funcs = HashMap::new();
+        let mut freestanding = Vec::new();
+        for (_, func) in interface.functions.iter() {
+            if let Some(id) = func.kind.resource() {
+                resource_funcs.entry(id).or_insert(Vec::new()).push(func);
+            } else {
+                freestanding.push(func);
+            }
+        }
+
+        self.print_types(
+            resolve,
+            TypeOwner::Interface(id),
+            interface
+                .types
+                .iter()
+                .map(|(name, id)| (name.as_str(), *id)),
+            &resource_funcs,
+        )?;
+
+        for func in freestanding {
+            self.new_item();
+            self.print_docs(&func.docs);
+            self.print_stability(&func.stability);
+            self.print_name_type(func.item_name(), TypeKind::FunctionFreestanding);
+            self.output.str(": ");
+            self.print_function(resolve, func)?;
+            self.output.semicolon();
+        }
+
+        self.any_items = prev_items;
+
+        Ok(())
+    }
+
+    /// Print types of an interface.
+    pub fn print_types<'a>(
+        &mut self,
+        resolve: &Resolve,
+        owner: TypeOwner,
+        types: impl Iterator<Item = (&'a str, TypeId)>,
+        resource_funcs: &HashMap<TypeId, Vec<&Function>>,
+    ) -> Result<()> {
+        // Partition types defined in this interface into either those imported
+        // from foreign interfaces or those defined locally.
+        let mut types_to_declare = Vec::new();
+        let mut types_to_import: Vec<(_, &_, Vec<_>)> = Vec::new();
+        for (name, ty_id) in types {
+            let ty = &resolve.types[ty_id];
+            if let TypeDefKind::Type(Type::Id(other)) = ty.kind {
+                let other = &resolve.types[other];
+                match other.owner {
+                    TypeOwner::None => {}
+                    other_owner if owner != other_owner => {
+                        let other_name = other
+                            .name
+                            .as_ref()
+                            .ok_or_else(|| anyhow!("cannot import unnamed type"))?;
+                        if let Some((owner, stability, list)) = types_to_import.last_mut() {
+                            if *owner == other_owner && ty.stability == **stability {
+                                list.push((name, other_name));
+                                continue;
+                            }
+                        }
+                        types_to_import.push((
+                            other_owner,
+                            &ty.stability,
+                            vec![(name, other_name)],
+                        ));
+                        continue;
+                    }
+                    _ => {}
+                }
+            }
+
+            types_to_declare.push(ty_id);
+        }
+
+        // Generate a `use` statement for all imported types.
+        let my_pkg = match owner {
+            TypeOwner::Interface(id) => resolve.interfaces[id].package.unwrap(),
+            TypeOwner::World(id) => resolve.worlds[id].package.unwrap(),
+            TypeOwner::None => unreachable!(),
+        };
+        for (owner, stability, tys) in types_to_import {
+            self.any_items = true;
+            self.print_stability(stability);
+            self.output.keyword("use");
+            self.output.str(" ");
+            let id = match owner {
+                TypeOwner::Interface(id) => id,
+                // it's only possible to import types from interfaces at
+                // this time.
+                _ => unreachable!(),
+            };
+            self.print_path_to_interface(resolve, id, my_pkg)?;
+            self.output.str(".{"); // Note: not changing the indentation.
+            for (i, (my_name, other_name)) in tys.into_iter().enumerate() {
+                if i > 0 {
+                    self.output.str(", ");
+                }
+                if my_name == other_name {
+                    self.print_name_type(my_name, TypeKind::TypeImport);
+                } else {
+                    self.print_name_type(other_name, TypeKind::TypeImport);
+                    self.output.str(" ");
+                    self.output.keyword("as");
+                    self.output.str(" ");
+                    self.print_name_type(my_name, TypeKind::TypeAlias);
+                }
+            }
+            self.output.str("}"); // Note: not changing the indentation.
+            self.output.semicolon();
+        }
+
+        for id in types_to_declare {
+            self.new_item();
+            self.print_docs(&resolve.types[id].docs);
+            self.print_stability(&resolve.types[id].stability);
+            match resolve.types[id].kind {
+                TypeDefKind::Resource => self.print_resource(
+                    resolve,
+                    id,
+                    resource_funcs.get(&id).unwrap_or(&Vec::new()),
+                )?,
+                _ => self.declare_type(resolve, &Type::Id(id))?,
+            }
+        }
+
+        Ok(())
+    }
+
+    fn print_resource(&mut self, resolve: &Resolve, id: TypeId, funcs: &[&Function]) -> Result<()> {
+        let ty = &resolve.types[id];
+        self.output.ty("resource", TypeKind::BuiltIn);
+        self.output.str(" ");
+        self.print_name_type(
+            ty.name.as_ref().expect("resources must be named"),
+            TypeKind::Resource,
+        );
+        if funcs.is_empty() {
+            self.output.semicolon();
+            return Ok(());
+        }
+        self.output.indent_start();
+        for func in funcs {
+            self.print_docs(&func.docs);
+            self.print_stability(&func.stability);
+
+            match &func.kind {
+                FunctionKind::Constructor(_) => {}
+                FunctionKind::Method(_) | FunctionKind::AsyncMethod(_) => {
+                    self.print_name_type(func.item_name(), TypeKind::FunctionMethod);
+                    self.output.str(": ");
+                }
+                FunctionKind::Static(_) | FunctionKind::AsyncStatic(_) => {
+                    self.print_name_type(func.item_name(), TypeKind::FunctionStatic);
+                    self.output.str(": ");
+                    self.output.keyword("static");
+                    self.output.str(" ");
+                }
+                FunctionKind::Freestanding | FunctionKind::AsyncFreestanding => unreachable!(),
+            }
+            self.print_function(resolve, func)?;
+            self.output.semicolon();
+        }
+        self.output.indent_end();
+
+        Ok(())
+    }
+
+    fn print_function(&mut self, resolve: &Resolve, func: &Function) -> Result<()> {
+        // Handle the `async` prefix if necessary
+        match &func.kind {
+            FunctionKind::AsyncFreestanding
+            | FunctionKind::AsyncMethod(_)
+            | FunctionKind::AsyncStatic(_) => {
+                self.output.keyword("async");
+                self.output.str(" ");
+            }
+            _ => {}
+        }
+
+        // Constructors are named slightly differently.
+        match &func.kind {
+            FunctionKind::Constructor(_) => {
+                self.output.keyword("constructor");
+                self.output.str("(");
+            }
+            FunctionKind::Freestanding
+            | FunctionKind::AsyncFreestanding
+            | FunctionKind::Method(_)
+            | FunctionKind::AsyncMethod(_)
+            | FunctionKind::Static(_)
+            | FunctionKind::AsyncStatic(_) => {
+                self.output.keyword("func");
+                self.output.str("(");
+            }
+        }
+
+        // Methods don't print their `self` argument
+        let params_to_skip = match &func.kind {
+            FunctionKind::Method(_) | FunctionKind::AsyncMethod(_) => 1,
+            _ => 0,
+        };
+        for (i, (name, ty)) in func.params.iter().skip(params_to_skip).enumerate() {
+            if i > 0 {
+                self.output.str(", ");
+            }
+            self.print_name_param(name);
+            self.output.str(": ");
+            self.print_type_name(resolve, ty)?;
+        }
+        self.output.str(")");
+
+        // shorthand constructors don't have their results printed
+        if func.is_constructor_shorthand(resolve) {
+            return Ok(());
+        }
+
+        if let Some(ty) = &func.result {
+            self.output.str(" -> ");
+            self.print_type_name(resolve, ty)?;
+        }
+        Ok(())
+    }
+
+    /// Prints the world `id` within `resolve`.
+    ///
+    /// This is a little tricky to preserve round-tripping that WIT wants. This
+    /// function inherently can't preserve ordering of imports because resource
+    /// functions aren't guaranteed to be all adjacent to the resource itself
+    /// they're attached to. That means that at the very least, when printing
+    /// resource functions, items may be printed out-of-order.
+    ///
+    /// To help solve this the printing here is kept in sync with WIT encoding
+    /// of worlds which is to print items in the order of:
+    ///
+    /// * Any imported interface. Ordering between interfaces is preserved.
+    /// * Any types, including resource functions on those types. Ordering
+    ///   between types is preserved.
+    /// * Any functions, which may refer to those types. Ordering between
+    ///   functions is preserved.
+    ///
+    /// This keeps things printed in a roughly topological fashion and makes
+    /// round-tripping a bit more reliable.
+    fn print_world(&mut self, resolve: &Resolve, id: WorldId) -> Result<()> {
+        let prev_items = mem::replace(&mut self.any_items, false);
+        let world = &resolve.worlds[id];
+        let pkgid = world.package.unwrap();
+        let mut types = Vec::new();
+        let mut resource_funcs = HashMap::new();
+        let mut function_imports_to_print = Vec::new();
+        for (name, import) in world.imports.iter() {
+            match import {
+                WorldItem::Type(t) => match name {
+                    WorldKey::Name(s) => types.push((s.as_str(), *t)),
+                    WorldKey::Interface(_) => unreachable!(),
+                },
+                _ => {
+                    if let WorldItem::Function(f) = import {
+                        if let Some(id) = f.kind.resource() {
+                            resource_funcs.entry(id).or_insert(Vec::new()).push(f);
+                            continue;
+                        }
+                        function_imports_to_print.push((name, import));
+                        continue;
+                    }
+                    self.print_world_item(resolve, name, import, pkgid, "import")?;
+                    // Don't put a blank line between imports, but count
+                    // imports as having printed something so if anything comes
+                    // after them then a blank line is printed after imports.
+                    self.any_items = true;
+                }
+            }
+        }
+        self.print_types(
+            resolve,
+            TypeOwner::World(id),
+            types.into_iter(),
+            &resource_funcs,
+        )?;
+
+        for (name, import) in function_imports_to_print {
+            self.print_world_item(resolve, name, import, pkgid, "import")?;
+            self.any_items = true;
+        }
+        if !world.exports.is_empty() {
+            self.new_item();
+        }
+        for (name, export) in world.exports.iter() {
+            self.print_world_item(resolve, name, export, pkgid, "export")?;
+        }
+        self.any_items = prev_items;
+        Ok(())
+    }
+
+    fn print_world_item(
+        &mut self,
+        resolve: &Resolve,
+        name: &WorldKey,
+        item: &WorldItem,
+        cur_pkg: PackageId,
+        import_or_export_keyword: &str,
+    ) -> Result<()> {
+        // Print inline item docs
+        if matches!(name, WorldKey::Name(_)) {
+            self.print_docs(match item {
+                WorldItem::Interface { id, .. } => &resolve.interfaces[*id].docs,
+                WorldItem::Function(f) => &f.docs,
+                // Types are handled separately
+                WorldItem::Type(_) => unreachable!(),
+            });
+        }
+
+        self.print_stability(item.stability(resolve));
+        self.output.keyword(import_or_export_keyword);
+        self.output.str(" ");
+        match name {
+            WorldKey::Name(name) => {
+                match item {
+                    WorldItem::Interface { id, .. } => {
+                        self.print_name_type(name, TypeKind::Other);
+                        self.output.str(": ");
+                        assert!(resolve.interfaces[*id].name.is_none());
+                        self.output.keyword("interface");
+                        self.output.indent_start();
+                        self.print_interface(resolve, *id)?;
+                        self.output.indent_end();
+                    }
+                    WorldItem::Function(f) => {
+                        self.print_name_type(&f.name, TypeKind::Other);
+                        self.output.str(": ");
+                        self.print_function(resolve, f)?;
+                        self.output.semicolon();
+                    }
+                    // Types are handled separately
+                    WorldItem::Type(_) => unreachable!(),
+                }
+            }
+            WorldKey::Interface(id) => {
+                match item {
+                    WorldItem::Interface { id: id2, .. } => assert_eq!(id, id2),
+                    _ => unreachable!(),
+                }
+                self.print_path_to_interface(resolve, *id, cur_pkg)?;
+                self.output.semicolon();
+            }
+        }
+        Ok(())
+    }
+
+    fn print_path_to_interface(
+        &mut self,
+        resolve: &Resolve,
+        interface: InterfaceId,
+        cur_pkg: PackageId,
+    ) -> Result<()> {
+        let iface = &resolve.interfaces[interface];
+        if iface.package == Some(cur_pkg) {
+            self.print_name_type(iface.name.as_ref().unwrap(), TypeKind::InterfacePath);
+        } else {
+            let pkg = &resolve.packages[iface.package.unwrap()].name;
+            self.print_name_type(&pkg.namespace, TypeKind::NamespacePath);
+            self.output.str(":");
+            self.print_name_type(&pkg.name, TypeKind::PackageNamePath);
+            self.output.str("/");
+            self.print_name_type(iface.name.as_ref().unwrap(), TypeKind::InterfacePath);
+            if let Some(version) = &pkg.version {
+                self.print_name_type(&format!("@{version}"), TypeKind::VersionPath);
+            }
+        }
+        Ok(())
+    }
+
+    /// Print the name of type `ty`.
+    pub fn print_type_name(&mut self, resolve: &Resolve, ty: &Type) -> Result<()> {
+        match ty {
+            Type::Bool => self.output.ty("bool", TypeKind::BuiltIn),
+            Type::U8 => self.output.ty("u8", TypeKind::BuiltIn),
+            Type::U16 => self.output.ty("u16", TypeKind::BuiltIn),
+            Type::U32 => self.output.ty("u32", TypeKind::BuiltIn),
+            Type::U64 => self.output.ty("u64", TypeKind::BuiltIn),
+            Type::S8 => self.output.ty("s8", TypeKind::BuiltIn),
+            Type::S16 => self.output.ty("s16", TypeKind::BuiltIn),
+            Type::S32 => self.output.ty("s32", TypeKind::BuiltIn),
+            Type::S64 => self.output.ty("s64", TypeKind::BuiltIn),
+            Type::F32 => {
+                if self.print_f32_f64 {
+                    self.output.ty("f32", TypeKind::BuiltIn)
+                } else {
+                    self.output.ty("f32", TypeKind::BuiltIn)
+                }
+            }
+            Type::F64 => {
+                if self.print_f32_f64 {
+                    self.output.ty("f64", TypeKind::BuiltIn)
+                } else {
+                    self.output.ty("f64", TypeKind::BuiltIn)
+                }
+            }
+            Type::Char => self.output.ty("char", TypeKind::BuiltIn),
+            Type::String => self.output.ty("string", TypeKind::BuiltIn),
+            Type::ErrorContext => self.output.ty("error-context", TypeKind::BuiltIn),
+
+            Type::Id(id) => {
+                let ty = &resolve.types[*id];
+                if let Some(name) = &ty.name {
+                    self.print_name_type(name, TypeKind::Other);
+                    return Ok(());
+                }
+
+                match &ty.kind {
+                    TypeDefKind::Handle(h) => {
+                        self.print_handle_type(resolve, h, false)?;
+                    }
+                    TypeDefKind::Resource => {
+                        bail!("resolve has an unnamed resource type");
+                    }
+                    TypeDefKind::Tuple(t) => {
+                        self.print_tuple_type(resolve, t)?;
+                    }
+                    TypeDefKind::Option(t) => {
+                        self.print_option_type(resolve, t)?;
+                    }
+                    TypeDefKind::Result(t) => {
+                        self.print_result_type(resolve, t)?;
+                    }
+                    TypeDefKind::Record(_) => {
+                        bail!("resolve has an unnamed record type");
+                    }
+                    TypeDefKind::Flags(_) => {
+                        bail!("resolve has unnamed flags type")
+                    }
+                    TypeDefKind::Enum(_) => {
+                        bail!("resolve has unnamed enum type")
+                    }
+                    TypeDefKind::Variant(_) => {
+                        bail!("resolve has unnamed variant type")
+                    }
+                    TypeDefKind::List(ty) => {
+                        self.output.ty("list", TypeKind::BuiltIn);
+                        self.output.generic_args_start();
+                        self.print_type_name(resolve, ty)?;
+                        self.output.generic_args_end();
+                    }
+                    TypeDefKind::Map(key_ty, value_ty) => {
+                        self.output.ty("map", TypeKind::BuiltIn);
+                        self.output.generic_args_start();
+                        self.print_type_name(resolve, key_ty)?;
+                        self.output.str(", ");
+                        self.print_type_name(resolve, value_ty)?;
+                        self.output.generic_args_end();
+                    }
+                    TypeDefKind::FixedSizeList(ty, size) => {
+                        self.output.ty("list", TypeKind::BuiltIn);
+                        self.output.generic_args_start();
+                        self.print_type_name(resolve, ty)?;
+                        self.output.push_str(&format!(", {}", *size));
+                        self.output.generic_args_end();
+                    }
+                    TypeDefKind::Type(ty) => self.print_type_name(resolve, ty)?,
+                    TypeDefKind::Future(ty) => {
+                        if let Some(ty) = ty {
+                            self.output.push_str("future<");
+                            self.print_type_name(resolve, ty)?;
+                            self.output.push_str(">");
+                        } else {
+                            self.output.push_str("future");
+                        }
+                    }
+                    TypeDefKind::Stream(ty) => {
+                        if let Some(ty) = ty {
+                            self.output.push_str("stream<");
+                            self.print_type_name(resolve, ty)?;
+                            self.output.push_str(">");
+                        } else {
+                            self.output.push_str("stream");
+                        }
+                    }
+                    TypeDefKind::Unknown => unreachable!(),
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn print_handle_type(
+        &mut self,
+        resolve: &Resolve,
+        handle: &Handle,
+        force_handle_type_printed: bool,
+    ) -> Result<()> {
+        match handle {
+            Handle::Own(ty) => {
+                let ty = &resolve.types[*ty];
+                if force_handle_type_printed {
+                    self.output.ty("own", TypeKind::BuiltIn);
+                    self.output.generic_args_start();
+                }
+                self.print_name_type(
+                    ty.name
+                        .as_ref()
+                        .ok_or_else(|| anyhow!("unnamed resource type"))?,
+                    TypeKind::Resource,
+                );
+                if force_handle_type_printed {
+                    self.output.generic_args_end();
+                }
+            }
+
+            Handle::Borrow(ty) => {
+                self.output.ty("borrow", TypeKind::BuiltIn);
+                self.output.generic_args_start();
+                let ty = &resolve.types[*ty];
+                self.print_name_type(
+                    ty.name
+                        .as_ref()
+                        .ok_or_else(|| anyhow!("unnamed resource type"))?,
+                    TypeKind::Resource,
+                );
+                self.output.generic_args_end();
+            }
+        }
+
+        Ok(())
+    }
+
+    fn print_tuple_type(&mut self, resolve: &Resolve, tuple: &Tuple) -> Result<()> {
+        self.output.ty("tuple", TypeKind::BuiltIn);
+        self.output.generic_args_start();
+        for (i, ty) in tuple.types.iter().enumerate() {
+            if i > 0 {
+                self.output.str(", ");
+            }
+            self.print_type_name(resolve, ty)?;
+        }
+        self.output.generic_args_end();
+
+        Ok(())
+    }
+
+    fn print_option_type(&mut self, resolve: &Resolve, payload: &Type) -> Result<()> {
+        self.output.ty("option", TypeKind::BuiltIn);
+        self.output.generic_args_start();
+        self.print_type_name(resolve, payload)?;
+        self.output.generic_args_end();
+        Ok(())
+    }
+
+    fn print_result_type(&mut self, resolve: &Resolve, result: &Result_) -> Result<()> {
+        match result {
+            Result_ {
+                ok: Some(ok),
+                err: Some(err),
+            } => {
+                self.output.ty("result", TypeKind::BuiltIn);
+                self.output.generic_args_start();
+                self.print_type_name(resolve, ok)?;
+                self.output.str(", ");
+                self.print_type_name(resolve, err)?;
+                self.output.generic_args_end();
+            }
+            Result_ {
+                ok: None,
+                err: Some(err),
+            } => {
+                self.output.ty("result", TypeKind::BuiltIn);
+                self.output.generic_args_start();
+                self.output.str("_, ");
+                self.print_type_name(resolve, err)?;
+                self.output.generic_args_end();
+            }
+            Result_ {
+                ok: Some(ok),
+                err: None,
+            } => {
+                self.output.ty("result", TypeKind::BuiltIn);
+                self.output.generic_args_start();
+                self.print_type_name(resolve, ok)?;
+                self.output.generic_args_end();
+            }
+            Result_ {
+                ok: None,
+                err: None,
+            } => {
+                self.output.ty("result", TypeKind::BuiltIn);
+            }
+        }
+        Ok(())
+    }
+
+    fn declare_type(&mut self, resolve: &Resolve, ty: &Type) -> Result<()> {
+        match ty {
+            Type::Bool
+            | Type::U8
+            | Type::U16
+            | Type::U32
+            | Type::U64
+            | Type::S8
+            | Type::S16
+            | Type::S32
+            | Type::S64
+            | Type::F32
+            | Type::F64
+            | Type::Char
+            | Type::String
+            | Type::ErrorContext => return Ok(()),
+
+            Type::Id(id) => {
+                let ty = &resolve.types[*id];
+                match &ty.kind {
+                    TypeDefKind::Handle(h) => {
+                        self.declare_handle(resolve, ty.name.as_deref(), h)?
+                    }
+                    TypeDefKind::Resource => panic!("resources should be processed separately"),
+                    TypeDefKind::Record(r) => {
+                        self.declare_record(resolve, ty.name.as_deref(), r)?
+                    }
+                    TypeDefKind::Tuple(t) => self.declare_tuple(resolve, ty.name.as_deref(), t)?,
+                    TypeDefKind::Flags(f) => self.declare_flags(ty.name.as_deref(), f)?,
+                    TypeDefKind::Variant(v) => {
+                        self.declare_variant(resolve, ty.name.as_deref(), v)?
+                    }
+                    TypeDefKind::Option(t) => {
+                        self.declare_option(resolve, ty.name.as_deref(), t)?
+                    }
+                    TypeDefKind::Result(r) => {
+                        self.declare_result(resolve, ty.name.as_deref(), r)?
+                    }
+                    TypeDefKind::Enum(e) => self.declare_enum(ty.name.as_deref(), e)?,
+                    TypeDefKind::List(inner) => {
+                        self.declare_list(resolve, ty.name.as_deref(), inner)?
+                    }
+                    TypeDefKind::Map(key, value) => {
+                        self.declare_map(resolve, ty.name.as_deref(), key, value)?
+                    }
+                    TypeDefKind::FixedSizeList(inner, size) => {
+                        self.declare_fixed_size_list(resolve, ty.name.as_deref(), inner, *size)?
+                    }
+                    TypeDefKind::Type(inner) => match ty.name.as_deref() {
+                        Some(name) => {
+                            self.output.keyword("type");
+                            self.output.str(" ");
+                            self.print_name_type(name, TypeKind::TypeName);
+                            self.output.str(" = ");
+                            self.print_type_name(resolve, inner)?;
+                            self.output.semicolon();
+                        }
+                        None => bail!("unnamed type in document"),
+                    },
+                    TypeDefKind::Future(inner) => {
+                        self.declare_future(resolve, ty.name.as_deref(), inner.as_ref())?
+                    }
+                    TypeDefKind::Stream(inner) => {
+                        self.declare_stream(resolve, ty.name.as_deref(), inner.as_ref())?
+                    }
+                    TypeDefKind::Unknown => unreachable!(),
+                }
+            }
+        }
+        Ok(())
+    }
+
+    fn declare_handle(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        handle: &Handle,
+    ) -> Result<()> {
+        match name {
+            Some(name) => {
+                self.output.keyword("type");
+                self.output.str(" ");
+                self.print_name_type(name, TypeKind::Resource);
+                self.output.str(" = ");
+                // Note that the `true` here forces owned handles to be printed
+                // as `own<T>`. The purpose of this is because `type a = b`, if
+                // `b` is a resource, is encoded differently as `type a =
+                // own<b>`. By forcing a handle to be printed here it's staying
+                // true to what's in the WIT document.
+                self.print_handle_type(resolve, handle, true)?;
+                self.output.semicolon();
+
+                Ok(())
+            }
+            None => bail!("document has unnamed handle type"),
+        }
+    }
+
+    fn declare_record(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        record: &Record,
+    ) -> Result<()> {
+        match name {
+            Some(name) => {
+                self.output.keyword("record");
+                self.output.str(" ");
+                self.print_name_type(name, TypeKind::Record);
+                self.output.indent_start();
+                for field in &record.fields {
+                    self.print_docs(&field.docs);
+                    self.print_name_param(&field.name);
+                    self.output.str(": ");
+                    self.print_type_name(resolve, &field.ty)?;
+                    self.output.str(",");
+                    self.output.newline();
+                }
+                self.output.indent_end();
+                Ok(())
+            }
+            None => bail!("document has unnamed record type"),
+        }
+    }
+
+    fn declare_tuple(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        tuple: &Tuple,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Tuple);
+            self.output.str(" = ");
+            self.print_tuple_type(resolve, tuple)?;
+            self.output.semicolon();
+        }
+        Ok(())
+    }
+
+    fn declare_flags(&mut self, name: Option<&str>, flags: &Flags) -> Result<()> {
+        match name {
+            Some(name) => {
+                self.output.keyword("flags");
+                self.output.str(" ");
+                self.print_name_type(name, TypeKind::Flags);
+                self.output.indent_start();
+                for flag in &flags.flags {
+                    self.print_docs(&flag.docs);
+                    self.print_name_case(&flag.name);
+                    self.output.str(",");
+                    self.output.newline();
+                }
+                self.output.indent_end();
+            }
+            None => bail!("document has unnamed flags type"),
+        }
+        Ok(())
+    }
+
+    fn declare_variant(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        variant: &Variant,
+    ) -> Result<()> {
+        let name = match name {
+            Some(name) => name,
+            None => bail!("document has unnamed variant type"),
+        };
+        self.output.keyword("variant");
+        self.output.str(" ");
+        self.print_name_type(name, TypeKind::Variant);
+        self.output.indent_start();
+        for case in &variant.cases {
+            self.print_docs(&case.docs);
+            self.print_name_case(&case.name);
+            if let Some(ty) = case.ty {
+                self.output.str("(");
+                self.print_type_name(resolve, &ty)?;
+                self.output.str(")");
+            }
+            self.output.str(",");
+            self.output.newline();
+        }
+        self.output.indent_end();
+        Ok(())
+    }
+
+    fn declare_option(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        payload: &Type,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Option);
+            self.output.str(" = ");
+            self.print_option_type(resolve, payload)?;
+            self.output.semicolon();
+        }
+        Ok(())
+    }
+
+    fn declare_result(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        result: &Result_,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Result);
+            self.output.str(" = ");
+            self.print_result_type(resolve, result)?;
+            self.output.semicolon();
+        }
+        Ok(())
+    }
+
+    fn declare_enum(&mut self, name: Option<&str>, enum_: &Enum) -> Result<()> {
+        let name = match name {
+            Some(name) => name,
+            None => bail!("document has unnamed enum type"),
+        };
+        self.output.keyword("enum");
+        self.output.str(" ");
+        self.print_name_type(name, TypeKind::Enum);
+        self.output.indent_start();
+        for case in &enum_.cases {
+            self.print_docs(&case.docs);
+            self.print_name_case(&case.name);
+            self.output.str(",");
+            self.output.newline();
+        }
+        self.output.indent_end();
+        Ok(())
+    }
+
+    fn declare_list(&mut self, resolve: &Resolve, name: Option<&str>, ty: &Type) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::List);
+            self.output.str(" = ");
+            self.output.ty("list", TypeKind::BuiltIn);
+            self.output.str("<");
+            self.print_type_name(resolve, ty)?;
+            self.output.str(">");
+            self.output.semicolon();
+            return Ok(());
+        }
+
+        Ok(())
+    }
+
+    fn declare_map(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        key_ty: &Type,
+        value_ty: &Type,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Map);
+            self.output.str(" = ");
+            self.output.ty("map", TypeKind::BuiltIn);
+            self.output.str("<");
+            self.print_type_name(resolve, key_ty)?;
+            self.output.str(", ");
+            self.print_type_name(resolve, value_ty)?;
+            self.output.str(">");
+            self.output.semicolon();
+            return Ok(());
+        }
+
+        Ok(())
+    }
+
+    fn declare_fixed_size_list(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        ty: &Type,
+        elements: u32,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::List);
+            self.output.str(" = ");
+            self.output.ty("list", TypeKind::BuiltIn);
+            self.output.str("<");
+            self.print_type_name(resolve, ty)?;
+            self.output.str(&format!(", {elements}"));
+            self.output.str(">");
+            self.output.semicolon();
+            return Ok(());
+        }
+
+        Ok(())
+    }
+
+    fn declare_stream(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        ty: Option<&Type>,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Stream);
+            self.output.str(" = ");
+            self.output.ty("stream", TypeKind::BuiltIn);
+            if let Some(ty) = ty {
+                self.output.str("<");
+                self.print_type_name(resolve, ty)?;
+                self.output.str(">");
+            }
+            self.output.semicolon();
+        }
+
+        Ok(())
+    }
+
+    fn declare_future(
+        &mut self,
+        resolve: &Resolve,
+        name: Option<&str>,
+        ty: Option<&Type>,
+    ) -> Result<()> {
+        if let Some(name) = name {
+            self.output.keyword("type");
+            self.output.str(" ");
+            self.print_name_type(name, TypeKind::Future);
+            self.output.str(" = ");
+            self.output.ty("future", TypeKind::BuiltIn);
+            if let Some(ty) = ty {
+                self.output.str("<");
+                self.print_type_name(resolve, ty)?;
+                self.output.str(">");
+            }
+            self.output.semicolon();
+        }
+
+        Ok(())
+    }
+
+    fn escape_name(name: &str) -> Cow<'_, str> {
+        if is_keyword(name) {
+            Cow::Owned(format!("%{name}"))
+        } else {
+            Cow::Borrowed(name)
+        }
+    }
+
+    fn print_name_type(&mut self, name: &str, kind: TypeKind) {
+        self.output.ty(Self::escape_name(name).deref(), kind);
+    }
+
+    fn print_name_param(&mut self, name: &str) {
+        self.output.param(Self::escape_name(name).deref());
+    }
+
+    fn print_name_case(&mut self, name: &str) {
+        self.output.case(Self::escape_name(name).deref());
+    }
+
+    fn print_docs(&mut self, docs: &Docs) {
+        if self.emit_docs {
+            if let Some(contents) = &docs.contents {
+                for line in contents.lines() {
+                    self.output.doc(line);
+                }
+            }
+        }
+    }
+
+    fn print_stability(&mut self, stability: &Stability) {
+        match stability {
+            Stability::Unknown => {}
+            Stability::Stable { since, deprecated } => {
+                self.output.keyword("@since");
+                self.output.str("(");
+                self.output.keyword("version");
+                self.output.str(" = ");
+                self.print_name_type(&since.to_string(), TypeKind::VersionAnnotation);
+                self.output.str(")");
+                self.output.newline();
+                if let Some(version) = deprecated {
+                    self.output.keyword("@deprecated");
+                    self.output.str("(");
+                    self.output.keyword("version");
+                    self.output.str(" = ");
+                    self.print_name_type(&version.to_string(), TypeKind::VersionAnnotation);
+                    self.output.str(")");
+                    self.output.newline();
+                }
+            }
+            Stability::Unstable {
+                feature,
+                deprecated,
+            } => {
+                self.output.keyword("@unstable");
+                self.output.str("(");
+                self.output.keyword("feature");
+                self.output.str(" = ");
+                self.output.str(feature);
+                self.output.str(")");
+                self.output.newline();
+                if let Some(version) = deprecated {
+                    self.output.keyword("@deprecated");
+                    self.output.str("(");
+                    self.output.keyword("version");
+                    self.output.str(" = ");
+                    self.print_name_type(&version.to_string(), TypeKind::VersionAnnotation);
+                    self.output.str(")");
+                    self.output.newline();
+                }
+            }
+        }
+    }
+}
+
+fn is_keyword(name: &str) -> bool {
+    matches!(
+        name,
+        "use"
+            | "type"
+            | "func"
+            | "u8"
+            | "u16"
+            | "u32"
+            | "u64"
+            | "s8"
+            | "s16"
+            | "s32"
+            | "s64"
+            | "f32"
+            | "f64"
+            | "float32"
+            | "float64"
+            | "char"
+            | "resource"
+            | "record"
+            | "flags"
+            | "variant"
+            | "enum"
+            | "bool"
+            | "string"
+            | "option"
+            | "result"
+            | "future"
+            | "stream"
+            | "list"
+            | "own"
+            | "borrow"
+            | "_"
+            | "as"
+            | "from"
+            | "static"
+            | "interface"
+            | "tuple"
+            | "world"
+            | "import"
+            | "export"
+            | "package"
+            | "with"
+            | "include"
+            | "constructor"
+            | "error-context"
+            | "async"
+    )
+}
+
+/// Trait defining visitor methods driven by [`WitPrinter`](WitPrinter).
+///
+/// Some methods in this trait have default implementations. These default
+/// implementations may rely on helper functions that are not
+/// invoked directly by `WitPrinter`.
+pub trait Output {
+    /// Push a string slice into a buffer or an output.
+    ///
+    /// Parameter `src` can contain punctation characters, and must be escaped
+    /// when outputing to languages like HTML.
+    /// Helper function used exclusively by the default implementations of trait methods.
+    /// This function is not called directly by `WitPrinter`.
+    /// When overriding all the trait methods, users do not need to handle this function.
+    fn push_str(&mut self, src: &str);
+
+    /// Set the appropriate indentation.
+    ///
+    /// Helper function used exclusively by the default implementations of trait methods.
+    /// This function is not called directly by `WitPrinter`.
+    /// When overriding all the trait methods, users do not need to handle this function.
+    fn indent_if_needed(&mut self) -> bool;
+
+    /// Start of indentation. In WIT this represents ` {\n`.
+    fn indent_start(&mut self);
+
+    /// End of indentation. In WIT this represents `}\n`.
+    fn indent_end(&mut self);
+
+    /// This method is designed to be used only by the default methods of this trait.
+    /// Called only from the default implementation functions of this trait.
+    fn indent_and_print(&mut self, src: &str) {
+        assert!(!src.contains('\n'));
+        let idented = self.indent_if_needed();
+        if idented && src.starts_with(' ') {
+            panic!("cannot add a space at the beginning of a line");
+        }
+        self.push_str(src);
+    }
+
+    /// A newline is added.
+    fn newline(&mut self);
+
+    /// A keyword is added. Keywords are hardcoded strings from `[a-z]`, but can start with `@`
+    /// when printing a [Feature Gate](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates)
+    fn keyword(&mut self, src: &str) {
+        self.indent_and_print(src);
+    }
+
+    /// A type is added.
+    fn ty(&mut self, src: &str, _kind: TypeKind) {
+        self.indent_and_print(src);
+    }
+
+    /// A parameter name of a function, record or a named return is added.
+    fn param(&mut self, src: &str) {
+        self.indent_and_print(src);
+    }
+
+    /// A case belonging to a variant, enum or flags is added.
+    fn case(&mut self, src: &str) {
+        self.indent_and_print(src);
+    }
+
+    /// Generic argument section starts. In WIT this represents the `<` character.
+    fn generic_args_start(&mut self) {
+        assert!(
+            !self.indent_if_needed(),
+            "`generic_args_start` is never called after newline"
+        );
+        self.push_str("<");
+    }
+
+    /// Generic argument section ends. In WIT this represents the '>' character.
+    fn generic_args_end(&mut self) {
+        assert!(
+            !self.indent_if_needed(),
+            "`generic_args_end` is never called after newline"
+        );
+        self.push_str(">");
+    }
+
+    /// Called when a single documentation line is added.
+    /// The `doc` parameter starts with `///` omitted, and can be an empty string.
+    fn doc(&mut self, doc: &str) {
+        assert!(!doc.contains('\n'));
+        self.indent_if_needed();
+        self.push_str("///");
+        if !doc.is_empty() {
+            self.push_str(" ");
+            self.push_str(doc);
+        }
+        self.newline();
+    }
+
+    /// A semicolon is added.
+    fn semicolon(&mut self) {
+        assert!(
+            !self.indent_if_needed(),
+            "`semicolon` is never called after newline"
+        );
+        self.push_str(";");
+        self.newline();
+    }
+
+    /// Any string that does not have a specialized function is added.
+    /// Parameter `src` can contain punctation characters, and must be escaped
+    /// when outputing to languages like HTML.
+    fn str(&mut self, src: &str) {
+        self.indent_and_print(src);
+    }
+}
+
+/// Represents the different kinds of types that can be encountered while
+/// visiting a WIT file.
+///
+/// Each variant refers to the name of the respective element (e.g., function, type, or namespace),
+/// not the entire declaration.
+#[non_exhaustive]
+#[derive(Clone, Copy, Debug)]
+pub enum TypeKind {
+    /// A built-in type, such as "list" or "option".
+    BuiltIn,
+    /// An enumeration type name.
+    Enum,
+    /// An error-context type name.
+    ErrorContext,
+    /// A flags type name.
+    Flags,
+    /// A freestanding function name, not associated with any specific type or namespace.
+    /// For example, "myfunc" in `myfunc: func() -> string;`.
+    FunctionFreestanding,
+    /// A method, associated with a resource.
+    FunctionMethod,
+    /// A static function, associated with a resource.
+    FunctionStatic,
+    /// A future type name.
+    Future,
+    /// An interface declaration name.
+    InterfaceDeclaration,
+    /// An interface name when printing a path, for example in `use`.
+    InterfacePath,
+    /// A list type name.
+    List,
+    /// A map type name.
+    Map,
+    /// A namespace declaration.
+    NamespaceDeclaration,
+    /// A namespace when printing a path, for example in `use`.
+    NamespacePath,
+    /// An option type name.
+    Option,
+    /// A package name declaration.
+    PackageNameDeclaration,
+    /// A package name when printing a path, for example in `use`.
+    PackageNamePath,
+    /// A record type name.
+    Record,
+    /// A resource type name.
+    Resource,
+    /// A result type name.
+    Result,
+    /// A stream type name.
+    Stream,
+    /// A tuple type name.
+    Tuple,
+    /// A type alias.
+    TypeAlias,
+    /// An imported type name.
+    TypeImport,
+    /// A user-defined type name.
+    TypeName,
+    /// A variant type name.
+    Variant,
+    /// A version declaration.
+    VersionDeclaration,
+    /// A version when printing a path, for example in `use`.
+    VersionPath,
+    /// A version when printing stability annotations, for example in `@since`
+    VersionAnnotation,
+    /// A world declaration name.
+    WorldDeclaration,
+    /// A fallback for types that do not fit into any other category.
+    Other,
+}
+
+/// Helper structure to help maintain an indentation level when printing source,
+/// modeled after the support in `wit-bindgen-core`. Indentation is set to two spaces.
+#[derive(Default)]
+pub struct OutputToString {
+    indent: usize,
+    output: String,
+    // set to true after newline, then to false after first item is indented.
+    needs_indent: bool,
+}
+
+impl Output for OutputToString {
+    fn push_str(&mut self, src: &str) {
+        self.output.push_str(src);
+    }
+
+    fn indent_if_needed(&mut self) -> bool {
+        if self.needs_indent {
+            for _ in 0..self.indent {
+                // Indenting by two spaces.
+                self.output.push_str("  ");
+            }
+            self.needs_indent = false;
+            true
+        } else {
+            false
+        }
+    }
+
+    fn indent_start(&mut self) {
+        assert!(
+            !self.needs_indent,
+            "`indent_start` is never called after newline"
+        );
+        self.output.push_str(" {");
+        self.indent += 1;
+        self.newline();
+    }
+
+    fn indent_end(&mut self) {
+        // Note that a `saturating_sub` is used here to prevent a panic
+        // here in the case of invalid code being generated in debug
+        // mode. It's typically easier to debug those issues through
+        // looking at the source code rather than getting a panic.
+        self.indent = self.indent.saturating_sub(1);
+        self.indent_if_needed();
+        self.output.push('}');
+        self.newline();
+    }
+
+    fn newline(&mut self) {
+        self.output.push('\n');
+        self.needs_indent = true;
+    }
+}
+
+impl From<OutputToString> for String {
+    fn from(output: OutputToString) -> String {
+        output.output
+    }
+}
+
+impl Display for OutputToString {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        self.output.fmt(f)
+    }
+}