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), typed handles, lists, maps,
136/// and iterators all cross the ABI as pointers. Scalars (`i32`/`bool`/etc.),
137/// `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::TypedHandle(_)
151            | TypeRef::List(_)
152            | TypeRef::Map(_, _)
153            | TypeRef::Iterator(_)
154    )
155}
156
157/// Convert a `snake_case` identifier to `PascalCase` by uppercasing the
158/// first character of each `_`-separated segment and preserving the rest.
159///
160/// This deliberately splits on `_` only — it does **not** re-case interior
161/// letters the way `heck::ToUpperCamelCase` does — so an acronym-bearing
162/// name like `get_HTTP` becomes `GetHTTP`, not `GetHttp`. It is the single
163/// source of truth for the `snake_to_pascal` / `to_pascal_case` helpers
164/// that the Python, Android, and WASM generators each defined locally.
165pub fn pascal_case(s: &str) -> String {
166    s.split('_')
167        .map(|part| {
168            let mut chars = part.chars();
169            match chars.next() {
170                None => String::new(),
171                Some(first) => first.to_uppercase().chain(chars).collect::<String>(),
172            }
173        })
174        .collect()
175}
176
177#[cfg(test)]
178mod tests {
179    use super::*;
180    use weaveffi_ir::ir::Module;
181
182    fn leaf(name: &str) -> Module {
183        Module {
184            name: name.to_string(),
185            functions: vec![],
186            structs: vec![],
187            enums: vec![],
188            callbacks: vec![],
189            listeners: vec![],
190            errors: None,
191            modules: vec![],
192        }
193    }
194
195    fn with_children(name: &str, children: Vec<Module>) -> Module {
196        Module {
197            modules: children,
198            ..leaf(name)
199        }
200    }
201
202    // --- walk_modules ---
203
204    #[test]
205    fn walk_modules_visits_pre_order() {
206        let roots = vec![
207            with_children("a", vec![leaf("a1"), leaf("a2")]),
208            with_children("b", vec![leaf("b1")]),
209        ];
210        let names: Vec<&str> = walk_modules(&roots).map(|m| m.name.as_str()).collect();
211        assert_eq!(names, vec!["a", "a1", "a2", "b", "b1"]);
212    }
213
214    #[test]
215    fn walk_modules_descends_to_arbitrary_depth() {
216        let roots = vec![with_children(
217            "a",
218            vec![with_children(
219                "b",
220                vec![with_children("c", vec![leaf("d")])],
221            )],
222        )];
223        let names: Vec<&str> = walk_modules(&roots).map(|m| m.name.as_str()).collect();
224        assert_eq!(names, vec!["a", "b", "c", "d"]);
225    }
226
227    #[test]
228    fn walk_modules_empty_input_yields_nothing() {
229        let roots: Vec<Module> = vec![];
230        assert_eq!(walk_modules(&roots).count(), 0);
231    }
232
233    // --- walk_modules_with_path ---
234
235    #[test]
236    fn walk_modules_with_path_joins_with_underscore() {
237        let roots = vec![with_children(
238            "outer",
239            vec![with_children("inner", vec![leaf("leaf")])],
240        )];
241        let pairs: Vec<(String, String)> = walk_modules_with_path(&roots)
242            .map(|(m, p)| (m.name.clone(), p))
243            .collect();
244        assert_eq!(
245            pairs,
246            vec![
247                ("outer".into(), "outer".into()),
248                ("inner".into(), "outer_inner".into()),
249                ("leaf".into(), "outer_inner_leaf".into()),
250            ]
251        );
252    }
253
254    #[test]
255    fn walk_modules_with_path_independent_roots() {
256        let roots = vec![
257            with_children("a", vec![leaf("a1")]),
258            with_children("b", vec![leaf("b1")]),
259        ];
260        let paths: Vec<String> = walk_modules_with_path(&roots).map(|(_, p)| p).collect();
261        assert_eq!(paths, vec!["a", "a_a1", "b", "b_b1"]);
262    }
263
264    // --- emit_doc ---
265
266    #[test]
267    fn emit_doc_none_writes_nothing() {
268        let mut out = String::new();
269        emit_doc(&mut out, &None, "", DocCommentStyle::TripleSlash);
270        assert!(out.is_empty());
271    }
272
273    #[test]
274    fn emit_doc_empty_string_writes_nothing() {
275        let mut out = String::new();
276        emit_doc(
277            &mut out,
278            &Some("   \n  ".into()),
279            "",
280            DocCommentStyle::TripleSlash,
281        );
282        assert!(out.is_empty());
283    }
284
285    #[test]
286    fn emit_doc_triple_slash_single_line() {
287        let mut out = String::new();
288        emit_doc(
289            &mut out,
290            &Some("Hello, world.".into()),
291            "  ",
292            DocCommentStyle::TripleSlash,
293        );
294        assert_eq!(out, "  /// Hello, world.\n");
295    }
296
297    #[test]
298    fn emit_doc_triple_slash_multi_line_with_blank() {
299        let mut out = String::new();
300        emit_doc(
301            &mut out,
302            &Some("First line.\n\nThird line.".into()),
303            "",
304            DocCommentStyle::TripleSlash,
305        );
306        assert_eq!(out, "/// First line.\n///\n/// Third line.\n");
307    }
308
309    #[test]
310    fn emit_doc_hash_single_line() {
311        let mut out = String::new();
312        emit_doc(
313            &mut out,
314            &Some("ruby/python style".into()),
315            "",
316            DocCommentStyle::Hash,
317        );
318        assert_eq!(out, "# ruby/python style\n");
319    }
320
321    #[test]
322    fn emit_doc_double_slash_single_line() {
323        let mut out = String::new();
324        emit_doc(
325            &mut out,
326            &Some("Go-style line comment.".into()),
327            "",
328            DocCommentStyle::DoubleSlash,
329        );
330        assert_eq!(out, "// Go-style line comment.\n");
331    }
332
333    #[test]
334    fn emit_doc_double_slash_multi_line() {
335        let mut out = String::new();
336        emit_doc(
337            &mut out,
338            &Some("first\n\nsecond".into()),
339            "\t",
340            DocCommentStyle::DoubleSlash,
341        );
342        assert_eq!(out, "\t// first\n\t//\n\t// second\n");
343    }
344
345    #[test]
346    fn emit_doc_hash_multi_line() {
347        let mut out = String::new();
348        emit_doc(
349            &mut out,
350            &Some("one\n\ntwo".into()),
351            "    ",
352            DocCommentStyle::Hash,
353        );
354        assert_eq!(out, "    # one\n    #\n    # two\n");
355    }
356
357    #[test]
358    fn emit_doc_javadoc_single_line_collapses() {
359        let mut out = String::new();
360        emit_doc(
361            &mut out,
362            &Some("short".into()),
363            "",
364            DocCommentStyle::Javadoc,
365        );
366        assert_eq!(out, "/** short */\n");
367    }
368
369    #[test]
370    fn emit_doc_javadoc_multi_line_expands() {
371        let mut out = String::new();
372        emit_doc(
373            &mut out,
374            &Some("line one\n\nline three".into()),
375            "  ",
376            DocCommentStyle::Javadoc,
377        );
378        assert_eq!(out, "  /**\n   * line one\n   *\n   * line three\n   */\n");
379    }
380
381    #[test]
382    fn emit_doc_trims_outer_whitespace_before_decisions() {
383        // A doc that's "single line" after trimming should still
384        // collapse to `/** text */` even if it had surrounding blank
385        // lines in the IR — the existing per-generator behaviour we
386        // are replacing did the same.
387        let mut out = String::new();
388        emit_doc(
389            &mut out,
390            &Some("\n\nhello\n\n".into()),
391            "",
392            DocCommentStyle::Javadoc,
393        );
394        assert_eq!(out, "/** hello */\n");
395    }
396
397    // --- is_c_pointer_type ---
398
399    #[test]
400    fn is_c_pointer_for_pointer_carrying_types() {
401        for ty in [
402            TypeRef::StringUtf8,
403            TypeRef::BorrowedStr,
404            TypeRef::Bytes,
405            TypeRef::BorrowedBytes,
406            TypeRef::Struct("X".into()),
407            TypeRef::TypedHandle("X".into()),
408            TypeRef::List(Box::new(TypeRef::I32)),
409            TypeRef::Map(Box::new(TypeRef::StringUtf8), Box::new(TypeRef::I32)),
410            TypeRef::Iterator(Box::new(TypeRef::StringUtf8)),
411        ] {
412            assert!(is_c_pointer_type(&ty), "expected pointer: {ty:?}");
413        }
414    }
415
416    #[test]
417    fn is_c_pointer_for_value_types_is_false() {
418        for ty in [
419            TypeRef::I32,
420            TypeRef::U32,
421            TypeRef::I64,
422            TypeRef::F64,
423            TypeRef::Bool,
424            TypeRef::Handle,
425            TypeRef::Enum("E".into()),
426        ] {
427            assert!(!is_c_pointer_type(&ty), "expected non-pointer: {ty:?}");
428        }
429    }
430
431    #[test]
432    fn is_c_pointer_does_not_recurse_into_optional() {
433        // Callers that care about Optional pointer-ness recurse first.
434        // We document and enforce that contract: bare Optional is not
435        // a pointer.
436        assert!(!is_c_pointer_type(&TypeRef::Optional(Box::new(
437            TypeRef::I32
438        ))));
439        assert!(!is_c_pointer_type(&TypeRef::Optional(Box::new(
440            TypeRef::StringUtf8
441        ))));
442    }
443
444    // --- pascal_case ---
445
446    #[test]
447    fn pascal_case_snake_segments() {
448        assert_eq!(pascal_case("first_name"), "FirstName");
449        assert_eq!(pascal_case("name"), "Name");
450        assert_eq!(pascal_case("is_active"), "IsActive");
451    }
452
453    #[test]
454    fn pascal_case_preserves_interior_casing() {
455        // Unlike heck, interior letters keep their case (acronym-safe).
456        assert_eq!(pascal_case("get_HTTP"), "GetHTTP");
457        assert_eq!(pascal_case("toJSON"), "ToJSON");
458    }
459
460    #[test]
461    fn pascal_case_empty_and_trailing_underscore() {
462        assert_eq!(pascal_case(""), "");
463        assert_eq!(pascal_case("a_"), "A");
464    }
465}
weaveffi_core/codegen/common.rs

weaveffi_core/codegen/
common.rs
