.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "HTML::HTML5::Parser 3pm"
.TH HTML::HTML5::Parser 3pm "2022-08-28" "perl v5.34.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::HTML5::Parser \- parse HTML reliably
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use HTML::HTML5::Parser;
\&
\& my $parser = HTML::HTML5::Parser\->new;
\& my $doc = $parser\->parse_string(<<\*(AqEOT\*(Aq);
\&
\&
Foo
\& Foo bar.
\&
BazQuux.
\& EOT
\&
\& my $fdoc = $parser\->parse_file( $html_file_name );
\& my $fhdoc = $parser\->parse_fh( $html_file_handle );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This library is substantially the same as the non-CPAN module Whatpm::HTML.
Changes include:
.IP "\(bu" 8
Provides an XML::LibXML\-like \s-1DOM\s0 interface. If you usually use XML::LibXML's \s-1DOM\s0 parser, this should be a drop-in solution for tag soup \s-1HTML.\s0
.IP "\(bu" 8
Constructs an XML::LibXML::Document as the result of parsing.
.IP "\(bu" 8
Via bundling and modifications, removed external dependencies on non-CPAN packages.
.SS "Constructor"
.IX Subsection "Constructor"
.ie n .IP """new""" 8
.el .IP "\f(CWnew\fR" 8
.IX Item "new"
.Vb 3
\& $parser = HTML::HTML5::Parser\->new;
\& # or
\& $parser = HTML::HTML5::Parser\->new(no_cache => 1);
.Ve
.Sp
The constructor does nothing interesting besides take one flag
argument, \f(CW\*(C`no_cache => 1\*(C'\fR, 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
\&\f(CW\*(C`/source_line\*(C'\fR will not work, and must be run from an instance of
this parser.
.SS "XML::LibXML\-Compatible Methods"
.IX Subsection "XML::LibXML-Compatible Methods"
.ie n .IP """parse_file"", ""parse_html_file""" 4
.el .IP "\f(CWparse_file\fR, \f(CWparse_html_file\fR" 4
.IX Item "parse_file, parse_html_file"
.Vb 1
\& $doc = $parser\->parse_file( $html_file_name [,\e%opts] );
.Ve
.Sp
This function parses an \s-1HTML\s0 document from a file or network;
\&\f(CW$html_file_name\fR can be either a filename or an \s-1URL.\s0
.Sp
Options include 'encoding' to indicate file encoding (e.g.
\&'utf\-8') and 'user_agent' which should be a blessed \f(CW\*(C`LWP::UserAgent\*(C'\fR
(or HTTP::Tiny) object to be used when retrieving URLs.
.Sp
If requesting a \s-1URL\s0 and the response Content-Type header indicates
an XML-based media type (such as \s-1XHTML\s0), XML::LibXML::Parser
will be used automatically (instead of the tag soup parser). The \s-1XML\s0
parser can be told to use a \s-1DTD\s0 catalogue by setting the option
\&'xml_catalogue' to the filename of the catalogue.
.Sp
\&\s-1HTML\s0 (tag soup) parsing can be forced using the option 'force_html', even
when an \s-1XML\s0 media type is returned. If an options hashref was passed,
parse_file will set \f(CW$options\fR\->{'parser_used'} to the name of the class used
to parse the \s-1URL,\s0 to allow the calling code to double-check which parser
was used afterwards.
.Sp
If an options hashref was passed, parse_file will set \f(CW$options\fR\->{'response'}
to the HTTP::Response object obtained by retrieving the \s-1URI.\s0
.ie n .IP """parse_fh"", ""parse_html_fh""" 4
.el .IP "\f(CWparse_fh\fR, \f(CWparse_html_fh\fR" 4
.IX Item "parse_fh, parse_html_fh"
.Vb 1
\& $doc = $parser\->parse_fh( $io_fh [,\e%opts] );
.Ve
.Sp
\&\f(CW\*(C`parse_fh()\*(C'\fR parses a \s-1IOREF\s0 or a subclass of \f(CW\*(C`IO::Handle\*(C'\fR.
.Sp
Options include 'encoding' to indicate file encoding (e.g.
\&'utf\-8').
.ie n .IP """parse_string"", ""parse_html_string""" 4
.el .IP "\f(CWparse_string\fR, \f(CWparse_html_string\fR" 4
.IX Item "parse_string, parse_html_string"
.Vb 1
\& $doc = $parser\->parse_string( $html_string [,\e%opts] );
.Ve
.Sp
This function is similar to \f(CW\*(C`parse_fh()\*(C'\fR, but it parses an \s-1HTML\s0
document that is available as a single string in memory.
.Sp
Options include 'encoding' to indicate file encoding (e.g.
\&'utf\-8').
.ie n .IP """load_xml"", ""load_html""" 4
.el .IP "\f(CWload_xml\fR, \f(CWload_html\fR" 4
.IX Item "load_xml, load_html"
Wrappers for the parse_* functions. These should be roughly compatible with
the equivalently named functions in XML::LibXML.
.Sp
Note that \f(CW\*(C`load_xml\*(C'\fR first attempts to parse as real \s-1XML,\s0 falling back to
\&\s-1HTML5\s0 parsing; \f(CW\*(C`load_html\*(C'\fR just goes straight for \s-1HTML5.\s0
.ie n .IP """parse_balanced_chunk""" 4
.el .IP "\f(CWparse_balanced_chunk\fR" 4
.IX Item "parse_balanced_chunk"
.Vb 1
\& $fragment = $parser\->parse_balanced_chunk( $string [,\e%opts] );
.Ve
.Sp
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 \*(L"balanced\*(R". 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...
.Sp
Consider the following string:
.Sp
.Vb 1
\& Hello World
.Ve
.Sp
What is the proper way to parse that? If it were found in a document like
this:
.Sp
.Vb 8
\&
\&
X
\&
\&
\& Hello World
\&
\&
\&
.Ve
.Sp
Then the document would end up equivalent to the following \s-1XHTML:\s0
.Sp
.Vb 8
\&
\& X
\&
\&
\& Hello World
\&
\&
\&
.Ve
.Sp
The superfluous \f(CW\*(C`\*(C'\fR is simply ignored. However, if it
were found in a document like this:
.Sp
.Vb 8
\&
\& X
\&
\&
\&
\&
.Ve
.Sp
Then the result would be:
.Sp
.Vb 9
\&
\& X
\&
\& World
\&
\&
\&
.Ve
.Sp
Yes, \f(CW\*(C`World\*(C'\fR gets hoisted up before the \f(CW\*(C`\*(C'\fR. This
is weird, I know, but it's how browsers do it in real life.
.Sp
So what should:
.Sp
.Vb 2
\& $string = q{Hello World};
\& $fragment = $parser\->parse_balanced_chunk($string);
.Ve
.Sp
actually return? Well, you can choose...
.Sp
.Vb 1
\& $string = q{Hello World};
\&
\& $frag1 = $parser\->parse_balanced_chunk($string, {within=>\*(Aqdiv\*(Aq});
\& say $frag1\->toString; # Hello World
\&
\& $frag2 = $parser\->parse_balanced_chunk($string, {within=>\*(Aqtd\*(Aq});
\& say $frag2\->toString; # WorldHello
.Ve
.Sp
If you don't pass a \*(L"within\*(R" option, then the chunk is parsed as if it
were within a \f(CW\*(C`\*(C'\fR element. This is often the most sensible
option. If you pass something like \f(CW\*(C`{ within => "foobar" }\*(C'\fR
where \*(L"foobar\*(R" is not a real \s-1HTML\s0 element name (as found in the \s-1HTML5\s0
spec), then this method will croak; if you pass the name of a void
element (e.g. \f(CW"br"\fR or \f(CW"meta"\fR) then this method will
croak; there are a handful of other unsupported elements which will
croak (namely: \f(CW"noscript"\fR, \f(CW"noembed"\fR, \f(CW"noframes"\fR).
.Sp
Note that the second time around, although we parsed the string "as
if it were within a \f(CW\*(C`
\*(C'\fR element", the \f(CW\*(C`Hello\*(C'\fR
bit did not strictly end up within the \f(CW\*(C` | \*(C'\fR element (not
even within the \f(CW\*(C`\*(C'\fR element!) yet it still gets returned.
We'll call things such as this \*(L"outliers\*(R". There is a \*(L"force_within\*(R"
option which tells parse_balanced_chunk to ignore outliers:
.Sp
.Vb 3
\& $frag3 = $parser\->parse_balanced_chunk($string,
\& {force_within=>\*(Aqtd\*(Aq});
\& say $frag3\->toString; # Hello
.Ve
.Sp
There is a boolean option \*(L"mark_outliers\*(R" which marks each outlier
with an attribute (\f(CW\*(C`data\-perl\-html\-html5\-parser\-outlier\*(C'\fR) to
indicate its outlier status. Clearly, this is ignored when you use
\&\*(L"force_within\*(R" 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.
.Sp
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:
.Sp
.Vb 2
\& # Get an XML::LibXML::NodeList
\& my $list = $parser\->parse_balanced_chunk($str, {as=>\*(Aqlist\*(Aq});
.Ve
.Sp
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 \s-1HTML\s0 fragments when implementing the setter
for \s-1DOM\s0's \f(CW\*(C`innerHTML\*(C'\fR attribute.
.PP
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.)
.SS "Error Handling"
.IX Subsection "Error Handling"
Error handling is obviously different to XML::LibXML, as errors are
(bugs notwithstanding) non-fatal.
.ie n .IP """error_handler""" 4
.el .IP "\f(CWerror_handler\fR" 4
.IX Item "error_handler"
Get/set an error handling function. Must be set to a coderef or undef.
.Sp
The error handling function will be called with a single parameter, a
HTML::HTML5::Parser::Error object.
.ie n .IP """errors""" 4
.el .IP "\f(CWerrors\fR" 4
.IX Item "errors"
Returns a list of errors that occurred during the last parse.
.Sp
See HTML::HTML5::Parser::Error.
.SS "Additional Methods"
.IX Subsection "Additional Methods"
The module provides a few methods to obtain additional, non-DOM data from
\&\s-1DOM\s0 nodes.
.ie n .IP """dtd_public_id""" 4
.el .IP "\f(CWdtd_public_id\fR" 4
.IX Item "dtd_public_id"
.Vb 1
\& $pubid = $parser\->dtd_public_id( $doc );
.Ve
.Sp
For an XML::LibXML::Document which has been returned by
HTML::HTML5::Parser, using this method will tell you the
Public Identifier of the \s-1DTD\s0 used (if any).
.ie n .IP """dtd_system_id""" 4
.el .IP "\f(CWdtd_system_id\fR" 4
.IX Item "dtd_system_id"
.Vb 1
\& $sysid = $parser\->dtd_system_id( $doc );
.Ve
.Sp
For an XML::LibXML::Document which has been returned by
HTML::HTML5::Parser, using this method will tell you the
System Identifier of the \s-1DTD\s0 used (if any).
.ie n .IP """dtd_element""" 4
.el .IP "\f(CWdtd_element\fR" 4
.IX Item "dtd_element"
.Vb 1
\& $element = $parser\->dtd_element( $doc );
.Ve
.Sp
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 \s-1DTD\s0 used (if any). That is,
if the document has this doctype:
.Sp
.Vb 1
\&
.Ve
.Sp
\&... it will return \*(L"html\*(R".
.Sp
This may return the empty string if a \s-1DTD\s0 was present but
did not contain a root element; or undef if no \s-1DTD\s0 was
present.
.ie n .IP """compat_mode""" 4
.el .IP "\f(CWcompat_mode\fR" 4
.IX Item "compat_mode"
.Vb 1
\& $mode = $parser\->compat_mode( $doc );
.Ve
.Sp
Returns 'quirks', 'limited quirks' or undef (standards mode).
.ie n .IP """charset""" 4
.el .IP "\f(CWcharset\fR" 4
.IX Item "charset"
.Vb 1
\& $charset = $parser\->charset( $doc );
.Ve
.Sp
The character set apparently used by the document.
.ie n .IP """source_line""" 4
.el .IP "\f(CWsource_line\fR" 4
.IX Item "source_line"
.Vb 2
\& ($line, $col) = $parser\->source_line( $node );
\& $line = $parser\->source_line( $node );
.Ve
.Sp
In scalar context, \f(CW\*(C`source_line\*(C'\fR returns the line number of the
source code that started a particular node (element, attribute or
comment).
.Sp
In list context, returns a tuple: \f(CW$line\fR, \f(CW$column\fR, \f(CW$implicitness\fR.
Tab characters count as one column, not eight.
.Sp
\&\f(CW$implicitness\fR 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 \s-1HTML, TITLE\s0 and P elements
are explicit, but the \s-1HEAD\s0 and \s-1BODY\s0 elements are implicit.
.Sp
.Vb 4
\&
\& I have an implicit head
\& And an implicit body too!
\&
.Ve
.Sp
(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.
.Sp
XML::LibXML::Node has a \f(CW\*(C`line_number\*(C'\fR 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 \f(CW\*(C`line_number\*(C'\fR method will start working (at least for
elements).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.
.PP
HTML::HTML5::Writer,
HTML::HTML5::Builder,
XML::LibXML,
XML::LibXML::PrettyPrint,
XML::LibXML::Devel::SetLineNumber.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster,
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
Copyright (C) 2007\-2011 by Wakaba
.PP
Copyright (C) 2009\-2012 by Toby Inkster
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0
|