wit-bindgen-core 0.63.0

Low-level support for bindings generation based on WIT files for use with `wit-bindgen-cli` and other languages.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

use anyhow::{Result, bail};
use std::collections::HashSet;
use std::fmt;
use wit_parser::{Function, FunctionKind, Resolve, WorldKey};

/// Structure used to parse the command line argument `--sync` consistently
/// across guest generators.
#[cfg_attr(feature = "clap", derive(clap::Parser))]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
#[derive(Clone, Default, Debug)]
pub struct AsyncFilterSet {
    /// Determines which `async` functions to lift or lower synchronously, if
    /// any.
    ///
    /// This option can be passed multiple times and additionally accepts
    /// comma-separated values for each option passed. Each individual argument
    /// passed here can be one of:
    ///
    /// - `all` - all imports and exports will be sync
    /// - `foo:bar/baz#method` - force this method to be sync
    /// - `import:foo:bar/baz#method` - force this method to be sync, but only
    ///   as an import
    /// - `export:foo:bar/baz#method` - force this method to be sync, but only
    ///   as an export
    ///
    /// Functions defined as `async` in WIT get async bindings unless they are
    /// listed here. Functions not defined as `async` always get sync bindings,
    /// as the component model does not allow lifting or lowering them async.
    #[cfg_attr(
        feature = "clap",
        arg(
            long = "sync",
            value_parser = parse_sync,
            value_delimiter =',',
            value_name = "FILTER",
        ),
    )]
    #[cfg_attr(feature = "serde", serde(rename = "sync"))]
    sync: Vec<SyncFilter>,

    #[cfg_attr(feature = "clap", arg(skip))]
    #[cfg_attr(feature = "serde", serde(skip))]
    used_options: HashSet<usize>,
}

#[cfg(feature = "clap")]
fn parse_sync(s: &str) -> Result<SyncFilter, String> {
    Ok(SyncFilter::parse(s))
}

impl AsyncFilterSet {
    /// Returns whether the `func` provided is to be bound `async` or not.
    pub fn is_async(
        &mut self,
        resolve: &Resolve,
        interface: Option<&WorldKey>,
        func: &Function,
        is_import: bool,
    ) -> bool {
        let name_to_test = match interface {
            Some(key) => format!("{}#{}", resolve.name_world_key(key), func.name),
            None => func.name.clone(),
        };
        let mut sync = false;
        for (i, filter) in self.sync.iter().enumerate() {
            let matches = match filter {
                SyncFilter::All => true,
                SyncFilter::Function(s) => *s == name_to_test,
                SyncFilter::Import(s) => is_import && *s == name_to_test,
                SyncFilter::Export(s) => !is_import && *s == name_to_test,
            };
            if matches {
                self.used_options.insert(i);
                sync = true;
            }
        }
        if sync {
            return false;
        }

        match &func.kind {
            FunctionKind::Freestanding
            | FunctionKind::Method(_)
            | FunctionKind::Static(_)
            | FunctionKind::Constructor(_)
            | FunctionKind::Getter
            | FunctionKind::MethodGetter(_)
            | FunctionKind::StaticGetter(_)
            | FunctionKind::Setter
            | FunctionKind::MethodSetter(_)
            | FunctionKind::StaticSetter(_) => false,
            FunctionKind::AsyncFreestanding
            | FunctionKind::AsyncMethod(_)
            | FunctionKind::AsyncStatic(_) => true,
        }
    }

    /// Intended to be used in the header comment of generated code to help
    /// indicate what options were specified.
    pub fn debug_opts(&self) -> impl Iterator<Item = String> + '_ {
        self.sync.iter().map(|filter| filter.to_string())
    }

    /// Tests whether all `--sync` options were used throughout bindings
    /// generation, returning an error if any were unused.
    pub fn ensure_all_used(&self) -> Result<()> {
        for (i, filter) in self.sync.iter().enumerate() {
            if self.used_options.contains(&i) {
                continue;
            }
            if !matches!(filter, SyncFilter::All) {
                bail!("unused sync option: {filter}");
            }
        }
        Ok(())
    }

    /// Pushes a new option into this set.
    pub fn push(&mut self, directive: &str) {
        self.sync.push(SyncFilter::parse(directive));
    }
}

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
enum SyncFilter {
    All,
    Function(String),
    Import(String),
    Export(String),
}

impl SyncFilter {
    fn parse(s: &str) -> SyncFilter {
        match s {
            "all" => SyncFilter::All,
            other => match other.strip_prefix("import:") {
                Some(s) => SyncFilter::Import(s.to_string()),
                None => match other.strip_prefix("export:") {
                    Some(s) => SyncFilter::Export(s.to_string()),
                    None => SyncFilter::Function(s.to_string()),
                },
            },
        }
    }
}

impl fmt::Display for SyncFilter {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            SyncFilter::All => write!(f, "all"),
            SyncFilter::Function(s) => write!(f, "{s}"),
            SyncFilter::Import(s) => write!(f, "import:{s}"),
            SyncFilter::Export(s) => write!(f, "export:{s}"),
        }
    }
}