wasm_encoder/component/
types.rs

1use super::CORE_TYPE_SORT;
2use crate::{
3    encode_section, Alias, ComponentExportKind, ComponentOuterAliasKind, ComponentSection,
4    ComponentSectionId, ComponentTypeRef, CoreTypeEncoder, Encode, EntityType, ValType,
5};
6use alloc::vec::Vec;
7
8/// Represents the type of a core module.
9#[derive(Debug, Clone, Default)]
10pub struct ModuleType {
11    bytes: Vec<u8>,
12    num_added: u32,
13    types_added: u32,
14}
15
16impl ModuleType {
17    /// Creates a new core module type.
18    pub fn new() -> Self {
19        Self::default()
20    }
21
22    /// Defines an import in this module type.
23    pub fn import(&mut self, module: &str, name: &str, ty: EntityType) -> &mut Self {
24        self.bytes.push(0x00);
25        module.encode(&mut self.bytes);
26        name.encode(&mut self.bytes);
27        ty.encode(&mut self.bytes);
28        self.num_added += 1;
29        self
30    }
31
32    /// Define a type in this module type.
33    ///
34    /// The returned encoder must be used before adding another definition.
35    #[must_use = "the encoder must be used to encode the type"]
36    pub fn ty(&mut self) -> CoreTypeEncoder {
37        self.bytes.push(0x01);
38        self.num_added += 1;
39        self.types_added += 1;
40        CoreTypeEncoder {
41            push_prefix_if_component_core_type: false,
42            bytes: &mut self.bytes,
43        }
44    }
45
46    /// Defines an outer core type alias in this module type.
47    pub fn alias_outer_core_type(&mut self, count: u32, index: u32) -> &mut Self {
48        self.bytes.push(0x02);
49        self.bytes.push(CORE_TYPE_SORT);
50        self.bytes.push(0x01); // outer
51        count.encode(&mut self.bytes);
52        index.encode(&mut self.bytes);
53        self.num_added += 1;
54        self.types_added += 1;
55        self
56    }
57
58    /// Defines an export in this module type.
59    pub fn export(&mut self, name: &str, ty: EntityType) -> &mut Self {
60        self.bytes.push(0x03);
61        name.encode(&mut self.bytes);
62        ty.encode(&mut self.bytes);
63        self.num_added += 1;
64        self
65    }
66
67    /// Gets the number of types that have been added to this module type.
68    pub fn type_count(&self) -> u32 {
69        self.types_added
70    }
71}
72
73impl Encode for ModuleType {
74    fn encode(&self, sink: &mut Vec<u8>) {
75        sink.push(0x50);
76        self.num_added.encode(sink);
77        sink.extend(&self.bytes);
78    }
79}
80
81/// Used to encode core types.
82#[derive(Debug)]
83pub struct ComponentCoreTypeEncoder<'a>(pub(crate) &'a mut Vec<u8>);
84
85impl<'a> ComponentCoreTypeEncoder<'a> {
86    /// Define a module type.
87    pub fn module(self, ty: &ModuleType) {
88        ty.encode(self.0);
89    }
90
91    /// Define any core type other than a module type.
92    #[must_use = "the encoder must be used to encode the type"]
93    pub fn core(self) -> CoreTypeEncoder<'a> {
94        CoreTypeEncoder {
95            bytes: self.0,
96            push_prefix_if_component_core_type: true,
97        }
98    }
99}
100
101/// An encoder for the core type section of WebAssembly components.
102///
103/// # Example
104///
105/// ```rust
106/// use wasm_encoder::{Component, CoreTypeSection, ModuleType};
107///
108/// let mut types = CoreTypeSection::new();
109///
110/// types.ty().module(&ModuleType::new());
111///
112/// let mut component = Component::new();
113/// component.section(&types);
114///
115/// let bytes = component.finish();
116/// ```
117#[derive(Clone, Debug, Default)]
118pub struct CoreTypeSection {
119    bytes: Vec<u8>,
120    num_added: u32,
121}
122
123impl CoreTypeSection {
124    /// Create a new core type section encoder.
125    pub fn new() -> Self {
126        Self::default()
127    }
128
129    /// The number of types in the section.
130    pub fn len(&self) -> u32 {
131        self.num_added
132    }
133
134    /// Determines if the section is empty.
135    pub fn is_empty(&self) -> bool {
136        self.num_added == 0
137    }
138
139    /// Encode a type into this section.
140    ///
141    /// The returned encoder must be finished before adding another type.
142    #[must_use = "the encoder must be used to encode the type"]
143    pub fn ty(&mut self) -> ComponentCoreTypeEncoder<'_> {
144        self.num_added += 1;
145        ComponentCoreTypeEncoder(&mut self.bytes)
146    }
147}
148
149impl Encode for CoreTypeSection {
150    fn encode(&self, sink: &mut Vec<u8>) {
151        encode_section(sink, self.num_added, &self.bytes);
152    }
153}
154
155impl ComponentSection for CoreTypeSection {
156    fn id(&self) -> u8 {
157        ComponentSectionId::CoreType.into()
158    }
159}
160
161/// Represents a component type.
162#[derive(Debug, Clone, Default)]
163pub struct ComponentType {
164    bytes: Vec<u8>,
165    num_added: u32,
166    core_types_added: u32,
167    types_added: u32,
168    instances_added: u32,
169}
170
171impl ComponentType {
172    /// Creates a new component type.
173    pub fn new() -> Self {
174        Self::default()
175    }
176
177    /// Define a core type in this component type.
178    ///
179    /// The returned encoder must be used before adding another definition.
180    #[must_use = "the encoder must be used to encode the type"]
181    pub fn core_type(&mut self) -> ComponentCoreTypeEncoder {
182        self.bytes.push(0x00);
183        self.num_added += 1;
184        self.core_types_added += 1;
185        ComponentCoreTypeEncoder(&mut self.bytes)
186    }
187
188    /// Define a type in this component type.
189    ///
190    /// The returned encoder must be used before adding another definition.
191    #[must_use = "the encoder must be used to encode the type"]
192    pub fn ty(&mut self) -> ComponentTypeEncoder {
193        self.bytes.push(0x01);
194        self.num_added += 1;
195        self.types_added += 1;
196        ComponentTypeEncoder(&mut self.bytes)
197    }
198
199    /// Defines an alias for an exported item of a prior instance or an
200    /// outer type.
201    pub fn alias(&mut self, alias: Alias<'_>) -> &mut Self {
202        self.bytes.push(0x02);
203        alias.encode(&mut self.bytes);
204        self.num_added += 1;
205        match &alias {
206            Alias::InstanceExport {
207                kind: ComponentExportKind::Type,
208                ..
209            }
210            | Alias::Outer {
211                kind: ComponentOuterAliasKind::Type,
212                ..
213            } => self.types_added += 1,
214            Alias::Outer {
215                kind: ComponentOuterAliasKind::CoreType,
216                ..
217            } => self.core_types_added += 1,
218            Alias::InstanceExport {
219                kind: ComponentExportKind::Instance,
220                ..
221            } => self.instances_added += 1,
222            _ => {}
223        }
224        self
225    }
226
227    /// Defines an import in this component type.
228    pub fn import(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
229        self.bytes.push(0x03);
230        crate::encode_component_import_name(&mut self.bytes, name);
231        ty.encode(&mut self.bytes);
232        self.num_added += 1;
233        match ty {
234            ComponentTypeRef::Type(..) => self.types_added += 1,
235            ComponentTypeRef::Instance(..) => self.instances_added += 1,
236            _ => {}
237        }
238        self
239    }
240
241    /// Defines an export in this component type.
242    pub fn export(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
243        self.bytes.push(0x04);
244        crate::encode_component_export_name(&mut self.bytes, name);
245        ty.encode(&mut self.bytes);
246        self.num_added += 1;
247        match ty {
248            ComponentTypeRef::Type(..) => self.types_added += 1,
249            ComponentTypeRef::Instance(..) => self.instances_added += 1,
250            _ => {}
251        }
252        self
253    }
254
255    /// Gets the number of core types that have been added to this component type.
256    pub fn core_type_count(&self) -> u32 {
257        self.core_types_added
258    }
259
260    /// Gets the number of types that have been added or aliased in this component type.
261    pub fn type_count(&self) -> u32 {
262        self.types_added
263    }
264
265    /// Gets the number of instances that have been defined in this component
266    /// type through imports, exports, or aliases.
267    pub fn instance_count(&self) -> u32 {
268        self.instances_added
269    }
270}
271
272impl Encode for ComponentType {
273    fn encode(&self, sink: &mut Vec<u8>) {
274        sink.push(0x41);
275        self.num_added.encode(sink);
276        sink.extend(&self.bytes);
277    }
278}
279
280/// Represents an instance type.
281#[derive(Debug, Clone, Default)]
282pub struct InstanceType(ComponentType);
283
284impl InstanceType {
285    /// Creates a new instance type.
286    pub fn new() -> Self {
287        Self::default()
288    }
289
290    /// Define a core type in this instance type.
291    ///
292    /// The returned encoder must be used before adding another definition.
293    #[must_use = "the encoder must be used to encode the type"]
294    pub fn core_type(&mut self) -> ComponentCoreTypeEncoder {
295        self.0.core_type()
296    }
297
298    /// Define a type in this instance type.
299    ///
300    /// The returned encoder must be used before adding another definition.
301    #[must_use = "the encoder must be used to encode the type"]
302    pub fn ty(&mut self) -> ComponentTypeEncoder {
303        self.0.ty()
304    }
305
306    /// Defines an outer core type alias in this component type.
307    pub fn alias(&mut self, alias: Alias<'_>) -> &mut Self {
308        self.0.alias(alias);
309        self
310    }
311
312    /// Defines an export in this instance type.
313    pub fn export(&mut self, name: &str, ty: ComponentTypeRef) -> &mut Self {
314        self.0.export(name, ty);
315        self
316    }
317
318    /// Gets the number of core types that have been added to this instance type.
319    pub fn core_type_count(&self) -> u32 {
320        self.0.core_types_added
321    }
322
323    /// Gets the number of types that have been added or aliased in this instance type.
324    pub fn type_count(&self) -> u32 {
325        self.0.types_added
326    }
327
328    /// Gets the number of instances that have been imported or exported or
329    /// aliased in this instance type.
330    pub fn instance_count(&self) -> u32 {
331        self.0.instances_added
332    }
333
334    /// Returns whether or not this instance type is empty.
335    pub fn is_empty(&self) -> bool {
336        self.0.num_added == 0
337    }
338
339    /// Returns the number of entries added to this instance types.
340    pub fn len(&self) -> u32 {
341        self.0.num_added
342    }
343}
344
345impl Encode for InstanceType {
346    fn encode(&self, sink: &mut Vec<u8>) {
347        sink.push(0x42);
348        self.0.num_added.encode(sink);
349        sink.extend(&self.0.bytes);
350    }
351}
352
353/// Used to encode component function types.
354#[derive(Debug)]
355pub struct ComponentFuncTypeEncoder<'a> {
356    params_encoded: bool,
357    results_encoded: bool,
358    sink: &'a mut Vec<u8>,
359}
360
361impl<'a> ComponentFuncTypeEncoder<'a> {
362    fn new(sink: &'a mut Vec<u8>) -> Self {
363        sink.push(0x40);
364        Self {
365            params_encoded: false,
366            results_encoded: false,
367            sink,
368        }
369    }
370
371    /// Defines named parameters.
372    ///
373    /// Parameters must be defined before defining results.
374    ///
375    /// # Panics
376    ///
377    /// This method will panic if the function is called twice since parameters
378    /// can only be encoded once.
379    pub fn params<'b, P, T>(&mut self, params: P) -> &mut Self
380    where
381        P: IntoIterator<Item = (&'b str, T)>,
382        P::IntoIter: ExactSizeIterator,
383        T: Into<ComponentValType>,
384    {
385        assert!(!self.params_encoded);
386        self.params_encoded = true;
387        let params = params.into_iter();
388        params.len().encode(self.sink);
389        for (name, ty) in params {
390            name.encode(self.sink);
391            ty.into().encode(self.sink);
392        }
393        self
394    }
395
396    /// Defines a single unnamed result.
397    ///
398    /// This method cannot be used with `results`.
399    ///
400    /// # Panics
401    ///
402    /// This method will panic if the function is called twice, called before
403    /// the `params` method, or called in addition to the `results` method.
404    pub fn result(&mut self, ty: Option<ComponentValType>) -> &mut Self {
405        assert!(self.params_encoded);
406        assert!(!self.results_encoded);
407        self.results_encoded = true;
408        match ty {
409            Some(ty) => {
410                self.sink.push(0x00);
411                ty.encode(self.sink);
412            }
413            None => {
414                self.sink.push(0x01);
415                self.sink.push(0x00);
416            }
417        }
418        self
419    }
420}
421
422/// Used to encode component and instance types.
423#[derive(Debug)]
424pub struct ComponentTypeEncoder<'a>(&'a mut Vec<u8>);
425
426impl<'a> ComponentTypeEncoder<'a> {
427    /// Define a component type.
428    pub fn component(self, ty: &ComponentType) {
429        ty.encode(self.0);
430    }
431
432    /// Define an instance type.
433    pub fn instance(self, ty: &InstanceType) {
434        ty.encode(self.0);
435    }
436
437    /// Define a function type.
438    pub fn function(self) -> ComponentFuncTypeEncoder<'a> {
439        ComponentFuncTypeEncoder::new(self.0)
440    }
441
442    /// Define a defined component type.
443    ///
444    /// The returned encoder must be used before adding another type.
445    #[must_use = "the encoder must be used to encode the type"]
446    pub fn defined_type(self) -> ComponentDefinedTypeEncoder<'a> {
447        ComponentDefinedTypeEncoder(self.0)
448    }
449
450    /// Define a resource type.
451    pub fn resource(self, rep: ValType, dtor: Option<u32>) {
452        self.0.push(0x3f);
453        rep.encode(self.0);
454        match dtor {
455            Some(i) => {
456                self.0.push(0x01);
457                i.encode(self.0);
458            }
459            None => self.0.push(0x00),
460        }
461    }
462}
463
464/// Represents a primitive component value type.
465#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
466pub enum PrimitiveValType {
467    /// The type is a boolean.
468    Bool,
469    /// The type is a signed 8-bit integer.
470    S8,
471    /// The type is an unsigned 8-bit integer.
472    U8,
473    /// The type is a signed 16-bit integer.
474    S16,
475    /// The type is an unsigned 16-bit integer.
476    U16,
477    /// The type is a signed 32-bit integer.
478    S32,
479    /// The type is an unsigned 32-bit integer.
480    U32,
481    /// The type is a signed 64-bit integer.
482    S64,
483    /// The type is an unsigned 64-bit integer.
484    U64,
485    /// The type is a 32-bit floating point number with only one NaN.
486    F32,
487    /// The type is a 64-bit floating point number with only one NaN.
488    F64,
489    /// The type is a Unicode character.
490    Char,
491    /// The type is a string.
492    String,
493}
494
495impl Encode for PrimitiveValType {
496    fn encode(&self, sink: &mut Vec<u8>) {
497        sink.push(match self {
498            Self::Bool => 0x7f,
499            Self::S8 => 0x7e,
500            Self::U8 => 0x7d,
501            Self::S16 => 0x7c,
502            Self::U16 => 0x7b,
503            Self::S32 => 0x7a,
504            Self::U32 => 0x79,
505            Self::S64 => 0x78,
506            Self::U64 => 0x77,
507            Self::F32 => 0x76,
508            Self::F64 => 0x75,
509            Self::Char => 0x74,
510            Self::String => 0x73,
511        });
512    }
513}
514
515/// Represents a component value type.
516#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
517pub enum ComponentValType {
518    /// The value is a primitive type.
519    Primitive(PrimitiveValType),
520    /// The value is to a defined value type.
521    ///
522    /// The type index must be to a value type.
523    Type(u32),
524}
525
526impl Encode for ComponentValType {
527    fn encode(&self, sink: &mut Vec<u8>) {
528        match self {
529            Self::Primitive(ty) => ty.encode(sink),
530            Self::Type(index) => (*index as i64).encode(sink),
531        }
532    }
533}
534
535impl From<PrimitiveValType> for ComponentValType {
536    fn from(ty: PrimitiveValType) -> Self {
537        Self::Primitive(ty)
538    }
539}
540
541/// Used for encoding component defined types.
542#[derive(Debug)]
543pub struct ComponentDefinedTypeEncoder<'a>(&'a mut Vec<u8>);
544
545impl ComponentDefinedTypeEncoder<'_> {
546    /// Define a primitive value type.
547    pub fn primitive(self, ty: PrimitiveValType) {
548        ty.encode(self.0);
549    }
550
551    /// Define a record type.
552    pub fn record<'a, F, T>(self, fields: F)
553    where
554        F: IntoIterator<Item = (&'a str, T)>,
555        F::IntoIter: ExactSizeIterator,
556        T: Into<ComponentValType>,
557    {
558        let fields = fields.into_iter();
559        self.0.push(0x72);
560        fields.len().encode(self.0);
561        for (name, ty) in fields {
562            name.encode(self.0);
563            ty.into().encode(self.0);
564        }
565    }
566
567    /// Define a variant type.
568    pub fn variant<'a, C>(self, cases: C)
569    where
570        C: IntoIterator<Item = (&'a str, Option<ComponentValType>, Option<u32>)>,
571        C::IntoIter: ExactSizeIterator,
572    {
573        let cases = cases.into_iter();
574        self.0.push(0x71);
575        cases.len().encode(self.0);
576        for (name, ty, refines) in cases {
577            name.encode(self.0);
578            ty.encode(self.0);
579            refines.encode(self.0);
580        }
581    }
582
583    /// Define a list type.
584    pub fn list(self, ty: impl Into<ComponentValType>) {
585        self.0.push(0x70);
586        ty.into().encode(self.0);
587    }
588
589    /// Define a tuple type.
590    pub fn tuple<I, T>(self, types: I)
591    where
592        I: IntoIterator<Item = T>,
593        I::IntoIter: ExactSizeIterator,
594        T: Into<ComponentValType>,
595    {
596        let types = types.into_iter();
597        self.0.push(0x6F);
598        types.len().encode(self.0);
599        for ty in types {
600            ty.into().encode(self.0);
601        }
602    }
603
604    /// Define a flags type.
605    pub fn flags<'a, I>(self, names: I)
606    where
607        I: IntoIterator<Item = &'a str>,
608        I::IntoIter: ExactSizeIterator,
609    {
610        let names = names.into_iter();
611        self.0.push(0x6E);
612        names.len().encode(self.0);
613        for name in names {
614            name.encode(self.0);
615        }
616    }
617
618    /// Define an enum type.
619    pub fn enum_type<'a, I>(self, tags: I)
620    where
621        I: IntoIterator<Item = &'a str>,
622        I::IntoIter: ExactSizeIterator,
623    {
624        let tags = tags.into_iter();
625        self.0.push(0x6D);
626        tags.len().encode(self.0);
627        for tag in tags {
628            tag.encode(self.0);
629        }
630    }
631
632    /// Define an option type.
633    pub fn option(self, ty: impl Into<ComponentValType>) {
634        self.0.push(0x6B);
635        ty.into().encode(self.0);
636    }
637
638    /// Define a result type.
639    pub fn result(self, ok: Option<ComponentValType>, err: Option<ComponentValType>) {
640        self.0.push(0x6A);
641        ok.encode(self.0);
642        err.encode(self.0);
643    }
644
645    /// Define a `own` handle type
646    pub fn own(self, idx: u32) {
647        self.0.push(0x69);
648        idx.encode(self.0);
649    }
650
651    /// Define a `borrow` handle type
652    pub fn borrow(self, idx: u32) {
653        self.0.push(0x68);
654        idx.encode(self.0);
655    }
656
657    /// Define a `future` type with the specified payload.
658    pub fn future(self, payload: Option<ComponentValType>) {
659        self.0.push(0x65);
660        payload.encode(self.0);
661    }
662
663    /// Define a `stream` type with the specified payload.
664    pub fn stream(self, payload: Option<ComponentValType>) {
665        self.0.push(0x66);
666        payload.encode(self.0);
667    }
668
669    /// Define the `error-context` type.
670    pub fn error_context(self) {
671        self.0.push(0x64);
672    }
673}
674
675/// An encoder for the type section of WebAssembly components.
676///
677/// # Example
678///
679/// ```rust
680/// use wasm_encoder::{Component, ComponentTypeSection, PrimitiveValType};
681///
682/// let mut types = ComponentTypeSection::new();
683///
684/// // Define a function type of `[string, string] -> string`.
685/// types
686///   .function()
687///   .params(
688///     [
689///       ("a", PrimitiveValType::String),
690///       ("b", PrimitiveValType::String)
691///     ]
692///   )
693///   .result(Some(PrimitiveValType::String.into()));
694///
695/// let mut component = Component::new();
696/// component.section(&types);
697///
698/// let bytes = component.finish();
699/// ```
700#[derive(Clone, Debug, Default)]
701pub struct ComponentTypeSection {
702    bytes: Vec<u8>,
703    num_added: u32,
704}
705
706impl ComponentTypeSection {
707    /// Create a new component type section encoder.
708    pub fn new() -> Self {
709        Self::default()
710    }
711
712    /// The number of types in the section.
713    pub fn len(&self) -> u32 {
714        self.num_added
715    }
716
717    /// Determines if the section is empty.
718    pub fn is_empty(&self) -> bool {
719        self.num_added == 0
720    }
721
722    /// Encode a type into this section.
723    ///
724    /// The returned encoder must be finished before adding another type.
725    #[must_use = "the encoder must be used to encode the type"]
726    pub fn ty(&mut self) -> ComponentTypeEncoder<'_> {
727        self.num_added += 1;
728        ComponentTypeEncoder(&mut self.bytes)
729    }
730
731    /// Define a component type in this type section.
732    pub fn component(&mut self, ty: &ComponentType) -> &mut Self {
733        self.ty().component(ty);
734        self
735    }
736
737    /// Define an instance type in this type section.
738    pub fn instance(&mut self, ty: &InstanceType) -> &mut Self {
739        self.ty().instance(ty);
740        self
741    }
742
743    /// Define a function type in this type section.
744    pub fn function(&mut self) -> ComponentFuncTypeEncoder<'_> {
745        self.ty().function()
746    }
747
748    /// Add a component defined type to this type section.
749    ///
750    /// The returned encoder must be used before adding another type.
751    #[must_use = "the encoder must be used to encode the type"]
752    pub fn defined_type(&mut self) -> ComponentDefinedTypeEncoder<'_> {
753        self.ty().defined_type()
754    }
755
756    /// Defines a new resource type.
757    pub fn resource(&mut self, rep: ValType, dtor: Option<u32>) -> &mut Self {
758        self.ty().resource(rep, dtor);
759        self
760    }
761}
762
763impl Encode for ComponentTypeSection {
764    fn encode(&self, sink: &mut Vec<u8>) {
765        encode_section(sink, self.num_added, &self.bytes);
766    }
767}
768
769impl ComponentSection for ComponentTypeSection {
770    fn id(&self) -> u8 {
771        ComponentSectionId::Type.into()
772    }
773}
wasm_encoder/component/types.rs

wasm_encoder/component/
types.rs
