=pod
=encoding UTF-8
=head1 NAME
Module::Metadata - Gather package and POD information from perl module files
=head1 VERSION
version 1.000038
=head1 SYNOPSIS
use Module::Metadata;
my $info = Module::Metadata->new_from_file( $file ); my $version = $info->version;
my $provides = Module::Metadata->provides( dir => 'lib', version => 2 );
=head1 DESCRIPTION
This module provides a standard way to gather metadata about a .pm file through
(mostly) static analysis and (some) code execution. When determining the
version of a module, the C<$VERSION> assignment is C
=head1 CLASS METHODS
=head2 C<< new_from_file($filename, collect_pod => 1, decode_pod => 1) >>
Constructs a C
C
If the file begins by an UTF-8, UTF-16BE or UTF-16LE byte-order mark, then it is skipped before processing, and the content of the file is also decoded appropriately starting from perl 5.8.
Alternatively, if C
=head2 C<< new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1) >>
This works just like C
Note that there is no validation to confirm that the handle is a handle or
something that can act like one. Passing something that isn't a handle will
cause a exception when trying to read from it. The C
You are responsible for setting the decoding layers on C<$handle> if required.
=head2 C<< new_from_module($module, collect_pod => 1, inc => \@dirs, decode_pod => 1) >>
Constructs a C
In addition to accepting the C
If the file that contains the module begins by an UTF-8, UTF-16BE or UTF-16LE byte-order mark, then it is skipped before processing, and the content of the file is also decoded appropriately starting from perl 5.8.
=head2 C<< find_module_by_name($module, \@dirs) >>
Returns the path to a module given the module or package name. A list of directories can be passed in as an optional parameter, otherwise @INC is searched.
Can be called as either an object or a class method.
=head2 C<< find_module_dir_by_name($module, \@dirs) >>
Returns the entry in C<@dirs> (or C<@INC> by default) that contains the module C<$module>. A list of directories can be passed in as an optional parameter, otherwise @INC is searched.
Can be called as either an object or a class method.
=head2 C<< provides( %options ) >>
This is a convenience wrapper around C
=over
=item version B<(required)>
Specifies which version of the L
The C
=item dir
Directory to search recursively for F<.pm> files. May not be specified with
C
=item files
Array reference of files to examine. May not be specified with C
=item prefix
String to prepend to the C
=back
For example, given C
{ 'Package::Name' => { version => '0.123', file => 'lib/Package/Name.pm' }, 'OtherPackage::Name' => ... }
=head2 C<< package_versions_from_directory($dir, \@files?) >>
Scans C<$dir> for .pm files (unless C<@files> is given, in which case looks for those files in C<$dir> - and reads each file for packages and versions, returning a hashref of the form:
{ 'Package::Name' => { version => '0.123', file => 'Package/Name.pm' }, 'OtherPackage::Name' => ... }
The C
Note that the file path is relative to C<$dir> if that is specified.
This B
=head2 C<< log_info (internal) >>
Used internally to perform logging; imported from Log::Contextual if Log::Contextual has already been loaded, otherwise simply calls warn.
=head1 OBJECT METHODS
=head2 C<< name() >>
Returns the name of the package represented by this module. If there is more than one package, it makes a best guess based on the filename. If it's a script (i.e. not a *.pm) the package name is 'main'.
=head2 C<< version($package) >>
Returns the version as defined by the $VERSION variable for the
package as returned by the C
=head2 C<< filename() >>
Returns the absolute path to the file. Note that this file may not actually exist on disk yet, e.g. if the module was read from an in-memory filehandle.
=head2 C<< packages_inside() >>
Returns a list of packages. Note: this is a raw list of packages
discovered (or assumed, in the case of C
=head2 C<< pod_inside() >>
Returns a list of POD sections.
=head2 C<< contains_pod() >>
Returns true if there is any POD in the file.
=head2 C<< pod($section) >>
Returns the POD data in the given section.
=head2 C<< is_indexable($package) >> or C<< is_indexable() >>
Available since version 1.000020.
Returns a boolean indicating whether the package (if provided) or any package
(otherwise) is eligible for indexing by PAUSE, the Perl Authors Upload Server.
Note This only checks for valid C
=head1 SUPPORT
Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Metadata> (or Lbug-Module-Metadata@rt.cpan.org|mailto:bug-Module-Metadata@rt.cpan.org).
There is also a mailing list available for users of this distribution, at Lhttp://lists.perl.org/list/cpan-workers.html.
There is also an irc channel available for users of this distribution, at
L<C<#toolchain> on C
=head1 AUTHOR
Original code from Module::Build::ModuleInfo by Ken Williams kwilliams@cpan.org, Randy W. Sims RandyS@ThePierianSpring.org
Released as Module::Metadata by Matt S Trout (mst) mst@shadowcat.co.uk with assistance from David Golden (xdg) dagolden@cpan.org.
=head1 CONTRIBUTORS
=for stopwords Karen Etheridge David Golden Vincent Pit Matt S Trout Chris Nehren Graham Knop Olivier Mengué Tomas Doran Christian Walde Craig A. Berry Tatsuhiko Miyagawa tokuhirom 'BinGOs' Williams Mitchell Steinbrunner Edward Zborowski Gareth Harper James Raspass Jerry D. Hedden Josh Jore Kent Fredric Leon Timmermans Peter Rabbitson Steve Hay
=over 4
=item *
Karen Etheridge ether@cpan.org
=item *
David Golden dagolden@cpan.org
=item *
Vincent Pit perl@profvince.com
=item *
Matt S Trout mst@shadowcat.co.uk
=item *
Chris Nehren apeiron@cpan.org
=item *
Graham Knop haarg@haarg.org
=item *
Olivier Mengué dolmen@cpan.org
=item *
Tomas Doran bobtfish@bobtfish.net
=item *
Christian Walde walde.christian@googlemail.com
=item *
Craig A. Berry cberry@cpan.org
=item *
Tatsuhiko Miyagawa miyagawa@bulknews.net
=item *
tokuhirom tokuhirom@gmail.com
=item *
Chris 'BinGOs' Williams chris@bingosnet.co.uk
=item *
David Mitchell davem@iabyn.com
=item *
David Steinbrunner dsteinbrunner@pobox.com
=item *
Edward Zborowski ed@rubensteintech.com
=item *
Gareth Harper gareth@broadbean.com
=item *
James Raspass jraspass@gmail.com
=item *
Jerry D. Hedden jdhedden@cpan.org
=item *
Josh Jore jjore@cpan.org
=item *
Kent Fredric kentnl@cpan.org
=item *
Leon Timmermans fawaka@gmail.com
=item *
Peter Rabbitson ribasushi@cpan.org
=item *
Steve Hay steve.m.hay@googlemail.com
=back
=head1 COPYRIGHT & LICENSE
Original code Copyright (c) 2001-2011 Ken Williams. Additional code Copyright (c) 2010-2011 Matt Trout and David Golden. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
=cut