Further reducing the rendering API

[jugglinmike]

My research in gh-1248 makes me think there may be a hazard resulting from our use of two different parsers. We've worked to reduce the number of Cheerio-specific rendering methods to just two functions: cheerio.html and cheerio.xml. This is an improvement over the prior state, but I'm wondering if it goes far enough.

In pre-1.0.0 Cheerio, htmlparser2 did all of the parsing and all of the rendering. In master, parsing may be done by either htmlparser2 or parse5. By exposing two distinct rendering methods, we're giving consumers the ability to parse in one mode and render in another.

For example:

const cheerio = require('cheerio');
let $;

$ = cheerio.load('<p>Some HTML</p>');
// `$` is now loaded with a standards-compliant HTML tree produced by parse5
// Is rendering a string of XML from this tree ever desirable?
console.log(cheerio.xml($.root()));

$ = cheerio.load('<media:thumbnail/>', {xml: true});
// `$` is now loaded with a loosely-interpreted XML tree produced by htmlparser2
// Is rendering a string of HTML from this tree ever desirable?
console.log(cheerio.html($.root()));

If we further simplified the API to a single method, cheerio.render, then we could select the appropriate rendering approach based on the input tree. As long as there are no use cases for the examples demonstrated above, this would eliminate a potential source of confusion.

@fb55 @inikulin Does this makes sense to you? Do you think we could reliably infer the correct rendering method based only on the tree being rendered?

[fb55]

In pre-1.0.0 cheerio, html renders xml if xmlMode is set to true. This can definitely be unexpected at times.

I think it makes a lot of sense to deprecate xml and html and just offer a single render method that automatically decides what it wants to do based on the type of the document, with an ability to force a specific rendering format.

Given that this hasn't been much of an issue so far, I would also not be opposed to just keeping the current behavior for the sake of backwards-compatibility.

[matthewmueller]

I agree that we should clean this up. I'm tempted to say we should keep the methods (or at least .html()), since everyone uses that.

This may also depend on if we can cleanup { xml: true } altogether. See #1271 for more details.

I also like the idea of cheerio.render($, options) 🙂