.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Dist::Metadata 3pm" .TH Dist::Metadata 3pm "2022-06-13" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Dist::Metadata \- Information about a perl module distribution .SH "VERSION" .IX Header "VERSION" version 0.927 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& 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\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides an easy interface for getting various metadata about a Perl module distribution. .PP It takes care of the common logic of: .IP "\(bu" 4 reading a tar file (Archive::Tar) .IP "\(bu" 4 finding and reading the correct \s-1META\s0 file if the distribution contains one (CPAN::Meta) .IP "\(bu" 4 and determining some of the metadata if there is no \s-1META\s0 file (Module::Metadata, CPAN::DistnameInfo) .PP This is mostly a wrapper around CPAN::Meta providing an easy interface to find and load the meta file from a \fItar.gz\fR file. A dist can also be represented by a directory or merely a structure of data. .PP If the dist does not contain a meta file the module will attempt to determine some of that data from the dist. .PP \&\fB\s-1NOTE\s0\fR: This interface is still being defined. Please submit any suggestions or concerns. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& Dist::Metadata\->new(file => $path); .Ve .PP A dist can be represented by a tar file, a directory, or a data structure. .PP The format will be determined by the presence of the following options (checked in this order): .IP "\(bu" 4 \&\f(CW\*(C`struct\*(C'\fR \- hash of data to build a mock dist; See Dist::Metadata::Struct. .IP "\(bu" 4 \&\f(CW\*(C`dir\*(C'\fR \- path to the root directory of a dist .IP "\(bu" 4 \&\f(CW\*(C`file\*(C'\fR \- the path to a \fI.tar.gz\fR file .PP You can also slyly pass in your own object as a \f(CW\*(C`dist\*(C'\fR 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). .PP Other options that can be specified: .IP "\(bu" 4 \&\f(CW\*(C`name\*(C'\fR \- dist name .IP "\(bu" 4 \&\f(CW\*(C`version\*(C'\fR \- dist version .IP "\(bu" 4 \&\f(CW\*(C`determine_packages\*(C'\fR \- boolean to indicate whether dist should be searched for packages if no \s-1META\s0 file is found. Defaults to true. .IP "\(bu" 4 \&\f(CW\*(C`include_inner_packages\*(C'\fR \- When determining provided packages the default behavior is to only include packages that match the name of the file that defines them (like \f(CW\*(C`Foo::Bar\*(C'\fR matches \f(CW\*(C`*/Bar.pm\*(C'\fR). This way only modules that can be loaded (via \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR) will be returned (and \*(L"inner\*(R" packages will be ignored). This mimics the behavior of \s-1PAUSE.\s0 Set this to true to include any \*(L"inner\*(R" packages provided by the dist (that are not otherwise excluded by another mechanism (such as \f(CW\*(C`no_index\*(C'\fR)). .SS "dist" .IX Subsection "dist" Returns the dist object (subclass of Dist::Metadata::Dist). .SS "default_metadata" .IX Subsection "default_metadata" Returns a hashref of default values used to initialize a CPAN::Meta object when a \s-1META\s0 file is not found. Called from \*(L"determine_metadata\*(R". .SS "determine_metadata" .IX Subsection "determine_metadata" Examine the dist and try to determine metadata. Returns a hashref which can be passed to \*(L"new\*(R" in CPAN::Meta. This is used when the dist does not contain a \s-1META\s0 file. .SS "determine_packages" .IX Subsection "determine_packages" .Vb 1 \& my $provides = $dm\->determine_packages($meta); .Ve .PP Attempt to determine packages provided by the dist. This is used when the \s-1META\s0 file does not include a \f(CW\*(C`provides\*(C'\fR section and \f(CW\*(C`determine_packages\*(C'\fR is not set to false in the constructor. .PP If a 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 \f(CW\*(C`no_index\*(C'\fR attribute (see \*(L"should_index_file\*(R" in CPAN::Meta and \*(L"should_index_package\*(R" in CPAN::Meta). By default this ignores any files found in \&\fIinc/\fR, \&\fIt/\fR, or \fIxt/\fR directories. .SS "load_meta" .IX Subsection "load_meta" Loads the metadata from the \*(L"dist\*(R". .SS "meta" .IX Subsection "meta" Returns the CPAN::Meta instance in use. .SS "meta_from_struct" .IX Subsection "meta_from_struct" .Vb 1 \& $meta = $dm\->meta_from_struct(\e%struct); .Ve .PP Passes the provided \f(CW\*(C`\e%struct\*(C'\fR to \*(L"create\*(R" in CPAN::Meta and returns the result. .SS "package_versions" .IX Subsection "package_versions" .Vb 2 \& $pv = $dm\->package_versions(); \& # { \*(AqPackage::Name\*(Aq => \*(Aq1.0\*(Aq, \*(AqModule::2\*(Aq => \*(Aq2.1\*(Aq } .Ve .PP Returns a simplified version of \f(CW\*(C`provides\*(C'\fR: a hashref with package names as keys and versions as values. .PP This can also be called as a class method which will operate on a passed in hashref. .PP .Vb 1 \& $pv = Dist::Metadata\->package_versions(\e%provides); .Ve .SS "module_info" .IX Subsection "module_info" Returns a hashref of meta data for each of the packages provided by this dist. .PP The hashref starts with the same data as \*(L"provides\*(R" but additional data can be added to the output by specifying options in a hashref: .ie n .IP """checksum""" 4 .el .IP "\f(CWchecksum\fR" 4 .IX Item "checksum" Use the specified algorithm to compute a hex digest of the file. The type you specify will be the key in the returned hashref. You can use an arrayref to specify more than one type. .Sp .Vb 10 \& $dm\->module_info({checksum => [\*(Aqsha256\*(Aq, \*(Aqmd5\*(Aq]}); \& # returns: \& { \& \*(AqMod::Name\*(Aq => { \& file => \*(Aqlib/Mod/Name.pm\*(Aq, \& version => \*(Aq0.1\*(Aq, \& md5 => \*(Aq258e88dcbd3cd44d8e7ab43f6ecb6af0\*(Aq, \& sha256 => \*(Aqf22136124cd3e1d65a48487cecf310771b2fd1e83dc032e3d19724160ac0ff71\*(Aq, \& }, \& } .Ve .Sp See \*(L"file_checksum\*(R" in Dist::Metadata::Dist for more information. .ie n .IP """provides""" 4 .el .IP "\f(CWprovides\fR" 4 .IX Item "provides" The default is to start with the hashref returned from \*(L"provides\*(R" but you can pass in an alternate hashref using this key. .PP Other options may be added in the future. .SH "INHERITED METHODS" .IX Header "INHERITED METHODS" The following methods are available on this object and simply call the corresponding method on the CPAN::Meta object. .IP "\(bu" 4 name .IX Xref "name" .IP "\(bu" 4 provides .IX Xref "provides" .IP "\(bu" 4 version .IX Xref "version" .SH "TODO" .IX Header "TODO" .IP "\(bu" 4 More tests .IP "\(bu" 4 \&\f(CW\*(C`trust_meta\*(C'\fR option (to allow setting it to false) .IP "\(bu" 4 Guess main module from dist name if no packages can be found .IP "\(bu" 4 Determine abstract? .IP "\(bu" 4 Add change log info (CPAN::Changes)? .IP "\(bu" 4 Subclass as \f(CW\*(C`CPAN::Dist::Metadata\*(C'\fR just so that it has \f(CW\*(C`CPAN\*(C'\fR in the name? .IP "\(bu" 4 Use File::Find::Rule::Perl? .SH "SEE ALSO" .IX Header "SEE ALSO" .SS "Dependencies" .IX Subsection "Dependencies" .IP "\(bu" 4 CPAN::Meta .IP "\(bu" 4 Module::Metadata .IP "\(bu" 4 CPAN::DistnameInfo .SS "Related Modules" .IX Subsection "Related Modules" .IP "\(bu" 4 MyCPAN::Indexer .IP "\(bu" 4 CPAN::ParseDistribution .SH "SUPPORT" .IX Header "SUPPORT" .SS "Perldoc" .IX Subsection "Perldoc" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Dist::Metadata .Ve .SS "Websites" .IX Subsection "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. .IP "\(bu" 4 MetaCPAN .Sp A modern, open-source \s-1CPAN\s0 search engine, useful to view \s-1POD\s0 in \s-1HTML\s0 format. .Sp .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests by email to \f(CW\*(C`bug\-dist\-metadata at rt.cpan.org\*(C'\fR, or through the web interface at . You will be automatically notified of any progress on the request by the system. .SS "Source Code" .IX Subsection "Source Code" .PP .Vb 1 \& git clone https://github.com/rwstauner/Dist\-Metadata.git .Ve .SH "AUTHOR" .IX Header "AUTHOR" Randy Stauner .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Graham Knop .IP "\(bu" 4 Jeffrey Ryan Thalhammer .IP "\(bu" 4 Sawyer X .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2011 by Randy Stauner. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.