weaveffi_core/codegen/
common.rs

1//! Shared codegen primitives that every language generator can reuse.
2//!
3//! Until 0.4.0, every generator hand-rolled its own copy of the module
4//! tree walker, the doc-comment emitter, and the "is this type a C
5//! pointer at the ABI boundary?" predicate. Pulling them in here gives
6//! the generators one source of truth and shrinks each crate by a few
7//! dozen lines of near-identical helper code.
8//!
9//! Specialised flavours that exist in only one generator (Go's
10//! godoc-style first-line symbol prefix, .NET's `<summary>` XML tags,
11//! Python's triple-quoted docstring) stay generator-local because
12//! their behaviour is non-uniform; this module deliberately covers
13//! only the common 80%.
14
15use weaveffi_ir::ir::{Module, TypeRef};
16
17/// Doc-comment flavour used by [`emit_doc`].
18///
19/// Specialised flavours like Go's godoc-symbol prefix or .NET's
20/// `<summary>` element are intentionally absent and remain in their
21/// own generators because their first-line behaviour is non-uniform.
22#[derive(Debug, Clone, Copy, PartialEq, Eq)]
23pub enum DocCommentStyle {
24    /// `/// ...` per line (Swift, Dart, Rust).
25    TripleSlash,
26    /// `# ...` per line (Python `#` comments, Ruby).
27    Hash,
28    /// `// ...` per line (Go base case; Go's symbol-prefixed
29    /// godoc convention stays generator-local).
30    DoubleSlash,
31    /// `/** ... */` block; single-line collapses to `/** text */`
32    /// (C, C++, Kotlin/KDoc, JSDoc, TypeScript .d.ts).
33    Javadoc,
34}
35
36/// Emit a doc comment for `doc` at the given `indent`, using the given
37/// `style`. No-op when `doc` is `None` or trims to empty.
38///
39/// The output always ends with a trailing newline so a generator can
40/// follow it directly with the symbol declaration on the next line.
41pub fn emit_doc(out: &mut String, doc: &Option<String>, indent: &str, style: DocCommentStyle) {
42    let Some(doc) = doc else {
43        return;
44    };
45    let doc = doc.trim();
46    if doc.is_empty() {
47        return;
48    }
49    match style {
50        DocCommentStyle::TripleSlash => emit_line_doc(out, doc, indent, "///"),
51        DocCommentStyle::Hash => emit_line_doc(out, doc, indent, "#"),
52        DocCommentStyle::DoubleSlash => emit_line_doc(out, doc, indent, "//"),
53        DocCommentStyle::Javadoc => emit_javadoc(out, doc, indent),
54    }
55}
56
57fn emit_line_doc(out: &mut String, doc: &str, indent: &str, marker: &str) {
58    for line in doc.lines() {
59        out.push_str(indent);
60        if line.is_empty() {
61            out.push_str(marker);
62            out.push('\n');
63        } else {
64            out.push_str(marker);
65            out.push(' ');
66            out.push_str(line);
67            out.push('\n');
68        }
69    }
70}
71
72fn emit_javadoc(out: &mut String, doc: &str, indent: &str) {
73    if doc.contains('\n') {
74        out.push_str(indent);
75        out.push_str("/**\n");
76        for line in doc.lines() {
77            out.push_str(indent);
78            if line.is_empty() {
79                out.push_str(" *\n");
80            } else {
81                out.push_str(" * ");
82                out.push_str(line);
83                out.push('\n');
84            }
85        }
86        out.push_str(indent);
87        out.push_str(" */\n");
88    } else {
89        out.push_str(indent);
90        out.push_str("/** ");
91        out.push_str(doc);
92        out.push_str(" */\n");
93    }
94}
95
96/// Iterate over every module in `roots` and its descendants in
97/// depth-first pre-order: each module is yielded before its children,
98/// and children are yielded left-to-right.
99///
100/// Equivalent to the recursive `collect_all_modules` helper that
101/// every generator used to define locally.
102pub fn walk_modules<'a>(roots: &'a [Module]) -> impl Iterator<Item = &'a Module> {
103    let mut stack: Vec<&'a Module> = roots.iter().rev().collect();
104    std::iter::from_fn(move || {
105        let m = stack.pop()?;
106        for child in m.modules.iter().rev() {
107            stack.push(child);
108        }
109        Some(m)
110    })
111}
112
113/// Like [`walk_modules`], but each module is paired with its
114/// underscore-joined path (e.g. `parent_child_grandchild`). The path
115/// matches the canonical C symbol prefix segment that the C generator
116/// builds when emitting `{c_prefix}_{module_path}_{name}`.
117pub fn walk_modules_with_path<'a>(
118    roots: &'a [Module],
119) -> impl Iterator<Item = (&'a Module, String)> {
120    let mut stack: Vec<(&'a Module, String)> =
121        roots.iter().rev().map(|m| (m, m.name.clone())).collect();
122    std::iter::from_fn(move || {
123        let (m, path) = stack.pop()?;
124        for child in m.modules.iter().rev() {
125            stack.push((child, format!("{path}_{}", child.name)));
126        }
127        Some((m, path))
128    })
129}
130
131/// Predicate: returns `true` when the IR type is represented as a
132/// pointer at the C ABI boundary.
133///
134/// String types, byte buffers, struct values (including rich/algebraic enums,
135/// which are spelled `Struct` after resolution), interfaces, typed handles,
136/// lists, maps, and iterators all cross the ABI as pointers. Scalars
137/// (`i32`/`bool`/etc.), `Handle`, and a C-style `Enum(_)` cross by value.
138///
139/// `Optional(T)` is *not* automatically a pointer here: callers that
140/// care about Optional pointer-ness (the C/C++ generators) recurse
141/// into the inner type before consulting this predicate.
142pub fn is_c_pointer_type(ty: &TypeRef) -> bool {
143    matches!(
144        ty,
145        TypeRef::StringUtf8
146            | TypeRef::BorrowedStr
147            | TypeRef::Bytes
148            | TypeRef::BorrowedBytes
149            | TypeRef::Struct(_)
150            | TypeRef::Interface(_)
151            | TypeRef::TypedHandle(_)
152            | TypeRef::List(_)
153            | TypeRef::Map(_, _)
154            | TypeRef::Iterator(_)
155    )
156}
157
158/// Convert a `snake_case` identifier to `PascalCase` by uppercasing the
159/// first character of each `_`-separated segment and preserving the rest.
160///
161/// This deliberately splits on `_` only; it does **not** re-case interior
162/// letters the way `heck::ToUpperCamelCase` does, so an acronym-bearing
163/// name like `get_HTTP` becomes `GetHTTP`, not `GetHttp`. It is the single
164/// source of truth for the `snake_to_pascal` / `to_pascal_case` helpers
165/// that the Python, Android, and Wasm generators each defined locally.
166pub fn pascal_case(s: &str) -> String {
167    s.split('_')
168        .map(|part| {
169            let mut chars = part.chars();
170            match chars.next() {
171                None => String::new(),
172                Some(first) => first.to_uppercase().chain(chars).collect::<String>(),
173            }
174        })
175        .collect()
176}
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181    use weaveffi_ir::ir::Module;
182
183    fn leaf(name: &str) -> Module {
184        Module {
185            name: name.to_string(),
186            functions: vec![],
187            interfaces: vec![],
188            structs: vec![],
189            enums: vec![],
190            callbacks: vec![],
191            listeners: vec![],
192            errors: None,
193            modules: vec![],
194        }
195    }
196
197    fn with_children(name: &str, children: Vec<Module>) -> Module {
198        Module {
199            modules: children,
200            ..leaf(name)
201        }
202    }
203
204    // --- walk_modules ---
205
206    #[test]
207    fn walk_modules_visits_pre_order() {
208        let roots = vec![
209            with_children("a", vec![leaf("a1"), leaf("a2")]),
210            with_children("b", vec![leaf("b1")]),
211        ];
212        let names: Vec<&str> = walk_modules(&roots).map(|m| m.name.as_str()).collect();
213        assert_eq!(names, vec!["a", "a1", "a2", "b", "b1"]);
214    }
215
216    #[test]
217    fn walk_modules_descends_to_arbitrary_depth() {
218        let roots = vec![with_children(
219            "a",
220            vec![with_children(
221                "b",
222                vec![with_children("c", vec![leaf("d")])],
223            )],
224        )];
225        let names: Vec<&str> = walk_modules(&roots).map(|m| m.name.as_str()).collect();
226        assert_eq!(names, vec!["a", "b", "c", "d"]);
227    }
228
229    #[test]
230    fn walk_modules_empty_input_yields_nothing() {
231        let roots: Vec<Module> = vec![];
232        assert_eq!(walk_modules(&roots).count(), 0);
233    }
234
235    // --- walk_modules_with_path ---
236
237    #[test]
238    fn walk_modules_with_path_joins_with_underscore() {
239        let roots = vec![with_children(
240            "outer",
241            vec![with_children("inner", vec![leaf("leaf")])],
242        )];
243        let pairs: Vec<(String, String)> = walk_modules_with_path(&roots)
244            .map(|(m, p)| (m.name.clone(), p))
245            .collect();
246        assert_eq!(
247            pairs,
248            vec![
249                ("outer".into(), "outer".into()),
250                ("inner".into(), "outer_inner".into()),
251                ("leaf".into(), "outer_inner_leaf".into()),
252            ]
253        );
254    }
255
256    #[test]
257    fn walk_modules_with_path_independent_roots() {
258        let roots = vec![
259            with_children("a", vec![leaf("a1")]),
260            with_children("b", vec![leaf("b1")]),
261        ];
262        let paths: Vec<String> = walk_modules_with_path(&roots).map(|(_, p)| p).collect();
263        assert_eq!(paths, vec!["a", "a_a1", "b", "b_b1"]);
264    }
265
266    // --- emit_doc ---
267
268    #[test]
269    fn emit_doc_none_writes_nothing() {
270        let mut out = String::new();
271        emit_doc(&mut out, &None, "", DocCommentStyle::TripleSlash);
272        assert!(out.is_empty());
273    }
274
275    #[test]
276    fn emit_doc_empty_string_writes_nothing() {
277        let mut out = String::new();
278        emit_doc(
279            &mut out,
280            &Some("   \n  ".into()),
281            "",
282            DocCommentStyle::TripleSlash,
283        );
284        assert!(out.is_empty());
285    }
286
287    #[test]
288    fn emit_doc_triple_slash_single_line() {
289        let mut out = String::new();
290        emit_doc(
291            &mut out,
292            &Some("Hello, world.".into()),
293            "  ",
294            DocCommentStyle::TripleSlash,
295        );
296        assert_eq!(out, "  /// Hello, world.\n");
297    }
298
299    #[test]
300    fn emit_doc_triple_slash_multi_line_with_blank() {
301        let mut out = String::new();
302        emit_doc(
303            &mut out,
304            &Some("First line.\n\nThird line.".into()),
305            "",
306            DocCommentStyle::TripleSlash,
307        );
308        assert_eq!(out, "/// First line.\n///\n/// Third line.\n");
309    }
310
311    #[test]
312    fn emit_doc_hash_single_line() {
313        let mut out = String::new();
314        emit_doc(
315            &mut out,
316            &Some("ruby/python style".into()),
317            "",
318            DocCommentStyle::Hash,
319        );
320        assert_eq!(out, "# ruby/python style\n");
321    }
322
323    #[test]
324    fn emit_doc_double_slash_single_line() {
325        let mut out = String::new();
326        emit_doc(
327            &mut out,
328            &Some("Go-style line comment.".into()),
329            "",
330            DocCommentStyle::DoubleSlash,
331        );
332        assert_eq!(out, "// Go-style line comment.\n");
333    }
334
335    #[test]
336    fn emit_doc_double_slash_multi_line() {
337        let mut out = String::new();
338        emit_doc(
339            &mut out,
340            &Some("first\n\nsecond".into()),
341            "\t",
342            DocCommentStyle::DoubleSlash,
343        );
344        assert_eq!(out, "\t// first\n\t//\n\t// second\n");
345    }
346
347    #[test]
348    fn emit_doc_hash_multi_line() {
349        let mut out = String::new();
350        emit_doc(
351            &mut out,
352            &Some("one\n\ntwo".into()),
353            "    ",
354            DocCommentStyle::Hash,
355        );
356        assert_eq!(out, "    # one\n    #\n    # two\n");
357    }
358
359    #[test]
360    fn emit_doc_javadoc_single_line_collapses() {
361        let mut out = String::new();
362        emit_doc(
363            &mut out,
364            &Some("short".into()),
365            "",
366            DocCommentStyle::Javadoc,
367        );
368        assert_eq!(out, "/** short */\n");
369    }
370
371    #[test]
372    fn emit_doc_javadoc_multi_line_expands() {
373        let mut out = String::new();
374        emit_doc(
375            &mut out,
376            &Some("line one\n\nline three".into()),
377            "  ",
378            DocCommentStyle::Javadoc,
379        );
380        assert_eq!(out, "  /**\n   * line one\n   *\n   * line three\n   */\n");
381    }
382
383    #[test]
384    fn emit_doc_trims_outer_whitespace_before_decisions() {
385        // A doc that's "single line" after trimming should still
386        // collapse to `/** text */` even if it had surrounding blank
387        // lines in the IR; the existing per-generator behaviour we
388        // are replacing did the same.
389        let mut out = String::new();
390        emit_doc(
391            &mut out,
392            &Some("\n\nhello\n\n".into()),
393            "",
394            DocCommentStyle::Javadoc,
395        );
396        assert_eq!(out, "/** hello */\n");
397    }
398
399    // --- is_c_pointer_type ---
400
401    #[test]
402    fn is_c_pointer_for_pointer_carrying_types() {
403        for ty in [
404            TypeRef::StringUtf8,
405            TypeRef::BorrowedStr,
406            TypeRef::Bytes,
407            TypeRef::BorrowedBytes,
408            TypeRef::Struct("X".into()),
409            TypeRef::TypedHandle("X".into()),
410            TypeRef::List(Box::new(TypeRef::I32)),
411            TypeRef::Map(Box::new(TypeRef::StringUtf8), Box::new(TypeRef::I32)),
412            TypeRef::Iterator(Box::new(TypeRef::StringUtf8)),
413        ] {
414            assert!(is_c_pointer_type(&ty), "expected pointer: {ty:?}");
415        }
416    }
417
418    #[test]
419    fn is_c_pointer_for_value_types_is_false() {
420        for ty in [
421            TypeRef::I32,
422            TypeRef::U32,
423            TypeRef::I64,
424            TypeRef::F64,
425            TypeRef::Bool,
426            TypeRef::Handle,
427            TypeRef::Enum("E".into()),
428        ] {
429            assert!(!is_c_pointer_type(&ty), "expected non-pointer: {ty:?}");
430        }
431    }
432
433    #[test]
434    fn is_c_pointer_does_not_recurse_into_optional() {
435        // Callers that care about Optional pointer-ness recurse first.
436        // We document and enforce that contract: bare Optional is not
437        // a pointer.
438        assert!(!is_c_pointer_type(&TypeRef::Optional(Box::new(
439            TypeRef::I32
440        ))));
441        assert!(!is_c_pointer_type(&TypeRef::Optional(Box::new(
442            TypeRef::StringUtf8
443        ))));
444    }
445
446    // --- pascal_case ---
447
448    #[test]
449    fn pascal_case_snake_segments() {
450        assert_eq!(pascal_case("first_name"), "FirstName");
451        assert_eq!(pascal_case("name"), "Name");
452        assert_eq!(pascal_case("is_active"), "IsActive");
453    }
454
455    #[test]
456    fn pascal_case_preserves_interior_casing() {
457        // Unlike heck, interior letters keep their case (acronym-safe).
458        assert_eq!(pascal_case("get_HTTP"), "GetHTTP");
459        assert_eq!(pascal_case("toJSON"), "ToJSON");
460    }
461
462    #[test]
463    fn pascal_case_empty_and_trailing_underscore() {
464        assert_eq!(pascal_case(""), "");
465        assert_eq!(pascal_case("a_"), "A");
466    }
467}
weaveffi_core/codegen/common.rs

weaveffi_core/codegen/
common.rs
