.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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::HTML5::Parser 3pm" .TH HTML::HTML5::Parser 3pm "2013-07-08" "perl v5.14.2" "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 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 \& \&
\& Hello |
\& Hello |
\*(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` |