cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm

   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 = '3.40';
   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 STDERR "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 STDERR "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 SUPPORT
 123
 124 Questions or discussion about POD and Pod::Simple should be sent to the
 125 pod-people@perl.org mail list. Send an empty email to
 126 pod-people-subscribe@perl.org to subscribe.
 127
 128 This module is managed in an open GitHub repository,
 129 L<https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or
 130 to clone L<git://github.com/perl-pod/pod-simple.git> and send patches!
 131
 132 Patches against Pod::Simple are welcome. Please send bug reports to
 133 <bug-pod-simple@rt.cpan.org>.
 134
 135 =head1 COPYRIGHT AND DISCLAIMERS
 136
 137 Copyright (c) 2002 Sean M. Burke.
 138
 139 This library is free software; you can redistribute it and/or modify it
 140 under the same terms as Perl itself.
 141
 142 This program is distributed in the hope that it will be useful, but
 143 without any warranty; without even the implied warranty of
 144 merchantability or fitness for a particular purpose.
 145
 146 =head1 AUTHOR
 147
 148 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
 149 But don't bother him, he's retired.
 150
 151 Pod::Simple is maintained by:
 152
 153 =over
 154
 155 =item * Allison Randal C<allison@perl.org>
 156
 157 =item * Hans Dieter Pearcey C<hdp@cpan.org>
 158
 159 =item * David E. Wheeler C<dwheeler@cpan.org>
 160
 161 =back
 162
 163 =cut