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;
23 if ($INC{'Log/Contextual.pm'}) {
24 Log::Contextual->import('log_info');
26 *log_info = sub (&) { warn $_[0]->() };
29 use File::Find qw(find);
31 my $V_NUM_REGEXP = qr{v?[0-9._]+}; # crudely, a v-string or decimal
33 my $PKG_FIRST_WORD_REGEXP = qr{ # the FIRST word in a package name
34 [a-zA-Z_] # the first word CANNOT start with a digit
36 [\w']? # can contain letters, digits, _, or ticks
37 \w # But, NO multi-ticks or trailing ticks
41 my $PKG_ADDL_WORD_REGEXP = qr{ # the 2nd+ word in a package name
42 \w # the 2nd+ word CAN start with digits
44 [\w']? # and can contain letters or ticks
45 \w # But, NO multi-ticks or trailing ticks
49 my $PKG_NAME_REGEXP = qr{ # match a package name
50 (?: :: )? # a pkg name can start with aristotle
51 $PKG_FIRST_WORD_REGEXP # a package word
53 (?: :: )+ ### aristotle (allow one or many times)
54 $PKG_ADDL_WORD_REGEXP ### a package word
55 )* # ^ zero, one or many times
57 :: # allow trailing aristotle
61 my $PKG_REGEXP = qr{ # match a package declaration
62 ^[\s\{;]* # intro chars on a line
63 package # the word 'package'
65 ($PKG_NAME_REGEXP) # a package name
66 \s* # optional whitespace
67 ($V_NUM_REGEXP)? # optional version number
68 \s* # optional whitesapce
69 [;\{] # semicolon line terminator or block start (since 5.16)
72 my $VARNAME_REGEXP = qr{ # match fully-qualified VERSION name
73 ([\$*]) # sigil - $ or *
75 ( # optional leading package name
76 (?:::|\')? # possibly starting like just :: (Ì la $::VERSION)
77 (?:\w+(?:::|\'))* # Foo::Bar:: ...
83 my $VERS_REGEXP = qr{ # match a VERSION definition
85 \(\s*$VARNAME_REGEXP\s*\) # with parens
87 $VARNAME_REGEXP # without parens
90 =[^=~>] # = but not ==, nor =~, nor =>
95 my $filename = File::Spec->rel2abs( shift );
97 return undef unless defined( $filename ) && -f $filename;
98 return $class->_init(undef, $filename, @_);
101 sub new_from_handle {
104 my $filename = shift;
105 return undef unless defined($handle) && defined($filename);
106 $filename = File::Spec->rel2abs( $filename );
108 return $class->_init(undef, $filename, @_, handle => $handle);
113 sub new_from_module {
118 $props{inc} ||= \@INC;
119 my $filename = $class->find_module_by_name( $module, $props{inc} );
120 return undef unless defined( $filename ) && -f $filename;
121 return $class->_init($module, $filename, %props);
126 my $compare_versions = sub {
127 my ($v1, $op, $v2) = @_;
128 $v1 = version->new($v1)
129 unless UNIVERSAL::isa($v1,'version');
131 my $eval_str = "\$v1 $op \$v2";
132 my $result = eval $eval_str;
133 log_info { "error comparing versions: '$eval_str' $@" } if $@;
138 my $normalize_version = sub {
140 if ( $version =~ /[=<>!,]/ ) { # logic, not just version
141 # take as is without modification
143 elsif ( ref $version eq 'version' ) { # version objects
144 $version = $version->is_qv ? $version->normal : $version->stringify;
146 elsif ( $version =~ /^[^v][^.]*\.[^.]+\./ ) { # no leading v, multiple dots
147 # normalize string tuples without "v": "1.2.3" -> "v1.2.3"
148 $version = "v$version";
156 # separate out some of the conflict resolution logic
158 my $resolve_module_versions = sub {
159 my $packages = shift;
161 my( $file, $version );
163 foreach my $p ( @$packages ) {
164 if ( defined( $p->{version} ) ) {
165 if ( defined( $version ) ) {
166 if ( $compare_versions->( $version, '!=', $p->{version} ) ) {
167 $err .= " $p->{file} ($p->{version})\n";
169 # same version declared multiple times, ignore
173 $version = $p->{version};
176 $file ||= $p->{file} if defined( $p->{file} );
180 $err = " $file ($version)\n" . $err;
195 croak "provides() requires key/value pairs \n" if @_ % 2;
198 croak "provides() takes only one of 'dir' or 'files'\n"
199 if $args{dir} && $args{files};
201 croak "provides() takes only one of 'files' or 'prefix'\n"
202 if $args{files} && $args{prefix};
204 croak "provides() requires a 'version' argument"
205 unless defined $args{version};
207 croak "provides() does not support version '$args{version}' metadata"
208 unless grep { $args{version} eq $_ } qw/1.4 2/;
210 $args{prefix} = 'lib' unless defined $args{prefix};
214 $p = $class->package_versions_from_directory($args{dir});
217 croak "provides() requires 'files' to be an array reference\n"
218 unless ref $args{files} eq 'ARRAY';
219 $p = $class->package_versions_from_directory('', $args{files});
222 # Now, fix up files with prefix
223 if ( not $args{files} and length $args{prefix} ) { # check in case disabled with q{}
224 $args{prefix} =~ s{/$}{};
225 for my $v ( values %$p ) {
226 $v->{file} = "$args{prefix}/$v->{file}";
233 sub package_versions_from_directory {
234 my ( $class, $dir, $files ) = @_;
243 push @files, $_ if -f $_ && /\.pm$/;
249 # First, we enumerate all packages & versions,
250 # separating into primary & alternative candidates
252 foreach my $file (@files) {
253 my $mapped_filename = File::Spec::Unix->abs2rel( $file, $dir );
254 my @path = split( /\//, $mapped_filename );
255 (my $prime_package = join( '::', @path )) =~ s/\.pm$//;
257 my $pm_info = $class->new_from_file( $file );
259 foreach my $package ( $pm_info->packages_inside ) {
260 next if $package eq 'main'; # main can appear numerous times, ignore
261 next if $package eq 'DB'; # special debugging package, ignore
262 next if grep /^_/, split( /::/, $package ); # private package, ignore
264 my $version = $pm_info->version( $package );
266 $prime_package = $package if lc($prime_package) eq lc($package);
267 if ( $package eq $prime_package ) {
268 if ( exists( $prime{$package} ) ) {
269 croak "Unexpected conflict in '$package'; multiple versions found.\n";
271 $mapped_filename = "$package.pm" if lc("$package.pm") eq lc($mapped_filename);
272 $prime{$package}{file} = $mapped_filename;
273 $prime{$package}{version} = $version if defined( $version );
276 push( @{$alt{$package}}, {
277 file => $mapped_filename,
284 # Then we iterate over all the packages found above, identifying conflicts
285 # and selecting the "best" candidate for recording the file & version
287 foreach my $package ( keys( %alt ) ) {
288 my $result = $resolve_module_versions->( $alt{$package} );
290 if ( exists( $prime{$package} ) ) { # primary package selected
292 if ( $result->{err} ) {
293 # Use the selected primary package, but there are conflicting
294 # errors among multiple alternative packages that need to be
297 "Found conflicting versions for package '$package'\n" .
298 " $prime{$package}{file} ($prime{$package}{version})\n" .
302 } elsif ( defined( $result->{version} ) ) {
303 # There is a primary package selected, and exactly one
304 # alternative package
306 if ( exists( $prime{$package}{version} ) &&
307 defined( $prime{$package}{version} ) ) {
308 # Unless the version of the primary package agrees with the
309 # version of the alternative package, report a conflict
310 if ( $compare_versions->(
311 $prime{$package}{version}, '!=', $result->{version}
316 "Found conflicting versions for package '$package'\n" .
317 " $prime{$package}{file} ($prime{$package}{version})\n" .
318 " $result->{file} ($result->{version})\n"
323 # The prime package selected has no version so, we choose to
324 # use any alternative package that does have a version
325 $prime{$package}{file} = $result->{file};
326 $prime{$package}{version} = $result->{version};
330 # no alt package found with a version, but we have a prime
331 # package so we use it whether it has a version or not
334 } else { # No primary package was selected, use the best alternative
336 if ( $result->{err} ) {
338 "Found conflicting versions for package '$package'\n" .
343 # Despite possible conflicting versions, we choose to record
344 # something rather than nothing
345 $prime{$package}{file} = $result->{file};
346 $prime{$package}{version} = $result->{version}
347 if defined( $result->{version} );
351 # Normalize versions. Can't use exists() here because of bug in YAML::Node.
352 # XXX "bug in YAML::Node" comment seems irrelevant -- dagolden, 2009-05-18
353 for (grep defined $_->{version}, values %prime) {
354 $_->{version} = $normalize_version->( $_->{version} );
365 my $filename = shift;
368 my $handle = delete $props{handle};
369 my( %valid_props, @valid_props );
370 @valid_props = qw( collect_pod inc );
371 @valid_props{@valid_props} = delete( @props{@valid_props} );
372 warn "Unknown properties: @{[keys %props]}\n" if scalar( %props );
376 filename => $filename,
387 my $self = bless(\%data, $class);
390 $self->_parse_fh($handle);
393 $self->_parse_file();
396 unless($self->{module} and length($self->{module})) {
397 my ($v, $d, $f) = File::Spec->splitpath($self->{filename});
400 my @candidates = grep /$f$/, @{$self->{packages}};
401 $self->{module} = shift(@candidates); # punt
404 if(grep /main/, @{$self->{packages}}) {
405 $self->{module} = 'main';
408 $self->{module} = $self->{packages}[0] || '';
413 $self->{version} = $self->{versions}{$self->{module}}
414 if defined( $self->{module} );
420 sub _do_find_module {
422 my $module = shift || croak 'find_module_by_name() requires a package name';
423 my $dirs = shift || \@INC;
425 my $file = File::Spec->catfile(split( /::/, $module));
426 foreach my $dir ( @$dirs ) {
427 my $testfile = File::Spec->catfile($dir, $file);
428 return [ File::Spec->rel2abs( $testfile ), $dir ]
429 if -e $testfile and !-d _; # For stuff like ExtUtils::xsubpp
430 return [ File::Spec->rel2abs( "$testfile.pm" ), $dir ]
431 if -e "$testfile.pm";
437 sub find_module_by_name {
438 my $found = shift()->_do_find_module(@_) or return;
443 sub find_module_dir_by_name {
444 my $found = shift()->_do_find_module(@_) or return;
449 # given a line of perl code, attempt to parse it if it looks like a
450 # $VERSION assignment, returning sigil, full name, & package name
451 sub _parse_version_expression {
455 my( $sig, $var, $pkg );
456 if ( $line =~ /$VERS_REGEXP/o ) {
457 ( $sig, $var, $pkg ) = $2 ? ( $1, $2, $3 ) : ( $4, $5, $6 );
459 $pkg = ($pkg eq '::') ? 'main' : $pkg;
464 return ( $sig, $var, $pkg );
470 my $filename = $self->{filename};
471 my $fh = IO::File->new( $filename )
472 or croak( "Can't open '$filename': $!" );
474 $self->_handle_bom($fh, $filename);
476 $self->_parse_fh($fh);
479 # Look for a UTF-8/UTF-16BE/UTF-16LE BOM at the beginning of the stream.
480 # If there's one, then skip it and set the :encoding layer appropriately.
482 my ($self, $fh, $filename) = @_;
484 my $pos = $fh->getpos;
485 return unless defined $pos;
488 my $count = $fh->read( $buf, length $buf );
489 return unless defined $count and $count >= 2;
492 if ( $buf eq "\x{FE}\x{FF}" ) {
493 $encoding = 'UTF-16BE';
494 } elsif ( $buf eq "\x{FF}\x{FE}" ) {
495 $encoding = 'UTF-16LE';
496 } elsif ( $buf eq "\x{EF}\x{BB}" ) {
498 $count = $fh->read( $buf, length $buf );
499 if ( defined $count and $count >= 1 and $buf eq "\x{BF}" ) {
504 if ( defined $encoding ) {
505 if ( "$]" >= 5.008 ) {
506 # $fh->binmode requires perl 5.10
507 binmode( $fh, ":encoding($encoding)" );
511 or croak( sprintf "Can't reset position to the top of '$filename'" );
518 my ($self, $fh) = @_;
520 my( $in_pod, $seen_end, $need_vers ) = ( 0, 0, 0 );
521 my( @pkgs, %vers, %pod, @pod );
527 while (defined( my $line = <$fh> )) {
532 # From toke.c : any line that begins by "=X", where X is an alphabetic
533 # character, introduces a POD segment.
535 if ( $line =~ /^=([a-zA-Z].*)/ ) {
537 # Then it goes back to Perl code for "=cutX" where X is a non-alphabetic
538 # character (which includes the newline, but here we chomped it away).
539 $is_cut = $cmd =~ /^cut(?:[^a-zA-Z]|$)/;
545 if ( $line =~ /^=head[1-4]\s+(.+)\s*$/ ) {
547 if ( $self->{collect_pod} && length( $pod_data ) ) {
548 $pod{$pod_sect} = $pod_data;
553 } elsif ( $self->{collect_pod} ) {
554 $pod_data .= "$line\n";
558 } elsif ( $is_cut ) {
560 if ( $self->{collect_pod} && length( $pod_data ) ) {
561 $pod{$pod_sect} = $pod_data;
571 # Skip comments in code
572 next if $line =~ /^\s*#/;
574 # Would be nice if we could also check $in_string or something too
575 if ($line eq '__END__') {
579 last if $line eq '__DATA__';
581 # parse $line to see if it's a $VERSION declaration
582 my( $vers_sig, $vers_fullname, $vers_pkg ) =
584 ? $self->_parse_version_expression( $line )
587 if ( $line =~ /$PKG_REGEXP/o ) {
589 push( @pkgs, $pkg ) unless grep( $pkg eq $_, @pkgs );
590 $vers{$pkg} = $2 unless exists( $vers{$pkg} );
591 $need_vers = defined $2 ? 0 : 1;
593 # VERSION defined with full package spec, i.e. $Module::VERSION
594 } elsif ( $vers_fullname && $vers_pkg ) {
595 push( @pkgs, $vers_pkg ) unless grep( $vers_pkg eq $_, @pkgs );
596 $need_vers = 0 if $vers_pkg eq $pkg;
598 unless ( defined $vers{$vers_pkg} && length $vers{$vers_pkg} ) {
600 $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
603 # first non-comment line in undeclared package main is VERSION
604 } elsif ( !exists($vers{main}) && $pkg eq 'main' && $vers_fullname ) {
607 $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
609 push( @pkgs, 'main' );
611 # first non-comment line in undeclared package defines package main
612 } elsif ( !exists($vers{main}) && $pkg eq 'main' && $line =~ /\w+/ ) {
615 push( @pkgs, 'main' );
617 # only keep if this is the first $VERSION seen
618 } elsif ( $vers_fullname && $need_vers ) {
621 $self->_evaluate_version_line( $vers_sig, $vers_fullname, $line );
624 unless ( defined $vers{$pkg} && length $vers{$pkg} ) {
634 if ( $self->{collect_pod} && length($pod_data) ) {
635 $pod{$pod_sect} = $pod_data;
638 $self->{versions} = \%vers;
639 $self->{packages} = \@pkgs;
640 $self->{pod} = \%pod;
641 $self->{pod_headings} = \@pod;
646 sub _evaluate_version_line {
648 my( $sigil, $var, $line ) = @_;
650 # Some of this code came from the ExtUtils:: hierarchy.
652 # We compile into $vsub because 'use version' would cause
653 # compiletime/runtime issues with local()
655 $pn++; # everybody gets their own package
656 my $eval = qq{BEGIN { my \$dummy = q# Hide from _packages_inside()
657 #; package Module::Metadata::_version::p$pn;
670 $eval = $1 if $eval =~ m{^(.+)}s;
673 # Try to get the $VERSION
675 # some modules say $VERSION = $Foo::Bar::VERSION, but Foo::Bar isn't
676 # installed, so we need to hunt in ./lib for it
677 if ( $@ =~ /Can't locate/ && -d 'lib' ) {
678 local @INC = ('lib',@INC);
681 warn "Error evaling version line '$eval' in $self->{filename}: $@\n"
683 (ref($vsub) eq 'CODE') or
684 croak "failed to build version sub for $self->{filename}";
685 my $result = eval { $vsub->() };
686 croak "Could not get version from $self->{filename} by executing:\n$eval\n\nThe fatal error was: $@\n"
689 # Upgrade it into a version object
690 my $version = eval { _dwim_version($result) };
692 croak "Version '$result' from $self->{filename} does not appear to be valid:\n$eval\n\nThe fatal error was: $@\n"
693 unless defined $version; # "0" is OK!
699 # Try to DWIM when things fail the lax version test in obvious ways
702 # Best case, it just works
703 sub { return shift },
705 # If we still don't have a version, try stripping any
706 # trailing junk that is prohibited by lax rules
709 $v =~ s{([0-9])[a-z-].*$}{$1}i; # 1.23-alpha or 1.23b
713 # Activestate apparently creates custom versions like '1.23_45_01', which
714 # cause version.pm to think it's an invalid alpha. So check for that
718 my $num_dots = () = $v =~ m{(\.)}g;
719 my $num_unders = () = $v =~ m{(_)}g;
720 my $leading_v = substr($v,0,1) eq 'v';
721 if ( ! $leading_v && $num_dots < 2 && $num_unders > 1 ) {
723 $num_unders = () = $v =~ m{(_)}g;
728 # Worst case, try numifying it like we would have before version objects
731 no warnings 'numeric';
738 my ($result) = shift;
740 return $result if ref($result) eq 'version';
742 my ($version, $error);
743 for my $f (@version_prep) {
744 $result = $f->($result);
745 $version = eval { version->new($result) };
746 $error ||= $@ if $@; # capture first failure
747 last if defined $version;
750 croak $error unless defined $version;
756 ############################################################
759 sub name { $_[0]->{module} }
761 sub filename { $_[0]->{filename} }
762 sub packages_inside { @{$_[0]->{packages}} }
763 sub pod_inside { @{$_[0]->{pod_headings}} }
764 sub contains_pod { 0+@{$_[0]->{pod_headings}} }
768 my $mod = shift || $self->{module};
770 if ( defined( $mod ) && length( $mod ) &&
771 exists( $self->{versions}{$mod} ) ) {
772 return $self->{versions}{$mod};
781 if ( defined( $sect ) && length( $sect ) &&
782 exists( $self->{pod}{$sect} ) ) {
783 return $self->{pod}{$sect};
790 my ($self, $package) = @_;
792 my @indexable_packages = grep { $_ ne 'main' } $self->packages_inside;
794 # check for specific package, if provided
795 return !! grep { $_ eq $package } @indexable_packages if $package;
797 # otherwise, check for any indexable packages at all
798 return !! @indexable_packages;
805 Module::Metadata - Gather package and POD information from perl module files
809 use Module::Metadata;
811 # information about a .pm file
812 my $info = Module::Metadata->new_from_file( $file );
813 my $version = $info->version;
815 # CPAN META 'provides' field for .pm files in a directory
816 my $provides = Module::Metadata->provides(
817 dir => 'lib', version => 2
822 This module provides a standard way to gather metadata about a .pm file through
823 (mostly) static analysis and (some) code execution. When determining the
824 version of a module, the C<$VERSION> assignment is C<eval>ed, as is traditional
825 in the CPAN toolchain.
833 =item C<< new_from_file($filename, collect_pod => 1) >>
835 Constructs a C<Module::Metadata> object given the path to a file. Returns
836 undef if the filename does not exist.
838 C<collect_pod> is a optional boolean argument that determines whether POD
839 data is collected and stored for reference. POD data is not collected by
840 default. POD headings are always collected.
842 If the file begins by an UTF-8, UTF-16BE or UTF-16LE byte-order mark, then
843 it is skipped before processing, and the content of the file is also decoded
844 appropriately starting from perl 5.8.
846 =item C<< new_from_handle($handle, $filename, collect_pod => 1) >>
848 This works just like C<new_from_file>, except that a handle can be provided
849 as the first argument.
851 Note that there is no validation to confirm that the handle is a handle or
852 something that can act like one. Passing something that isn't a handle will
853 cause a exception when trying to read from it. The C<filename> argument is
854 mandatory or undef will be returned.
856 You are responsible for setting the decoding layers on C<$handle> if
859 =item C<< new_from_module($module, collect_pod => 1, inc => \@dirs) >>
861 Constructs a C<Module::Metadata> object given a module or package name.
862 Returns undef if the module cannot be found.
864 In addition to accepting the C<collect_pod> argument as described above,
865 this method accepts a C<inc> argument which is a reference to an array of
866 directories to search for the module. If none are given, the default is
869 If the file that contains the module begins by an UTF-8, UTF-16BE or
870 UTF-16LE byte-order mark, then it is skipped before processing, and the
871 content of the file is also decoded appropriately starting from perl 5.8.
873 =item C<< find_module_by_name($module, \@dirs) >>
875 Returns the path to a module given the module or package name. A list
876 of directories can be passed in as an optional parameter, otherwise
879 Can be called as either an object or a class method.
881 =item C<< find_module_dir_by_name($module, \@dirs) >>
883 Returns the entry in C<@dirs> (or C<@INC> by default) that contains
884 the module C<$module>. A list of directories can be passed in as an
885 optional parameter, otherwise @INC is searched.
887 Can be called as either an object or a class method.
889 =item C<< provides( %options ) >>
891 This is a convenience wrapper around C<package_versions_from_directory>
892 to generate a CPAN META C<provides> data structure. It takes key/value
893 pairs. Valid option keys include:
897 =item version B<(required)>
899 Specifies which version of the L<CPAN::Meta::Spec> should be used as
900 the format of the C<provides> output. Currently only '1.4' and '2'
901 are supported (and their format is identical). This may change in
902 the future as the definition of C<provides> changes.
904 The C<version> option is required. If it is omitted or if
905 an unsupported version is given, then C<provides> will throw an error.
909 Directory to search recursively for F<.pm> files. May not be specified with
914 Array reference of files to examine. May not be combined with C<dir> or
919 String to prepend to the C<file> field of the resulting output. This defaults
920 to F<lib>, which is the common case for most CPAN distributions with their
921 F<.pm> files in F<lib>. This option ensures the META information has the
922 correct relative path even when the C<dir> argument is
923 absolute or has relative paths from a location other than the distribution
928 For example, given C<dir> of 'lib' and C<prefix> of 'lib', the return value
929 is a hashref of the form:
934 file => 'lib/Package/Name.pm'
936 'OtherPackage::Name' => ...
939 =item C<< package_versions_from_directory($dir, \@files?) >>
941 Scans C<$dir> for .pm files (unless C<@files> is given, in which case looks
942 for those files in C<$dir> - and reads each file for packages and versions,
943 returning a hashref of the form:
948 file => 'Package/Name.pm'
950 'OtherPackage::Name' => ...
953 The C<DB> and C<main> packages are always omitted, as are any "private"
954 packages that have leading underscores in the namespace (e.g.
957 Note that the file path is relative to C<$dir> if that is specified.
958 This B<must not> be used directly for CPAN META C<provides>. See
959 the C<provides> method instead.
961 =item C<< log_info (internal) >>
963 Used internally to perform logging; imported from Log::Contextual if
964 Log::Contextual has already been loaded, otherwise simply calls warn.
968 =head2 Object methods
974 Returns the name of the package represented by this module. If there
975 is more than one package, it makes a best guess based on the
976 filename. If it's a script (i.e. not a *.pm) the package name is
979 =item C<< version($package) >>
981 Returns the version as defined by the $VERSION variable for the
982 package as returned by the C<name> method if no arguments are
983 given. If given the name of a package it will attempt to return the
984 version of that package if it is specified in the file.
986 =item C<< filename() >>
988 Returns the absolute path to the file.
990 =item C<< packages_inside() >>
992 Returns a list of packages. Note: this is a raw list of packages
993 discovered (or assumed, in the case of C<main>). It is not
994 filtered for C<DB>, C<main> or private packages the way the
995 C<provides> method does. Invalid package names are not returned,
996 for example "Foo:Bar". Strange but valid package names are
997 returned, for example "Foo::Bar::", and are left up to the caller
1000 =item C<< pod_inside() >>
1002 Returns a list of POD sections.
1004 =item C<< contains_pod() >>
1006 Returns true if there is any POD in the file.
1008 =item C<< pod($section) >>
1010 Returns the POD data in the given section.
1012 =item C<< is_indexable($package) >> or C<< is_indexable() >>
1014 Returns a boolean indicating whether the package (if provided) or any package
1015 (otherwise) is eligible for indexing by PAUSE, the Perl Authors Upload Server.
1016 Note This only checks for valid C<package> declarations, and does not take any
1017 ownership information into account.
1023 Original code from Module::Build::ModuleInfo by Ken Williams
1024 <kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
1026 Released as Module::Metadata by Matt S Trout (mst) <mst@shadowcat.co.uk> with
1027 assistance from David Golden (xdg) <dagolden@cpan.org>.
1029 =head1 COPYRIGHT & LICENSE
1031 Original code Copyright (c) 2001-2011 Ken Williams.
1032 Additional code Copyright (c) 2010-2011 Matt Trout and David Golden.
1033 All rights reserved.
1035 This library is free software; you can redistribute it and/or
1036 modify it under the same terms as Perl itself.