.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTML::Gumbo 3pm"
.TH HTML::Gumbo 3pm "2020-11-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::Gumbo \- HTML5 parser based on gumbo C library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use HTML::Gumbo;
\&    say HTML::Gumbo\->new\->parse(\*(Aq<div></div>\*(Aq);
\&
\&    say HTML::Gumbo\->new\->parse(\*(Aq<h1>Hello</h1>\*(Aq, format => \*(Aqtree\*(Aq)\->as_HTML;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Gumbo <https://github.com/google/gumbo-parser> is an implementation
of the \s-1HTML5\s0 parsing algorithm <http://www.w3.org/TR/html5/syntax.html>
implemented as a pure C99 library with no outside dependencies.
.PP
Goals and features of the C library:
.IP "\(bu" 4
Fully conformant with the \s-1HTML5\s0 spec.
.IP "\(bu" 4
Robust and resilient to bad input.
.IP "\(bu" 4
Simple \s-1API\s0 that can be easily wrapped by other languages. (This is one of such wrappers.)
.IP "\(bu" 4
Support for source locations and pointers back to the original text.
(Not exposed by this implementation at the moment.)
.IP "\(bu" 4
Relatively lightweight, with no outside dependencies.
.IP "\(bu" 4
Passes all html5lib\-0.95 tests.
.IP "\(bu" 4
Tested on over 2.5 billion pages from Google's index.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    my $parser = HTML::Gumbo\->new;
.Ve
.PP
No options at the moment.
.SS "parse"
.IX Subsection "parse"
.Vb 5
\&    my $res = $parser\->parse(
\&        "<h1>hello world!</h1>",
\&        format => \*(Aqtree\*(Aq,
\&        input_is => \*(Aqstring\*(Aq,
\&    );
.Ve
.PP
Takes html string and pairs of named arguments:
.IP "format" 4
.IX Item "format"
Output format, default is string. See \*(L"\s-1SUPPORTED OUTPUT FORMATS\*(R"\s0.
.IP "fragment_namespace" 4
.IX Item "fragment_namespace"
Enables fragments parsing algorithm. Pass either '\s-1HTML\s0', '\s-1SVG\s0' or '\s-1MATHML\s0'
to enable and set namespace. Without this input is parsed as html document,
so html, head, title and body tags are added if absent.
.Sp
\&\fBNote\fR that fragment_enclosing_tag is set to '<body>' and can not be changed
at the moment. Feel free to send patches implementing this part.
.Sp
See \*(L"\s-1SUPPORTED OUTPUT FORMATS\*(R"\s0 for additional details.
.Sp
\&\fBNote\fR that \s-1SVG\s0 and \s-1MATHML\s0 parsing is not tested, feel free to file bug reports
with tests in case it doesn't work.
.IP "input_is" 4
.IX Item "input_is"
Whether html is perl 'string', 'octets' or 'utf8' (octets known to
be utf8). See \*(L"\s-1CHARACTER ENCODING OF THE INPUT\*(R"\s0.
.IP "encoding, encoding_content_type, encoding_tentative" 4
.IX Item "encoding, encoding_content_type, encoding_tentative"
See \*(L"\s-1CHARACTER ENCODING OF THE INPUT\*(R"\s0.
.IP "..." 4
Some formatters may have additional arguments, see \*(L"\s-1SUPPORTED OUTPUT FORMATS\*(R"\s0
.PP
Return value depends on the picked format.
.SH "SUPPORTED OUTPUT FORMATS"
.IX Header "SUPPORTED OUTPUT FORMATS"
.SS "string"
.IX Subsection "string"
\&\s-1HTML\s0 is parsed and re-built from the tree, so tags are balanced
(except void elements).
.PP
No additional arguments specific for this format.
.PP
.Vb 1
\&    $html = HTML::Gumbo\->new\->parse( $html );
.Ve
.SS "callback"
.IX Subsection "callback"
HTML::Parser like interface. Pass a sub as \f(CW\*(C`callback\*(C'\fR argument to
\&\*(L"parse\*(R" method and it will be called for every node in the document:
.PP
.Vb 10
\&    HTML::Gumbo\->new\->parse( $html, format => \*(Aqcallback\*(Aq, callback => sub {
\&        my ($event) = shift;
\&        if ( $event eq \*(Aqdocument start\*(Aq ) {
\&            my ($doctype) = @_;
\&        }
\&        elsif ( $event eq \*(Aqdocument end\*(Aq ) {
\&        }
\&        elsif ( $event eq \*(Aqstart\*(Aq ) {
\&            my ($tag, $attrs) = @_;
\&        }
\&        elsif ( $event eq \*(Aqend\*(Aq ) {
\&            my ($tag) = @_;
\&        }
\&        elsif ( $event eq /^(text|space|cdata|comment)$/ ) {
\&            my ($text) = @_;
\&        }
\&        else {
\&            die "Unknown event";
\&        }
\&    } );
.Ve
.PP
Note that 'end' events are not generated for
void elements <http://www.w3.org/TR/html5/syntax.html#void-elements>,
for example \f(CW\*(C`hr\*(C'\fR, \f(CW\*(C`br\*(C'\fR and \f(CW\*(C`img\*(C'\fR.
.PP
No additional arguments except mentioned \f(CW\*(C`callback\*(C'\fR.
.PP
Fragment parsing still generates 'document start' and 'document end' events what
can be handy to initialize your parsing callback.
.SS "tree"
.IX Subsection "tree"
Alpha stage.
.PP
Produces tree based on HTML::Elements, like HTML::TreeBuilder.
.PP
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.
.PP
Fragments parsing still produces top level 'document' element as fragment
can be a list of tags, for example: '<p>hello</p><p>world</p'.
.PP
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.
.SH "CHARACTER ENCODING OF THE INPUT"
.IX Header "CHARACTER ENCODING OF THE INPUT"
The C parser works only with \s-1UTF\-8,\s0 so you have several options to make
sure input is \s-1UTF\-8.\s0 First of all define \f(CW\*(C`input_is\*(C'\fR argument:
.IP "string" 4
.IX Item "string"
Input is Perl string, for example obtained from \*(L"decoded_content\*(R" in HTTP::Response.
Default value.
.Sp
.Vb 1
\&    $gumbo\->parse( decode_utf8($octets) );
.Ve
.IP "octets" 4
.IX Item "octets"
Input are octets. Partial implementation of
encoding sniffing algorithm <http://www.w3.org/TR/html5/syntax.html#encoding-sniffing-algorithm>
is used. First thing wins:
.RS 4
.ie n .IP """encoding"" argument" 4
.el .IP "\f(CWencoding\fR argument" 4
.IX Item "encoding argument"
Use it to hardcode a specific encoding.
.Sp
.Vb 1
\&    $gumbo\->parse( $octets, input_is => \*(Aqoctets\*(Aq, encoding => \*(Aqlatin\-1\*(Aq );
.Ve
.IP "\s-1BOM\s0" 4
.IX Item "BOM"
\&\s-1UTF\-8/UTF\-16\s0 BOMs are checked.
.ie n .IP """encoding_content_type"" argument" 4
.el .IP "\f(CWencoding_content_type\fR argument" 4
.IX Item "encoding_content_type argument"
Encdoning from rransport layer, charset in content-type header.
.Sp
.Vb 1
\&    $gumbo\->parse( $octets, input_is => \*(Aqoctets\*(Aq, encoding_content_type => \*(Aqlatin\-1\*(Aq );
.Ve
.IP "Prescan" 4
.IX Item "Prescan"
Not implemented, follow issue 58 <https://github.com/google/gumbo-parser/issues/58>.
.Sp
\&\s-1HTML5\s0 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.
.Sp
It would be cool to get it in the C library, but I will accept a patch that impements it in pure perl.
.ie n .IP """encoding_tentative"" argument" 4
.el .IP "\f(CWencoding_tentative\fR argument" 4
.IX Item "encoding_tentative argument"
The likely encoding for this page, e.g. based on the encoding of the
page when it was last visited.
.Sp
.Vb 1
\&    $gumbo\->parse( $octets, input_is => \*(Aqoctets\*(Aq, encoding_tentative => \*(Aqlatin\-1\*(Aq );
.Ve
.IP "nested browsing context" 4
.IX Item "nested browsing context"
Not implemented. Fragment parsing with or without context is not implemented. Parser
also has no origin information, so it wouldn't be implemented.
.IP "autodetection" 4
.IX Item "autodetection"
Not implemented.
.Sp
Can be implemented using Encode::Detect::Detector. Patches are welcome.
.IP "otherwise" 4
.IX Item "otherwise"
It \fBdies\fR.
.RE
.RS 4
.RE
.ie n .IP """utf8""" 4
.el .IP "\f(CWutf8\fR" 4
.IX Item "utf8"
Use utf8 as input_is when you're sure input is \s-1UTF\-8,\s0 but octets.
No pre-processing at all. Should only be used on trusted input or
when it's preprocessed already.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ruslan Zakirov <ruz@bestpractical.com>
.SH "LICENSE"
.IX Header "LICENSE"
Under the same terms as perl itself.