1package Pod::Simple::PullParserToken; 2 # Base class for tokens gotten from Pod::Simple::PullParser's $parser->get_token 3our @ISA = (); 4our $VERSION = '3.45'; 5use strict; 6 7sub new { # Class->new('type', stuff...); ## Overridden in derived classes anyway 8 my $class = shift; 9 return bless [@_], ref($class) || $class; 10} 11 12sub type { $_[0][0] } # Can't change the type of an object 13sub dump { Pod::Simple::pretty( [ @{ $_[0] } ] ) } 14 15sub is_start { $_[0][0] eq 'start' } 16sub is_end { $_[0][0] eq 'end' } 17sub is_text { $_[0][0] eq 'text' } 18 191; 20__END__ 21 22sub dump { '[' . _esc( @{ $_[0] } ) . ']' } 23 24# JUNK: 25 26sub _esc { 27 return '' unless @_; 28 my @out; 29 foreach my $in (@_) { 30 push @out, '"' . $in . '"'; 31 $out[-1] =~ s/([^- \:\:\.\,\'\>\<\"\/\=\?\+\|\[\]\{\}\_a-zA-Z0-9_\`\~\!\#\%\^\&\*\(\)])/ 32 sprintf( (ord($1) < 256) ? "\\x%02X" : "\\x{%X}", ord($1)) 33 /eg; 34 } 35 return join ', ', @out; 36} 37 38 39__END__ 40 41=head1 NAME 42 43Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser 44 45=head1 SYNOPSIS 46 47Given a $parser that's an object of class Pod::Simple::PullParser 48(or a subclass)... 49 50 while(my $token = $parser->get_token) { 51 $DEBUG and print STDERR "Token: ", $token->dump, "\n"; 52 if($token->is_start) { 53 ...access $token->tagname, $token->attr, etc... 54 55 } elsif($token->is_text) { 56 ...access $token->text, $token->text_r, etc... 57 58 } elsif($token->is_end) { 59 ...access $token->tagname... 60 61 } 62 } 63 64(Also see L<Pod::Simple::PullParser>) 65 66=head1 DESCRIPTION 67 68When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should 69get an object of a subclass of Pod::Simple::PullParserToken. 70 71Subclasses will add methods, and will also inherit these methods: 72 73=over 74 75=item $token->type 76 77This returns the type of the token. This will be either the string 78"start", the string "text", or the string "end". 79 80Once you know what the type of an object is, you then know what 81subclass it belongs to, and therefore what methods it supports. 82 83Yes, you could probably do the same thing with code like 84$token->isa('Pod::Simple::PullParserEndToken'), but that's not so 85pretty as using just $token->type, or even the following shortcuts: 86 87=item $token->is_start 88 89This is a shortcut for C<< $token->type() eq "start" >> 90 91=item $token->is_text 92 93This is a shortcut for C<< $token->type() eq "text" >> 94 95=item $token->is_end 96 97This is a shortcut for C<< $token->type() eq "end" >> 98 99=item $token->dump 100 101This returns a handy stringified value of this object. This 102is useful for debugging, as in: 103 104 while(my $token = $parser->get_token) { 105 $DEBUG and print STDERR "Token: ", $token->dump, "\n"; 106 ... 107 } 108 109=back 110 111=head1 SEE ALSO 112 113My subclasses: 114L<Pod::Simple::PullParserStartToken>, 115L<Pod::Simple::PullParserTextToken>, and 116L<Pod::Simple::PullParserEndToken>. 117 118L<Pod::Simple::PullParser> and L<Pod::Simple> 119 120=head1 SUPPORT 121 122Questions or discussion about POD and Pod::Simple should be sent to the 123pod-people@perl.org mail list. Send an empty email to 124pod-people-subscribe@perl.org to subscribe. 125 126This module is managed in an open GitHub repository, 127L<https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or 128to clone L<https://github.com/perl-pod/pod-simple.git> and send patches! 129 130Patches against Pod::Simple are welcome. Please send bug reports to 131<bug-pod-simple@rt.cpan.org>. 132 133=head1 COPYRIGHT AND DISCLAIMERS 134 135Copyright (c) 2002 Sean M. Burke. 136 137This library is free software; you can redistribute it and/or modify it 138under the same terms as Perl itself. 139 140This program is distributed in the hope that it will be useful, but 141without any warranty; without even the implied warranty of 142merchantability or fitness for a particular purpose. 143 144=head1 AUTHOR 145 146Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. 147But don't bother him, he's retired. 148 149Pod::Simple is maintained by: 150 151=over 152 153=item * Allison Randal C<allison@perl.org> 154 155=item * Hans Dieter Pearcey C<hdp@cpan.org> 156 157=item * David E. Wheeler C<dwheeler@cpan.org> 158 159=back 160 161=cut 162use warnings; 163