1 # -*- mode: cperl; tab-width: 8; indent-tabs-mode: nil; basic-offset: 2 -*-
2 # vim:ts=8:sw=2:et:sta:sts=2
3 package Module::Metadata;
5 # Adapted from Perl-licensed code originally distributed with
6 # Module-Build by Ken Williams
8 # This module provides routines to gather information about
9 # perl modules (assuming this may be expanded in the distant
10 # parrot future to look at other types of modules).
15 our $VERSION = '1.000019';
16 $VERSION = eval $VERSION;
21 # Try really hard to not depend ony any DynaLoaded module, such as IO::File or Fcntl
23 require Fcntl; Fcntl->import('SEEK_SET'); 1;
24 } or *SEEK_SET = sub { 0 }
28 if ($INC{'Log/Contextual.pm'}) {
29 Log::Contextual->import('log_info');
31 *log_info = sub (&) { warn $_[0]->() };
34 use File::Find qw(find);
36 my $V_NUM_REGEXP = qr{v?[0-9._]+}; # crudely, a v-string or decimal
38 my $PKG_FIRST_WORD_REGEXP = qr{ # the FIRST word in a package name
39 [a-zA-Z_] # the first word CANNOT start with a digit
41 [\w']? # can contain letters, digits, _, or ticks
42 \w # But, NO multi-ticks or trailing ticks
46 my $PKG_ADDL_WORD_REGEXP = qr{ # the 2nd+ word in a package name
47 \w # the 2nd+ word CAN start with digits
49 [\w']? # and can contain letters or ticks
50 \w # But, NO multi-ticks or trailing ticks
54 my $PKG_NAME_REGEXP = qr{ # match a package name
55 (?: :: )? # a pkg name can start with arisdottle
56 $PKG_FIRST_WORD_REGEXP # a package word
58 (?: :: )+ ### arisdottle (allow one or many times)
59 $PKG_ADDL_WORD_REGEXP ### a package word
60 )* # ^ zero, one or many times
62 :: # allow trailing arisdottle
66 my $PKG_REGEXP = qr{ # match a package declaration
67 ^[\s\{;]* # intro chars on a line
68 package # the word 'package'
70 ($PKG_NAME_REGEXP) # a package name
71 \s* # optional whitespace
72 ($V_NUM_REGEXP)? # optional version number
73 \s* # optional whitesapce
74 [;\{] # semicolon line terminator or block start (since 5.16)
77 my $VARNAME_REGEXP = qr{ # match fully-qualified VERSION name
78 ([\$*]) # sigil - $ or *
80 ( # optional leading package name
81 (?:::|\')? # possibly starting like just :: (Ì la $::VERSION)
82 (?:\w+(?:::|\'))* # Foo::Bar:: ...
88 my $VERS_REGEXP = qr{ # match a VERSION definition
90 \(\s*$VARNAME_REGEXP\s*\) # with parens
92 $VARNAME_REGEXP # without parens
95 =[^=~>] # = but not ==, nor =~, nor =>
100 my $filename = File::Spec->rel2abs( shift );
102 return undef unless defined( $filename ) && -f $filename;
103 return $class->_init(undef, $filename, @_);
106 sub new_from_handle {
109 my $filename = shift;
110 return undef unless defined($handle) && defined($filename);
111 $filename = File::Spec->rel2abs( $filename );
113 return $class->_init(undef, $filename, @_, handle => $handle);
118 sub new_from_module {
123 $props{inc} ||= \@INC;
124 my $filename = $class->find_module_by_name( $module, $props{inc} );
125 return undef unless defined( $filename ) && -f $filename;
126 return $class->_init($module, $filename, %props);
131 my $compare_versions = sub {
132 my ($v1, $op, $v2) = @_;
133 $v1 = version->new($v1)
134 unless UNIVERSAL::isa($v1,'version');
136 my $eval_str = "\$v1 $op \$v2";
137 my $result = eval $eval_str;
138 log_info { "error comparing versions: '$eval_str' $@" } if $@;
143 my $normalize_version = sub {
145 if ( $version =~ /[=<>!,]/ ) { # logic, not just version
146 # take as is without modification
148 elsif ( ref $version eq 'version' ) { # version objects
149 $version = $version->is_qv ? $version->normal : $version->stringify;
151 elsif ( $version =~ /^[^v][^.]*\.[^.]+\./ ) { # no leading v, multiple dots
152 # normalize string tuples without "v": "1.2.3" -> "v1.2.3"
153 $version = "v$version";
161 # separate out some of the conflict resolution logic
163 my $resolve_module_versions = sub {
164 my $packages = shift;
166 my( $file, $version );
168 foreach my $p ( @$packages ) {
169 if ( defined( $p->{version} ) ) {
170 if ( defined( $version ) ) {
171 if ( $compare_versions->( $version, '!=', $p->{version} ) ) {
172 $err .= " $p->{file} ($p->{version})\n";
174 # same version declared multiple times, ignore
178 $version = $p->{version};
181 $file ||= $p->{file} if defined( $p->{file} );
185 $err = " $file ($version)\n" . $err;
200 croak "provides() requires key/value pairs \n" if @_ % 2;
203 croak "provides() takes only one of 'dir' or 'files'\n"
204 if $args{dir} && $args{files};
206 croak "provides() requires a 'version' argument"
207 unless defined $args{version};
209 croak "provides() does not support version '$args{version}' metadata"
210 unless grep { $args{version} eq $_ } qw/1.4 2/;
212 $args{prefix} = 'lib' unless defined $args{prefix};
216 $p = $class->package_versions_from_directory($args{dir});
219 croak "provides() requires 'files' to be an array reference\n"
220 unless ref $args{files} eq 'ARRAY';
221 $p = $class->package_versions_from_directory($args{files});
224 # Now, fix up files with prefix
225 if ( length $args{prefix} ) { # check in case disabled with q{}
226 $args{prefix} =~ s{/$}{};
227 for my $v ( values %$p ) {
228 $v->{file} = "$args{prefix}/$v->{file}";
235 sub package_versions_from_directory {
236 my ( $class, $dir, $files ) = @_;
245 push @files, $_ if -f $_ && /\.pm$/;
251 # First, we enumerate all packages & versions,
252 # separating into primary & alternative candidates
254 foreach my $file (@files) {
255 my $mapped_filename = File::Spec::Unix->abs2rel( $file, $dir );
256 my @path = split( /\//, $mapped_filename );
257 (my $prime_package = join( '::', @path )) =~ s/\.pm$//;
259 my $pm_info = $class->new_from_file( $file );
261 foreach my $package ( $pm_info->packages_inside ) {
262 next if $package eq 'main'; # main can appear numerous times, ignore
263 next if $package eq 'DB'; # special debugging package, ignore
264 next if grep /^_/, split( /::/, $package ); # private package, ignore
266 my $version = $pm_info->version( $package );
268 $prime_package = $package if lc($prime_package) eq lc($package);
269 if ( $package eq $prime_package ) {
270 if ( exists( $prime{$package} ) ) {
271 croak "Unexpected conflict in '$package'; multiple versions found.\n";
273 $mapped_filename = "$package.pm" if lc("$package.pm") eq lc($mapped_filename);
274 $prime{$package}{file} = $mapped_filename;
275 $prime{$package}{version} = $version if defined( $version );
278 push( @{$alt{$package}}, {
279 file => $mapped_filename,
286 # Then we iterate over all the packages found above, identifying conflicts
287 # and selecting the "best" candidate for recording the file & version
289 foreach my $package ( keys( %alt ) ) {
290 my $result = $resolve_module_versions->( $alt{$package} );
292 if ( exists( $prime{$package} ) ) { # primary package selected
294 if ( $result->{err} ) {
295 # Use the selected primary package, but there are conflicting
296 # errors among multiple alternative packages that need to be
299 "Found conflicting versions for package '$package'\n" .
300 " $prime{$package}{file} ($prime{$package}{version})\n" .
304 } elsif ( defined( $result->{version} ) ) {
305 # There is a primary package selected, and exactly one
306 # alternative package
308 if ( exists( $prime{$package}{version} ) &&
309 defined( $prime{$package}{version} ) ) {
310 # Unless the version of the primary package agrees with the
311 # version of the alternative package, report a conflict
312 if ( $compare_versions->(
313 $prime{$package}{version}, '!=', $result->{version}
318 "Found conflicting versions for package '$package'\n" .
319 " $prime{$package}{file} ($prime{$package}{version})\n" .
320 " $result->{file} ($result->{version})\n"
325 # The prime package selected has no version so, we choose to
326 # use any alternative package that does have a version
327 $prime{$package}{file} = $result->{file};
328 $prime{$package}{version} = $result->{version};
332 # no alt package found with a version, but we have a prime
333 # package so we use it whether it has a version or not
336 } else { # No primary package was selected, use the best alternative
338 if ( $result->{err} ) {
340 "Found conflicting versions for package '$package'\n" .
345 # Despite possible conflicting versions, we choose to record
346 # something rather than nothing
347 $prime{$package}{file} = $result->{file};
348 $prime{$package}{version} = $result->{version}
349 if defined( $result->{version} );
353 # Normalize versions. Can't use exists() here because of bug in YAML::Node.
354 # XXX "bug in YAML::Node" comment seems irrelevant -- dagolden, 2009-05-18
355 for (grep defined $_->{version}, values %prime) {
356 $_->{version} = $normalize_version->( $_->{version} );
367 my $filename = shift;
370 my $handle = delete $props{handle};
371 my( %valid_props, @valid_props );
372 @valid_props = qw( collect_pod inc );
373 @valid_props{@valid_props} = delete( @props{@valid_props} );
374 warn "Unknown properties: @{[keys %props]}\n" if scalar( %props );
378 filename => $filename,
389 my $self = bless(\%data, $class);
392 my $filename = $self->{filename};
393 open $handle, '<', $filename
394 or croak( "Can't open '$filename': $!" );
396 $self->_handle_bom($handle, $filename);
398 $self->_parse_fh($handle);
400 unless($self->{module} and length($self->{module})) {
401 my ($v, $d, $f) = File::Spec->splitpath($self->{filename});
404 my @candidates = grep /$f$/, @{$self->{packages}};
405 $self->{module} = shift(@candidates); # punt
408 if(grep /main/, @{$self->{packages}}) {
409 $self->{module} = 'main';
412 $self->{module} = $self->{packages}[0] || '';
417 $self->{version} = $self->{versions}{$self->{module}}
418 if defined( $self->{module} );
424 sub _do_find_module {
426 my $module = shift || croak 'find_module_by_name() requires a package name';
427 my $dirs = shift || \@INC;
429 my $file = File::Spec->catfile(split( /::/, $module));
430 foreach my $dir ( @$dirs ) {
431 my $testfile = File::Spec->catfile($dir, $file);
432 return [ File::Spec->rel2abs( $testfile ), $dir ]
433 if -e $testfile and !-d _; # For stuff like ExtUtils::xsubpp
434 return [ File::Spec->rel2abs( "$testfile.pm" ), $dir ]
435 if -e "$testfile.pm";
441 sub find_module_by_name {
442 my $found = shift()->_do_find_module(@_) or return;
447 sub find_module_dir_by_name {
448 my $found = shift()->_do_find_module(@_) or return;
453 # given a line of perl code, attempt to parse it if it looks like a
454 # $VERSION assignment, returning sigil, full name, & package name
455 sub _parse_version_expression {
459 my( $sigil, $variable_name, $package);
460 if ( $line =~ /$VERS_REGEXP/o ) {
461 ( $sigil, $variable_name, $package) = $2 ? ( $1, $2, $3 ) : ( $4, $5, $6 );
463 $package = ($package eq '::') ? 'main' : $package;
468 return ( $sigil, $variable_name, $package );
471 # Look for a UTF-8/UTF-16BE/UTF-16LE BOM at the beginning of the stream.
472 # If there's one, then skip it and set the :encoding layer appropriately.
474 my ($self, $fh, $filename) = @_;
477 return unless defined $pos;
480 my $count = read $fh, $buf, length $buf;
481 return unless defined $count and $count >= 2;
484 if ( $buf eq "\x{FE}\x{FF}" ) {
485 $encoding = 'UTF-16BE';
486 } elsif ( $buf eq "\x{FF}\x{FE}" ) {
487 $encoding = 'UTF-16LE';
488 } elsif ( $buf eq "\x{EF}\x{BB}" ) {
490 $count = read $fh, $buf, length $buf;
491 if ( defined $count and $count >= 1 and $buf eq "\x{BF}" ) {
496 if ( defined $encoding ) {
497 if ( "$]" >= 5.008 ) {
498 binmode( $fh, ":encoding($encoding)" );
501 seek $fh, $pos, SEEK_SET
502 or croak( sprintf "Can't reset position to the top of '$filename'" );
509 my ($self, $fh) = @_;
511 my( $in_pod, $seen_end, $need_vers ) = ( 0, 0, 0 );
512 my( @packages, %vers, %pod, @pod );
513 my $package = 'main';
518 while (defined( my $line = <$fh> )) {
523 # From toke.c : any line that begins by "=X", where X is an alphabetic
524 # character, introduces a POD segment.
526 if ( $line =~ /^=([a-zA-Z].*)/ ) {
528 # Then it goes back to Perl code for "=cutX" where X is a non-alphabetic
529 # character (which includes the newline, but here we chomped it away).
530 $is_cut = $cmd =~ /^cut(?:[^a-zA-Z]|$)/;
536 if ( $line =~ /^=head[1-4]\s+(.+)\s*$/ ) {
538 if ( $self->{collect_pod} && length( $pod_data ) ) {
539 $pod{$pod_sect} = $pod_data;
544 } elsif ( $self->{collect_pod} ) {
545 $pod_data .= "$line\n";
549 } elsif ( $is_cut ) {
551 if ( $self->{collect_pod} && length( $pod_data ) ) {
552 $pod{$pod_sect} = $pod_data;
562 # Skip comments in code
563 next if $line =~ /^\s*#/;
565 # Would be nice if we could also check $in_string or something too
566 if ($line eq '__END__') {
570 last if $line eq '__DATA__';
572 # parse $line to see if it's a $VERSION declaration
573 my( $version_sigil, $version_fullname, $version_package ) =
575 ? $self->_parse_version_expression( $line )
578 if ( $line =~ /$PKG_REGEXP/o ) {
580 push( @packages, $package ) unless grep( $package eq $_, @packages );
581 $vers{$package} = $2 unless exists( $vers{$package} );
582 $need_vers = defined $2 ? 0 : 1;
584 # VERSION defined with full package spec, i.e. $Module::VERSION
585 } elsif ( $version_fullname && $version_package ) {
586 push( @packages, $version_package ) unless grep( $version_package eq $_, @packages );
587 $need_vers = 0 if $version_package eq $package;
589 unless ( defined $vers{$version_package} && length $vers{$version_package} ) {
590 $vers{$version_package} = $self->_evaluate_version_line( $version_sigil, $version_fullname, $line );
593 # first non-comment line in undeclared package main is VERSION
594 } elsif ( !exists($vers{main}) && $package eq 'main' && $version_fullname ) {
596 my $v = $self->_evaluate_version_line( $version_sigil, $version_fullname, $line );
597 $vers{$package} = $v;
598 push( @packages, 'main' );
600 # first non-comment line in undeclared package defines package main
601 } elsif ( !exists($vers{main}) && $package eq 'main' && $line =~ /\w+/ ) {
604 push( @packages, 'main' );
606 # only keep if this is the first $VERSION seen
607 } elsif ( $version_fullname && $need_vers ) {
609 my $v = $self->_evaluate_version_line( $version_sigil, $version_fullname, $line );
611 unless ( defined $vers{$package} && length $vers{$package} ) {
612 $vers{$package} = $v;
618 if ( $self->{collect_pod} && length($pod_data) ) {
619 $pod{$pod_sect} = $pod_data;
622 $self->{versions} = \%vers;
623 $self->{packages} = \@packages;
624 $self->{pod} = \%pod;
625 $self->{pod_headings} = \@pod;
630 sub _evaluate_version_line {
632 my( $sigil, $variable_name, $line ) = @_;
634 # Some of this code came from the ExtUtils:: hierarchy.
636 # We compile into $vsub because 'use version' would cause
637 # compiletime/runtime issues with local()
639 $pn++; # everybody gets their own package
640 my $eval = qq{BEGIN { my \$dummy = q# Hide from _packages_inside()
641 #; package Module::Metadata::_version::p$pn;
647 local $sigil$variable_name;
648 \$$variable_name=undef;
654 $eval = $1 if $eval =~ m{^(.+)}s;
657 # Try to get the $VERSION
659 # some modules say $VERSION = $Foo::Bar::VERSION, but Foo::Bar isn't
660 # installed, so we need to hunt in ./lib for it
661 if ( $@ =~ /Can't locate/ && -d 'lib' ) {
662 local @INC = ('lib',@INC);
665 warn "Error evaling version line '$eval' in $self->{filename}: $@\n"
667 (ref($vsub) eq 'CODE') or
668 croak "failed to build version sub for $self->{filename}";
669 my $result = eval { $vsub->() };
670 croak "Could not get version from $self->{filename} by executing:\n$eval\n\nThe fatal error was: $@\n"
673 # Upgrade it into a version object
674 my $version = eval { _dwim_version($result) };
676 croak "Version '$result' from $self->{filename} does not appear to be valid:\n$eval\n\nThe fatal error was: $@\n"
677 unless defined $version; # "0" is OK!
683 # Try to DWIM when things fail the lax version test in obvious ways
686 # Best case, it just works
687 sub { return shift },
689 # If we still don't have a version, try stripping any
690 # trailing junk that is prohibited by lax rules
693 $v =~ s{([0-9])[a-z-].*$}{$1}i; # 1.23-alpha or 1.23b
697 # Activestate apparently creates custom versions like '1.23_45_01', which
698 # cause version.pm to think it's an invalid alpha. So check for that
702 my $num_dots = () = $v =~ m{(\.)}g;
703 my $num_unders = () = $v =~ m{(_)}g;
704 my $leading_v = substr($v,0,1) eq 'v';
705 if ( ! $leading_v && $num_dots < 2 && $num_unders > 1 ) {
707 $num_unders = () = $v =~ m{(_)}g;
712 # Worst case, try numifying it like we would have before version objects
715 no warnings 'numeric';
722 my ($result) = shift;
724 return $result if ref($result) eq 'version';
726 my ($version, $error);
727 for my $f (@version_prep) {
728 $result = $f->($result);
729 $version = eval { version->new($result) };
730 $error ||= $@ if $@; # capture first failure
731 last if defined $version;
734 croak $error unless defined $version;
740 ############################################################
743 sub name { $_[0]->{module} }
745 sub filename { $_[0]->{filename} }
746 sub packages_inside { @{$_[0]->{packages}} }
747 sub pod_inside { @{$_[0]->{pod_headings}} }
748 sub contains_pod { 0+@{$_[0]->{pod_headings}} }
752 my $mod = shift || $self->{module};
754 if ( defined( $mod ) && length( $mod ) &&
755 exists( $self->{versions}{$mod} ) ) {
756 return $self->{versions}{$mod};
765 if ( defined( $sect ) && length( $sect ) &&
766 exists( $self->{pod}{$sect} ) ) {
767 return $self->{pod}{$sect};
774 my ($self, $package) = @_;
776 my @indexable_packages = grep { $_ ne 'main' } $self->packages_inside;
778 # check for specific package, if provided
779 return !! grep { $_ eq $package } @indexable_packages if $package;
781 # otherwise, check for any indexable packages at all
782 return !! @indexable_packages;
789 Module::Metadata - Gather package and POD information from perl module files
793 use Module::Metadata;
795 # information about a .pm file
796 my $info = Module::Metadata->new_from_file( $file );
797 my $version = $info->version;
799 # CPAN META 'provides' field for .pm files in a directory
800 my $provides = Module::Metadata->provides(
801 dir => 'lib', version => 2
806 This module provides a standard way to gather metadata about a .pm file through
807 (mostly) static analysis and (some) code execution. When determining the
808 version of a module, the C<$VERSION> assignment is C<eval>ed, as is traditional
809 in the CPAN toolchain.
817 =item C<< new_from_file($filename, collect_pod => 1) >>
819 Constructs a C<Module::Metadata> object given the path to a file. Returns
820 undef if the filename does not exist.
822 C<collect_pod> is a optional boolean argument that determines whether POD
823 data is collected and stored for reference. POD data is not collected by
824 default. POD headings are always collected.
826 If the file begins by an UTF-8, UTF-16BE or UTF-16LE byte-order mark, then
827 it is skipped before processing, and the content of the file is also decoded
828 appropriately starting from perl 5.8.
830 =item C<< new_from_handle($handle, $filename, collect_pod => 1) >>
832 This works just like C<new_from_file>, except that a handle can be provided
833 as the first argument.
835 Note that there is no validation to confirm that the handle is a handle or
836 something that can act like one. Passing something that isn't a handle will
837 cause a exception when trying to read from it. The C<filename> argument is
838 mandatory or undef will be returned.
840 You are responsible for setting the decoding layers on C<$handle> if
843 =item C<< new_from_module($module, collect_pod => 1, inc => \@dirs) >>
845 Constructs a C<Module::Metadata> object given a module or package name.
846 Returns undef if the module cannot be found.
848 In addition to accepting the C<collect_pod> argument as described above,
849 this method accepts a C<inc> argument which is a reference to an array of
850 directories to search for the module. If none are given, the default is
853 If the file that contains the module begins by an UTF-8, UTF-16BE or
854 UTF-16LE byte-order mark, then it is skipped before processing, and the
855 content of the file is also decoded appropriately starting from perl 5.8.
857 =item C<< find_module_by_name($module, \@dirs) >>
859 Returns the path to a module given the module or package name. A list
860 of directories can be passed in as an optional parameter, otherwise
863 Can be called as either an object or a class method.
865 =item C<< find_module_dir_by_name($module, \@dirs) >>
867 Returns the entry in C<@dirs> (or C<@INC> by default) that contains
868 the module C<$module>. A list of directories can be passed in as an
869 optional parameter, otherwise @INC is searched.
871 Can be called as either an object or a class method.
873 =item C<< provides( %options ) >>
875 This is a convenience wrapper around C<package_versions_from_directory>
876 to generate a CPAN META C<provides> data structure. It takes key/value
877 pairs. Valid option keys include:
881 =item version B<(required)>
883 Specifies which version of the L<CPAN::Meta::Spec> should be used as
884 the format of the C<provides> output. Currently only '1.4' and '2'
885 are supported (and their format is identical). This may change in
886 the future as the definition of C<provides> changes.
888 The C<version> option is required. If it is omitted or if
889 an unsupported version is given, then C<provides> will throw an error.
893 Directory to search recursively for F<.pm> files. May not be specified with
898 Array reference of files to examine. May not be specified with C<dir>.
902 String to prepend to the C<file> field of the resulting output. This defaults
903 to F<lib>, which is the common case for most CPAN distributions with their
904 F<.pm> files in F<lib>. This option ensures the META information has the
905 correct relative path even when the C<dir> or C<files> arguments are
906 absolute or have relative paths from a location other than the distribution
911 For example, given C<dir> of 'lib' and C<prefix> of 'lib', the return value
912 is a hashref of the form:
917 file => 'lib/Package/Name.pm'
919 'OtherPackage::Name' => ...
922 =item C<< package_versions_from_directory($dir, \@files?) >>
924 Scans C<$dir> for .pm files (unless C<@files> is given, in which case looks
925 for those files in C<$dir> - and reads each file for packages and versions,
926 returning a hashref of the form:
931 file => 'Package/Name.pm'
933 'OtherPackage::Name' => ...
936 The C<DB> and C<main> packages are always omitted, as are any "private"
937 packages that have leading underscores in the namespace (e.g.
940 Note that the file path is relative to C<$dir> if that is specified.
941 This B<must not> be used directly for CPAN META C<provides>. See
942 the C<provides> method instead.
944 =item C<< log_info (internal) >>
946 Used internally to perform logging; imported from Log::Contextual if
947 Log::Contextual has already been loaded, otherwise simply calls warn.
951 =head2 Object methods
957 Returns the name of the package represented by this module. If there
958 is more than one package, it makes a best guess based on the
959 filename. If it's a script (i.e. not a *.pm) the package name is
962 =item C<< version($package) >>
964 Returns the version as defined by the $VERSION variable for the
965 package as returned by the C<name> method if no arguments are
966 given. If given the name of a package it will attempt to return the
967 version of that package if it is specified in the file.
969 =item C<< filename() >>
971 Returns the absolute path to the file.
973 =item C<< packages_inside() >>
975 Returns a list of packages. Note: this is a raw list of packages
976 discovered (or assumed, in the case of C<main>). It is not
977 filtered for C<DB>, C<main> or private packages the way the
978 C<provides> method does. Invalid package names are not returned,
979 for example "Foo:Bar". Strange but valid package names are
980 returned, for example "Foo::Bar::", and are left up to the caller
983 =item C<< pod_inside() >>
985 Returns a list of POD sections.
987 =item C<< contains_pod() >>
989 Returns true if there is any POD in the file.
991 =item C<< pod($section) >>
993 Returns the POD data in the given section.
995 =item C<< is_indexable($package) >> or C<< is_indexable() >>
997 Returns a boolean indicating whether the package (if provided) or any package
998 (otherwise) is eligible for indexing by PAUSE, the Perl Authors Upload Server.
999 Note This only checks for valid C<package> declarations, and does not take any
1000 ownership information into account.
1006 Original code from Module::Build::ModuleInfo by Ken Williams
1007 <kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
1009 Released as Module::Metadata by Matt S Trout (mst) <mst@shadowcat.co.uk> with
1010 assistance from David Golden (xdg) <dagolden@cpan.org>.
1012 =head1 COPYRIGHT & LICENSE
1014 Original code Copyright (c) 2001-2011 Ken Williams.
1015 Additional code Copyright (c) 2010-2011 Matt Trout and David Golden.
1016 All rights reserved.
1018 This library is free software; you can redistribute it and/or
1019 modify it under the same terms as Perl itself.