NAME
    HTML::HTML5::Parser - parse HTML reliably

SYNOPSIS
      use HTML::HTML5::Parser;
  
      my $parser = HTML::HTML5::Parser->new;
      my $doc    = $parser->parse_string(<<'EOT');
      <!doctype html>
      <title>Foo</title>
      <p><b><i>Foo</b> bar</i>.
      <p>Baz</br>Quux.
      EOT
  
      my $fdoc   = $parser->parse_file( $html_file_name );
      my $fhdoc  = $parser->parse_fh( $html_file_handle );

DESCRIPTION
    This library is substantially the same as the non-CPAN module
    Whatpm::HTML. Changes include:

    *       Provides an XML::LibXML-like DOM interface. If you usually use
            XML::LibXML's DOM parser, this should be a drop-in solution for
            tag soup HTML.

    *       Constructs an XML::LibXML::Document as the result of parsing.

    *       Via bundling and modifications, removed external dependencies on
            non-CPAN packages.

  Constructor
    `new`
              $parser = HTML::HTML5::Parser->new;
              # or
              $parser = HTML::HTML5::Parser->new(no_cache => 1);

            The constructor does nothing interesting besides take one flag
            argument, `no_cache => 1`, to disable the global element metadata
            cache. Disabling the cache is handy for conserving memory if you
            parse a large number of documents, however, class methods such as
            `/source_line` will not work, and must be run from an instance of
            this parser.

  XML::LibXML-Compatible Methods
    `parse_file`, `parse_html_file`
          $doc = $parser->parse_file( $html_file_name [,\%opts] );

        This function parses an HTML document from a file or network;
        $html_file_name can be either a filename or an URL.

        Options include 'encoding' to indicate file encoding (e.g. 'utf-8')
        and 'user_agent' which should be a blessed `LWP::UserAgent` (or
        HTTP::Tiny) object to be used when retrieving URLs.

        If requesting a URL and the response Content-Type header indicates an
        XML-based media type (such as XHTML), XML::LibXML::Parser will be used
        automatically (instead of the tag soup parser). The XML parser can be
        told to use a DTD catalogue by setting the option 'xml_catalogue' to
        the filename of the catalogue.

        HTML (tag soup) parsing can be forced using the option 'force_html',
        even when an XML media type is returned. If an options hashref was
        passed, parse_file will set $options->{'parser_used'} to the name of
        the class used to parse the URL, to allow the calling code to
        double-check which parser was used afterwards.

        If an options hashref was passed, parse_file will set
        $options->{'response'} to the HTTP::Response object obtained by
        retrieving the URI.

    `parse_fh`, `parse_html_fh`
          $doc = $parser->parse_fh( $io_fh [,\%opts] );

        `parse_fh()` parses a IOREF or a subclass of `IO::Handle`.

        Options include 'encoding' to indicate file encoding (e.g. 'utf-8').

    `parse_string`, `parse_html_string`
          $doc = $parser->parse_string( $html_string [,\%opts] );

        This function is similar to `parse_fh()`, but it parses an HTML
        document that is available as a single string in memory.

        Options include 'encoding' to indicate file encoding (e.g. 'utf-8').

    `load_xml`, `load_html`
        Wrappers for the parse_* functions. These should be roughly compatible
        with the equivalently named functions in XML::LibXML.

        Note that `load_xml` first attempts to parse as real XML, falling back
        to HTML5 parsing; `load_html` just goes straight for HTML5.

    `parse_balanced_chunk`
          $fragment = $parser->parse_balanced_chunk( $string [,\%opts] );

        This method is roughly equivalent to XML::LibXML's method of the same
        name, but unlike XML::LibXML, and despite its name it does not require
        the chunk to be "balanced". This method is somewhat black magic, but
        should work, and do the proper thing in most cases. Of course, the
        proper thing might not be what you'd expect! I'll try to keep this
        explanation as brief as possible...

        Consider the following string:

          <b>Hello</b></td></tr> <i>World</i>

        What is the proper way to parse that? If it were found in a document
        like this:

          <html>
            <head><title>X</title></head>
            <body>
              <div>
                <b>Hello</b></td></tr> <i>World</i>
              </div>
            </body>
          </html>

        Then the document would end up equivalent to the following XHTML:

          <html>
            <head><title>X</title></head>
            <body>
              <div>
                <b>Hello</b> <i>World</i>
              </div>
            </body>
          </html>

        The superfluous `</td></tr>` is simply ignored. However, if it were
        found in a document like this:

          <html>
            <head><title>X</title></head>
            <body>
              <table><tbody><tr><td>
                <b>Hello</b></td></tr> <i>World</i>
              </td></tr></tbody></table>
            </body>
          </html>

        Then the result would be:

          <html>
            <head><title>X</title></head>
            <body>
              <i>World</i>
              <table><tbody><tr><td>
                <b>Hello</b></td></tr>
              </tbody></table>
            </body>
          </html>

        Yes, `<i>World</i>` gets hoisted up before the `<table>`. This is
        weird, I know, but it's how browsers do it in real life.

        So what should:

          $string   = q{<b>Hello</b></td></tr> <i>World</i>};
          $fragment = $parser->parse_balanced_chunk($string);

        actually return? Well, you can choose...

          $string = q{<b>Hello</b></td></tr> <i>World</i>};
  
          $frag1  = $parser->parse_balanced_chunk($string, {within=>'div'});
          say $frag1->toString; # <b>Hello</b> <i>World</i>
  
          $frag2  = $parser->parse_balanced_chunk($string, {within=>'td'});
          say $frag2->toString; # <i>World</i><b>Hello</b>

        If you don't pass a "within" option, then the chunk is parsed as if it
        were within a `<div>` element. This is often the most sensible option.
        If you pass something like `{ within => "foobar" }` where "foobar" is
        not a real HTML element name (as found in the HTML5 spec), then this
        method will croak; if you pass the name of a void element (e.g. "br"
        or "meta") then this method will croak; there are a handful of other
        unsupported elements which will croak (namely: "noscript", "noembed",
        "noframes").

        Note that the second time around, although we parsed the string "as if
        it were within a `<td>` element", the `<i>Hello</i>` bit did not
        strictly end up within the `<td>` element (not even within the
        `<table>` element!) yet it still gets returned. We'll call things such
        as this "outliers". There is a "force_within" option which tells
        parse_balanced_chunk to ignore outliers:

          $frag3  = $parser->parse_balanced_chunk($string,
                                                  {force_within=>'td'});
          say $frag3->toString; # <b>Hello</b>

        There is a boolean option "mark_outliers" which marks each outlier
        with an attribute (`data-perl-html-html5-parser-outlier`) to indicate
        its outlier status. Clearly, this is ignored when you use
        "force_within" because no outliers are returned. Some outliers may be
        XML::LibXML::Text elements; text nodes don't have attributes, so these
        will not be marked with an attribute.

        A last note is to mention what gets returned by this method. Normally
        it's an XML::LibXML::DocumentFragment object, but if you call the
        method in list context, a list of the individual node elements is
        returned. Alternatively you can request the data to be returned as an
        XML::LibXML::NodeList object:

         # Get an XML::LibXML::NodeList
         my $list = $parser->parse_balanced_chunk($str, {as=>'list'});

        The exact implementation of this method may change from version to
        version, but the long-term goal will be to approach how common desktop
        browsers parse HTML fragments when implementing the setter for DOM's
        `innerHTML` attribute.

    The push parser and SAX-based parser are not supported. Trying to change
    an option (such as recover_silently) will make HTML::HTML5::Parser carp a
    warning. (But you can inspect the options.)

  Error Handling
    Error handling is obviously different to XML::LibXML, as errors are (bugs
    notwithstanding) non-fatal.

    `error_handler`
        Get/set an error handling function. Must be set to a coderef or undef.

        The error handling function will be called with a single parameter, a
        HTML::HTML5::Parser::Error object.

    `errors`
        Returns a list of errors that occurred during the last parse.

        See HTML::HTML5::Parser::Error.

  Additional Methods
    The module provides a few methods to obtain additional, non-DOM data from
    DOM nodes.

    `dtd_public_id`
          $pubid = $parser->dtd_public_id( $doc );

        For an XML::LibXML::Document which has been returned by
        HTML::HTML5::Parser, using this method will tell you the Public
        Identifier of the DTD used (if any).

    `dtd_system_id`
          $sysid = $parser->dtd_system_id( $doc );

        For an XML::LibXML::Document which has been returned by
        HTML::HTML5::Parser, using this method will tell you the System
        Identifier of the DTD used (if any).

    `dtd_element`
          $element = $parser->dtd_element( $doc );

        For an XML::LibXML::Document which has been returned by
        HTML::HTML5::Parser, using this method will tell you the root element
        declared in the DTD used (if any). That is, if the document has this
        doctype:

          <!doctype html>

        ... it will return "html".

        This may return the empty string if a DTD was present but did not
        contain a root element; or undef if no DTD was present.

    `compat_mode`
          $mode = $parser->compat_mode( $doc );

        Returns 'quirks', 'limited quirks' or undef (standards mode).

    `charset`
          $charset = $parser->charset( $doc );

        The character set apparently used by the document.

    `source_line`
          ($line, $col) = $parser->source_line( $node );
          $line = $parser->source_line( $node );

        In scalar context, `source_line` returns the line number of the source
        code that started a particular node (element, attribute or comment).

        In list context, returns a tuple: $line, $column, $implicitness. Tab
        characters count as one column, not eight.

        $implicitness indicates that the node was not explicitly marked up in
        the source code, but its existence was inferred by the parser. For
        example, in the following markup, the HTML, TITLE and P elements are
        explicit, but the HEAD and BODY elements are implicit.

         <html>
          <title>I have an implicit head</title>
          <p>And an implicit body too!</p>
         </html>

        (Note that implicit elements do still have a line number and column
        number.) The implictness indicator is a new feature, and I'd
        appreciate any bug reports where it gets things wrong.

        XML::LibXML::Node has a `line_number` method. In general this will
        always return 0 and HTML::HTML5::Parser has no way of influencing it.
        However, if you install XML::LibXML::Devel::SetLineNumber on your
        system, the `line_number` method will start working (at least for
        elements).

SEE ALSO
    <http://suika.fam.cx/www/markup/html/whatpm/Whatpm/HTML.html>.

    HTML::HTML5::Writer, HTML::HTML5::Builder, XML::LibXML,
    XML::LibXML::PrettyPrint, XML::LibXML::Devel::SetLineNumber.

AUTHOR
    Toby Inkster, <tobyink@cpan.org>

COPYRIGHT AND LICENCE
    Copyright (C) 2007-2011 by Wakaba

    Copyright (C) 2009-2012 by Toby Inkster

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

