Move Pod::Simple from ext/ to cpan/
[perl.git] / cpan / Pod-Simple / lib / Pod / Simple / PullParserTextToken.pm
1
2 require 5;
3 package Pod::Simple::PullParserTextToken;
4 use Pod::Simple::PullParserToken ();
5 @ISA = ('Pod::Simple::PullParserToken');
6 use strict;
7
8 sub new {  # Class->new(text);
9   my $class = shift;
10   return bless ['text', @_], ref($class) || $class;
11 }
12
13 # Purely accessors:
14
15 sub text { (@_ == 2) ? ($_[0][1] = $_[1]) : $_[0][1] }
16
17 sub text_r { \ $_[0][1] }
18
19 1;
20
21 __END__
22
23 =head1 NAME
24
25 Pod::Simple::PullParserTextToken -- text-tokens from Pod::Simple::PullParser
26
27 =head1 SYNOPSIS
28
29 (See L<Pod::Simple::PullParser>)
30
31 =head1 DESCRIPTION
32
33 When you do $parser->get_token on a L<Pod::Simple::PullParser>, you might
34 get an object of this class.
35
36 This is a subclass of L<Pod::Simple::PullParserToken> and inherits all its methods,
37 and adds these methods:
38
39 =over
40
41 =item $token->text
42
43 This returns the text that this token holds.  For example, parsing
44 CZ<><foo> will return a C start-token, a text-token, and a C end-token.  And
45 if you want to get the "foo" out of the text-token, call C<< $token->text >>
46
47 =item $token->text(I<somestring>)
48
49 This changes the string that this token holds.  You probably won't need
50 to do this.
51
52 =item $token->text_r()
53
54 This returns a scalar reference to the string that this token holds.
55 This can be useful if you don't want to memory-copy the potentially
56 large text value (well, as large as a paragraph or a verbatim block)
57 as calling $token->text would do.
58
59 Or, if you want to alter the value, you can even do things like this:
60
61   for ( ${  $token->text_r  } ) {  # Aliases it with $_ !!
62   
63     s/ The / the /g; # just for example
64     
65     if( 'A' eq chr(65) ) {  # (if in an ASCII world)
66       tr/\xA0/ /;
67       tr/\xAD//d;
68     }
69     
70     ...or however you want to alter the value...
71   }
72
73 =back
74
75 You're unlikely to ever need to construct an object of this class for
76 yourself, but if you want to, call
77 C<<
78 Pod::Simple::PullParserTextToken->new( I<text> )
79 >>
80
81 =head1 SEE ALSO
82
83 L<Pod::Simple::PullParserToken>, L<Pod::Simple>, L<Pod::Simple::Subclassing>
84
85 =head1 COPYRIGHT AND DISCLAIMERS
86
87 Copyright (c) 2002 Sean M. Burke.  All rights reserved.
88
89 This library is free software; you can redistribute it and/or modify it
90 under the same terms as Perl itself.
91
92 This program is distributed in the hope that it will be useful, but
93 without any warranty; without even the implied warranty of
94 merchantability or fitness for a particular purpose.
95
96 =head1 AUTHOR
97
98 Sean M. Burke C<sburke@cpan.org>
99
100 =cut
101