9ec3659f4ed34d8a20bab094aa90b14b682cd40f
[perl.git] / ext / 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 = '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