cdata results from the CPAN

cdata
HTML-Gumbo
view release on metacpan or search on metacpan
=item 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.

B<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 L</SUPPORTED OUTPUT FORMATS> for additional details.

B<Note> that SVG and MATHML parsing is not tested, feel free to file bug reports
with tests in case it doesn't work.

=item input_is

Whether html is perl 'string', 'octets' or 'utf8' (octets known to
be utf8). See L</CHARACTER ENCODING OF THE INPUT>.

=item encoding, encoding_content_type, encoding_tentative

See L</CHARACTER ENCODING OF THE INPUT>.

=item ...

Some formatters may have additional arguments, see L</SUPPORTED OUTPUT FORMATS>

=back

Return value depends on the picked format.

=head1 SUPPORTED OUTPUT FORMATS

=head2 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 );

=head2 callback

L<HTML::Parser> like interface. Pass a sub as C<callback> argument to
L</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 =~ /^(text|space|cdata|comment)$/ ) {
            my ($text) = @_;
        }
        else {
            die "Unknown event";
        }
    } );

Note that 'end' events are not generated for
L<void elements|http://www.w3.org/TR/html5/syntax.html#void-elements>,
for example C<hr>, C<br> and C<img>.

No additional arguments except mentioned C<callback>.

Fragment parsing still generates 'document start' and 'document end' events what
can be handy to initialize your parsing callback.

=head2 tree

Alpha stage.

Produces tree based on L<HTML::Element>s, like L<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 L<HTML::Element> or implements a small subset of methods of HTML::Element.

=head1 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 C<input_is> argument:

=over 4

=item string

Input is Perl string, for example obtained from L<HTTP::Response/decoded_content>.
Default value.

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

=item octets

Input are octets. Partial implementation of
L<encoding sniffing algorithm|http://www.w3.org/TR/html5/syntax.html#encoding-sniffing-algorithm>
is used. First thing wins:

=over 4

=item C<encoding> argument

Use it to hardcode a specific encoding.
( run in 3.528 seconds using v1.01-cache-2.11-cpan-7fcb06a456a )