1
2require 5;
3package Pod::Simple::PullParserToken;
4 # Base class for tokens gotten from Pod::Simple::PullParser's $parser->get_token
5@ISA = ();
6$VERSION = '3.14';
7use strict;
8
9sub new {  # Class->new('type', stuff...);  ## Overridden in derived classes anyway
10  my $class = shift;
11  return bless [@_], ref($class) || $class;
12}
13
14sub type { $_[0][0] }  # Can't change the type of an object
15sub dump { Pod::Simple::pretty( [ @{ $_[0] } ] ) }
16
17sub is_start { $_[0][0] eq 'start' }
18sub is_end   { $_[0][0] eq 'end'   }
19sub is_text  { $_[0][0] eq 'text'  }
20
211;
22__END__
23
24sub dump { '[' . _esc( @{ $_[0] } ) . ']' }
25
26# JUNK:
27
28sub _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
45Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
46
47=head1 SYNOPSIS
48
49Given 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
70When you do $parser->get_token on a L<Pod::Simple::PullParser>, you should
71get an object of a subclass of Pod::Simple::PullParserToken.
72
73Subclasses will add methods, and will also inherit these methods:
74
75=over
76
77=item $token->type
78
79This returns the type of the token.  This will be either the string
80"start", the string "text", or the string "end".
81
82Once you know what the type of an object is, you then know what
83subclass it belongs to, and therefore what methods it supports.
84
85Yes, you could probably do the same thing with code like
86$token->isa('Pod::Simple::PullParserEndToken'), but that's not so
87pretty as using just $token->type, or even the following shortcuts:
88
89=item $token->is_start
90
91This is a shortcut for C<< $token->type() eq "start" >>
92
93=item $token->is_text
94
95This is a shortcut for C<< $token->type() eq "text" >>
96
97=item $token->is_end
98
99This is a shortcut for C<< $token->type() eq "end" >>
100
101=item $token->dump
102
103This returns a handy stringified value of this object.  This
104is 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
115My subclasses:
116L<Pod::Simple::PullParserStartToken>,
117L<Pod::Simple::PullParserTextToken>, and
118L<Pod::Simple::PullParserEndToken>.
119
120L<Pod::Simple::PullParser> and L<Pod::Simple>
121
122=head1 SUPPORT
123
124Questions or discussion about POD and Pod::Simple should be sent to the
125pod-people@perl.org mail list. Send an empty email to
126pod-people-subscribe@perl.org to subscribe.
127
128This module is managed in an open GitHub repository,
129L<http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or
130to clone L<git://github.com/theory/pod-simple.git> and send patches!
131
132Patches against Pod::Simple are welcome. Please send bug reports to
133<bug-pod-simple@rt.cpan.org>.
134
135=head1 COPYRIGHT AND DISCLAIMERS
136
137Copyright (c) 2002 Sean M. Burke.
138
139This library is free software; you can redistribute it and/or modify it
140under the same terms as Perl itself.
141
142This program is distributed in the hope that it will be useful, but
143without any warranty; without even the implied warranty of
144merchantability or fitness for a particular purpose.
145
146=head1 AUTHOR
147
148Pod::Simple was created by Sean M. Burke <sburke@cpan.org>.
149But don't bother him, he's retired.
150
151Pod::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
164