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, "#nullable enable").ok();
757    writeln!(out).ok();
758    writeln!(out, "using System;").ok();
759    writeln!(out).ok();
760    writeln!(out, "namespace {namespace};").ok();
761    writeln!(out).ok();
762    writeln!(out, "/// <summary>Context passed to every visitor callback.</summary>").ok();
763    writeln!(out, "public record NodeContext(").ok();
764    writeln!(out, "    /// <summary>Coarse-grained node type tag.</summary>").ok();
765    writeln!(out, "    int NodeType,").ok();
766    writeln!(out, "    /// <summary>HTML element tag name (e.g. \"div\").</summary>").ok();
767    writeln!(out, "    string TagName,").ok();
768    writeln!(out, "    /// <summary>DOM depth (0 = root).</summary>").ok();
769    writeln!(out, "    ulong Depth,").ok();
770    writeln!(out, "    /// <summary>0-based sibling index.</summary>").ok();
771    writeln!(out, "    ulong IndexInParent,").ok();
772    writeln!(
773        out,
774        "    /// <summary>Parent element tag name, or null at the root.</summary>"
775    )
776    .ok();
777    writeln!(out, "    string? ParentTag,").ok();
778    writeln!(
779        out,
780        "    /// <summary>True when this element is treated as inline.</summary>"
781    )
782    .ok();
783    writeln!(out, "    bool IsInline").ok();
784    writeln!(out, ");").ok();
785    out
786}
787
788fn gen_visit_result(namespace: &str) -> String {
789    let mut out = String::with_capacity(2048);
790    out.push_str(&hash::header(CommentStyle::DoubleSlash));
791    writeln!(out, "#nullable enable").ok();
792    writeln!(out).ok();
793    writeln!(out, "using System;").ok();
794    writeln!(out).ok();
795    writeln!(out, "namespace {namespace};").ok();
796    writeln!(out).ok();
797    writeln!(
798        out,
799        "/// <summary>Controls how the visitor affects the conversion pipeline.</summary>"
800    )
801    .ok();
802    writeln!(out, "public abstract record VisitResult").ok();
803    writeln!(out, "{{").ok();
804    writeln!(out, "    private VisitResult() {{}}").ok();
805    writeln!(out).ok();
806    writeln!(out, "    /// <summary>Proceed with default conversion.</summary>").ok();
807    writeln!(out, "    public sealed record Continue : VisitResult;").ok();
808    writeln!(out).ok();
809    writeln!(
810        out,
811        "    /// <summary>Omit this element from output entirely.</summary>"
812    )
813    .ok();
814    writeln!(out, "    public sealed record Skip : VisitResult;").ok();
815    writeln!(out).ok();
816    writeln!(out, "    /// <summary>Keep original HTML verbatim.</summary>").ok();
817    writeln!(out, "    public sealed record PreserveHtml : VisitResult;").ok();
818    writeln!(out).ok();
819    writeln!(out, "    /// <summary>Replace with custom Markdown.</summary>").ok();
820    writeln!(out, "    public sealed record Custom(string Markdown) : VisitResult;").ok();
821    writeln!(out).ok();
822    writeln!(
823        out,
824        "    /// <summary>Abort conversion with an error message.</summary>"
825    )
826    .ok();
827    writeln!(out, "    public sealed record Error(string Message) : VisitResult;").ok();
828    writeln!(out, "}}").ok();
829    out
830}
831
832fn gen_ivisitor(namespace: &str) -> String {
833    let mut out = String::with_capacity(4096);
834    out.push_str(&hash::header(CommentStyle::DoubleSlash));
835    writeln!(out, "#nullable enable").ok();
836    writeln!(out).ok();
837    writeln!(out, "using System;").ok();
838    writeln!(out).ok();
839    writeln!(out, "namespace {namespace};").ok();
840    writeln!(out).ok();
841    writeln!(
842        out,
843        "/// <summary>Visitor interface for the HTML-to-Markdown conversion pipeline.</summary>"
844    )
845    .ok();
846    writeln!(out, "public interface IVisitor").ok();
847    writeln!(out, "{{").ok();
848    for spec in CALLBACKS {
849        let params = iface_param_str(spec);
850        writeln!(out, "    /// <summary>{}</summary>", spec.doc).ok();
851        writeln!(
852            out,
853            "    VisitResult {}({}) => new VisitResult.Continue();",
854            spec.cs_method, params
855        )
856        .ok();
857    }
858    writeln!(out, "}}").ok();
859    out
860}
861
862/// Generate `VisitorCallbacks.cs` which holds `GCHandle`s for all 40 delegates and
863/// writes them into a `Marshal.AllocHGlobal` block matching the C struct layout.
864fn gen_visitor_callbacks(namespace: &str) -> String {
865    let mut out = String::with_capacity(32_768);
866    out.push_str(&hash::header(CommentStyle::DoubleSlash));
867    writeln!(out, "#nullable enable").ok();
868    writeln!(out).ok();
869    writeln!(out, "using System;").ok();
870    writeln!(out, "using System.Runtime.InteropServices;").ok();
871    writeln!(out).ok();
872    writeln!(out, "namespace {namespace};").ok();
873    writeln!(out).ok();
874    writeln!(out, "/// <summary>").ok();
875    writeln!(out, "/// Allocates P/Invoke delegates for a IVisitor and assembles").ok();
876    writeln!(out, "/// the C HTMHtmVisitorCallbacks struct in unmanaged memory.").ok();
877    writeln!(out, "/// </summary>").ok();
878    writeln!(out, "internal sealed class VisitorCallbacks : IDisposable").ok();
879    writeln!(out, "{{").ok();
880    writeln!(out, "    private readonly IVisitor _visitor;").ok();
881    writeln!(
882        out,
883        "    private readonly IntPtr _nativeStruct; // HTMHtmVisitorCallbacks"
884    )
885    .ok();
886    writeln!(out, "    private bool _disposed;").ok();
887    writeln!(out).ok();
888
889    // Declare delegate types and delegate fields
890    for spec in CALLBACKS {
891        let delegate_type = delegate_type_name(spec.cs_method);
892        let pinvoke_params = delegate_pinvoke_params(spec);
893        writeln!(out, "    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]").ok();
894        writeln!(
895            out,
896            "    private delegate int {}Delegate({});",
897            delegate_type, pinvoke_params
898        )
899        .ok();
900        writeln!(
901            out,
902            "    private readonly {}Delegate _del{};",
903            delegate_type, spec.cs_method
904        )
905        .ok();
906    }
907
908    writeln!(out).ok();
909    writeln!(out, "    internal IntPtr NativePtr => _nativeStruct;").ok();
910    writeln!(out).ok();
911
912    // Constructor
913    let num_slots = CALLBACKS.len() + 1; // user_data + callbacks
914    writeln!(out, "    internal VisitorCallbacks(IVisitor visitor)").ok();
915    writeln!(out, "    {{").ok();
916    writeln!(out, "        _visitor = visitor;").ok();
917    writeln!(out).ok();
918
919    // Create delegates
920    for spec in CALLBACKS {
921        let dt = delegate_type_name(spec.cs_method);
922        writeln!(
923            out,
924            "        _del{} = new {}Delegate(Handle{});",
925            spec.cs_method, dt, spec.cs_method
926        )
927        .ok();
928    }
929
930    // Allocate struct: user_data + 40 IntPtr slots = 41 * IntPtr.Size
931    writeln!(out).ok();
932    writeln!(
933        out,
934        "        // HTMHtmVisitorCallbacks = user_data + {n} callback function pointers",
935        n = CALLBACKS.len()
936    )
937    .ok();
938    writeln!(
939        out,
940        "        _nativeStruct = Marshal.AllocHGlobal(IntPtr.Size * {num_slots});"
941    )
942    .ok();
943    writeln!(
944        out,
945        "        // Slot 0: user_data = IntPtr.Zero (visitor captured via delegate closure)"
946    )
947    .ok();
948    writeln!(out, "        Marshal.WriteIntPtr(_nativeStruct, 0, IntPtr.Zero);").ok();
949
950    for (i, spec) in CALLBACKS.iter().enumerate() {
951        let offset = (i + 1) * 8; // assuming 8-byte pointers (64-bit)
952        writeln!(
953            out,
954            "        Marshal.WriteIntPtr(_nativeStruct, {offset}, Marshal.GetFunctionPointerForDelegate(_del{}));",
955            spec.cs_method
956        )
957        .ok();
958    }
959
960    writeln!(out, "    }}").ok();
961    writeln!(out).ok();
962
963    // Handle methods
964    for spec in CALLBACKS {
965        gen_handle_method(&mut out, spec);
966    }
967
968    // DecodeNodeContext helper
969    writeln!(out, "    private static NodeContext DecodeNodeContext(IntPtr ctxPtr)").ok();
970    writeln!(out, "    {{").ok();
971    writeln!(
972        out,
973        "        // HTMHtmNodeContext: int32 node_type, char* tag_name, uintptr depth,"
974    )
975    .ok();
976    writeln!(
977        out,
978        "        //                    uintptr index_in_parent, char* parent_tag, int32 is_inline"
979    )
980    .ok();
981    writeln!(out, "        int nodeType = Marshal.ReadInt32(ctxPtr, 0);").ok();
982    writeln!(out, "        var tagNamePtr = Marshal.ReadIntPtr(ctxPtr, 8);").ok();
983    writeln!(
984        out,
985        "        string tagName = Marshal.PtrToStringAnsi(tagNamePtr) ?? string.Empty;"
986    )
987    .ok();
988    writeln!(out, "        ulong depth = (ulong)(long)Marshal.ReadInt64(ctxPtr, 16);").ok();
989    writeln!(
990        out,
991        "        ulong indexInParent = (ulong)(long)Marshal.ReadInt64(ctxPtr, 24);"
992    )
993    .ok();
994    writeln!(out, "        var parentTagPtr = Marshal.ReadIntPtr(ctxPtr, 32);").ok();
995    writeln!(
996        out,
997        "        string? parentTag = parentTagPtr == IntPtr.Zero ? null : Marshal.PtrToStringAnsi(parentTagPtr);"
998    )
999    .ok();
1000    writeln!(out, "        int isInlineRaw = Marshal.ReadInt32(ctxPtr, 40);").ok();
1001    writeln!(
1002        out,
1003        "        return new NodeContext(nodeType, tagName, depth, indexInParent, parentTag, isInlineRaw != 0);"
1004    )
1005    .ok();
1006    writeln!(out, "    }}").ok();
1007    writeln!(out).ok();
1008
1009    // DecodeCells helper
1010    writeln!(
1011        out,
1012        "    private static string[] DecodeCells(IntPtr cellsPtr, long count)"
1013    )
1014    .ok();
1015    writeln!(out, "    {{").ok();
1016    writeln!(out, "        var result = new string[count];").ok();
1017    writeln!(out, "        for (long i = 0; i < count; i++)").ok();
1018    writeln!(out, "        {{").ok();
1019    writeln!(
1020        out,
1021        "            var ptr = Marshal.ReadIntPtr(cellsPtr, (int)(i * IntPtr.Size));"
1022    )
1023    .ok();
1024    writeln!(
1025        out,
1026        "            result[i] = Marshal.PtrToStringAnsi(ptr) ?? string.Empty;"
1027    )
1028    .ok();
1029    writeln!(out, "        }}").ok();
1030    writeln!(out, "        return result;").ok();
1031    writeln!(out, "    }}").ok();
1032    writeln!(out).ok();
1033
1034    // EncodeVisitResult helper
1035    writeln!(
1036        out,
1037        "    private static int EncodeVisitResult(VisitResult result, IntPtr outCustom, IntPtr outLen)"
1038    )
1039    .ok();
1040    writeln!(out, "    {{").ok();
1041    writeln!(out, "        return result switch").ok();
1042    writeln!(out, "        {{").ok();
1043    writeln!(out, "            VisitResult.Continue => 0,").ok();
1044    writeln!(out, "            VisitResult.Skip => 1,").ok();
1045    writeln!(out, "            VisitResult.PreserveHtml => 2,").ok();
1046    writeln!(
1047        out,
1048        "            VisitResult.Custom c => EncodeString(c.Markdown, outCustom, outLen, 3),"
1049    )
1050    .ok();
1051    writeln!(
1052        out,
1053        "            VisitResult.Error e => EncodeString(e.Message, outCustom, outLen, 4),"
1054    )
1055    .ok();
1056    writeln!(out, "            _ => 0").ok();
1057    writeln!(out, "        }};").ok();
1058    writeln!(out, "    }}").ok();
1059    writeln!(out).ok();
1060
1061    writeln!(
1062        out,
1063        "    private static int EncodeString(string text, IntPtr outCustom, IntPtr outLen, int code)"
1064    )
1065    .ok();
1066    writeln!(out, "    {{").ok();
1067    writeln!(out, "        var bytes = System.Text.Encoding.UTF8.GetBytes(text);").ok();
1068    writeln!(out, "        var buf = Marshal.AllocHGlobal(bytes.Length + 1);").ok();
1069    writeln!(out, "        Marshal.Copy(bytes, 0, buf, bytes.Length);").ok();
1070    writeln!(out, "        Marshal.WriteByte(buf, bytes.Length, 0);").ok();
1071    writeln!(out, "        Marshal.WriteIntPtr(outCustom, buf);").ok();
1072    writeln!(out, "        Marshal.WriteInt64(outLen, (long)bytes.Length);").ok();
1073    writeln!(out, "        return code;").ok();
1074    writeln!(out, "    }}").ok();
1075    writeln!(out).ok();
1076
1077    // Dispose
1078    writeln!(out, "    public void Dispose()").ok();
1079    writeln!(out, "    {{").ok();
1080    writeln!(out, "        if (_disposed) return;").ok();
1081    writeln!(out, "        _disposed = true;").ok();
1082    writeln!(out, "        Marshal.FreeHGlobal(_nativeStruct);").ok();
1083    writeln!(out, "    }}").ok();
1084    writeln!(out, "}}").ok();
1085    out
1086}
1087
1088// ---------------------------------------------------------------------------
1089// Helpers
1090// ---------------------------------------------------------------------------
1091
1092fn delegate_type_name(cs_method: &str) -> String {
1093    cs_method.to_string()
1094}
1095
1096fn iface_param_str(spec: &CallbackSpec) -> String {
1097    let mut params = vec!["NodeContext context".to_string()];
1098    for ep in spec.extra {
1099        params.push(format!("{} {}", ep.cs_type, ep.cs_name));
1100    }
1101    if spec.has_is_header {
1102        params.push("bool isHeader".to_string());
1103    }
1104    params.join(", ")
1105}
1106
1107/// Build the P/Invoke delegate parameter list (all raw C types).
1108fn delegate_pinvoke_params(spec: &CallbackSpec) -> String {
1109    let mut params = vec!["IntPtr ctx".to_string(), "IntPtr userData".to_string()];
1110    for ep in spec.extra {
1111        for (idx, ptype) in ep.pinvoke_types.iter().enumerate() {
1112            params.push(format!("{ptype} {}", raw_var_name(ep.cs_name, idx)));
1113        }
1114    }
1115    if spec.has_is_header {
1116        params.push("int isHeader".to_string());
1117    }
1118    params.push("IntPtr outCustom".to_string());
1119    params.push("IntPtr outLen".to_string());
1120    params.join(", ")
1121}
1122
1123/// Generate one `Handle*` method inside `VisitorCallbacks`.
1124fn gen_handle_method(out: &mut String, spec: &CallbackSpec) {
1125    let params = delegate_pinvoke_params(spec);
1126    writeln!(out, "    private int Handle{}({})", spec.cs_method, params).ok();
1127    writeln!(out, "    {{").ok();
1128    writeln!(out, "        try").ok();
1129    writeln!(out, "        {{").ok();
1130    writeln!(out, "            var context = DecodeNodeContext(ctx);").ok();
1131
1132    // Decode extra params
1133    for ep in spec.extra {
1134        let mut decode = ep.decode.to_string();
1135        for (idx, _) in ep.pinvoke_types.iter().enumerate() {
1136            let placeholder = format!("raw{}{}", capitalize(ep.cs_name), idx);
1137            let var = raw_var_name(ep.cs_name, idx);
1138            decode = decode.replace(&placeholder, &var);
1139        }
1140        writeln!(out, "            var {} = {};", ep.cs_name, decode).ok();
1141    }
1142    if spec.has_is_header {
1143        writeln!(out, "            var goIsHeader = isHeader != 0;").ok();
1144    }
1145
1146    let mut call_args = vec!["context".to_string()];
1147    for ep in spec.extra {
1148        call_args.push(ep.cs_name.to_string());
1149    }
1150    if spec.has_is_header {
1151        call_args.push("goIsHeader".to_string());
1152    }
1153
1154    writeln!(
1155        out,
1156        "            var result = _visitor.{}({});",
1157        spec.cs_method,
1158        call_args.join(", ")
1159    )
1160    .ok();
1161    writeln!(out, "            return EncodeVisitResult(result, outCustom, outLen);").ok();
1162    writeln!(out, "        }}").ok();
1163    writeln!(out, "        catch").ok();
1164    writeln!(out, "        {{").ok();
1165    writeln!(out, "            return 0;").ok();
1166    writeln!(out, "        }}").ok();
1167    writeln!(out, "    }}").ok();
1168    writeln!(out).ok();
1169}
1170
1171fn raw_var_name(cs_name: &str, idx: usize) -> String {
1172    format!("raw{}{idx}", capitalize(cs_name))
1173}
1174
1175fn capitalize(s: &str) -> String {
1176    let mut chars = s.chars();
1177    match chars.next() {
1178        None => String::new(),
1179        Some(c) => c.to_uppercase().collect::<String>() + chars.as_str(),
1180    }
1181}
alef_backend_csharp/gen_visitor.rs

alef_backend_csharp/
gen_visitor.rs
