Provided by: libhtml-gumbo-perl_0.18-3build5_amd64 bug

NAME

       HTML::Gumbo - HTML5 parser based on gumbo C library

SYNOPSIS

           use HTML::Gumbo;
           say HTML::Gumbo->new->parse('<div></div>');

           say HTML::Gumbo->new->parse('<h1>Hello</h1>', format => 'tree')->as_HTML;

DESCRIPTION

       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:

       •   Fully conformant with the HTML5 spec.

       •   Robust and resilient to bad input.

       •   Simple API that can be easily wrapped by other languages. (This is one of such
           wrappers.)

       •   Support for source locations and pointers back to the original text.  (Not exposed by
           this implementation at the moment.)

       •   Relatively lightweight, with no outside dependencies.

       •   Passes all html5lib-0.95 tests.

       •   Tested on over 2.5 billion pages from Google's index.

METHODS

   new
           my $parser = HTML::Gumbo->new;

       No options at the moment.

   parse
           my $res = $parser->parse(
               "<h1>hello world!</h1>",
               format => 'tree',
               input_is => 'string',
           );

       Takes html string and pairs of named arguments:

       format
           Output format, default is string. See "SUPPORTED OUTPUT FORMATS".

       fragment_namespace
           Enables fragments parsing algorithm. Pass either 'HTML', 'SVG' or 'MATHML' to enable
           and set namespace. Without this input is parsed as html document, so html, head, title
           and body tags are added if absent.

           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.

       input_is
           Whether html is perl 'string', 'octets' or 'utf8' (octets known to be utf8). See
           "CHARACTER ENCODING OF THE INPUT".

       encoding, encoding_content_type, encoding_tentative
           See "CHARACTER ENCODING OF THE INPUT".

       ... Some formatters may have additional arguments, see "SUPPORTED OUTPUT FORMATS"

       Return value depends on the picked format.

SUPPORTED OUTPUT FORMATS

   string
       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 );

   callback
       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.

   tree
       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.

CHARACTER ENCODING OF THE INPUT

       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:

       string
           Input is Perl string, for example obtained from "decoded_content" in HTTP::Response.
           Default value.

               $gumbo->parse( decode_utf8($octets) );

       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:

           "encoding" argument
               Use it to hardcode a specific encoding.

                   $gumbo->parse( $octets, input_is => 'octets', encoding => 'latin-1' );

           BOM UTF-8/UTF-16 BOMs are checked.

           "encoding_content_type" argument
               Encdoning from rransport layer, charset in content-type header.

                   $gumbo->parse( $octets, input_is => 'octets', encoding_content_type => 'latin-1' );

           Prescan
               Not implemented, follow issue 58 <https://github.com/google/gumbo-
               parser/issues/58>.

               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.

           "encoding_tentative" argument
               The likely encoding for this page, e.g. based on the encoding of the page when it
               was last visited.

                   $gumbo->parse( $octets, input_is => 'octets', encoding_tentative => 'latin-1' );

           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.

           autodetection
               Not implemented.

               Can be implemented using Encode::Detect::Detector. Patches are welcome.

           otherwise
               It dies.

       "utf8"
           Use utf8 as input_is when you're sure input is UTF-8, but octets.  No pre-processing
           at all. Should only be used on trusted input or when it's preprocessed already.

AUTHOR

       Ruslan Zakirov <ruz@bestpractical.com>

LICENSE

       Under the same terms as perl itself.