Commit | Line | Data |
3fea05b9 |
1 | package PPI::Token::Pod; |
2 | |
3 | =pod |
4 | |
5 | =head1 NAME |
6 | |
7 | PPI::Token::Pod - Sections of POD in Perl documents |
8 | |
9 | =head1 INHERITANCE |
10 | |
11 | PPI::Token::Pod |
12 | isa PPI::Token |
13 | isa PPI::Element |
14 | |
15 | =head1 DESCRIPTION |
16 | |
17 | A single C<PPI::Token::Pod> object represents a complete section of POD |
18 | documentation within a Perl document. |
19 | |
20 | =head1 METHODS |
21 | |
22 | This class provides some additional methods beyond those provided by its |
23 | L<PPI::Token> and L<PPI::Element> parent classes. |
24 | |
25 | Got any ideas for more methods? Submit a report to rt.cpan.org! |
26 | |
27 | =cut |
28 | |
29 | use strict; |
30 | use Params::Util qw{_INSTANCE}; |
31 | use PPI::Token (); |
32 | |
33 | use vars qw{$VERSION @ISA}; |
34 | BEGIN { |
35 | $VERSION = '1.206'; |
36 | @ISA = 'PPI::Token'; |
37 | } |
38 | |
39 | |
40 | |
41 | |
42 | |
43 | ##################################################################### |
44 | # PPI::Token::Pod Methods |
45 | |
46 | =pod |
47 | |
48 | =head2 merge @podtokens |
49 | |
50 | The C<merge> constructor takes a number of C<PPI::Token::Pod> objects, |
51 | and returns a new object that represents one combined POD block with |
52 | the content of all of them. |
53 | |
54 | Returns a new C<PPI::Token::Pod> object, or C<undef> on error. |
55 | |
56 | =cut |
57 | |
58 | sub merge { |
59 | my $class = (! ref $_[0]) ? shift : return undef; |
60 | |
61 | # Check there are no bad arguments |
62 | if ( grep { ! _INSTANCE($_, 'PPI::Token::Pod') } @_ ) { |
63 | return undef; |
64 | } |
65 | |
66 | # Get the tokens, and extract the lines |
67 | my @content = (map { $_->lines } @_) or return undef; |
68 | |
69 | # Remove the leading =pod tags, trailing =cut tags, and any empty lines |
70 | # between them and the pod contents. |
71 | foreach my $pod ( @content ) { |
72 | # Leading =pod tag |
73 | if ( @$pod and $pod->[0] =~ /^=pod\b/o ) { |
74 | shift @$pod; |
75 | } |
76 | |
77 | # Trailing =cut tag |
78 | if ( @$pod and $pod->[-1] =~ /^=cut\b/o ) { |
79 | pop @$pod; |
80 | } |
81 | |
82 | # Leading and trailing empty lines |
83 | while ( @$pod and $pod->[0] eq '' ) { shift @$pod } |
84 | while ( @$pod and $pod->[-1] eq '' ) { pop @$pod } |
85 | } |
86 | |
87 | # Remove any empty pod sections, and add the =pod and =cut tags |
88 | # for the merged pod back to it. |
89 | @content = ( [ '=pod' ], grep { @$_ } @content, [ '=cut' ] ); |
90 | |
91 | # Create the new object |
92 | $class->new( join "\n", map { join( "\n", @$_ ) . "\n" } @content ); |
93 | } |
94 | |
95 | =pod |
96 | |
97 | =head2 lines |
98 | |
99 | The C<lines> method takes the string of POD and breaks it into lines, |
100 | returning them as a list. |
101 | |
102 | =cut |
103 | |
104 | sub lines { split /(?:\015{1,2}\012|\015|\012)/, $_[0]->{content} } |
105 | |
106 | |
107 | |
108 | |
109 | |
110 | |
111 | ##################################################################### |
112 | # PPI::Element Methods |
113 | |
114 | ### XS -> PPI/XS.xs:_PPI_Token_Pod__significant 0.900+ |
115 | sub significant { '' } |
116 | |
117 | |
118 | |
119 | |
120 | |
121 | ##################################################################### |
122 | # Tokenizer Methods |
123 | |
124 | sub __TOKENIZER__on_line_start { |
125 | my $t = $_[1]; |
126 | |
127 | # Add the line to the token first |
128 | $t->{token}->{content} .= $t->{line}; |
129 | |
130 | # Check the line to see if it is a =cut line |
131 | if ( $t->{line} =~ /^=(\w+)/ ) { |
132 | # End of the token |
133 | $t->_finalize_token if lc $1 eq 'cut'; |
134 | } |
135 | |
136 | 0; |
137 | } |
138 | |
139 | 1; |
140 | |
141 | =pod |
142 | |
143 | =head1 SUPPORT |
144 | |
145 | See the L<support section|PPI/SUPPORT> in the main module. |
146 | |
147 | =head1 AUTHOR |
148 | |
149 | Adam Kennedy E<lt>adamk@cpan.orgE<gt> |
150 | |
151 | =head1 COPYRIGHT |
152 | |
153 | Copyright 2001 - 2009 Adam Kennedy. |
154 | |
155 | This program is free software; you can redistribute |
156 | it and/or modify it under the same terms as Perl itself. |
157 | |
158 | The full text of the license can be found in the |
159 | LICENSE file included with this module. |
160 | |
161 | =cut |