alef_backend_csharp/
gen_visitor.rs

1/// Generate C# visitor support: IVisitor interface, NodeContext/VisitResult records,
2/// VisitorCallbacks (P/Invoke delegate struct), and ConvertWithVisitor method.
3///
4/// # P/Invoke delegate callback strategy
5///
6/// C# uses `[UnmanagedFunctionPointer]` delegate types to create `IntPtr` function pointers
7/// that can be passed through the `HTMHtmVisitorCallbacks` C struct.
8///
9/// - `NodeContext`: a `record` with fields from `HTMHtmNodeContext`.
10/// - `VisitResult`: a discriminated union using a record class hierarchy.
11/// - `IVisitor`: an interface with default no-op implementations for all 40 callbacks.
12/// - `VisitorCallbacks`: an internal class that allocates `GCHandle`s for all delegate
13///   instances and writes them into a marshalled struct layout matching the C struct.
14/// - `ConvertWithVisitor`: static method on the wrapper class that creates the delegate
15///   struct, calls `htm_visitor_create`, `htm_convert_with_visitor`, deserialises JSON.
16use alef_core::hash::{self, CommentStyle};
17use std::fmt::Write;
18
19// ---------------------------------------------------------------------------
20// Callback specification table
21// ---------------------------------------------------------------------------
22
23pub struct CallbackSpec {
24    /// Field name in `HTMHtmVisitorCallbacks`.
25    pub c_field: &'static str,
26    /// C# interface method name (PascalCase).
27    pub cs_method: &'static str,
28    /// XML doc summary.
29    pub doc: &'static str,
30    /// Extra parameters beyond `NodeContext` in the C# interface.
31    pub extra: &'static [ExtraParam],
32    /// If true, add `bool isHeader` (only visit_table_row).
33    pub has_is_header: bool,
34}
35
36pub struct ExtraParam {
37    /// C# parameter name in the interface.
38    pub cs_name: &'static str,
39    /// C# type in the interface method signature.
40    pub cs_type: &'static str,
41    /// P/Invoke types for each raw C parameter (one or more per Java param).
42    pub pinvoke_types: &'static [&'static str],
43    /// C# expression to decode the raw P/Invoke args (vars named `raw<CsName>N`).
44    pub decode: &'static str,
45}
46
47pub const CALLBACKS: &[CallbackSpec] = &[
48    CallbackSpec {
49        c_field: "visit_text",
50        cs_method: "VisitText",
51        doc: "Called for text nodes.",
52        extra: &[ExtraParam {
53            cs_name: "text",
54            cs_type: "string",
55            pinvoke_types: &["IntPtr"],
56            decode: "Marshal.PtrToStringAnsi(rawText0)!",
57        }],
58        has_is_header: false,
59    },
60    CallbackSpec {
61        c_field: "visit_element_start",
62        cs_method: "VisitElementStart",
63        doc: "Called before entering any element.",
64        extra: &[],
65        has_is_header: false,
66    },
67    CallbackSpec {
68        c_field: "visit_element_end",
69        cs_method: "VisitElementEnd",
70        doc: "Called after exiting any element; receives the default markdown output.",
71        extra: &[ExtraParam {
72            cs_name: "output",
73            cs_type: "string",
74            pinvoke_types: &["IntPtr"],
75            decode: "Marshal.PtrToStringAnsi(rawOutput0)!",
76        }],
77        has_is_header: false,
78    },
79    CallbackSpec {
80        c_field: "visit_link",
81        cs_method: "VisitLink",
82        doc: "Called for anchor links. title is null when the attribute is absent.",
83        extra: &[
84            ExtraParam {
85                cs_name: "href",
86                cs_type: "string",
87                pinvoke_types: &["IntPtr"],
88                decode: "Marshal.PtrToStringAnsi(rawHref0)!",
89            },
90            ExtraParam {
91                cs_name: "text",
92                cs_type: "string",
93                pinvoke_types: &["IntPtr"],
94                decode: "Marshal.PtrToStringAnsi(rawText0)!",
95            },
96            ExtraParam {
97                cs_name: "title",
98                cs_type: "string?",
99                pinvoke_types: &["IntPtr"],
100                decode: "rawTitle0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawTitle0)",
101            },
102        ],
103        has_is_header: false,
104    },
105    CallbackSpec {
106        c_field: "visit_image",
107        cs_method: "VisitImage",
108        doc: "Called for images. title is null when absent.",
109        extra: &[
110            ExtraParam {
111                cs_name: "src",
112                cs_type: "string",
113                pinvoke_types: &["IntPtr"],
114                decode: "Marshal.PtrToStringAnsi(rawSrc0)!",
115            },
116            ExtraParam {
117                cs_name: "alt",
118                cs_type: "string",
119                pinvoke_types: &["IntPtr"],
120                decode: "Marshal.PtrToStringAnsi(rawAlt0)!",
121            },
122            ExtraParam {
123                cs_name: "title",
124                cs_type: "string?",
125                pinvoke_types: &["IntPtr"],
126                decode: "rawTitle0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawTitle0)",
127            },
128        ],
129        has_is_header: false,
130    },
131    CallbackSpec {
132        c_field: "visit_heading",
133        cs_method: "VisitHeading",
134        doc: "Called for heading elements h1-h6. id is null when absent.",
135        extra: &[
136            ExtraParam {
137                cs_name: "level",
138                cs_type: "uint",
139                pinvoke_types: &["uint"],
140                decode: "rawLevel0",
141            },
142            ExtraParam {
143                cs_name: "text",
144                cs_type: "string",
145                pinvoke_types: &["IntPtr"],
146                decode: "Marshal.PtrToStringAnsi(rawText0)!",
147            },
148            ExtraParam {
149                cs_name: "id",
150                cs_type: "string?",
151                pinvoke_types: &["IntPtr"],
152                decode: "rawId0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawId0)",
153            },
154        ],
155        has_is_header: false,
156    },
157    CallbackSpec {
158        c_field: "visit_code_block",
159        cs_method: "VisitCodeBlock",
160        doc: "Called for code blocks. lang is null when absent.",
161        extra: &[
162            ExtraParam {
163                cs_name: "lang",
164                cs_type: "string?",
165                pinvoke_types: &["IntPtr"],
166                decode: "rawLang0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawLang0)",
167            },
168            ExtraParam {
169                cs_name: "code",
170                cs_type: "string",
171                pinvoke_types: &["IntPtr"],
172                decode: "Marshal.PtrToStringAnsi(rawCode0)!",
173            },
174        ],
175        has_is_header: false,
176    },
177    CallbackSpec {
178        c_field: "visit_code_inline",
179        cs_method: "VisitCodeInline",
180        doc: "Called for inline code elements.",
181        extra: &[ExtraParam {
182            cs_name: "code",
183            cs_type: "string",
184            pinvoke_types: &["IntPtr"],
185            decode: "Marshal.PtrToStringAnsi(rawCode0)!",
186        }],
187        has_is_header: false,
188    },
189    CallbackSpec {
190        c_field: "visit_list_item",
191        cs_method: "VisitListItem",
192        doc: "Called for list items.",
193        extra: &[
194            ExtraParam {
195                cs_name: "ordered",
196                cs_type: "bool",
197                pinvoke_types: &["int"],
198                decode: "rawOrdered0 != 0",
199            },
200            ExtraParam {
201                cs_name: "marker",
202                cs_type: "string",
203                pinvoke_types: &["IntPtr"],
204                decode: "Marshal.PtrToStringAnsi(rawMarker0)!",
205            },
206            ExtraParam {
207                cs_name: "text",
208                cs_type: "string",
209                pinvoke_types: &["IntPtr"],
210                decode: "Marshal.PtrToStringAnsi(rawText0)!",
211            },
212        ],
213        has_is_header: false,
214    },
215    CallbackSpec {
216        c_field: "visit_list_start",
217        cs_method: "VisitListStart",
218        doc: "Called before processing a list.",
219        extra: &[ExtraParam {
220            cs_name: "ordered",
221            cs_type: "bool",
222            pinvoke_types: &["int"],
223            decode: "rawOrdered0 != 0",
224        }],
225        has_is_header: false,
226    },
227    CallbackSpec {
228        c_field: "visit_list_end",
229        cs_method: "VisitListEnd",
230        doc: "Called after processing a list.",
231        extra: &[
232            ExtraParam {
233                cs_name: "ordered",
234                cs_type: "bool",
235                pinvoke_types: &["int"],
236                decode: "rawOrdered0 != 0",
237            },
238            ExtraParam {
239                cs_name: "output",
240                cs_type: "string",
241                pinvoke_types: &["IntPtr"],
242                decode: "Marshal.PtrToStringAnsi(rawOutput0)!",
243            },
244        ],
245        has_is_header: false,
246    },
247    CallbackSpec {
248        c_field: "visit_table_start",
249        cs_method: "VisitTableStart",
250        doc: "Called before processing a table.",
251        extra: &[],
252        has_is_header: false,
253    },
254    CallbackSpec {
255        c_field: "visit_table_row",
256        cs_method: "VisitTableRow",
257        doc: "Called for table rows. cells contains the cell text values.",
258        extra: &[ExtraParam {
259            cs_name: "cells",
260            cs_type: "string[]",
261            pinvoke_types: &["IntPtr", "UIntPtr"],
262            decode: "DecodeCells(rawCells0, (long)(ulong)rawCells1)",
263        }],
264        has_is_header: true,
265    },
266    CallbackSpec {
267        c_field: "visit_table_end",
268        cs_method: "VisitTableEnd",
269        doc: "Called after processing a table.",
270        extra: &[ExtraParam {
271            cs_name: "output",
272            cs_type: "string",
273            pinvoke_types: &["IntPtr"],
274            decode: "Marshal.PtrToStringAnsi(rawOutput0)!",
275        }],
276        has_is_header: false,
277    },
278    CallbackSpec {
279        c_field: "visit_blockquote",
280        cs_method: "VisitBlockquote",
281        doc: "Called for blockquote elements.",
282        extra: &[
283            ExtraParam {
284                cs_name: "content",
285                cs_type: "string",
286                pinvoke_types: &["IntPtr"],
287                decode: "Marshal.PtrToStringAnsi(rawContent0)!",
288            },
289            ExtraParam {
290                cs_name: "depth",
291                cs_type: "ulong",
292                pinvoke_types: &["UIntPtr"],
293                decode: "(ulong)rawDepth0",
294            },
295        ],
296        has_is_header: false,
297    },
298    CallbackSpec {
299        c_field: "visit_strong",
300        cs_method: "VisitStrong",
301        doc: "Called for strong/bold elements.",
302        extra: &[ExtraParam {
303            cs_name: "text",
304            cs_type: "string",
305            pinvoke_types: &["IntPtr"],
306            decode: "Marshal.PtrToStringAnsi(rawText0)!",
307        }],
308        has_is_header: false,
309    },
310    CallbackSpec {
311        c_field: "visit_emphasis",
312        cs_method: "VisitEmphasis",
313        doc: "Called for emphasis/italic elements.",
314        extra: &[ExtraParam {
315            cs_name: "text",
316            cs_type: "string",
317            pinvoke_types: &["IntPtr"],
318            decode: "Marshal.PtrToStringAnsi(rawText0)!",
319        }],
320        has_is_header: false,
321    },
322    CallbackSpec {
323        c_field: "visit_strikethrough",
324        cs_method: "VisitStrikethrough",
325        doc: "Called for strikethrough elements.",
326        extra: &[ExtraParam {
327            cs_name: "text",
328            cs_type: "string",
329            pinvoke_types: &["IntPtr"],
330            decode: "Marshal.PtrToStringAnsi(rawText0)!",
331        }],
332        has_is_header: false,
333    },
334    CallbackSpec {
335        c_field: "visit_underline",
336        cs_method: "VisitUnderline",
337        doc: "Called for underline elements.",
338        extra: &[ExtraParam {
339            cs_name: "text",
340            cs_type: "string",
341            pinvoke_types: &["IntPtr"],
342            decode: "Marshal.PtrToStringAnsi(rawText0)!",
343        }],
344        has_is_header: false,
345    },
346    CallbackSpec {
347        c_field: "visit_subscript",
348        cs_method: "VisitSubscript",
349        doc: "Called for subscript elements.",
350        extra: &[ExtraParam {
351            cs_name: "text",
352            cs_type: "string",
353            pinvoke_types: &["IntPtr"],
354            decode: "Marshal.PtrToStringAnsi(rawText0)!",
355        }],
356        has_is_header: false,
357    },
358    CallbackSpec {
359        c_field: "visit_superscript",
360        cs_method: "VisitSuperscript",
361        doc: "Called for superscript elements.",
362        extra: &[ExtraParam {
363            cs_name: "text",
364            cs_type: "string",
365            pinvoke_types: &["IntPtr"],
366            decode: "Marshal.PtrToStringAnsi(rawText0)!",
367        }],
368        has_is_header: false,
369    },
370    CallbackSpec {
371        c_field: "visit_mark",
372        cs_method: "VisitMark",
373        doc: "Called for mark/highlight elements.",
374        extra: &[ExtraParam {
375            cs_name: "text",
376            cs_type: "string",
377            pinvoke_types: &["IntPtr"],
378            decode: "Marshal.PtrToStringAnsi(rawText0)!",
379        }],
380        has_is_header: false,
381    },
382    CallbackSpec {
383        c_field: "visit_line_break",
384        cs_method: "VisitLineBreak",
385        doc: "Called for line break elements.",
386        extra: &[],
387        has_is_header: false,
388    },
389    CallbackSpec {
390        c_field: "visit_horizontal_rule",
391        cs_method: "VisitHorizontalRule",
392        doc: "Called for horizontal rule elements.",
393        extra: &[],
394        has_is_header: false,
395    },
396    CallbackSpec {
397        c_field: "visit_custom_element",
398        cs_method: "VisitCustomElement",
399        doc: "Called for custom or unknown elements.",
400        extra: &[
401            ExtraParam {
402                cs_name: "tagName",
403                cs_type: "string",
404                pinvoke_types: &["IntPtr"],
405                decode: "Marshal.PtrToStringAnsi(rawTagName0)!",
406            },
407            ExtraParam {
408                cs_name: "html",
409                cs_type: "string",
410                pinvoke_types: &["IntPtr"],
411                decode: "Marshal.PtrToStringAnsi(rawHtml0)!",
412            },
413        ],
414        has_is_header: false,
415    },
416    CallbackSpec {
417        c_field: "visit_definition_list_start",
418        cs_method: "VisitDefinitionListStart",
419        doc: "Called before a definition list.",
420        extra: &[],
421        has_is_header: false,
422    },
423    CallbackSpec {
424        c_field: "visit_definition_term",
425        cs_method: "VisitDefinitionTerm",
426        doc: "Called for definition term elements.",
427        extra: &[ExtraParam {
428            cs_name: "text",
429            cs_type: "string",
430            pinvoke_types: &["IntPtr"],
431            decode: "Marshal.PtrToStringAnsi(rawText0)!",
432        }],
433        has_is_header: false,
434    },
435    CallbackSpec {
436        c_field: "visit_definition_description",
437        cs_method: "VisitDefinitionDescription",
438        doc: "Called for definition description elements.",
439        extra: &[ExtraParam {
440            cs_name: "text",
441            cs_type: "string",
442            pinvoke_types: &["IntPtr"],
443            decode: "Marshal.PtrToStringAnsi(rawText0)!",
444        }],
445        has_is_header: false,
446    },
447    CallbackSpec {
448        c_field: "visit_definition_list_end",
449        cs_method: "VisitDefinitionListEnd",
450        doc: "Called after a definition list.",
451        extra: &[ExtraParam {
452            cs_name: "output",
453            cs_type: "string",
454            pinvoke_types: &["IntPtr"],
455            decode: "Marshal.PtrToStringAnsi(rawOutput0)!",
456        }],
457        has_is_header: false,
458    },
459    CallbackSpec {
460        c_field: "visit_form",
461        cs_method: "VisitForm",
462        doc: "Called for form elements. action and method may be null.",
463        extra: &[
464            ExtraParam {
465                cs_name: "action",
466                cs_type: "string?",
467                pinvoke_types: &["IntPtr"],
468                decode: "rawAction0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawAction0)",
469            },
470            ExtraParam {
471                cs_name: "method",
472                cs_type: "string?",
473                pinvoke_types: &["IntPtr"],
474                decode: "rawMethod0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawMethod0)",
475            },
476        ],
477        has_is_header: false,
478    },
479    CallbackSpec {
480        c_field: "visit_input",
481        cs_method: "VisitInput",
482        doc: "Called for input elements. name and value may be null.",
483        extra: &[
484            ExtraParam {
485                cs_name: "inputType",
486                cs_type: "string",
487                pinvoke_types: &["IntPtr"],
488                decode: "Marshal.PtrToStringAnsi(rawInputType0)!",
489            },
490            ExtraParam {
491                cs_name: "name",
492                cs_type: "string?",
493                pinvoke_types: &["IntPtr"],
494                decode: "rawName0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawName0)",
495            },
496            ExtraParam {
497                cs_name: "value",
498                cs_type: "string?",
499                pinvoke_types: &["IntPtr"],
500                decode: "rawValue0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawValue0)",
501            },
502        ],
503        has_is_header: false,
504    },
505    CallbackSpec {
506        c_field: "visit_button",
507        cs_method: "VisitButton",
508        doc: "Called for button elements.",
509        extra: &[ExtraParam {
510            cs_name: "text",
511            cs_type: "string",
512            pinvoke_types: &["IntPtr"],
513            decode: "Marshal.PtrToStringAnsi(rawText0)!",
514        }],
515        has_is_header: false,
516    },
517    CallbackSpec {
518        c_field: "visit_audio",
519        cs_method: "VisitAudio",
520        doc: "Called for audio elements. src may be null.",
521        extra: &[ExtraParam {
522            cs_name: "src",
523            cs_type: "string?",
524            pinvoke_types: &["IntPtr"],
525            decode: "rawSrc0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawSrc0)",
526        }],
527        has_is_header: false,
528    },
529    CallbackSpec {
530        c_field: "visit_video",
531        cs_method: "VisitVideo",
532        doc: "Called for video elements. src may be null.",
533        extra: &[ExtraParam {
534            cs_name: "src",
535            cs_type: "string?",
536            pinvoke_types: &["IntPtr"],
537            decode: "rawSrc0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawSrc0)",
538        }],
539        has_is_header: false,
540    },
541    CallbackSpec {
542        c_field: "visit_iframe",
543        cs_method: "VisitIframe",
544        doc: "Called for iframe elements. src may be null.",
545        extra: &[ExtraParam {
546            cs_name: "src",
547            cs_type: "string?",
548            pinvoke_types: &["IntPtr"],
549            decode: "rawSrc0 == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(rawSrc0)",
550        }],
551        has_is_header: false,
552    },
553    CallbackSpec {
554        c_field: "visit_details",
555        cs_method: "VisitDetails",
556        doc: "Called for details elements.",
557        extra: &[ExtraParam {
558            cs_name: "open",
559            cs_type: "bool",
560            pinvoke_types: &["int"],
561            decode: "rawOpen0 != 0",
562        }],
563        has_is_header: false,
564    },
565    CallbackSpec {
566        c_field: "visit_summary",
567        cs_method: "VisitSummary",
568        doc: "Called for summary elements.",
569        extra: &[ExtraParam {
570            cs_name: "text",
571            cs_type: "string",
572            pinvoke_types: &["IntPtr"],
573            decode: "Marshal.PtrToStringAnsi(rawText0)!",
574        }],
575        has_is_header: false,
576    },
577    CallbackSpec {
578        c_field: "visit_figure_start",
579        cs_method: "VisitFigureStart",
580        doc: "Called before a figure element.",
581        extra: &[],
582        has_is_header: false,
583    },
584    CallbackSpec {
585        c_field: "visit_figcaption",
586        cs_method: "VisitFigcaption",
587        doc: "Called for figcaption elements.",
588        extra: &[ExtraParam {
589            cs_name: "text",
590            cs_type: "string",
591            pinvoke_types: &["IntPtr"],
592            decode: "Marshal.PtrToStringAnsi(rawText0)!",
593        }],
594        has_is_header: false,
595    },
596    CallbackSpec {
597        c_field: "visit_figure_end",
598        cs_method: "VisitFigureEnd",
599        doc: "Called after a figure element.",
600        extra: &[ExtraParam {
601            cs_name: "output",
602            cs_type: "string",
603            pinvoke_types: &["IntPtr"],
604            decode: "Marshal.PtrToStringAnsi(rawOutput0)!",
605        }],
606        has_is_header: false,
607    },
608];
609
610// ---------------------------------------------------------------------------
611// Public API
612// ---------------------------------------------------------------------------
613
614/// Returns `(filename, content)` pairs for all visitor-related C# files.
615pub fn gen_visitor_files(namespace: &str) -> Vec<(String, String)> {
616    vec![
617        ("NodeContext.cs".to_string(), gen_node_context(namespace)),
618        ("VisitResult.cs".to_string(), gen_visit_result(namespace)),
619        ("IVisitor.cs".to_string(), gen_ivisitor(namespace)),
620        ("VisitorCallbacks.cs".to_string(), gen_visitor_callbacks(namespace)),
621    ]
622}
623
624/// Generate the P/Invoke declarations needed in NativeMethods.cs for visitor FFI.
625pub fn gen_native_methods_visitor(namespace: &str, lib_name: &str, prefix: &str) -> String {
626    let mut out = String::with_capacity(512);
627    writeln!(out).ok();
628    writeln!(out, "    // Visitor FFI").ok();
629    writeln!(
630        out,
631        "    [DllImport(LibName, CallingConvention = CallingConvention.Cdecl, EntryPoint = \"{prefix}_visitor_create\")]"
632    )
633    .ok();
634    writeln!(
635        out,
636        "    internal static extern IntPtr VisitorCreate(IntPtr callbacks);"
637    )
638    .ok();
639    writeln!(out).ok();
640    writeln!(
641        out,
642        "    [DllImport(LibName, CallingConvention = CallingConvention.Cdecl, EntryPoint = \"{prefix}_visitor_free\")]"
643    )
644    .ok();
645    writeln!(out, "    internal static extern void VisitorFree(IntPtr visitor);").ok();
646    writeln!(out).ok();
647    writeln!(
648        out,
649        "    [DllImport(LibName, CallingConvention = CallingConvention.Cdecl, EntryPoint = \"{prefix}_convert_with_visitor\")]"
650    )
651    .ok();
652    writeln!(
653        out,
654        "    internal static extern IntPtr ConvertWithVisitor([MarshalAs(UnmanagedType.LPStr)] string html, IntPtr options, IntPtr visitor);"
655    )
656    .ok();
657    let _ = namespace;
658    let _ = lib_name;
659    out
660}
661
662/// Generate the `ConvertWithVisitor` method to inject into the wrapper class.
663pub fn gen_convert_with_visitor_method(exception_name: &str, prefix: &str) -> String {
664    let mut out = String::with_capacity(2048);
665    writeln!(out, "    /// <summary>").ok();
666    writeln!(
667        out,
668        "    /// Convert HTML to Markdown, invoking visitor callbacks during processing."
669    )
670    .ok();
671    writeln!(out, "    /// </summary>").ok();
672    writeln!(
673        out,
674        "    public static ConversionResult? ConvertWithVisitor(string html, ConversionOptions? options, IVisitor visitor)"
675    )
676    .ok();
677    writeln!(out, "    {{").ok();
678    writeln!(out, "        ArgumentNullException.ThrowIfNull(html);").ok();
679    writeln!(out, "        ArgumentNullException.ThrowIfNull(visitor);").ok();
680    writeln!(out).ok();
681    writeln!(out, "        using var callbacks = new VisitorCallbacks(visitor);").ok();
682    writeln!(out).ok();
683    writeln!(out, "        var optionsHandle = IntPtr.Zero;").ok();
684    writeln!(out, "        if (options != null)").ok();
685    writeln!(out, "        {{").ok();
686    writeln!(
687        out,
688        "            var optionsJson = JsonSerializer.Serialize(options, JsonOptions);"
689    )
690    .ok();
691    writeln!(
692        out,
693        "            optionsHandle = NativeMethods.ConversionOptionsFromJson(optionsJson);"
694    )
695    .ok();
696    writeln!(out, "        }}").ok();
697    writeln!(out).ok();
698    writeln!(
699        out,
700        "        var visitorHandle = NativeMethods.VisitorCreate(callbacks.NativePtr);"
701    )
702    .ok();
703    writeln!(out, "        if (visitorHandle == IntPtr.Zero)").ok();
704    writeln!(out, "        {{").ok();
705    writeln!(
706        out,
707        "            if (optionsHandle != IntPtr.Zero) NativeMethods.ConversionOptionsFree(optionsHandle);"
708    )
709    .ok();
710    writeln!(out, "            throw GetLastError();").ok();
711    writeln!(out, "        }}").ok();
712    writeln!(out).ok();
713    writeln!(out, "        try").ok();
714    writeln!(out, "        {{").ok();
715    writeln!(
716        out,
717        "            var resultPtr = NativeMethods.ConvertWithVisitor(html, optionsHandle, visitorHandle);"
718    )
719    .ok();
720    writeln!(
721        out,
722        "            if (optionsHandle != IntPtr.Zero) NativeMethods.ConversionOptionsFree(optionsHandle);"
723    )
724    .ok();
725    writeln!(out, "            if (resultPtr == IntPtr.Zero)").ok();
726    writeln!(out, "            {{").ok();
727    writeln!(out, "                var err = GetLastError();").ok();
728    writeln!(out, "                if (err.Code != 0) throw err;").ok();
729    writeln!(out, "                return null;").ok();
730    writeln!(out, "            }}").ok();
731    writeln!(out, "            var json = Marshal.PtrToStringAnsi(resultPtr);").ok();
732    writeln!(out, "            NativeMethods.FreeString(resultPtr);").ok();
733    writeln!(
734        out,
735        "            return JsonSerializer.Deserialize<ConversionResult>(json!, JsonOptions);"
736    )
737    .ok();
738    writeln!(out, "        }}").ok();
739    writeln!(out, "        finally").ok();
740    writeln!(out, "        {{").ok();
741    writeln!(out, "            NativeMethods.VisitorFree(visitorHandle);").ok();
742    writeln!(out, "        }}").ok();
743    writeln!(out, "    }}").ok();
744    let _ = exception_name;
745    let _ = prefix;
746    out
747}
748
749// ---------------------------------------------------------------------------
750// Individual file generators
751// ---------------------------------------------------------------------------
752
753fn gen_node_context(namespace: &str) -> String {
754    let mut out = String::with_capacity(1024);
755    out.push_str(&hash::header(CommentStyle::DoubleSlash));
756    writeln!(out, "using System;").ok();
757    writeln!(out).ok();
758    writeln!(out, "namespace {namespace};").ok();
759    writeln!(out).ok();
760    writeln!(out, "/// <summary>Context passed to every visitor callback.</summary>").ok();
761    writeln!(out, "public record NodeContext(").ok();
762    writeln!(out, "    /// <summary>Coarse-grained node type tag.</summary>").ok();
763    writeln!(out, "    int NodeType,").ok();
764    writeln!(out, "    /// <summary>HTML element tag name (e.g. \"div\").</summary>").ok();
765    writeln!(out, "    string TagName,").ok();
766    writeln!(out, "    /// <summary>DOM depth (0 = root).</summary>").ok();
767    writeln!(out, "    ulong Depth,").ok();
768    writeln!(out, "    /// <summary>0-based sibling index.</summary>").ok();
769    writeln!(out, "    ulong IndexInParent,").ok();
770    writeln!(
771        out,
772        "    /// <summary>Parent element tag name, or null at the root.</summary>"
773    )
774    .ok();
775    writeln!(out, "    string? ParentTag,").ok();
776    writeln!(
777        out,
778        "    /// <summary>True when this element is treated as inline.</summary>"
779    )
780    .ok();
781    writeln!(out, "    bool IsInline").ok();
782    writeln!(out, ");").ok();
783    out
784}
785
786fn gen_visit_result(namespace: &str) -> String {
787    let mut out = String::with_capacity(2048);
788    out.push_str(&hash::header(CommentStyle::DoubleSlash));
789    writeln!(out, "using System;").ok();
790    writeln!(out).ok();
791    writeln!(out, "namespace {namespace};").ok();
792    writeln!(out).ok();
793    writeln!(
794        out,
795        "/// <summary>Controls how the visitor affects the conversion pipeline.</summary>"
796    )
797    .ok();
798    writeln!(out, "public abstract record VisitResult").ok();
799    writeln!(out, "{{").ok();
800    writeln!(out, "    private VisitResult() {{}}").ok();
801    writeln!(out).ok();
802    writeln!(out, "    /// <summary>Proceed with default conversion.</summary>").ok();
803    writeln!(out, "    public sealed record Continue : VisitResult;").ok();
804    writeln!(out).ok();
805    writeln!(
806        out,
807        "    /// <summary>Omit this element from output entirely.</summary>"
808    )
809    .ok();
810    writeln!(out, "    public sealed record Skip : VisitResult;").ok();
811    writeln!(out).ok();
812    writeln!(out, "    /// <summary>Keep original HTML verbatim.</summary>").ok();
813    writeln!(out, "    public sealed record PreserveHtml : VisitResult;").ok();
814    writeln!(out).ok();
815    writeln!(out, "    /// <summary>Replace with custom Markdown.</summary>").ok();
816    writeln!(out, "    public sealed record Custom(string Markdown) : VisitResult;").ok();
817    writeln!(out).ok();
818    writeln!(
819        out,
820        "    /// <summary>Abort conversion with an error message.</summary>"
821    )
822    .ok();
823    writeln!(out, "    public sealed record Error(string Message) : VisitResult;").ok();
824    writeln!(out, "}}").ok();
825    out
826}
827
828fn gen_ivisitor(namespace: &str) -> String {
829    let mut out = String::with_capacity(4096);
830    out.push_str(&hash::header(CommentStyle::DoubleSlash));
831    writeln!(out, "using System;").ok();
832    writeln!(out).ok();
833    writeln!(out, "namespace {namespace};").ok();
834    writeln!(out).ok();
835    writeln!(
836        out,
837        "/// <summary>Visitor interface for the HTML-to-Markdown conversion pipeline.</summary>"
838    )
839    .ok();
840    writeln!(out, "public interface IVisitor").ok();
841    writeln!(out, "{{").ok();
842    for spec in CALLBACKS {
843        let params = iface_param_str(spec);
844        writeln!(out, "    /// <summary>{}</summary>", spec.doc).ok();
845        writeln!(
846            out,
847            "    VisitResult {}({}) => new VisitResult.Continue();",
848            spec.cs_method, params
849        )
850        .ok();
851    }
852    writeln!(out, "}}").ok();
853    out
854}
855
856/// Generate `VisitorCallbacks.cs` which holds `GCHandle`s for all 40 delegates and
857/// writes them into a `Marshal.AllocHGlobal` block matching the C struct layout.
858fn gen_visitor_callbacks(namespace: &str) -> String {
859    let mut out = String::with_capacity(32_768);
860    out.push_str(&hash::header(CommentStyle::DoubleSlash));
861    writeln!(out, "using System;").ok();
862    writeln!(out, "using System.Runtime.InteropServices;").ok();
863    writeln!(out).ok();
864    writeln!(out, "namespace {namespace};").ok();
865    writeln!(out).ok();
866    writeln!(out, "/// <summary>").ok();
867    writeln!(out, "/// Allocates P/Invoke delegates for a IVisitor and assembles").ok();
868    writeln!(out, "/// the C HTMHtmVisitorCallbacks struct in unmanaged memory.").ok();
869    writeln!(out, "/// </summary>").ok();
870    writeln!(out, "internal sealed class VisitorCallbacks : IDisposable").ok();
871    writeln!(out, "{{").ok();
872    writeln!(out, "    private readonly IVisitor _visitor;").ok();
873    writeln!(
874        out,
875        "    private readonly IntPtr _nativeStruct; // HTMHtmVisitorCallbacks"
876    )
877    .ok();
878    writeln!(out, "    private bool _disposed;").ok();
879    writeln!(out).ok();
880
881    // Declare delegate types and delegate fields
882    for spec in CALLBACKS {
883        let delegate_type = delegate_type_name(spec.cs_method);
884        let pinvoke_params = delegate_pinvoke_params(spec);
885        writeln!(out, "    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]").ok();
886        writeln!(
887            out,
888            "    private delegate int {}Delegate({});",
889            delegate_type, pinvoke_params
890        )
891        .ok();
892        writeln!(
893            out,
894            "    private readonly {}Delegate _del{};",
895            delegate_type, spec.cs_method
896        )
897        .ok();
898    }
899
900    writeln!(out).ok();
901    writeln!(out, "    internal IntPtr NativePtr => _nativeStruct;").ok();
902    writeln!(out).ok();
903
904    // Constructor
905    let num_slots = CALLBACKS.len() + 1; // user_data + callbacks
906    writeln!(out, "    internal VisitorCallbacks(IVisitor visitor)").ok();
907    writeln!(out, "    {{").ok();
908    writeln!(out, "        _visitor = visitor;").ok();
909    writeln!(out).ok();
910
911    // Create delegates
912    for spec in CALLBACKS {
913        let dt = delegate_type_name(spec.cs_method);
914        writeln!(
915            out,
916            "        _del{} = new {}Delegate(Handle{});",
917            spec.cs_method, dt, spec.cs_method
918        )
919        .ok();
920    }
921
922    // Allocate struct: user_data + 40 IntPtr slots = 41 * IntPtr.Size
923    writeln!(out).ok();
924    writeln!(
925        out,
926        "        // HTMHtmVisitorCallbacks = user_data + {n} callback function pointers",
927        n = CALLBACKS.len()
928    )
929    .ok();
930    writeln!(
931        out,
932        "        _nativeStruct = Marshal.AllocHGlobal(IntPtr.Size * {num_slots});"
933    )
934    .ok();
935    writeln!(
936        out,
937        "        // Slot 0: user_data = IntPtr.Zero (visitor captured via delegate closure)"
938    )
939    .ok();
940    writeln!(out, "        Marshal.WriteIntPtr(_nativeStruct, 0, IntPtr.Zero);").ok();
941
942    for (i, spec) in CALLBACKS.iter().enumerate() {
943        let offset = (i + 1) * 8; // assuming 8-byte pointers (64-bit)
944        writeln!(
945            out,
946            "        Marshal.WriteIntPtr(_nativeStruct, {offset}, Marshal.GetFunctionPointerForDelegate(_del{}));",
947            spec.cs_method
948        )
949        .ok();
950    }
951
952    writeln!(out, "    }}").ok();
953    writeln!(out).ok();
954
955    // Handle methods
956    for spec in CALLBACKS {
957        gen_handle_method(&mut out, spec);
958    }
959
960    // DecodeNodeContext helper
961    writeln!(out, "    private static NodeContext DecodeNodeContext(IntPtr ctxPtr)").ok();
962    writeln!(out, "    {{").ok();
963    writeln!(
964        out,
965        "        // HTMHtmNodeContext: int32 node_type, char* tag_name, uintptr depth,"
966    )
967    .ok();
968    writeln!(
969        out,
970        "        //                    uintptr index_in_parent, char* parent_tag, int32 is_inline"
971    )
972    .ok();
973    writeln!(out, "        int nodeType = Marshal.ReadInt32(ctxPtr, 0);").ok();
974    writeln!(out, "        var tagNamePtr = Marshal.ReadIntPtr(ctxPtr, 8);").ok();
975    writeln!(
976        out,
977        "        string tagName = Marshal.PtrToStringAnsi(tagNamePtr) ?? string.Empty;"
978    )
979    .ok();
980    writeln!(out, "        ulong depth = (ulong)(long)Marshal.ReadInt64(ctxPtr, 16);").ok();
981    writeln!(
982        out,
983        "        ulong indexInParent = (ulong)(long)Marshal.ReadInt64(ctxPtr, 24);"
984    )
985    .ok();
986    writeln!(out, "        var parentTagPtr = Marshal.ReadIntPtr(ctxPtr, 32);").ok();
987    writeln!(
988        out,
989        "        string? parentTag = parentTagPtr == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(parentTagPtr);"
990    )
991    .ok();
992    writeln!(out, "        int isInlineRaw = Marshal.ReadInt32(ctxPtr, 40);").ok();
993    writeln!(
994        out,
995        "        return new NodeContext(nodeType, tagName, depth, indexInParent, parentTag, isInlineRaw != 0);"
996    )
997    .ok();
998    writeln!(out, "    }}").ok();
999    writeln!(out).ok();
1000
1001    // DecodeCells helper
1002    writeln!(
1003        out,
1004        "    private static string[] DecodeCells(IntPtr cellsPtr, long count)"
1005    )
1006    .ok();
1007    writeln!(out, "    {{").ok();
1008    writeln!(out, "        var result = new string[count];").ok();
1009    writeln!(out, "        for (long i = 0; i < count; i++)").ok();
1010    writeln!(out, "        {{").ok();
1011    writeln!(
1012        out,
1013        "            var ptr = Marshal.ReadIntPtr(cellsPtr, (int)(i * IntPtr.Size));"
1014    )
1015    .ok();
1016    writeln!(
1017        out,
1018        "            result[i] = Marshal.PtrToStringAnsi(ptr) ?? string.Empty;"
1019    )
1020    .ok();
1021    writeln!(out, "        }}").ok();
1022    writeln!(out, "        return result;").ok();
1023    writeln!(out, "    }}").ok();
1024    writeln!(out).ok();
1025
1026    // EncodeVisitResult helper
1027    writeln!(
1028        out,
1029        "    private static int EncodeVisitResult(VisitResult result, IntPtr outCustom, IntPtr outLen)"
1030    )
1031    .ok();
1032    writeln!(out, "    {{").ok();
1033    writeln!(out, "        return result switch").ok();
1034    writeln!(out, "        {{").ok();
1035    writeln!(out, "            VisitResult.Continue => 0,").ok();
1036    writeln!(out, "            VisitResult.Skip => 1,").ok();
1037    writeln!(out, "            VisitResult.PreserveHtml => 2,").ok();
1038    writeln!(
1039        out,
1040        "            VisitResult.Custom c => EncodeString(c.Markdown, outCustom, outLen, 3),"
1041    )
1042    .ok();
1043    writeln!(
1044        out,
1045        "            VisitResult.Error e => EncodeString(e.Message, outCustom, outLen, 4),"
1046    )
1047    .ok();
1048    writeln!(out, "            _ => 0").ok();
1049    writeln!(out, "        }};").ok();
1050    writeln!(out, "    }}").ok();
1051    writeln!(out).ok();
1052
1053    writeln!(
1054        out,
1055        "    private static int EncodeString(string text, IntPtr outCustom, IntPtr outLen, int code)"
1056    )
1057    .ok();
1058    writeln!(out, "    {{").ok();
1059    writeln!(out, "        var bytes = System.Text.Encoding.UTF8.GetBytes(text);").ok();
1060    writeln!(out, "        var buf = Marshal.AllocHGlobal(bytes.Length + 1);").ok();
1061    writeln!(out, "        Marshal.Copy(bytes, 0, buf, bytes.Length);").ok();
1062    writeln!(out, "        Marshal.WriteByte(buf, bytes.Length, 0);").ok();
1063    writeln!(out, "        Marshal.WriteIntPtr(outCustom, buf);").ok();
1064    writeln!(out, "        Marshal.WriteInt64(outLen, (long)bytes.Length);").ok();
1065    writeln!(out, "        return code;").ok();
1066    writeln!(out, "    }}").ok();
1067    writeln!(out).ok();
1068
1069    // Dispose
1070    writeln!(out, "    public void Dispose()").ok();
1071    writeln!(out, "    {{").ok();
1072    writeln!(out, "        if (_disposed) return;").ok();
1073    writeln!(out, "        _disposed = true;").ok();
1074    writeln!(out, "        Marshal.FreeHGlobal(_nativeStruct);").ok();
1075    writeln!(out, "    }}").ok();
1076    writeln!(out, "}}").ok();
1077    out
1078}
1079
1080// ---------------------------------------------------------------------------
1081// Helpers
1082// ---------------------------------------------------------------------------
1083
1084fn delegate_type_name(cs_method: &str) -> String {
1085    cs_method.to_string()
1086}
1087
1088fn iface_param_str(spec: &CallbackSpec) -> String {
1089    let mut params = vec!["NodeContext context".to_string()];
1090    for ep in spec.extra {
1091        params.push(format!("{} {}", ep.cs_type, ep.cs_name));
1092    }
1093    if spec.has_is_header {
1094        params.push("bool isHeader".to_string());
1095    }
1096    params.join(", ")
1097}
1098
1099/// Build the P/Invoke delegate parameter list (all raw C types).
1100fn delegate_pinvoke_params(spec: &CallbackSpec) -> String {
1101    let mut params = vec!["IntPtr ctx".to_string(), "IntPtr userData".to_string()];
1102    for ep in spec.extra {
1103        for (idx, ptype) in ep.pinvoke_types.iter().enumerate() {
1104            params.push(format!("{ptype} {}", raw_var_name(ep.cs_name, idx)));
1105        }
1106    }
1107    if spec.has_is_header {
1108        params.push("int isHeader".to_string());
1109    }
1110    params.push("IntPtr outCustom".to_string());
1111    params.push("IntPtr outLen".to_string());
1112    params.join(", ")
1113}
1114
1115/// Generate one `Handle*` method inside `VisitorCallbacks`.
1116fn gen_handle_method(out: &mut String, spec: &CallbackSpec) {
1117    let params = delegate_pinvoke_params(spec);
1118    writeln!(out, "    private int Handle{}({})", spec.cs_method, params).ok();
1119    writeln!(out, "    {{").ok();
1120    writeln!(out, "        try").ok();
1121    writeln!(out, "        {{").ok();
1122    writeln!(out, "            var context = DecodeNodeContext(ctx);").ok();
1123
1124    // Decode extra params
1125    for ep in spec.extra {
1126        let mut decode = ep.decode.to_string();
1127        for (idx, _) in ep.pinvoke_types.iter().enumerate() {
1128            let placeholder = format!("raw{}{}", capitalize(ep.cs_name), idx);
1129            let var = raw_var_name(ep.cs_name, idx);
1130            decode = decode.replace(&placeholder, &var);
1131        }
1132        writeln!(out, "            var {} = {};", ep.cs_name, decode).ok();
1133    }
1134    if spec.has_is_header {
1135        writeln!(out, "            var goIsHeader = isHeader != 0;").ok();
1136    }
1137
1138    let mut call_args = vec!["context".to_string()];
1139    for ep in spec.extra {
1140        call_args.push(ep.cs_name.to_string());
1141    }
1142    if spec.has_is_header {
1143        call_args.push("goIsHeader".to_string());
1144    }
1145
1146    writeln!(
1147        out,
1148        "            var result = _visitor.{}({});",
1149        spec.cs_method,
1150        call_args.join(", ")
1151    )
1152    .ok();
1153    writeln!(out, "            return EncodeVisitResult(result, outCustom, outLen);").ok();
1154    writeln!(out, "        }}").ok();
1155    writeln!(out, "        catch").ok();
1156    writeln!(out, "        {{").ok();
1157    writeln!(out, "            return 0;").ok();
1158    writeln!(out, "        }}").ok();
1159    writeln!(out, "    }}").ok();
1160    writeln!(out).ok();
1161}
1162
1163fn raw_var_name(cs_name: &str, idx: usize) -> String {
1164    format!("raw{}{idx}", capitalize(cs_name))
1165}
1166
1167fn capitalize(s: &str) -> String {
1168    let mut chars = s.chars();
1169    match chars.next() {
1170        None => String::new(),
1171        Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
1172    }
1173}
alef_backend_csharp/gen_visitor.rs

alef_backend_csharp/
gen_visitor.rs
