html::parser.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

.Vb 1
\&  </A>
.Ve
.ie n .IP """end_document""" 4
.el .IP "\f(CWend_document\fR" 4
.IX Item "end_document"
This event is triggered when \f(CW$p\fR\->eof is called and after any remaining
text is flushed.  There is no document text associated with this event.
.ie n .IP """process""" 4
.el .IP "\f(CWprocess\fR" 4
.IX Item "process"
This event is triggered when a processing instructions markup is
recognized.
.Sp
The format and content of processing instructions are system and
application dependent.
.Sp
Examples:
.Sp
.Vb 2
\&  <? HTML processing instructions >
\&  <? XML processing instructions ?>
.Ve
.ie n .IP """start""" 4
.el .IP "\f(CWstart\fR" 4
.IX Item "start"
This event is triggered when a start tag is recognized.
.Sp
Example:
.Sp
.Vb 1
\&  <A HREF="http://www.perl.com/">
.Ve
.ie n .IP """start_document""" 4
.el .IP "\f(CWstart_document\fR" 4
.IX Item "start_document"
This event is triggered before any other events for a new document.  A
handler for it can be used to initialize stuff.  There is no document
text associated with this event.
.ie n .IP """text""" 4
.el .IP "\f(CWtext\fR" 4
.IX Item "text"
This event is triggered when plain text (characters) is recognized.
The text may contain multiple lines.  A sequence of text may be broken
between several text events unless \f(CW$p\fR\->unbroken_text is enabled.
.Sp
The parser will make sure that it does not break a word or a sequence
of whitespace between two text events.
.Sh "Unicode"
.IX Subsection "Unicode"
The \f(CW\*(C`HTML::Parser\*(C'\fR can parse Unicode strings when running under
perl\-5.8 or better.  If Unicode is passed to \f(CW$p\fR\->\fIparse()\fR then chunks
of Unicode will be reported to the handlers.  The offset and length
argspecs will also report their position in terms of characters.
.PP
It is safe to parse raw undecoded \s-1UTF\-8\s0 if you either avoid decoding
entities and make sure to not use \fIargspecs\fR that do, or enable the
\&\f(CW\*(C`utf8_mode\*(C'\fR for the parser.  Parsing of undecoded \s-1UTF\-8\s0 might be
useful when parsing from a file where you need the reported offsets
and lengths to match the byte offsets in the file.
.PP
If a filename is passed to \f(CW$p\fR\->\fIparse_file()\fR then the file will be read
in binary mode.  This will be fine if the file contains only \s-1ASCII\s0 or
Latin\-1 characters.  If the file contains \s-1UTF\-8\s0 encoded text then care
must be taken when decoding entities as described in the previous
paragraph, but better is to open the file with the \s-1UTF\-8\s0 layer so that
it is decoded properly:
.PP
.Vb 2
\&   open(my $fh, "<:utf8", "index.html") || die "...: $!";
\&   $p\->parse_file($fh);
.Ve
.PP
If the file contains text encoded in a charset besides \s-1ASCII\s0, Latin\-1
or \s-1UTF\-8\s0 then decoding will always be needed.
.SH "VERSION 2 COMPATIBILITY"
.IX Header "VERSION 2 COMPATIBILITY"
When an \f(CW\*(C`HTML::Parser\*(C'\fR object is constructed with no arguments, a set
of handlers is automatically provided that is compatible with the old
HTML::Parser version 2 callback methods.
.PP
This is equivalent to the following method calls:
.PP
.Vb 10
\&   $p\->handler(start   => "start",   "self, tagname, attr, attrseq, text");
\&   $p\->handler(end     => "end",     "self, tagname, text");
\&   $p\->handler(text    => "text",    "self, text, is_cdata");
\&   $p\->handler(process => "process", "self, token0, text");
\&   $p\->handler(comment =>
\&             sub {
\&                 my($self, $tokens) = @_;
\&                 for (@$tokens) {$self\->comment($_);}},
\&             "self, tokens");
\&   $p\->handler(declaration =>
\&             sub {
\&                 my $self = shift;
\&                 $self\->declaration(substr($_[0], 2, \-1));},
\&             "self, text");
.Ve
.PP
Setting up these handlers can also be requested with the \*(L"api_version =>
2\*(R" constructor option.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
The \f(CW\*(C`HTML::Parser\*(C'\fR class is subclassable.  Parser objects are plain
hashes and \f(CW\*(C`HTML::Parser\*(C'\fR reserves only hash keys that start with
\&\*(L"_hparser\*(R".  The parser state can be set up by invoking the \fIinit()\fR
method, which takes the same arguments as \fInew()\fR.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
The first simple example shows how you might strip out comments from
an \s-1HTML\s0 document.  We achieve this by setting up a comment handler that
does nothing and a default handler that will print out anything else:
.PP
.Vb 4
\&  use HTML::Parser;
\&  HTML::Parser\->new(default_h => [sub { print shift }, \*(Aqtext\*(Aq],
\&                    comment_h => [""],
\&                   )\->parse_file(shift || die) || die $!;
.Ve
.PP
An alternative implementation is:
.PP
.Vb 5
\&  use HTML::Parser;
\&  HTML::Parser\->new(end_document_h => [sub { print shift },
\&                                       \*(Aqskipped_text\*(Aq],
\&                    comment_h      => [""],
\&                   )\->parse_file(shift || die) || die $!;
.Ve
.PP
This will in most cases be much more efficient since only a single
callback will be made.
.PP
The next example prints out the text that is inside the <title>
element of an \s-1HTML\s0 document.  Here we start by setting up a start
handler.  When it sees the title start tag it enables a text handler
that prints any text found and an end handler that will terminate
parsing as soon as the title end tag is seen:
.PP
.Vb 1
\&  use HTML::Parser ();
\&
\&  sub start_handler
\&  {
\&    return if shift ne "title";
\&    my $self = shift;
\&    $self\->handler(text => sub { print shift }, "dtext");
\&    $self\->handler(end  => sub { shift\->eof if shift eq "title"; },
\&                           "tagname,self");
\&  }
\&
\&  my $p = HTML::Parser\->new(api_version => 3);
\&  $p\->handler( start => \e&start_handler, "tagname,self");
\&  $p\->parse_file(shift || die) || die $!;
\&  print "\en";
.Ve
.PP
More examples are found in the \fIeg/\fR directory of the \f(CW\*(C`HTML\-Parser\*(C'\fR
distribution: the program \f(CW\*(C`hrefsub\*(C'\fR shows how you can edit all links
found in a document; the program \f(CW\*(C`htextsub\*(C'\fR shows how to edit the text only; the
program \f(CW\*(C`hstrip\*(C'\fR shows how you can strip out certain tags/elements
and/or attributes; and the program \f(CW\*(C`htext\*(C'\fR show how to obtain the
plain text, but not any script/style content.
.PP
You can browse the \fIeg/\fR directory online from the \fI[Browse]\fR link on
the http://search.cpan.org/~gaas/HTML\-Parser/ page.
.SH "BUGS"
.IX Header "BUGS"
The <style> and <script> sections do not end with the first \*(L"</\*(R", but
need the complete corresponding end tag.  The standard behaviour is
not really practical.
.PP
When the \fIstrict_comment\fR option is enabled, we still recognize
comments where there is something other than whitespace between even
and odd \*(L"\-\-\*(R" markers.
.PP
Once \f(CW$p\fR\->boolean_attribute_value has been set, there is no way to
restore the default behaviour.
.PP
There is currently no way to get both quote characters
into the same literal argspec.
.PP
Empty tags, e.g. \*(L"<>\*(R" and \*(L"</>\*(R", are not recognized.  \s-1SGML\s0 allows them
to repeat the previous start tag or close the previous start tag
respectively.
.PP
\&\s-1NET\s0 tags, e.g. \*(L"code/.../\*(R" are not recognized.  This is \s-1SGML\s0
shorthand for \*(L"<code>...</code>\*(R".
.PP
Unclosed start or end tags, e.g. \*(L"<tt<b>...</b</tt>\*(R" are not
recognized.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
The following messages may be produced by HTML::Parser.  The notation
in this listing is the same as used in perldiag:
.IP "Not a reference to a hash" 4
.IX Item "Not a reference to a hash"
(F) The object blessed into or subclassed from HTML::Parser is not a
hash as required by the HTML::Parser methods.
.ie n .IP "Bad signature in parser state object at %p" 4
.el .IP "Bad signature in parser state object at \f(CW%p\fR" 4
.IX Item "Bad signature in parser state object at %p"
(F) The _hparser_xs_state element does not refer to a valid state structure.
Something must have changed the internal value
stored in this hash element, or the memory has been overwritten.
.IP "_hparser_xs_state element is not a reference" 4
.IX Item "_hparser_xs_state element is not a reference"
(F) The _hparser_xs_state element has been destroyed.
.IP "Can't find '_hparser_xs_state' element in HTML::Parser hash" 4
.IX Item "Can't find '_hparser_xs_state' element in HTML::Parser hash"
(F) The _hparser_xs_state element is missing from the parser hash.
It was either deleted, or not created when the object was created.
.ie n .IP "\s-1API\s0 version %s\fR not supported by HTML::Parser \f(CW%s" 4
.el .IP "\s-1API\s0 version \f(CW%s\fR not supported by HTML::Parser \f(CW%s\fR" 4
.IX Item "API version %s not supported by HTML::Parser %s"
(F) The constructor option 'api_version' with an argument greater than
or equal to 4 is reserved for future extensions.
.IP "Bad constructor option '%s'" 4
.IX Item "Bad constructor option '%s'"
(F) An unknown constructor option key was passed to the \fInew()\fR or
\&\fIinit()\fR methods.
.IP "Parse loop not allowed" 4
.IX Item "Parse loop not allowed"
(F) A handler invoked the \fIparse()\fR or \fIparse_file()\fR method.
This is not permitted.
.IP "marked sections not supported" 4
.IX Item "marked sections not supported"
(F) The \f(CW$p\fR\->\fImarked_sections()\fR method was invoked in a HTML::Parser
module that was compiled without support for marked sections.
.IP "Unknown boolean attribute (%d)" 4
.IX Item "Unknown boolean attribute (%d)"
(F) Something is wrong with the internal logic that set up aliases for
boolean attributes.
.IP "Only code or array references allowed as handler" 4
.IX Item "Only code or array references allowed as handler"
(F) The second argument for \f(CW$p\fR\->handler must be either a subroutine
reference, then name of a subroutine or method, or a reference to an
array.
.ie n .IP "No handler for %s events" 4
.el .IP "No handler for \f(CW%s\fR events" 4
.IX Item "No handler for %s events"
(F) The first argument to \f(CW$p\fR\->handler must be a valid event name; i.e. one
of \*(L"start\*(R", \*(L"end\*(R", \*(L"text\*(R", \*(L"process\*(R", \*(L"declaration\*(R" or \*(L"comment\*(R".
.ie n .IP "Unrecognized identifier %s in argspec" 4
.el .IP "Unrecognized identifier \f(CW%s\fR in argspec" 4
.IX Item "Unrecognized identifier %s in argspec"
(F) The identifier is not a known argspec name.
Use one of the names mentioned in the argspec section above.
.IP "Literal string is longer than 255 chars in argspec" 4
.IX Item "Literal string is longer than 255 chars in argspec"
(F) The current implementation limits the length of literals in
an argspec to 255 characters.  Make the literal shorter.
.IP "Backslash reserved for literal string in argspec" 4
.IX Item "Backslash reserved for literal string in argspec"
(F) The backslash character \*(L"\e\*(R" is not allowed in argspec literals.
It is reserved to permit quoting inside a literal in a later version.
.IP "Unterminated literal string in argspec" 4
.IX Item "Unterminated literal string in argspec"
(F) The terminating quote character for a literal was not found.
.IP "Bad argspec (%s)" 4
.IX Item "Bad argspec (%s)"
(F) Only identifier names, literals, spaces and commas
are allowed in argspecs.
.IP "Missing comma separator in argspec" 4
.IX Item "Missing comma separator in argspec"
(F) Identifiers in an argspec must be separated with \*(L",\*(R".
.IP "Parsing of undecoded \s-1UTF\-8\s0 will give garbage when decoding entities" 4
.IX Item "Parsing of undecoded UTF-8 will give garbage when decoding entities"
(W) The first chunk parsed appears to contain undecoded \s-1UTF\-8\s0 and one
or more argspecs that decode entities are used for the callback
handlers.
.Sp
The result of decoding will be a mix of encoded and decoded characters
for any entities that expand to characters with code above 127.  This
is not a good thing.
.Sp
The solution is to use the \fIEncode::encode_utf8()\fR on the data before
feeding it to the \f(CW$p\fR\->\fIparse()\fR.  For \f(CW$p\fR\->\fIparse_file()\fR pass a file that
has been opened in \*(L":utf8\*(R" mode.
.Sp
The parser can process raw undecoded \s-1UTF\-8\s0 sanely if the \f(CW\*(C`utf8_mode\*(C'\fR
is enabled or if the \*(L"attr\*(R", \*(L"@attr\*(R" or \*(L"dtext\*(R" argspecs is avoided.
.IP "Parsing string decoded with wrong endianess" 4
.IX Item "Parsing string decoded with wrong endianess"
(W) The first character in the document is U+FFFE.  This is not a
legal Unicode character but a byte swapped \s-1BOM\s0.  The result of parsing
will likely be garbage.
.IP "Parsing of undecoded \s-1UTF\-32\s0" 4
.IX Item "Parsing of undecoded UTF-32"
(W) The parser found the Unicode \s-1UTF\-32\s0 \s-1BOM\s0 signature at the start
of the document.  The result of parsing will likely be garbage.
.IP "Parsing of undecoded \s-1UTF\-16\s0" 4
.IX Item "Parsing of undecoded UTF-16"
(W) The parser found the Unicode \s-1UTF\-16\s0 \s-1BOM\s0 signature at the start of
the document.  The result of parsing will likely be garbage.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
HTML::Entities, HTML::PullParser, HTML::TokeParser, HTML::HeadParser,
HTML::LinkExtor, HTML::Form
.PP
HTML::TreeBuilder (part of the \fIHTML-Tree\fR distribution)
.PP
http://www.w3.org/TR/html4
.PP
More information about marked sections and processing instructions may
be found at \f(CW\*(C`http://www.sgml.u\-net.com/book/sgml\-8.htm\*(C'\fR.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 2
\& Copyright 1996\-2007 Gisle Aas. All rights reserved.
\& Copyright 1999\-2000 Michael A. Chase.  All rights reserved.
.Ve
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.