[Summary view] [Print] [Text view]

   1  
   2  require 5;
   3  package Pod::Simple::PullParserToken;
   4   # Base class for tokens gotten from Pod::Simple::PullParser's $parser->get_token
   5  @ISA = ();
   6  $VERSION = '2.02';
   7  use strict;
   8  
   9  sub new {  # Class->new('type', stuff...);  ## Overridden in derived classes anyway
  10    my $class = shift;
  11    return bless [@_], ref($class) || $class;
  12  }
  13  
  14  sub type { $_[0][0] }  # Can't change the type of an object
  15  sub dump { Pod::Simple::pretty( [ @{ $_[0] } ] ) }
  16  
  17  sub is_start { $_[0][0] eq 'start' }
  18  sub is_end   { $_[0][0] eq 'end'   }
  19  sub is_text  { $_[0][0] eq 'text'  }
  20  
  21  1;
  22  __END__
  23  
  24  sub dump { '[' . _esc( @{ $_[0] } ) . ']' }
  25  
  26  # JUNK:
  27  
  28  sub _esc {
  29    return '' unless @_;
  30    my @out;
  31    foreach my $in (@_) {
  32      push @out, '"' . $in . '"';
  33      $out[-1] =~ s/([^- \:\:\.\,\'\>\<\"\/\=\?\+\|\[\]\{\}\_a-zA-Z0-9_\`\~\!\#\%\^\&\*\(\)])/
  34        sprintf( (ord($1) < 256) ? "\\x%02X" : "\\x{%X}", ord($1))
  35      /eg;
  36    }
  37    return join ', ', @out;
  38  }
  39  
  40  
  41  __END__
  42  
  43  =head1 NAME
  44  
  45  Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
  46  
  47  =head1 SYNOPSIS
  48  
  49  Given a $parser that's an object of class Pod::Simple::PullParser
  50  (or a subclass)...
  51  
  52    while(my $token = $parser->get_token) {
  53      $DEBUG and print "Token: ", $token->dump, "\n";
  54      if($token->is_start) {
  55        ...access $token->tagname, $token->attr, etc...
  56  
  57      } elsif($token->is_text) {
  58        ...access $token->text, $token->text_r, etc...
  59      
  60      } elsif($token->is_end) {
  61        ...access $token->tagname...
  62      
  63      }
  64    }
  65  
  66  (Also see L<Pod::Simple::PullParser>)
  67  
  68  =head1 DESCRIPTION
  69  
  70  When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should
  71  get an object of a subclass of Pod::Simple::PullParserToken.
  72  
  73  Subclasses will add methods, and will also inherit these methods:
  74  
  75  =over
  76  
  77  =item $token->type
  78  
  79  This returns the type of the token.  This will be either the string
  80  "start", the string "text", or the string "end".
  81  
  82  Once you know what the type of an object is, you then know what
  83  subclass it belongs to, and therefore what methods it supports.
  84  
  85  Yes, you could probably do the same thing with code like
  86  $token->isa('Pod::Simple::PullParserEndToken'), but that's not so
  87  pretty as using just $token->type, or even the following shortcuts:
  88  
  89  =item $token->is_start
  90  
  91  This is a shortcut for C<< $token->type() eq "start" >>
  92  
  93  =item $token->is_text
  94  
  95  This is a shortcut for C<< $token->type() eq "text" >>
  96  
  97  =item $token->is_end
  98  
  99  This is a shortcut for C<< $token->type() eq "end" >>
 100  
 101  =item $token->dump
 102  
 103  This returns a handy stringified value of this object.  This
 104  is useful for debugging, as in:
 105  
 106    while(my $token = $parser->get_token) {
 107      $DEBUG and print "Token: ", $token->dump, "\n";
 108      ...
 109    }
 110  
 111  =back
 112  
 113  =head1 SEE ALSO
 114  
 115  My subclasses:
 116  L<Pod::Simple::PullParserStartToken>,
 117  L<Pod::Simple::PullParserTextToken>, and
 118  L<Pod::Simple::PullParserEndToken>.
 119  
 120  L<Pod::Simple::PullParser> and L<Pod::Simple>
 121  
 122  =head1 COPYRIGHT AND DISCLAIMERS
 123  
 124  Copyright (c) 2002 Sean M. Burke.  All rights reserved.
 125  
 126  This library is free software; you can redistribute it and/or modify it
 127  under the same terms as Perl itself.
 128  
 129  This program is distributed in the hope that it will be useful, but
 130  without any warranty; without even the implied warranty of
 131  merchantability or fitness for a particular purpose.
 132  
 133  =head1 AUTHOR
 134  
 135  Sean M. Burke C<sburke@cpan.org>
 136  
 137  =cut
 138