1HTML::Parser(3)       User Contributed Perl Documentation      HTML::Parser(3)
2
3
4

NAME

6       HTML::Parser - HTML parser class
7

SYNOPSIS

9           use strict;
10           use warnings;
11           use HTML::Parser ();
12
13           # Create parser object
14           my $p = HTML::Parser->new(
15               api_version     => 3,
16               start_h         => [\&start, "tagname, attr"],
17               end_h           => [\&end,   "tagname"],
18               marked_sections => 1,
19           );
20
21           # Parse document text chunk by chunk
22           $p->parse($chunk1);
23           $p->parse($chunk2);
24
25           # ...
26           # signal end of document
27           $p->eof;
28
29           # Parse directly from file
30           $p->parse_file("foo.html");
31
32           # or
33           open(my $fh, "<:utf8", "foo.html") || die;
34           $p->parse_file($fh);
35

DESCRIPTION

37       Objects of the "HTML::Parser" class will recognize markup and separate
38       it from plain text (alias data content) in HTML documents.  As
39       different kinds of markup and text are recognized, the corresponding
40       event handlers are invoked.
41
42       "HTML::Parser" is not a generic SGML parser.  We have tried to make it
43       able to deal with the HTML that is actually "out there", and it
44       normally parses as closely as possible to the way the popular web
45       browsers do it instead of strictly following one of the many HTML
46       specifications from W3C.  Where there is disagreement, there is often
47       an option that you can enable to get the official behaviour.
48
49       The document to be parsed may be supplied in arbitrary chunks.  This
50       makes on-the-fly parsing as documents are received from the network
51       possible.
52
53       If event driven parsing does not feel right for your application, you
54       might want to use "HTML::PullParser".  This is an "HTML::Parser"
55       subclass that allows a more conventional program structure.
56

METHODS

58       The following method is used to construct a new "HTML::Parser" object:
59
60       $p = HTML::Parser->new( %options_and_handlers )
61           This class method creates a new "HTML::Parser" object and returns
62           it.  Key/value argument pairs may be provided to assign event
63           handlers or initialize parser options.  The handlers and parser
64           options can also be set or modified later by the method calls
65           described below.
66
67           If a top level key is in the form "<event>_h" (e.g., "text_h") then
68           it assigns a handler to that event, otherwise it initializes a
69           parser option. The event handler specification value must be an
70           array reference.  Multiple handlers may also be assigned with the
71           'handlers => [%handlers]' option.  See examples below.
72
73           If new() is called without any arguments, it will create a parser
74           that uses callback methods compatible with version 2 of
75           "HTML::Parser".  See the section on "version 2 compatibility" below
76           for details.
77
78           The special constructor option 'api_version => 2' can be used to
79           initialize version 2 callbacks while still setting other options
80           and handlers.  The 'api_version => 3' option can be used if you
81           don't want to set any options and don't want to fall back to v2
82           compatible mode.
83
84           Examples:
85
86            $p = HTML::Parser->new(
87              api_version => 3,
88              text_h => [ sub {...}, "dtext" ]
89            );
90
91           This creates a new parser object with a text event handler
92           subroutine that receives the original text with general entities
93           decoded.
94
95            $p = HTML::Parser->new(
96              api_version => 3,
97              start_h => [ 'my_start', "self,tokens" ]
98            );
99
100           This creates a new parser object with a start event handler method
101           that receives the $p and the tokens array.
102
103            $p = HTML::Parser->new(
104              api_version => 3,
105              handlers => {
106                text => [\@array, "event,text"],
107                comment => [\@array, "event,text"],
108              }
109            );
110
111           This creates a new parser object that stores the event type and the
112           original text in @array for text and comment events.
113
114       The following methods feed the HTML document to the "HTML::Parser"
115       object:
116
117       $p->parse( $string )
118           Parse $string as the next chunk of the HTML document.  Handlers
119           invoked should not attempt to modify the $string in-place until
120           $p->parse returns.
121
122           If an invoked event handler aborts parsing by calling $p->eof, then
123           $p->parse() will return a FALSE value.  Otherwise the return value
124           is a reference to the parser object ($p).
125
126       $p->parse( $code_ref )
127           If a code reference is passed as the argument to be parsed, then
128           the chunks to be parsed are obtained by invoking this function
129           repeatedly.  Parsing continues until the function returns an empty
130           (or undefined) result.  When this happens $p->eof is automatically
131           signaled.
132
133           Parsing will also abort if one of the event handlers calls $p->eof.
134
135           The effect of this is the same as:
136
137               while (1) {
138                   my $chunk = &$code_ref();
139                   if (!defined($chunk) || !length($chunk)) {
140                       $p->eof;
141                       return $p;
142                   }
143                   $p->parse($chunk) || return undef;
144               }
145
146           But it is more efficient as this loop runs internally in XS code.
147
148       $p->parse_file( $file )
149           Parse text directly from a file.  The $file argument can be a
150           filename, an open file handle, or a reference to an open file
151           handle.
152
153           If $file contains a filename and the file can't be opened, then the
154           method returns an undefined value and $! tells why it failed.
155           Otherwise the return value is a reference to the parser object.
156
157           If a file handle is passed as the $file argument, then the file
158           will normally be read until EOF, but not closed.
159
160           If an invoked event handler aborts parsing by calling $p->eof, then
161           $p->parse_file() may not have read the entire file.
162
163           On systems with multi-byte line terminators, the values passed for
164           the offset and length argspecs may be too low if parse_file() is
165           called on a file handle that is not in binary mode.
166
167           If a filename is passed in, then parse_file() will open the file in
168           binary mode.
169
170       $p->eof
171           Signals the end of the HTML document.  Calling the $p->eof method
172           outside a handler callback will flush any remaining buffered text
173           (which triggers the "text" event if there is any remaining text).
174
175           Calling $p->eof inside a handler will terminate parsing at that
176           point and cause $p->parse to return a FALSE value.  This also
177           terminates parsing by $p->parse_file().
178
179           After $p->eof has been called, the parse() and parse_file() methods
180           can be invoked to feed new documents with the parser object.
181
182           The return value from eof() is a reference to the parser object.
183
184       Most parser options are controlled by boolean attributes.  Each boolean
185       attribute is enabled by calling the corresponding method with a TRUE
186       argument and disabled with a FALSE argument.  The attribute value is
187       left unchanged if no argument is given.  The return value from each
188       method is the old attribute value.
189
190       Methods that can be used to get and/or set parser options are:
191
192       $p->attr_encoded
193       $p->attr_encoded( $bool )
194           By default, the "attr" and @attr argspecs will have general
195           entities for attribute values decoded.  Enabling this attribute
196           leaves entities alone.
197
198       $p->backquote
199       $p->backquote( $bool )
200           By default, only ' and " are recognized as quote characters around
201           attribute values.  MSIE also recognizes backquotes for some reason.
202           Enabling this attribute provides compatibility with this behaviour.
203
204       $p->boolean_attribute_value( $val )
205           This method sets the value reported for boolean attributes inside
206           HTML start tags.  By default, the name of the attribute is also
207           used as its value.  This affects the values reported for "tokens"
208           and "attr" argspecs.
209
210       $p->case_sensitive
211       $p->case_sensitive( $bool )
212           By default, tag names and attribute names are down-cased.  Enabling
213           this attribute leaves them as found in the HTML source document.
214
215       $p->closing_plaintext
216       $p->closing_plaintext( $bool )
217           By default, "plaintext" element can never be closed. Everything up
218           to the end of the document is parsed in CDATA mode.  This
219           historical behaviour is what at least MSIE does.  Enabling this
220           attribute makes closing " </plaintext" > tag effective and the
221           parsing process will resume after seeing this tag.  This emulates
222           early gecko-based browsers.
223
224       $p->empty_element_tags
225       $p->empty_element_tags( $bool )
226           By default, empty element tags are not recognized as such and the
227           "/" before ">" is just treated like a normal name character (unless
228           "strict_names" is enabled).  Enabling this attribute make
229           "HTML::Parser" recognize these tags.
230
231           Empty element tags look like start tags, but end with the character
232           sequence "/>" instead of ">".  When recognized by "HTML::Parser"
233           they cause an artificial end event in addition to the start event.
234           The "text" for the artificial end event will be empty and the
235           "tokenpos" array will be undefined even though the token array will
236           have one element containing the tag name.
237
238       $p->marked_sections
239       $p->marked_sections( $bool )
240           By default, section markings like <![CDATA[...]]> are treated like
241           ordinary text.  When this attribute is enabled section markings are
242           honoured.
243
244           There are currently no events associated with the marked section
245           markup, but the text can be returned as "skipped_text".
246
247       $p->strict_comment
248       $p->strict_comment( $bool )
249           By default, comments are terminated by the first occurrence of
250           "-->".  This is the behaviour of most popular browsers (like
251           Mozilla, Opera and MSIE), but it is not correct according to the
252           official HTML standard.  Officially, you need an even number of
253           "--" tokens before the closing ">" is recognized and there may not
254           be anything but whitespace between an even and an odd "--".
255
256           The official behaviour is enabled by enabling this attribute.
257
258           Enabling of 'strict_comment' also disables recognizing these forms
259           as comments:
260
261             </ comment>
262             <! comment>
263
264       $p->strict_end
265       $p->strict_end( $bool )
266           By default, attributes and other junk are allowed to be present on
267           end tags in a manner that emulates MSIE's behaviour.
268
269           The official behaviour is enabled with this attribute.  If enabled,
270           only whitespace is allowed between the tagname and the final ">".
271
272       $p->strict_names
273       $p->strict_names( $bool )
274           By default, almost anything is allowed in tag and attribute names.
275           This is the behaviour of most popular browsers and allows us to
276           parse some broken tags with invalid attribute values like:
277
278              <IMG SRC=newprevlstGr.gif ALT=[PREV LIST] BORDER=0>
279
280           By default, "LIST]" is parsed as a boolean attribute, not as part
281           of the ALT value as was clearly intended.  This is also what
282           Mozilla sees.
283
284           The official behaviour is enabled by enabling this attribute.  If
285           enabled, it will cause the tag above to be reported as text since
286           "LIST]" is not a legal attribute name.
287
288       $p->unbroken_text
289       $p->unbroken_text( $bool )
290           By default, blocks of text are given to the text handler as soon as
291           possible (but the parser takes care always to break text at a
292           boundary between whitespace and non-whitespace so single words and
293           entities can always be decoded safely).  This might create breaks
294           that make it hard to do transformations on the text. When this
295           attribute is enabled, blocks of text are always reported in one
296           piece.  This will delay the text event until the following (non-
297           text) event has been recognized by the parser.
298
299           Note that the "offset" argspec will give you the offset of the
300           first segment of text and "length" is the combined length of the
301           segments.  Since there might be ignored tags in between, these
302           numbers can't be used to directly index in the original document
303           file.
304
305       $p->utf8_mode
306       $p->utf8_mode( $bool )
307           Enable this option when parsing raw undecoded UTF-8.  This tells
308           the parser that the entities expanded for strings reported by
309           "attr", @attr and "dtext" should be expanded as decoded UTF-8 so
310           they end up compatible with the surrounding text.
311
312           If "utf8_mode" is enabled then it is an error to pass strings
313           containing characters with code above 255 to the parse() method,
314           and the parse() method will croak if you try.
315
316           Example: The Unicode character "\x{2665}" is "\xE2\x99\xA5" when
317           UTF-8 encoded.  The character can also be represented by the entity
318           "&hearts;" or "&#x2665".  If we feed the parser:
319
320             $p->parse("\xE2\x99\xA5&hearts;");
321
322           then "dtext" will be reported as "\xE2\x99\xA5\x{2665}" without
323           "utf8_mode" enabled, but as "\xE2\x99\xA5\xE2\x99\xA5" when
324           enabled.  The later string is what you want.
325
326           This option is only available with perl-5.8 or better.
327
328       $p->xml_mode
329       $p->xml_mode( $bool )
330           Enabling this attribute changes the parser to allow some XML
331           constructs.  This enables the behaviour controlled by individually
332           by the "case_sensitive", "empty_element_tags", "strict_names" and
333           "xml_pic" attributes and also suppresses special treatment of
334           elements that are parsed as CDATA for HTML.
335
336       $p->xml_pic
337       $p->xml_pic( $bool )
338           By default, processing instructions are terminated by ">". When
339           this attribute is enabled, processing instructions are terminated
340           by "?>" instead.
341
342       As markup and text is recognized, handlers are invoked.  The following
343       method is used to set up handlers for different events:
344
345       $p->handler( event => \&subroutine, $argspec )
346       $p->handler( event => $method_name, $argspec )
347       $p->handler( event => \@accum, $argspec )
348       $p->handler( event => "" );
349       $p->handler( event => undef );
350       $p->handler( event );
351           This method assigns a subroutine, method, or array to handle an
352           event.
353
354           Event is one of "text", "start", "end", "declaration", "comment",
355           "process", "start_document", "end_document" or "default".
356
357           The "\&subroutine" is a reference to a subroutine which is called
358           to handle the event.
359
360           The $method_name is the name of a method of $p which is called to
361           handle the event.
362
363           The @accum is an array that will hold the event information as sub-
364           arrays.
365
366           If the second argument is "", the event is ignored.  If it is
367           undef, the default handler is invoked for the event.
368
369           The $argspec is a string that describes the information to be
370           reported for the event.  Any requested information that does not
371           apply to a specific event is passed as "undef".  If argspec is
372           omitted, then it is left unchanged.
373
374           The return value from $p->handler is the old callback routine or a
375           reference to the accumulator array.
376
377           Any return values from handler callback routines/methods are always
378           ignored.  A handler callback can request parsing to be aborted by
379           invoking the $p->eof method.  A handler callback is not allowed to
380           invoke the $p->parse() or $p->parse_file() method.  An exception
381           will be raised if it tries.
382
383           Examples:
384
385               $p->handler(start =>  "start", 'self, attr, attrseq, text' );
386
387           This causes the "start" method of object $p to be called for
388           'start' events.  The callback signature is "$p->start(\%attr,
389           \@attr_seq, $text)".
390
391               $p->handler(start =>  \&start, 'attr, attrseq, text' );
392
393           This causes subroutine start() to be called for 'start' events.
394           The callback signature is start(\%attr, \@attr_seq, $text).
395
396               $p->handler(start =>  \@accum, '"S", attr, attrseq, text' );
397
398           This causes 'start' event information to be saved in @accum.  The
399           array elements will be ['S', \%attr, \@attr_seq, $text].
400
401              $p->handler(start => "");
402
403           This causes 'start' events to be ignored.  It also suppresses
404           invocations of any default handler for start events.  It is in most
405           cases equivalent to $p->handler(start => sub {}), but is more
406           efficient.  It is different from the empty-sub-handler in that
407           "skipped_text" is not reset by it.
408
409              $p->handler(start => undef);
410
411           This causes no handler to be associated with start events.  If
412           there is a default handler it will be invoked.
413
414       Filters based on tags can be set up to limit the number of events
415       reported.  The main bottleneck during parsing is often the huge number
416       of callbacks made from the parser.  Applying filters can improve
417       performance significantly.
418
419       The following methods control filters:
420
421       $p->ignore_elements( @tags )
422           Both the "start" event and the "end" event as well as any events
423           that would be reported in between are suppressed.  The ignored
424           elements can contain nested occurrences of itself.  Example:
425
426              $p->ignore_elements(qw(script style));
427
428           The "script" and "style" tags will always nest properly since their
429           content is parsed in CDATA mode.  For most other tags
430           "ignore_elements" must be used with caution since HTML is often not
431           well formed.
432
433       $p->ignore_tags( @tags )
434           Any "start" and "end" events involving any of the tags given are
435           suppressed.  To reset the filter (i.e. don't suppress any "start"
436           and "end" events), call "ignore_tags" without an argument.
437
438       $p->report_tags( @tags )
439           Any "start" and "end" events involving any of the tags not given
440           are suppressed.  To reset the filter (i.e. report all "start" and
441           "end" events), call "report_tags" without an argument.
442
443       Internally, the system has two filter lists, one for "report_tags" and
444       one for "ignore_tags", and both filters are applied.  This effectively
445       gives "ignore_tags" precedence over "report_tags".
446
447       Examples:
448
449          $p->ignore_tags(qw(style));
450          $p->report_tags(qw(script style));
451
452       results in only "script" events being reported.
453
454   Argspec
455       Argspec is a string containing a comma-separated list that describes
456       the information reported by the event.  The following argspec
457       identifier names can be used:
458
459       "attr"
460           Attr causes a reference to a hash of attribute name/value pairs to
461           be passed.
462
463           Boolean attributes' values are either the value set by
464           $p->boolean_attribute_value, or the attribute name if no value has
465           been set by $p->boolean_attribute_value.
466
467           This passes undef except for "start" events.
468
469           Unless "xml_mode" or "case_sensitive" is enabled, the attribute
470           names are forced to lower case.
471
472           General entities are decoded in the attribute values and one layer
473           of matching quotes enclosing the attribute values is removed.
474
475           The Unicode character set is assumed for entity decoding.
476
477       @attr
478           Basically the same as "attr", but keys and values are passed as
479           individual arguments and the original sequence of the attributes is
480           kept.  The parameters passed will be the same as the @attr
481           calculated here:
482
483              @attr = map { $_ => $attr->{$_} } @$attrseq;
484
485           assuming $attr and $attrseq here are the hash and array passed as
486           the result of "attr" and "attrseq" argspecs.
487
488           This passes no values for events besides "start".
489
490       "attrseq"
491           Attrseq causes a reference to an array of attribute names to be
492           passed.  This can be useful if you want to walk the "attr" hash in
493           the original sequence.
494
495           This passes undef except for "start" events.
496
497           Unless "xml_mode" or "case_sensitive" is enabled, the attribute
498           names are forced to lower case.
499
500       "column"
501           Column causes the column number of the start of the event to be
502           passed.  The first column on a line is 0.
503
504       "dtext"
505           Dtext causes the decoded text to be passed.  General entities are
506           automatically decoded unless the event was inside a CDATA section
507           or was between literal start and end tags ("script", "style",
508           "xmp", "iframe", "title", "textarea" and "plaintext").
509
510           The Unicode character set is assumed for entity decoding.  With
511           Perl version 5.6 or earlier only the Latin-1 range is supported,
512           and entities for characters outside the range 0..255 are left
513           unchanged.
514
515           This passes undef except for "text" events.
516
517       "event"
518           Event causes the event name to be passed.
519
520           The event name is one of "text", "start", "end", "declaration",
521           "comment", "process", "start_document" or "end_document".
522
523       "is_cdata"
524           Is_cdata causes a TRUE value to be passed if the event is inside a
525           CDATA section or between literal start and end tags ("script",
526           "style", "xmp", "iframe", "title", "textarea" and "plaintext").
527
528           if the flag is FALSE for a text event, then you should normally
529           either use "dtext" or decode the entities yourself before the text
530           is processed further.
531
532       "length"
533           Length causes the number of bytes of the source text of the event
534           to be passed.
535
536       "line"
537           Line causes the line number of the start of the event to be passed.
538           The first line in the document is 1.  Line counting doesn't start
539           until at least one handler requests this value to be reported.
540
541       "offset"
542           Offset causes the byte position in the HTML document of the start
543           of the event to be passed.  The first byte in the document has
544           offset 0.
545
546       "offset_end"
547           Offset_end causes the byte position in the HTML document of the end
548           of the event to be passed.  This is the same as "offset" +
549           "length".
550
551       "self"
552           Self causes the current object to be passed to the handler.  If the
553           handler is a method, this must be the first element in the argspec.
554
555           An alternative to passing self as an argspec is to register
556           closures that capture $self by themselves as handlers.
557           Unfortunately this creates circular references which prevent the
558           HTML::Parser object from being garbage collected.  Using the "self"
559           argspec avoids this problem.
560
561       "skipped_text"
562           Skipped_text returns the concatenated text of all the events that
563           have been skipped since the last time an event was reported.
564           Events might be skipped because no handler is registered for them
565           or because some filter applies.  Skipped text also includes marked
566           section markup, since there are no events that can catch it.
567
568           If an ""-handler is registered for an event, then the text for this
569           event is not included in "skipped_text".  Skipped text both before
570           and after the ""-event is included in the next reported
571           "skipped_text".
572
573       "tag"
574           Same as "tagname", but prefixed with "/" if it belongs to an "end"
575           event and "!" for a declaration.  The "tag" does not have any
576           prefix for "start" events, and is in this case identical to
577           "tagname".
578
579       "tagname"
580           This is the element name (or generic identifier in SGML jargon) for
581           start and end tags.  Since HTML is case insensitive, this name is
582           forced to lower case to ease string matching.
583
584           Since XML is case sensitive, the tagname case is not changed when
585           "xml_mode" is enabled.  The same happens if the "case_sensitive"
586           attribute is set.
587
588           The declaration type of declaration elements is also passed as a
589           tagname, even if that is a bit strange.  In fact, in the current
590           implementation tagname is identical to "token0" except that the
591           name may be forced to lower case.
592
593       "token0"
594           Token0 causes the original text of the first token string to be
595           passed.  This should always be the same as $tokens->[0].
596
597           For "declaration" events, this is the declaration type.
598
599           For "start" and "end" events, this is the tag name.
600
601           For "process" and non-strict "comment" events, this is everything
602           inside the tag.
603
604           This passes undef if there are no tokens in the event.
605
606       "tokenpos"
607           Tokenpos causes a reference to an array of token positions to be
608           passed.  For each string that appears in "tokens", this array
609           contains two numbers.  The first number is the offset of the start
610           of the token in the original "text" and the second number is the
611           length of the token.
612
613           Boolean attributes in a "start" event will have (0,0) for the
614           attribute value offset and length.
615
616           This passes undef if there are no tokens in the event (e.g.,
617           "text") and for artificial "end" events triggered by empty element
618           tags.
619
620           If you are using these offsets and lengths to modify "text", you
621           should either work from right to left, or be very careful to
622           calculate the changes to the offsets.
623
624       "tokens"
625           Tokens causes a reference to an array of token strings to be
626           passed.  The strings are exactly as they were found in the original
627           text, no decoding or case changes are applied.
628
629           For "declaration" events, the array contains each word, comment,
630           and delimited string starting with the declaration type.
631
632           For "comment" events, this contains each sub-comment.  If
633           $p->strict_comments is disabled, there will be only one sub-
634           comment.
635
636           For "start" events, this contains the original tag name followed by
637           the attribute name/value pairs.  The values of boolean attributes
638           will be either the value set by $p->boolean_attribute_value, or the
639           attribute name if no value has been set by
640           $p->boolean_attribute_value.
641
642           For "end" events, this contains the original tag name (always one
643           token).
644
645           For "process" events, this contains the process instructions
646           (always one token).
647
648           This passes "undef" for "text" events.
649
650       "text"
651           Text causes the source text (including markup element delimiters)
652           to be passed.
653
654       "undef"
655           Pass an undefined value.  Useful as padding where the same handler
656           routine is registered for multiple events.
657
658       '...'
659           A literal string of 0 to 255 characters enclosed in single (') or
660           double (") quotes is passed as entered.
661
662       The whole argspec string can be wrapped up in '@{...}' to signal that
663       the resulting event array should be flattened.  This only makes a
664       difference if an array reference is used as the handler target.
665       Consider this example:
666
667          $p->handler(text => [], 'text');
668          $p->handler(text => [], '@{text}']);
669
670       With two text events; "foo", "bar"; then the first example will end up
671       with [["foo"], ["bar"]] and the second with ["foo", "bar"] in the
672       handler target array.
673
674   Events
675       Handlers for the following events can be registered:
676
677       "comment"
678           This event is triggered when a markup comment is recognized.
679
680           Example:
681
682             <!-- This is a comment -- -- So is this -->
683
684       "declaration"
685           This event is triggered when a markup declaration is recognized.
686
687           For typical HTML documents, the only declaration you are likely to
688           find is <!DOCTYPE ...>.
689
690           Example:
691
692             <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
693                 "http://www.w3.org/TR/html4/strict.dtd">
694
695           DTDs inside <!DOCTYPE ...> will confuse HTML::Parser.
696
697       "default"
698           This event is triggered for events that do not have a specific
699           handler.  You can set up a handler for this event to catch stuff
700           you did not want to catch explicitly.
701
702       "end"
703           This event is triggered when an end tag is recognized.
704
705           Example:
706
707             </A>
708
709       "end_document"
710           This event is triggered when $p->eof is called and after any
711           remaining text is flushed.  There is no document text associated
712           with this event.
713
714       "process"
715           This event is triggered when a processing instructions markup is
716           recognized.
717
718           The format and content of processing instructions are system and
719           application dependent.
720
721           Examples:
722
723             <? HTML processing instructions >
724             <? XML processing instructions ?>
725
726       "start"
727           This event is triggered when a start tag is recognized.
728
729           Example:
730
731             <A HREF="http://www.perl.com/">
732
733       "start_document"
734           This event is triggered before any other events for a new document.
735           A handler for it can be used to initialize stuff.  There is no
736           document text associated with this event.
737
738       "text"
739           This event is triggered when plain text (characters) is recognized.
740           The text may contain multiple lines.  A sequence of text may be
741           broken between several text events unless $p->unbroken_text is
742           enabled.
743
744           The parser will make sure that it does not break a word or a
745           sequence of whitespace between two text events.
746
747   Unicode
748       "HTML::Parser" can parse Unicode strings when running under perl-5.8 or
749       better.  If Unicode is passed to $p->parse() then chunks of Unicode
750       will be reported to the handlers.  The offset and length argspecs will
751       also report their position in terms of characters.
752
753       It is safe to parse raw undecoded UTF-8 if you either avoid decoding
754       entities and make sure to not use argspecs that do, or enable the
755       "utf8_mode" for the parser.  Parsing of undecoded UTF-8 might be useful
756       when parsing from a file where you need the reported offsets and
757       lengths to match the byte offsets in the file.
758
759       If a filename is passed to $p->parse_file() then the file will be read
760       in binary mode.  This will be fine if the file contains only ASCII or
761       Latin-1 characters.  If the file contains UTF-8 encoded text then care
762       must be taken when decoding entities as described in the previous
763       paragraph, but better is to open the file with the UTF-8 layer so that
764       it is decoded properly:
765
766          open(my $fh, "<:utf8", "index.html") || die "...: $!";
767          $p->parse_file($fh);
768
769       If the file contains text encoded in a charset besides ASCII, Latin-1
770       or UTF-8 then decoding will always be needed.
771

VERSION 2 COMPATIBILITY

773       When an "HTML::Parser" object is constructed with no arguments, a set
774       of handlers is automatically provided that is compatible with the old
775       HTML::Parser version 2 callback methods.
776
777       This is equivalent to the following method calls:
778
779           $p->handler(start   => "start",   "self, tagname, attr, attrseq, text");
780           $p->handler(end     => "end",     "self, tagname, text");
781           $p->handler(text    => "text",    "self, text, is_cdata");
782           $p->handler(process => "process", "self, token0, text");
783           $p->handler(
784               comment => sub {
785                   my ($self, $tokens) = @_;
786                   for (@$tokens) { $self->comment($_); }
787               },
788               "self, tokens"
789           );
790           $p->handler(
791               declaration => sub {
792                   my $self = shift;
793                   $self->declaration(substr($_[0], 2, -1));
794               },
795               "self, text"
796           );
797
798       Setting up these handlers can also be requested with the "api_version
799       => 2" constructor option.
800

SUBCLASSING

802       The "HTML::Parser" class is able to be subclassed.  Parser objects are
803       plain hashes and "HTML::Parser" reserves only hash keys that start with
804       "_hparser".  The parser state can be set up by invoking the init()
805       method, which takes the same arguments as new().
806

EXAMPLES

808       The first simple example shows how you might strip out comments from an
809       HTML document.  We achieve this by setting up a comment handler that
810       does nothing and a default handler that will print out anything else:
811
812           use HTML::Parser ();
813           HTML::Parser->new(
814               default_h => [sub { print shift }, 'text'],
815               comment_h => [""],
816           )->parse_file(shift || die)
817               || die $!;
818
819       An alternative implementation is:
820
821           use HTML::Parser ();
822           HTML::Parser->new(
823               end_document_h => [sub { print shift }, 'skipped_text'],
824               comment_h      => [""],
825           )->parse_file(shift || die)
826               || die $!;
827
828       This will in most cases be much more efficient since only a single
829       callback will be made.
830
831       The next example prints out the text that is inside the <title> element
832       of an HTML document.  Here we start by setting up a start handler.
833       When it sees the title start tag it enables a text handler that prints
834       any text found and an end handler that will terminate parsing as soon
835       as the title end tag is seen:
836
837           use HTML::Parser ();
838
839           sub start_handler {
840               return if shift ne "title";
841               my $self = shift;
842               $self->handler(text => sub { print shift }, "dtext");
843               $self->handler(
844                   end => sub {
845                       shift->eof if shift eq "title";
846                   },
847                   "tagname,self"
848               );
849           }
850
851           my $p = HTML::Parser->new(api_version => 3);
852           $p->handler(start => \&start_handler, "tagname,self");
853           $p->parse_file(shift || die) || die $!;
854           print "\n";
855
856       More examples are found in the eg/ directory of the "HTML-Parser"
857       distribution: the program "hrefsub" shows how you can edit all links
858       found in a document; the program "htextsub" shows how to edit the text
859       only; the program "hstrip" shows how you can strip out certain
860       tags/elements and/or attributes; and the program "htext" show how to
861       obtain the plain text, but not any script/style content.
862
863       You can browse the eg/ directory online from the [Browse] link on the
864       http://search.cpan.org/~gaas/HTML-Parser/ page.
865

BUGS

867       The <style> and <script> sections do not end with the first "</", but
868       need the complete corresponding end tag.  The standard behaviour is not
869       really practical.
870
871       When the strict_comment option is enabled, we still recognize comments
872       where there is something other than whitespace between even and odd
873       "--" markers.
874
875       Once $p->boolean_attribute_value has been set, there is no way to
876       restore the default behaviour.
877
878       There is currently no way to get both quote characters into the same
879       literal argspec.
880
881       Empty tags, e.g. "<>" and "</>", are not recognized.  SGML allows them
882       to repeat the previous start tag or close the previous start tag
883       respectively.
884
885       NET tags, e.g. "code/.../" are not recognized.  This is SGML shorthand
886       for "<code>...</code>".
887
888       Incomplete start or end tags, e.g. "<tt<b>...</b</tt>" are not
889       recognized.
890

DIAGNOSTICS

892       The following messages may be produced by HTML::Parser.  The notation
893       in this listing is the same as used in perldiag:
894
895       Not a reference to a hash
896           (F) The object blessed into or subclassed from HTML::Parser is not
897           a hash as required by the HTML::Parser methods.
898
899       Bad signature in parser state object at %p
900           (F) The _hparser_xs_state element does not refer to a valid state
901           structure.  Something must have changed the internal value stored
902           in this hash element, or the memory has been overwritten.
903
904       _hparser_xs_state element is not a reference
905           (F) The _hparser_xs_state element has been destroyed.
906
907       Can't find '_hparser_xs_state' element in HTML::Parser hash
908           (F) The _hparser_xs_state element is missing from the parser hash.
909           It was either deleted, or not created when the object was created.
910
911       API version %s not supported by HTML::Parser %s
912           (F) The constructor option 'api_version' with an argument greater
913           than or equal to 4 is reserved for future extensions.
914
915       Bad constructor option '%s'
916           (F) An unknown constructor option key was passed to the new() or
917           init() methods.
918
919       Parse loop not allowed
920           (F) A handler invoked the parse() or parse_file() method.  This is
921           not permitted.
922
923       marked sections not supported
924           (F) The $p->marked_sections() method was invoked in a HTML::Parser
925           module that was compiled without support for marked sections.
926
927       Unknown boolean attribute (%d)
928           (F) Something is wrong with the internal logic that set up aliases
929           for boolean attributes.
930
931       Only code or array references allowed as handler
932           (F) The second argument for $p->handler must be either a subroutine
933           reference, then name of a subroutine or method, or a reference to
934           an array.
935
936       No handler for %s events
937           (F) The first argument to $p->handler must be a valid event name;
938           i.e. one of "start", "end", "text", "process", "declaration" or
939           "comment".
940
941       Unrecognized identifier %s in argspec
942           (F) The identifier is not a known argspec name.  Use one of the
943           names mentioned in the argspec section above.
944
945       Literal string is longer than 255 chars in argspec
946           (F) The current implementation limits the length of literals in an
947           argspec to 255 characters.  Make the literal shorter.
948
949       Backslash reserved for literal string in argspec
950           (F) The backslash character "\" is not allowed in argspec literals.
951           It is reserved to permit quoting inside a literal in a later
952           version.
953
954       Unterminated literal string in argspec
955           (F) The terminating quote character for a literal was not found.
956
957       Bad argspec (%s)
958           (F) Only identifier names, literals, spaces and commas are allowed
959           in argspecs.
960
961       Missing comma separator in argspec
962           (F) Identifiers in an argspec must be separated with ",".
963
964       Parsing of undecoded UTF-8 will give garbage when decoding entities
965           (W) The first chunk parsed appears to contain undecoded UTF-8 and
966           one or more argspecs that decode entities are used for the callback
967           handlers.
968
969           The result of decoding will be a mix of encoded and decoded
970           characters for any entities that expand to characters with code
971           above 127.  This is not a good thing.
972
973           The recommended solution is to apply Encode::decode_utf8() on the
974           data before feeding it to the $p->parse().  For $p->parse_file()
975           pass a file that has been opened in ":utf8" mode.
976
977           The alternative solution is to enable the "utf8_mode" and not
978           decode before passing strings to $p->parse().  The parser can
979           process raw undecoded UTF-8 sanely if the "utf8_mode" is enabled,
980           or if the "attr", @attr or "dtext" argspecs are avoided.
981
982       Parsing string decoded with wrong endian selection
983           (W) The first character in the document is U+FFFE.  This is not a
984           legal Unicode character but a byte swapped "BOM".  The result of
985           parsing will likely be garbage.
986
987       Parsing of undecoded UTF-32
988           (W) The parser found the Unicode UTF-32 "BOM" signature at the
989           start of the document.  The result of parsing will likely be
990           garbage.
991
992       Parsing of undecoded UTF-16
993           (W) The parser found the Unicode UTF-16 "BOM" signature at the
994           start of the document.  The result of parsing will likely be
995           garbage.
996

SEE ALSO

998       HTML::Entities, HTML::PullParser, HTML::TokeParser, HTML::HeadParser,
999       HTML::LinkExtor, HTML::Form
1000
1001       HTML::TreeBuilder (part of the HTML-Tree distribution)
1002
1003       <http://www.w3.org/TR/html4/>
1004
1005       More information about marked sections and processing instructions may
1006       be found at <http://www.is-thought.co.uk/book/sgml-8.htm>.
1007
1009        Copyright 1996-2016 Gisle Aas. All rights reserved.
1010        Copyright 1999-2000 Michael A. Chase.  All rights reserved.
1011
1012       This library is free software; you can redistribute it and/or modify it
1013       under the same terms as Perl itself.
1014
1015
1016
1017perl v5.36.0                      2022-11-02                   HTML::Parser(3)
Impressum