wit_bindgen_core/
lib.rs

1use std::fmt::Write;
2
3use anyhow::Result;
4pub use wit_parser;
5use wit_parser::*;
6pub mod abi;
7mod ns;
8pub use ns::Ns;
9pub mod source;
10pub use source::{Files, Source};
11mod types;
12pub use types::{TypeInfo, Types};
13mod path;
14pub use path::name_package_module;
15mod async_;
16pub use async_::AsyncFilterSet;
17
18#[derive(Default, Copy, Clone, PartialEq, Eq, Debug)]
19pub enum Direction {
20    #[default]
21    Import,
22    Export,
23}
24
25pub trait WorldGenerator {
26    fn generate(&mut self, resolve: &mut Resolve, id: WorldId, files: &mut Files) -> Result<()> {
27        if self.uses_nominal_type_ids() {
28            resolve.generate_nominal_type_ids(id);
29        }
30        let world = &resolve.worlds[id];
31        self.preprocess(resolve, id)?;
32
33        fn unwrap_name(key: &WorldKey) -> &str {
34            match key {
35                WorldKey::Name(name) => name,
36                WorldKey::Interface(_) => panic!("unexpected interface key"),
37            }
38        }
39
40        let mut funcs = Vec::new();
41        let mut types = Vec::new();
42        for (name, import) in world.imports.iter() {
43            match import {
44                WorldItem::Function(f) => funcs.push((unwrap_name(name), f)),
45                WorldItem::Interface { id, .. } => {
46                    self.import_interface(resolve, name, *id, files)?
47                }
48                WorldItem::Type { id, .. } => types.push((unwrap_name(name), *id)),
49            }
50        }
51        if !types.is_empty() {
52            self.import_types(resolve, id, &types, files);
53        }
54        if !funcs.is_empty() {
55            self.import_funcs(resolve, id, &funcs, files);
56        }
57        funcs.clear();
58
59        self.finish_imports(resolve, id, files);
60
61        // First generate bindings for any freestanding functions, if any. If
62        // these refer to types defined in the world they need to refer to the
63        // imported types generated above.
64        //
65        // Interfaces are then generated afterwards so if the same interface is
66        // both imported and exported the right types are all used everywhere.
67        let mut interfaces = Vec::new();
68        for (name, export) in world.exports.iter() {
69            match export {
70                WorldItem::Function(f) => funcs.push((unwrap_name(name), f)),
71                WorldItem::Interface { id, .. } => interfaces.push((name, id)),
72                WorldItem::Type { .. } => unreachable!(),
73            }
74        }
75        if !funcs.is_empty() {
76            self.export_funcs(resolve, id, &funcs, files)?;
77        }
78
79        self.pre_export_interface(resolve, files)?;
80
81        for (name, id) in interfaces {
82            self.export_interface(resolve, name, *id, files)?;
83        }
84        self.finish(resolve, id, files)
85    }
86
87    /// Whether or not this bindings generator expects
88    /// [`Resolve::generate_nominal_type_ids`] to be used before generating
89    /// bindings.
90    fn uses_nominal_type_ids(&self) -> bool {
91        true
92    }
93
94    fn finish_imports(&mut self, resolve: &Resolve, world: WorldId, files: &mut Files) {
95        let _ = (resolve, world, files);
96    }
97
98    fn preprocess(&mut self, resolve: &Resolve, world: WorldId) -> Result<()> {
99        let _ = (resolve, world);
100        Ok(())
101    }
102
103    fn import_interface(
104        &mut self,
105        resolve: &Resolve,
106        name: &WorldKey,
107        iface: InterfaceId,
108        files: &mut Files,
109    ) -> Result<()>;
110
111    /// Called before any exported interfaces are generated.
112    fn pre_export_interface(&mut self, resolve: &Resolve, files: &mut Files) -> Result<()> {
113        let _ = (resolve, files);
114        Ok(())
115    }
116
117    fn export_interface(
118        &mut self,
119        resolve: &Resolve,
120        name: &WorldKey,
121        iface: InterfaceId,
122        files: &mut Files,
123    ) -> Result<()>;
124    fn import_funcs(
125        &mut self,
126        resolve: &Resolve,
127        world: WorldId,
128        funcs: &[(&str, &Function)],
129        files: &mut Files,
130    );
131    fn export_funcs(
132        &mut self,
133        resolve: &Resolve,
134        world: WorldId,
135        funcs: &[(&str, &Function)],
136        files: &mut Files,
137    ) -> Result<()>;
138    fn import_types(
139        &mut self,
140        resolve: &Resolve,
141        world: WorldId,
142        types: &[(&str, TypeId)],
143        files: &mut Files,
144    );
145    fn finish(&mut self, resolve: &Resolve, world: WorldId, files: &mut Files) -> Result<()>;
146}
147
148/// This is a possible replacement for the `Generator` trait above, currently
149/// only used by the JS bindings for generating bindings for a component.
150///
151/// The current plan is to see how things shake out with worlds and various
152/// other generators to see if everything can be updated to a less
153/// per-`*.wit`-file centric interface in the future. Even this will probably
154/// change for JS though. In any case it's something that was useful for JS and
155/// is suitable to replace otherwise at any time.
156pub trait InterfaceGenerator<'a> {
157    fn resolve(&self) -> &'a Resolve;
158
159    fn type_record(&mut self, id: TypeId, name: &str, record: &Record, docs: &Docs);
160    fn type_resource(&mut self, id: TypeId, name: &str, docs: &Docs);
161    fn type_flags(&mut self, id: TypeId, name: &str, flags: &Flags, docs: &Docs);
162    fn type_tuple(&mut self, id: TypeId, name: &str, tuple: &Tuple, docs: &Docs);
163    fn type_variant(&mut self, id: TypeId, name: &str, variant: &Variant, docs: &Docs);
164    fn type_option(&mut self, id: TypeId, name: &str, payload: &Type, docs: &Docs);
165    fn type_result(&mut self, id: TypeId, name: &str, result: &Result_, docs: &Docs);
166    fn type_enum(&mut self, id: TypeId, name: &str, enum_: &Enum, docs: &Docs);
167    fn type_alias(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
168    fn type_list(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
169    fn type_fixed_length_list(&mut self, id: TypeId, name: &str, ty: &Type, size: u32, docs: &Docs);
170    fn type_map(&mut self, id: TypeId, name: &str, key: &Type, value: &Type, docs: &Docs);
171    fn type_builtin(&mut self, id: TypeId, name: &str, ty: &Type, docs: &Docs);
172    fn type_future(&mut self, id: TypeId, name: &str, ty: &Option<Type>, docs: &Docs);
173    fn type_stream(&mut self, id: TypeId, name: &str, ty: &Option<Type>, docs: &Docs);
174    fn types(&mut self, iface: InterfaceId) {
175        let iface = &self.resolve().interfaces[iface];
176        for (name, id) in iface.types.iter() {
177            self.define_type(name, *id);
178        }
179    }
180
181    fn define_type(&mut self, name: &str, id: TypeId) {
182        define_type(self, name, id)
183    }
184}
185
186pub fn define_type<'a, T>(generator: &mut T, name: &str, id: TypeId)
187where
188    T: InterfaceGenerator<'a> + ?Sized,
189{
190    let ty = &generator.resolve().types[id];
191    match &ty.kind {
192        TypeDefKind::Record(record) => generator.type_record(id, name, record, &ty.docs),
193        TypeDefKind::Resource => generator.type_resource(id, name, &ty.docs),
194        TypeDefKind::Flags(flags) => generator.type_flags(id, name, flags, &ty.docs),
195        TypeDefKind::Tuple(tuple) => generator.type_tuple(id, name, tuple, &ty.docs),
196        TypeDefKind::Enum(enum_) => generator.type_enum(id, name, enum_, &ty.docs),
197        TypeDefKind::Variant(variant) => generator.type_variant(id, name, variant, &ty.docs),
198        TypeDefKind::Option(t) => generator.type_option(id, name, t, &ty.docs),
199        TypeDefKind::Result(r) => generator.type_result(id, name, r, &ty.docs),
200        TypeDefKind::List(t) => generator.type_list(id, name, t, &ty.docs),
201        TypeDefKind::Type(t) => generator.type_alias(id, name, t, &ty.docs),
202        TypeDefKind::Future(t) => generator.type_future(id, name, t, &ty.docs),
203        TypeDefKind::Stream(t) => generator.type_stream(id, name, t, &ty.docs),
204        TypeDefKind::Handle(_) => panic!("handle types do not require definition"),
205        TypeDefKind::FixedLengthList(t, size) => {
206            generator.type_fixed_length_list(id, name, t, *size, &ty.docs)
207        }
208        TypeDefKind::Map(key, value) => generator.type_map(id, name, key, value, &ty.docs),
209        TypeDefKind::Unknown => unreachable!(),
210    }
211}
212
213pub trait AnonymousTypeGenerator<'a> {
214    fn resolve(&self) -> &'a Resolve;
215
216    fn anonymous_type_handle(&mut self, id: TypeId, handle: &Handle, docs: &Docs);
217    fn anonymous_type_tuple(&mut self, id: TypeId, ty: &Tuple, docs: &Docs);
218    fn anonymous_type_option(&mut self, id: TypeId, ty: &Type, docs: &Docs);
219    fn anonymous_type_result(&mut self, id: TypeId, ty: &Result_, docs: &Docs);
220    fn anonymous_type_list(&mut self, id: TypeId, ty: &Type, docs: &Docs);
221    fn anonymous_type_fixed_length_list(&mut self, id: TypeId, ty: &Type, size: u32, docs: &Docs);
222    fn anonymous_type_map(&mut self, id: TypeId, key: &Type, value: &Type, docs: &Docs);
223    fn anonymous_type_future(&mut self, id: TypeId, ty: &Option<Type>, docs: &Docs);
224    fn anonymous_type_stream(&mut self, id: TypeId, ty: &Option<Type>, docs: &Docs);
225    fn anonymous_type_type(&mut self, id: TypeId, ty: &Type, docs: &Docs);
226
227    fn define_anonymous_type(&mut self, id: TypeId) {
228        let ty = &self.resolve().types[id];
229        match &ty.kind {
230            TypeDefKind::Flags(_)
231            | TypeDefKind::Record(_)
232            | TypeDefKind::Resource
233            | TypeDefKind::Enum(_)
234            | TypeDefKind::Variant(_) => {
235                unreachable!()
236            }
237            TypeDefKind::Type(t) => self.anonymous_type_type(id, t, &ty.docs),
238            TypeDefKind::Tuple(tuple) => self.anonymous_type_tuple(id, tuple, &ty.docs),
239            TypeDefKind::Option(t) => self.anonymous_type_option(id, t, &ty.docs),
240            TypeDefKind::Result(r) => self.anonymous_type_result(id, r, &ty.docs),
241            TypeDefKind::List(t) => self.anonymous_type_list(id, t, &ty.docs),
242            TypeDefKind::Future(f) => self.anonymous_type_future(id, f, &ty.docs),
243            TypeDefKind::Stream(s) => self.anonymous_type_stream(id, s, &ty.docs),
244            TypeDefKind::Handle(handle) => self.anonymous_type_handle(id, handle, &ty.docs),
245            TypeDefKind::FixedLengthList(t, size) => {
246                self.anonymous_type_fixed_length_list(id, t, *size, &ty.docs)
247            }
248            TypeDefKind::Map(key, value) => self.anonymous_type_map(id, key, value, &ty.docs),
249            TypeDefKind::Unknown => unreachable!(),
250        }
251    }
252}
253
254pub fn generated_preamble(src: &mut Source, version: &str) {
255    uwriteln!(src, "// Generated by `wit-bindgen` {version}. DO NOT EDIT!")
256}
257
258pub fn dealias(resolve: &Resolve, mut id: TypeId) -> TypeId {
259    loop {
260        match &resolve.types[id].kind {
261            TypeDefKind::Type(Type::Id(that_id)) => id = *that_id,
262            _ => break id,
263        }
264    }
265}
wit_bindgen_core/lib.rs

wit_bindgen_core/
lib.rs
