Best way to override HtmlFormatter

[digitalmoksha]

So I'm reaching a point where I want to override some aspects of the HtmlFormatter. For example, I plan on using the gemoji option to handle shortcodes, rather than our own specific code. However one of the things we do is wrap any such emoji with <gl-emoji> with additional attributes.

<gl-emoji data-unicode-version="6.0" data-name="smile" title="smiling face with open mouth and smiling eyes">😄</gl-emoji>

I believe the gemoji crate can give us all that information, so in my head it makes sense to write it out during rendering rather modifying a parsed nokogiri tree later. Even if it doesn't, wrapping it in our tag would allow us to pluck them out of the tree more reliably.

So my question is what would be the best way to replace just the handling of that node? I really don't want to duplicate that file.

What I think I want is to rewrite format_node such that for each node it calls a separate function. I actually handled the NodeValue::Math node in that way, calling self.render_math_inline.

Then my goal would be to have a GlHtmlFormatter that inherits from HtmlFormatter and only overrides the methods I want.

Knowing much more Ruby than Rust, would this be possible, and would you support such a rewrite of format_node?

[kivikakk]

Rust has no inheritance, so we'd need to take a different approach. (I briefly started to think about this in #442 (comment).) The problem largely is in allowing some methods to be overridden while providing defaults for all, without pessimising the default case (and therefore Comrak for the large proportion of use cases).

One way would be to separate each node type's formatting code into its own (#[inline]) function, so they can be referred to separately. Then a rendering trait can be defined which has defaults set for each node type. The normal format method wouldn't take such a trait object at all, preserving default performance, but a format_with_renderer or something would. The complexity here would be in extracting the relevant state/output stream/etc. so as to be usable by both default and external implementations.

Another approach would be to construct a formatting function with a macro, allowing overrides to be provided for node types. This would shift the burden of custom renderers to compile-time.

There's also the middleware approach I mentioned in that earlier discussion; that's perhaps simplest of all, though we'd need to see what any of these looked like in implementation to know for sure.

[digitalmoksha]

Not sure which of these would be better. I'm not quite understanding the middleware approach yet.

If each node has it's own render function, I was naively thinking you could put a feature flag around each function such that if that flag is turned on when the crate is complied, the crate version doesn't get compiled and instead the one in the enclosing crate gets used. But even if that were possible, seems more like a hack than anything.

[kivikakk]

Yeah, I don't think that can work as-is — there isn't really an "enclosing crate" concept. (But again, perhaps a macro to do something similar would be workable.) Unfortunately I'm not really in a position to attempt any of them at the moment, my health is on the down presently.

[digitalmoksha]

Oof, sorry to hear that - hope you feel better. No problem, I may take a crack at it once I better understand macros 😄

[digitalmoksha]

Ran across https://github.com/Shizcow/overrider-rs, which looks interesting and uses macros. But it hasn't been updated in 4 years. Kinda (I think) fits with your comment

Another approach would be to construct a formatting function with a macro, allowing overrides to be provided for node types. This would shift the burden of custom renderers to compile-time.

Don't know if there is anything to reuse here or not.

Edit: just throwing some ideas / resources out here as I keep investigating.

[kivikakk]

I don't think that'll do it — it can't reach into another crate, and it's a bit awkward to boot.

My intention with the macro idea is that we could supply a macro which constructs a render function out of parts supplied to it, with a fallback that then calls the defaults.

Here's a very barebones POC; don't use this directly as a base or anything (it only works on one node), but hopefully it shows you what kind of thing you can do with macros. Try pasting this at the end of src/html.rs:

#[cfg(test)]
macro_rules! create_formatter {
    ($name:ident, |$out:ident| { $( $pat:pat => $case:tt ),+, }) => {
        fn $name<'a>(
            node: &'a AstNode<'a>,
            $out: &mut dyn Write,
        ) -> io::Result<()> {
            let value = &node.data.borrow().value;
            match value {
                $(
                    $pat => $case
                ),+
                _ => {
                    write!($out, "default: {:?}\n", value)?;
                }
            }
            Ok(())
        }
    };
}

#[cfg(test)]
create_formatter!(thingy, |out| {
    NodeValue::Document => {
        write!(out, "document!\n")?;
    },
    NodeValue::Text(t) => {
        write!(out, "text {:?}\n", t)?;
    },
});

#[test]
fn test_thingy() {
    let arena = crate::Arena::new();
    let root = crate::parse_document(&arena, "hello", &Options::default());

    let mut out = vec![];
    thingy(root, &mut out).unwrap();
    thingy(root.first_child().unwrap(), &mut out).unwrap();
    thingy(root.first_child().unwrap().first_child().unwrap(), &mut out).unwrap();
    assert_eq!(
        std::str::from_utf8(&out).unwrap(),
        concat!(
            "document!\n",
            "default: Paragraph\n",
            "text \"hello\"\n",
        ),
    );
}

(cargo test html:: to ensure it does what it claims.)

This shows how a function can be made with a macro, which takes a variable number of patterns and actions to be used in some context, passing relevant context to them (note Rust macro hygiene rules), with some default behaviour.

Hopefully it's not too much effort to refactor the common parts of HtmlFormatter in a way that doesn't reduce its performance.