home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _e3c9ba2b832261f790bc43dc239d035c < prev    next >
Text File  |  2000-03-23  |  8KB  |  183 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>HTML::TokeParser - Alternative HTML::Parser interface</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> HTML::TokeParser - Alternative HTML::Parser interface</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#examples">EXAMPLES</A></LI>
  26.     <LI><A HREF="#see also">SEE ALSO</A></LI>
  27.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  28. </UL>
  29. <!-- INDEX END -->
  30.  
  31. <HR>
  32. <P>
  33. <H1><A NAME="name">NAME</A></H1>
  34. <P>HTML::TokeParser - Alternative HTML::Parser interface</P>
  35. <P>
  36. <HR>
  37. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  38. <UL>
  39. <LI>Linux</LI>
  40. <LI>Solaris</LI>
  41. <LI>Windows</LI>
  42. </UL>
  43. <HR>
  44. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  45. <PRE>
  46.  require HTML::TokeParser;
  47.  $p = HTML::TokeParser->new("index.html") || die "Can't open: $!";
  48.  while (my $token = $p->get_token) {
  49.      #...
  50.  }</PRE>
  51. <P>
  52. <HR>
  53. <H1><A NAME="description">DESCRIPTION</A></H1>
  54. <P>The HTML::TokeParser is an alternative interface to the HTML::Parser class.
  55. It basically turns the HTML::Parser inside out.  You associate a file
  56. (or any IO::Handle object or string) with the parser at construction time and
  57. then repeatedly call $parser->get_token to obtain the tags and text
  58. found in the parsed document.  No need to make a subclass to make the
  59. parser do anything.</P>
  60. <P>Calling the methods defined by the HTML::Parser base class will be
  61. confusing, so don't do that.  Use the following methods instead:</P>
  62. <DL>
  63. <DT><STRONG><A NAME="item_new">$p = HTML::TokeParser->new( $file_or_doc );</A></STRONG><BR>
  64. <DD>
  65. The object constructor argument is either a file name, a file handle
  66. object, or the complete document to be parsed.
  67. <P>If the argument is a plain scalar, then it is taken as the name of a
  68. file to be opened and parsed.  If the file can't be opened for
  69. reading, then the constructor will return an undefined value and $!
  70. will tell you why it failed.</P>
  71. <P>If the argument is a reference to a plain scalar, then this scalar is
  72. taken to be the document to parse.</P>
  73. <P>Otherwise the argument is taken to be some object that the
  74. <CODE>HTML::TokeParser</CODE> can <A HREF="../../../lib/Pod/perlfunc.html#item_read"><CODE>read()</CODE></A> from when it need more data.  Typically
  75. it will be a filehandle of some kind.The stream will be <A HREF="../../../lib/Pod/perlfunc.html#item_read"><CODE>read()</CODE></A> until
  76. EOF, but not closed.</P>
  77. <P></P>
  78. <DT><STRONG><A NAME="item_get_token">$p->get_token</A></STRONG><BR>
  79. <DD>
  80. This method will return the next <EM>token</EM> found in the HTML document,
  81. or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> at the end of the document.  The token is returned as an
  82. array reference.  The first element of the array will be a single
  83. character string denoting the type of this token; ``S'' for start tag,
  84. ``E'' for end tag, ``T'' for text, ``C'' for comment, and ``D'' for
  85. declaration.  The rest of the array is the same as the arguments
  86. passed to the corresponding HTML::Parser callbacks (see
  87. <A HREF="../../../site/lib/HTML/Parser.html">the HTML::Parser manpage</A>).  This summarize the tokens that can occur:
  88. <PRE>
  89.   ["S", $tag, %$attr, @$attrseq, $origtext]
  90.   ["E", $tag, $origtext]
  91.   ["T", $text]
  92.   ["C", $text]
  93.   ["D", $text]</PRE>
  94. <P></P>
  95. <DT><STRONG><A NAME="item_unget_token">$p-><CODE>unget_token($token,...)</CODE></A></STRONG><BR>
  96. <DD>
  97. If you find out you have read too many tokens you can push them back,
  98. so that they are returned the next time $p->get_token is called.
  99. <P></P>
  100. <DT><STRONG><A NAME="item_get_tag">$p->get_tag( [$tag] )</A></STRONG><BR>
  101. <DD>
  102. This method return the next start or end tag (skipping any other
  103. tokens), or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if there is no more tags in the document.  If an
  104. argument is given, then we skip tokens until the specified tag is
  105. found.  A tag is returned as an array reference of the same form as
  106. for $p->get_token above, but the type code (first element) is missing
  107. and the name of end tags are prefixed with ``/''.  This means that the
  108. tags returned look like this:
  109. <PRE>
  110.   [$tag, %$attr, @$attrseq, $origtext]
  111.   ["/$tag", $origtext]</PRE>
  112. <P></P>
  113. <DT><STRONG><A NAME="item_get_text">$p->get_text( [$endtag] )</A></STRONG><BR>
  114. <DD>
  115. This method returns all text found at the current position. It will
  116. return a zero length string if the next token is not text.  The
  117. optional $endtag argument specify that any text occurring before the
  118. given tag is to be returned.  Any entities will be expanded to their
  119. corresponding character.
  120. <P>The $p->{textify} attribute is a hash that define how certain tags can
  121. be treated as text.  If the name of a start tag match a key in this
  122. hash then this tag is converted to text.  The hash value is used to
  123. specify which tag attribute to obtain the text from.  If this tag
  124. attribute is missing, then the upper case name of the tag enclosed in
  125. brackets is returned, e.g. ``[IMG]''.  The hash value can also be a
  126. subroutine reference.  In this case the routine is called with the
  127. start tag token content as arguments and the return values is treated
  128. as the text.</P>
  129. <P>The default $p->{textify} value is:</P>
  130. <PRE>
  131.   {img => "alt", applet => "alt"}</PRE>
  132. <P>This means that <IMG> and <APPLET> tags are treated as text, and that
  133. the text to substitute can be found as ALT attribute.</P>
  134. <P></P>
  135. <DT><STRONG><A NAME="item_get_trimmed_text">$p->get_trimmed_text( [$endtag] )</A></STRONG><BR>
  136. <DD>
  137. Same as $p->get_text above, but will collapse any sequence of white
  138. space to a single space character.  Leading and trailing space is
  139. removed.
  140. <P></P></DL>
  141. <P>
  142. <HR>
  143. <H1><A NAME="examples">EXAMPLES</A></H1>
  144. <P>This example extract all links from a document.  It will print one
  145. line for each link, containing the URL and the textual description
  146. between the <A>...</A> tags:</P>
  147. <PRE>
  148.   use HTML::TokeParser;
  149.   $p = HTML::TokeParser->new(shift||"index.html");</PRE>
  150. <PRE>
  151.   while (my $token = $p->get_tag("a")) {
  152.       my $url = $token->[1]{href} || "-";
  153.       my $text = $p->get_trimmed_text("/a");
  154.       print "$url\t$text\n";
  155.   }</PRE>
  156. <P>This example extract the <TITLE> from the document:</P>
  157. <PRE>
  158.   use HTML::TokeParser;
  159.   $p = HTML::TokeParser->new(shift||"index.html");
  160.   if ($p->get_tag("title")) {
  161.       my $title = $p->get_trimmed_text;
  162.       print "Title: $title\n";
  163.   }</PRE>
  164. <P>
  165. <HR>
  166. <H1><A NAME="see also">SEE ALSO</A></H1>
  167. <P><A HREF="../../../site/lib/HTML/Parser.html">the HTML::Parser manpage</A></P>
  168. <P>
  169. <HR>
  170. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  171. <P>Copyright 1998-1999 Gisle Aas.</P>
  172. <P>This library is free software; you can redistribute it and/or
  173. modify it under the same terms as Perl itself.</P>
  174. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  175. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  176. <STRONG><P CLASS=block> HTML::TokeParser - Alternative HTML::Parser interface</P></STRONG>
  177. </TD></TR>
  178. </TABLE>
  179.  
  180. </BODY>
  181.  
  182. </HTML>
  183.