local-lib5/man/man3/HTML::TokeParser.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "HTML::TokeParser 3"
 132 .TH HTML::TokeParser 3 "2008-04-04" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 HTML::TokeParser \- Alternative HTML::Parser interface
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 4
 138 \& require HTML::TokeParser;
 139 \& $p = HTML::TokeParser\->new("index.html") ||
 140 \&      die "Can't open: $!";
 141 \& $p\->empty_element_tags(1);  # configure its behaviour
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \& while (my $token = $p\->get_token) {
 146 \&     #...
 147 \& }
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 The \f(CW\*(C`HTML::TokeParser\*(C'\fR is an alternative interface to the
 152 \&\f(CW\*(C`HTML::Parser\*(C'\fR class.  It is an \f(CW\*(C`HTML::PullParser\*(C'\fR subclass with a
 153 predeclared set of token types.  If you wish the tokens to be reported
 154 differently you probably want to use the \f(CW\*(C`HTML::PullParser\*(C'\fR directly.
 155 .PP
 156 The following methods are available:
 157 .ie n .IP "$p = HTML::TokeParser\->new( $filename\fR, \f(CW%opt );" 4
 158 .el .IP "$p = HTML::TokeParser\->new( \f(CW$filename\fR, \f(CW%opt\fR );" 4
 159 .IX Item "$p = HTML::TokeParser->new( $filename, %opt );"
 160 .PD 0
 161 .ie n .IP "$p = HTML::TokeParser\->new( $filehandle\fR, \f(CW%opt );" 4
 162 .el .IP "$p = HTML::TokeParser\->new( \f(CW$filehandle\fR, \f(CW%opt\fR );" 4
 163 .IX Item "$p = HTML::TokeParser->new( $filehandle, %opt );"
 164 .ie n .IP "$p = HTML::TokeParser\->new( \e$document, %opt );" 4
 165 .el .IP "$p = HTML::TokeParser\->new( \e$document, \f(CW%opt\fR );" 4
 166 .IX Item "$p = HTML::TokeParser->new( $document, %opt );"
 167 .PD
 168 The object constructor argument is either a file name, a file handle
 169 object, or the complete document to be parsed.  Extra options can be
 170 provided as key/value pairs and are processed as documented by the base
 171 classes.
 172 .Sp
 173 If the argument is a plain scalar, then it is taken as the name of a
 174 file to be opened and parsed.  If the file can't be opened for
 175 reading, then the constructor will return \f(CW\*(C`undef\*(C'\fR and $! will tell
 176 you why it failed.
 177 .Sp
 178 If the argument is a reference to a plain scalar, then this scalar is
 179 taken to be the literal document to parse.  The value of this
 180 scalar should not be changed before all tokens have been extracted.
 181 .Sp
 182 Otherwise the argument is taken to be some object that the
 183 \&\f(CW\*(C`HTML::TokeParser\*(C'\fR can \fIread()\fR from when it needs more data.  Typically
 184 it will be a filehandle of some kind.  The stream will be \fIread()\fR until
 185 \&\s-1EOF\s0, but not closed.
 186 .Sp
 187 A newly constructed \f(CW\*(C`HTML::TokeParser\*(C'\fR differ from its base classes
 188 by having the \f(CW\*(C`unbroken_text\*(C'\fR attribute enabled by default. See
 189 HTML::Parser for a description of this and other attributes that
 190 influence how the document is parsed. It is often a good idea to enable
 191 \&\f(CW\*(C`empty_element_tags\*(C'\fR behaviour.
 192 .Sp
 193 Note that the parsing result will likely not be valid if raw undecoded
 194 \&\s-1UTF\-8\s0 is used as a source.  When parsing \s-1UTF\-8\s0 encoded files turn
 195 on \s-1UTF\-8\s0 decoding:
 196 .Sp
 197 .Vb 3
 198 \&   open(my $fh, "<:utf8", "index.html") || die "Can't open 'index.html': $!";
 199 \&   my $p = HTML::TokeParser\->new( $fh );
 200 \&   # ...
 201 .Ve
 202 .Sp
 203 If a \f(CW$filename\fR is passed to the constructor the file will be opened in
 204 raw mode and the parsing result will only be valid if its content is
 205 Latin\-1 or pure \s-1ASCII\s0.
 206 .Sp
 207 If parsing from an \s-1UTF\-8\s0 encoded string buffer decode it first:
 208 .Sp
 209 .Vb 3
 210 \&   utf8::decode($document);
 211 \&   my $p = HTML::TokeParser\->new( \e$document );
 212 \&   # ...
 213 .Ve
 214 .IP "$p\->get_token" 4
 215 .IX Item "$p->get_token"
 216 This method will return the next \fItoken\fR found in the \s-1HTML\s0 document,
 217 or \f(CW\*(C`undef\*(C'\fR at the end of the document.  The token is returned as an
 218 array reference.  The first element of the array will be a string
 219 denoting the type of this token: \*(L"S\*(R" for start tag, \*(L"E\*(R" for end tag,
 220 \&\*(L"T\*(R" for text, \*(L"C\*(R" for comment, \*(L"D\*(R" for declaration, and \*(L"\s-1PI\s0\*(R" for
 221 process instructions.  The rest of the token array depend on the type
 222 like this:
 223 .Sp
 224 .Vb 6
 225 \&  ["S",  $tag, $attr, $attrseq, $text]
 226 \&  ["E",  $tag, $text]
 227 \&  ["T",  $text, $is_data]
 228 \&  ["C",  $text]
 229 \&  ["D",  $text]
 230 \&  ["PI", $token0, $text]
 231 .Ve
 232 .Sp
 233 where \f(CW$attr\fR is a hash reference, \f(CW$attrseq\fR is an array reference and
 234 the rest are plain scalars.  The \*(L"Argspec\*(R" in HTML::Parser explains the
 235 details.
 236 .ie n .IP "$p\->unget_token( @tokens )" 4
 237 .el .IP "$p\->unget_token( \f(CW@tokens\fR )" 4
 238 .IX Item "$p->unget_token( @tokens )"
 239 If you find you have read too many tokens you can push them back,
 240 so that they are returned the next time \f(CW$p\fR\->get_token is called.
 241 .IP "$p\->get_tag" 4
 242 .IX Item "$p->get_tag"
 243 .PD 0
 244 .ie n .IP "$p\->get_tag( @tags )" 4
 245 .el .IP "$p\->get_tag( \f(CW@tags\fR )" 4
 246 .IX Item "$p->get_tag( @tags )"
 247 .PD
 248 This method returns the next start or end tag (skipping any other
 249 tokens), or \f(CW\*(C`undef\*(C'\fR if there are no more tags in the document.  If
 250 one or more arguments are given, then we skip tokens until one of the
 251 specified tag types is found.  For example:
 252 .Sp
 253 .Vb 1
 254 \&   $p\->get_tag("font", "/font");
 255 .Ve
 256 .Sp
 257 will find the next start or end tag for a font\-element.
 258 .Sp
 259 The tag information is returned as an array reference in the same form
 260 as for \f(CW$p\fR\->get_token above, but the type code (first element) is
 261 missing. A start tag will be returned like this:
 262 .Sp
 263 .Vb 1
 264 \&  [$tag, $attr, $attrseq, $text]
 265 .Ve
 266 .Sp
 267 The tagname of end tags are prefixed with \*(L"/\*(R", i.e. end tag is
 268 returned like this:
 269 .Sp
 270 .Vb 1
 271 \&  ["/$tag", $text]
 272 .Ve
 273 .IP "$p\->get_text" 4
 274 .IX Item "$p->get_text"
 275 .PD 0
 276 .ie n .IP "$p\->get_text( @endtags )" 4
 277 .el .IP "$p\->get_text( \f(CW@endtags\fR )" 4
 278 .IX Item "$p->get_text( @endtags )"
 279 .PD
 280 This method returns all text found at the current position. It will
 281 return a zero length string if the next token is not text. Any
 282 entities will be converted to their corresponding character.
 283 .Sp
 284 If one or more arguments are given, then we return all text occurring
 285 before the first of the specified tags found. For example:
 286 .Sp
 287 .Vb 1
 288 \&   $p\->get_text("p", "br");
 289 .Ve
 290 .Sp
 291 will return the text up to either a paragraph of linebreak element.
 292 .Sp
 293 The text might span tags that should be \fItextified\fR.  This is
 294 controlled by the \f(CW$p\fR\->{textify} attribute, which is a hash that
 295 defines how certain tags can be treated as text.  If the name of a
 296 start tag matches a key in this hash then this tag is converted to
 297 text.  The hash value is used to specify which tag attribute to obtain
 298 the text from.  If this tag attribute is missing, then the upper case
 299 name of the tag enclosed in brackets is returned, e.g. \*(L"[\s-1IMG\s0]\*(R".  The
 300 hash value can also be a subroutine reference.  In this case the
 301 routine is called with the start tag token content as its argument and
 302 the return value is treated as the text.
 303 .Sp
 304 The default \f(CW$p\fR\->{textify} value is:
 305 .Sp
 306 .Vb 1
 307 \&  {img => "alt", applet => "alt"}
 308 .Ve
 309 .Sp
 310 This means that <\s-1IMG\s0> and <\s-1APPLET\s0> tags are treated as text, and that
 311 the text to substitute can be found in the \s-1ALT\s0 attribute.
 312 .IP "$p\->get_trimmed_text" 4
 313 .IX Item "$p->get_trimmed_text"
 314 .PD 0
 315 .ie n .IP "$p\->get_trimmed_text( @endtags )" 4
 316 .el .IP "$p\->get_trimmed_text( \f(CW@endtags\fR )" 4
 317 .IX Item "$p->get_trimmed_text( @endtags )"
 318 .PD
 319 Same as \f(CW$p\fR\->get_text above, but will collapse any sequences of white
 320 space to a single space character.  Leading and trailing white space is
 321 removed.
 322 .IP "$p\->get_phrase" 4
 323 .IX Item "$p->get_phrase"
 324 This will return all text found at the current position ignoring any
 325 phrasal-level tags.  Text is extracted until the first non
 326 phrasal-level tag.  Textification of tags is the same as for
 327 \&\fIget_text()\fR.  This method will collapse white space in the same way as
 328 \&\fIget_trimmed_text()\fR does.
 329 .Sp
 330 The definition of <i>phrasal\-level tags</i> is obtained from the
 331 HTML::Tagset module.
 332 .SH "EXAMPLES"
 333 .IX Header "EXAMPLES"
 334 This example extracts all links from a document.  It will print one
 335 line for each link, containing the \s-1URL\s0 and the textual description
 336 between the <A>...</A> tags:
 337 .PP
 338 .Vb 2
 339 \&  use HTML::TokeParser;
 340 \&  $p = HTML::TokeParser\->new(shift||"index.html");
 341 .Ve
 342 .PP
 343 .Vb 5
 344 \&  while (my $token = $p\->get_tag("a")) {
 345 \&      my $url = $token\->[1]{href} || "\-";
 346 \&      my $text = $p\->get_trimmed_text("/a");
 347 \&      print "$url\et$text\en";
 348 \&  }
 349 .Ve
 350 .PP
 351 This example extract the <\s-1TITLE\s0> from the document:
 352 .PP
 353 .Vb 6
 354 \&  use HTML::TokeParser;
 355 \&  $p = HTML::TokeParser\->new(shift||"index.html");
 356 \&  if ($p\->get_tag("title")) {
 357 \&      my $title = $p\->get_trimmed_text;
 358 \&      print "Title: $title\en";
 359 \&  }
 360 .Ve
 361 .SH "SEE ALSO"
 362 .IX Header "SEE ALSO"
 363 HTML::PullParser, HTML::Parser
 364 .SH "COPYRIGHT"
 365 .IX Header "COPYRIGHT"
 366 Copyright 1998\-2005 Gisle Aas.
 367 .PP
 368 This library is free software; you can redistribute it and/or
 369 modify it under the same terms as Perl itself.