| HTML::Gumbo(3pm) | User Contributed Perl Documentation | HTML::Gumbo(3pm) |
HTML::Gumbo - HTML5 parser based on gumbo C library
use HTML::Gumbo;
say HTML::Gumbo->new->parse('<div></div>');
say HTML::Gumbo->new->parse('<h1>Hello</h1>', format => 'tree')->as_HTML;
Gumbo <https://github.com/google/gumbo-parser> is an implementation of the HTML5 parsing algorithm <http://www.w3.org/TR/html5/syntax.html> implemented as a pure C99 library with no outside dependencies.
Goals and features of the C library:
my $parser = HTML::Gumbo->new;
No options at the moment.
my $res = $parser->parse(
"<h1>hello world!</h1>",
format => 'tree',
input_is => 'string',
);
Takes html string and pairs of named arguments:
Note that fragment_enclosing_tag is set to '<body>' and can not be changed at the moment. Feel free to send patches implementing this part.
See "SUPPORTED OUTPUT FORMATS" for additional details.
Note that SVG and MATHML parsing is not tested, feel free to file bug reports with tests in case it doesn't work.
Return value depends on the picked format.
HTML is parsed and re-built from the tree, so tags are balanced (except void elements).
No additional arguments specific for this format.
$html = HTML::Gumbo->new->parse( $html );
HTML::Parser like interface. Pass a sub as "callback" argument to "parse" method and it will be called for every node in the document:
HTML::Gumbo->new->parse( $html, format => 'callback', callback => sub {
my ($event) = shift;
if ( $event eq 'document start' ) {
my ($doctype) = @_;
}
elsif ( $event eq 'document end' ) {
}
elsif ( $event eq 'start' ) {
my ($tag, $attrs) = @_;
}
elsif ( $event eq 'end' ) {
my ($tag) = @_;
}
elsif ( $event eq /^(text|space|cdata|comment)$/ ) {
my ($text) = @_;
}
else {
die "Unknown event";
}
} );
Note that 'end' events are not generated for void elements <http://www.w3.org/TR/html5/syntax.html#void-elements>, for example "hr", "br" and "img".
No additional arguments except mentioned "callback".
Fragment parsing still generates 'document start' and 'document end' events what can be handy to initialize your parsing callback.
Alpha stage.
Produces tree based on HTML::Elements, like HTML::TreeBuilder.
There is major difference from HTML::TreeBuilder, this method produces top level element with tag name 'document' which may have doctype, comments and html tags as children.
Fragments parsing still produces top level 'document' element as fragment can be a list of tags, for example: '<p>hello</p><p>world</p'.
Yes, it's not ready to use as drop in replacement of tree builder. Patches are wellcome as I don't use this formatter at the moment. Note that it's hard to get rid of top level element because of situations described above. So not bad idea is to write HTML::Gumbo::Document class that is either subclass of HTML::Element or implements a small subset of methods of HTML::Element.
The C parser works only with UTF-8, so you have several options to make sure input is UTF-8. First of all define "input_is" argument:
$gumbo->parse( decode_utf8($octets) );
$gumbo->parse( $octets, input_is => 'octets', encoding => 'latin-1' );
$gumbo->parse( $octets, input_is => 'octets', encoding_content_type => 'latin-1' );
HTML5 defines prescan algorithm <http://www.w3.org/TR/html5/syntax.html#prescan-a-byte-stream-to-determine-its-encoding> that extracts encoding from meta tags in the head.
It would be cool to get it in the C library, but I will accept a patch that impements it in pure perl.
$gumbo->parse( $octets, input_is => 'octets', encoding_tentative => 'latin-1' );
Can be implemented using Encode::Detect::Detector. Patches are welcome.
Ruslan Zakirov <ruz@bestpractical.com>
Under the same terms as perl itself.
| 2024-04-01 | perl v5.38.2 |