Permalink
Browse files

v0.923

  - By default, when determining packages, filter out packages
    that don't match the file name (ones that can't be loaded via use/require).
    This mimics the behavior of PAUSE.
    If you want the old behavior of including "inner" packages in the meta
    "provides" set "include_inner_packages" to true in the constructor.
    Thanks to Jeffrey Ryan Thalhammer for finding and fixing this
    (and including tests)!
  • Loading branch information...
1 parent 3417100 commit 1f258424e5688a9ed2cf2da6a916d44560ca6c63 @rwstauner committed Jun 19, 2012
Showing with 357 additions and 7 deletions.
  1. +2 −0 Changes
  2. +355 −7 README.pod
View
@@ -2,6 +2,8 @@ Revision history for Dist-Metadata
{{$NEXT}}
+0.923 2012-06-19T03:13:55Z
+
- By default, when determining packages, filter out packages
that don't match the file name (ones that can't be loaded via use/require).
This mimics the behavior of PAUSE.
View
@@ -1,15 +1,364 @@
-=head1 Dist::Metadata
+=encoding utf-8
-This is sort of a companion to L<Module::Metadata>.
-It provides an interface for getting information about a distribution.
+=for :stopwords Randy Stauner ACKNOWLEDGEMENTS TODO dist dists dir unix cpan testmatrix url
+annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata
+placeholders metacpan
-This is mostly a wrapper around L<CPAN::Meta>
-providing an easy interface to find and load the meta file from a F<tar.gz> file.
+=head1 NAME
+
+Dist::Metadata - Information about a perl module distribution
+
+=head1 VERSION
+
+version 0.923
+
+=head1 SYNOPSIS
+
+ my $dist = Dist::Metadata->new(file => $path_to_archive);
+
+ my $description = sprintf "Dist %s (%s)", $dist->name, $dist->version;
+
+ my $provides = $dist->package_versions;
+ while( my ($package, $version) = each %$provides ){
+ print "$description includes $package $version\n";
+ }
+
+=head1 DESCRIPTION
+
+This module provides an easy interface for getting various metadata
+about a Perl module distribution.
+
+It takes care of the common logic of:
+
+=over 4
+
+=item *
+
+reading a tar file (L<Archive::Tar>)
+
+=item *
+
+finding and reading the correct META file if the distribution contains one (L<CPAN::Meta>)
+
+=item *
+
+and determining some of the metadata if there is no META file (L<Module::Metadata>, L<CPAN::DistnameInfo>)
+
+=back
+
+This is mostly a wrapper around L<CPAN::Meta> providing an easy interface
+to find and load the meta file from a F<tar.gz> file.
+A dist can also be represented by a directory or merely a structure of data.
If the dist does not contain a meta file
the module will attempt to determine some of that data from the dist.
-See module POD for more information.
+B<NOTE>: This interface is still being defined.
+Please submit any suggestions or concerns.
+
+=head1 METHODS
+
+=head2 new
+
+ Dist::Metadata->new(file => $path);
+
+A dist can be represented by
+a tar file,
+a directory,
+or a data structure.
+
+The format will be determined by the presence of the following options
+(checked in this order):
+
+=over 4
+
+=item *
+
+C<struct> - hash of data to build a mock dist; See L<Dist::Metadata::Struct>.
+
+=item *
+
+C<dir> - path to the root directory of a dist
+
+=item *
+
+C<file> - the path to a F<.tar.gz> file
+
+=back
+
+You can also slyly pass in your own object as a C<dist> parameter
+in which case this module will just use that.
+This can be useful if you need to use your own subclass
+(perhaps while developing a new format).
+
+Other options that can be specified:
+
+=over 4
+
+=item *
+
+C<name> - dist name
+
+=item *
+
+C<version> - dist version
+
+=item *
+
+C<determine_packages> - boolean to indicate whether dist should be searched
+for packages if no META file is found. Defaults to true.
+
+=item *
+
+C<include_inner_packages> - When determining provided packages
+the default behavior is to only include packages that match the name
+of the file that defines them (like C<Foo::Bar> matches C<*/Bar.pm>).
+This way only modules that can be loaded (via C<use> or C<require>)
+will be returned (and "inner" packages will be ignored).
+This mimics the behavior of PAUSE.
+Set this to true to include any "inner" packages provided by the dist
+(that are not otherwise excluded by another mechanism (such as C<no_index>)).
+
+=back
+
+=head2 dist
+
+Returns the dist object (subclass of L<Dist::Metadata::Dist>).
+
+=head2 default_metadata
+
+Returns a hashref of default values
+used to initialize a L<CPAN::Meta> object
+when a META file is not found.
+Called from L</determine_metadata>.
+
+=head2 determine_metadata
+
+Examine the dist and try to determine metadata.
+Returns a hashref which can be passed to L<CPAN::Meta/new>.
+This is used when the dist does not contain a META file.
+
+=head2 determine_packages
+
+ my $provides = $dm->determine_packages($meta);
+
+Attempt to determine packages provided by the dist.
+This is used when the META file does not include a C<provides>
+section and C<determine_packages> is not set to false in the constructor.
+
+If a L<CPAN::Meta> object is not provided a default one will be used.
+Files contained in the dist and packages found therein will be checked against
+the meta object's C<no_index> attribute
+(see L<CPAN::Meta/should_index_file>
+and L<CPAN::Meta/should_index_package>).
+By default this ignores any files found in
+F<inc/>,
+F<t/>,
+or F<xt/>
+directories.
+
+=head2 load_meta
+
+Loads the metadata from the L</dist>.
+
+=head2 meta
+
+Returns the L<CPAN::Meta> instance in use.
+
+=head2 meta_from_struct
+
+ $meta = $dm->meta_from_struct(\%struct);
+
+Passes the the provided C<\%struct> to L<CPAN::Meta/create>
+and returns the result.
+
+=head2 package_versions
+
+ $pv = $dm->package_versions();
+ # { 'Package::Name' => '1.0', 'Module::2' => '2.1' }
+
+Returns a simplified version of C<provides>:
+a hashref with package names as keys and versions as values.
+
+This can also be called as a class method
+which will operate on a passed in hashref.
+
+ $pv = Dist::Metadata->package_versions(\%provides);
+
+=head1 INHERITED METHODS
+
+The following methods are available on this object
+and simply call the corresponding method on the L<CPAN::Meta> object.
+
+=over 4
+
+=item *
+
+X<name> name
+
+=item *
+
+X<provides> provides
+
+=item *
+
+X<version> version
+
+=back
+
+=for Pod::Coverage name version provides
+
+=for test_synopsis my $path_to_archive;
+
+=head1 TODO
+
+=over 4
+
+=item *
+
+More tests
+
+=item *
+
+C<trust_meta> option (to allow setting it to false)
+
+=item *
+
+Guess main module from dist name if no packages can be found
+
+=item *
+
+Determine abstract?
+
+=item *
+
+Add change log info (L<CPAN::Changes>)?
+
+=item *
+
+Subclass as C<CPAN::Dist::Metadata> just so that it has C<CPAN> in the name?
+
+=item *
+
+Use L<File::Find::Rule::Perl>?
+
+=back
+
+=head1 SEE ALSO
+
+=head2 Dependencies
+
+=over 4
+
+=item *
+
+L<CPAN::Meta>
+
+=item *
+
+L<Module::Metadata>
+
+=item *
+
+L<CPAN::DistnameInfo>
+
+=back
+
+=head2 Related Modules
+
+=over 4
+
+=item *
+
+L<MyCPAN::Indexer>
+
+=item *
+
+L<CPAN::ParseDistribution>
+
+=back
+
+=head1 SUPPORT
+
+=head2 Perldoc
+
+You can find documentation for this module with the perldoc command.
+
+ perldoc Dist::Metadata
+
+=head2 Websites
+
+The following websites have more information about this module, and may be of help to you. As always,
+in addition to those websites please use your favorite search engine to discover more resources.
+
+=over 4
+
+=item *
+
+Search CPAN
+
+The default CPAN search engine, useful to view POD in HTML format.
+
+L<http://search.cpan.org/dist/Dist-Metadata>
+
+=item *
+
+RT: CPAN's Bug Tracker
+
+The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.
+
+L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dist-Metadata>
+
+=item *
+
+CPAN Ratings
+
+The CPAN Ratings is a website that allows community ratings and reviews of Perl modules.
+
+L<http://cpanratings.perl.org/d/Dist-Metadata>
+
+=item *
+
+CPAN Testers
+
+The CPAN Testers is a network of smokers who run automated tests on uploaded CPAN distributions.
+
+L<http://www.cpantesters.org/distro/D/Dist-Metadata>
+
+=item *
+
+CPAN Testers Matrix
+
+The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.
+
+L<http://matrix.cpantesters.org/?dist=Dist-Metadata>
+
+=item *
+
+CPAN Testers Dependencies
+
+The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.
+
+L<http://deps.cpantesters.org/?module=Dist::Metadata>
+
+=back
+
+=head2 Bugs / Feature Requests
+
+Please report any bugs or feature requests by email to C<bug-dist-metadata at rt.cpan.org>, or through
+the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dist-Metadata>. You will be automatically notified of any
+progress on the request by the system.
+
+=head2 Source Code
+
+
+L<https://github.com/rwstauner/Dist-Metadata>
+
+ git clone https://github.com/rwstauner/Dist-Metadata.git
+
+=head1 AUTHOR
+
+Randy Stauner <rwstauner@cpan.org>
=head1 COPYRIGHT AND LICENSE
@@ -18,4 +367,3 @@ This software is copyright (c) 2011 by Randy Stauner.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
-=cut

0 comments on commit 1f25842

Please sign in to comment.