local-lib5/lib/perl5/PPI/Token/Pod.pm

   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