Dist::Metadata(3pm)

1Dist::Metadata(3)     User Contributed Perl Documentation    Dist::Metadata(3)
2
3
4

NAME

6       Dist::Metadata - Information about a perl module distribution
7

VERSION

9       version 0.927
10

SYNOPSIS

12         my $dist = Dist::Metadata->new(file => $path_to_archive);
13
14         my $description = sprintf "Dist %s (%s)", $dist->name, $dist->version;
15
16         my $provides = $dist->package_versions;
17         while( my ($package, $version) = each %$provides ){
18           print "$description includes $package $version\n";
19         }
20

DESCRIPTION

22       This module provides an easy interface for getting various metadata
23       about a Perl module distribution.
24
25       It takes care of the common logic of:
26
27       •   reading a tar file (Archive::Tar)
28
29       •   finding and reading the correct META file if the distribution
30           contains one (CPAN::Meta)
31
32       •   and determining some of the metadata if there is no META file
33           (Module::Metadata, CPAN::DistnameInfo)
34
35       This is mostly a wrapper around CPAN::Meta providing an easy interface
36       to find and load the meta file from a tar.gz file.  A dist can also be
37       represented by a directory or merely a structure of data.
38
39       If the dist does not contain a meta file the module will attempt to
40       determine some of that data from the dist.
41
42       NOTE: This interface is still being defined.  Please submit any
43       suggestions or concerns.
44

METHODS

46   new
47         Dist::Metadata->new(file => $path);
48
49       A dist can be represented by a tar file, a directory, or a data
50       structure.
51
52       The format will be determined by the presence of the following options
53       (checked in this order):
54
55       •   "struct" - hash of data to build a mock dist; See
56           Dist::Metadata::Struct.
57
58       •   "dir" - path to the root directory of a dist
59
60       •   "file" - the path to a .tar.gz file
61
62       You can also slyly pass in your own object as a "dist" parameter in
63       which case this module will just use that.  This can be useful if you
64       need to use your own subclass (perhaps while developing a new format).
65
66       Other options that can be specified:
67
68       •   "name" - dist name
69
70       •   "version" - dist version
71
72       •   "determine_packages" - boolean to indicate whether dist should be
73           searched for packages if no META file is found.  Defaults to true.
74
75       •   "include_inner_packages" - When determining provided packages the
76           default behavior is to only include packages that match the name of
77           the file that defines them (like "Foo::Bar" matches "*/Bar.pm").
78           This way only modules that can be loaded (via "use" or "require")
79           will be returned (and "inner" packages will be ignored).  This
80           mimics the behavior of PAUSE.  Set this to true to include any
81           "inner" packages provided by the dist (that are not otherwise
82           excluded by another mechanism (such as "no_index")).
83
84   dist
85       Returns the dist object (subclass of Dist::Metadata::Dist).
86
87   default_metadata
88       Returns a hashref of default values used to initialize a CPAN::Meta
89       object when a META file is not found.  Called from
90       "determine_metadata".
91
92   determine_metadata
93       Examine the dist and try to determine metadata.  Returns a hashref
94       which can be passed to "new" in CPAN::Meta.  This is used when the dist
95       does not contain a META file.
96
97   determine_packages
98         my $provides = $dm->determine_packages($meta);
99
100       Attempt to determine packages provided by the dist.  This is used when
101       the META file does not include a "provides" section and
102       "determine_packages" is not set to false in the constructor.
103
104       If a CPAN::Meta object is not provided a default one will be used.
105       Files contained in the dist and packages found therein will be checked
106       against the meta object's "no_index" attribute (see "should_index_file"
107       in CPAN::Meta and  "should_index_package" in CPAN::Meta).  By default
108       this ignores any files found in inc/, t/, or xt/ directories.
109
110   load_meta
111       Loads the metadata from the "dist".
112
113   meta
114       Returns the CPAN::Meta instance in use.
115
116   meta_from_struct
117         $meta = $dm->meta_from_struct(\%struct);
118
119       Passes the provided "\%struct" to "create" in CPAN::Meta and returns
120       the result.
121
122   package_versions
123         $pv = $dm->package_versions();
124         # { 'Package::Name' => '1.0', 'Module::2' => '2.1' }
125
126       Returns a simplified version of "provides": a hashref with package
127       names as keys and versions as values.
128
129       This can also be called as a class method which will operate on a
130       passed in hashref.
131
132         $pv = Dist::Metadata->package_versions(\%provides);
133
134   module_info
135       Returns a hashref of meta data for each of the packages provided by
136       this dist.
137
138       The hashref starts with the same data as "provides" but additional data
139       can be added to the output by specifying options in a hashref:
140
141       "checksum"
142           Use the specified algorithm to compute a hex digest of the file.
143           The type you specify will be the key in the returned hashref.  You
144           can use an arrayref to specify more than one type.
145
146             $dm->module_info({checksum => ['sha256', 'md5']});
147             # returns:
148             {
149               'Mod::Name' => {
150                 file    => 'lib/Mod/Name.pm',
151                 version => '0.1',
152                 md5     => '258e88dcbd3cd44d8e7ab43f6ecb6af0',
153                 sha256  => 'f22136124cd3e1d65a48487cecf310771b2fd1e83dc032e3d19724160ac0ff71',
154               },
155             }
156
157           See "file_checksum" in Dist::Metadata::Dist for more information.
158
159       "provides"
160           The default is to start with the hashref returned from "provides"
161           but you can pass in an alternate hashref using this key.
162
163       Other options may be added in the future.
164

INHERITED METHODS

166       The following methods are available on this object and simply call the
167       corresponding method on the CPAN::Meta object.
168
169       •
170            name
171
172       •
173            provides
174
175       •
176            version
177

TODO

179       •   More tests
180
181       •   "trust_meta" option (to allow setting it to false)
182
183       •   Guess main module from dist name if no packages can be found
184
185       •   Determine abstract?
186
187       •   Add change log info (CPAN::Changes)?
188
189       •   Subclass as "CPAN::Dist::Metadata" just so that it has "CPAN" in
190           the name?
191
192       •   Use File::Find::Rule::Perl?
193

SUPPORT

208   Perldoc
209       You can find documentation for this module with the perldoc command.
210
211         perldoc Dist::Metadata
212
213   Websites
214       The following websites have more information about this module, and may
215       be of help to you. As always, in addition to those websites please use
216       your favorite search engine to discover more resources.
217
218       •   MetaCPAN
219
220           A modern, open-source CPAN search engine, useful to view POD in
221           HTML format.
222
223           <http://metacpan.org/release/Dist-Metadata>
224
225   Bugs / Feature Requests
226       Please report any bugs or feature requests by email to
227       "bug-dist-metadata at rt.cpan.org", or through the web interface at
228       <https://rt.cpan.org/Public/Bug/Report.html?Queue=Dist-Metadata>. You
229       will be automatically notified of any progress on the request by the
230       system.
231
232   Source Code
233       <https://github.com/rwstauner/Dist-Metadata>
234
235         git clone https://github.com/rwstauner/Dist-Metadata.git
236

AUTHOR

238       Randy Stauner <rwstauner@cpan.org>
239

CONTRIBUTORS

241       •   David Steinbrunner <dsteinbrunner@pobox.com>
242
243       •   Graham Knop <haarg@haarg.org>
244
245       •   Jeffrey Ryan Thalhammer <thaljef@cpan.org>
246
247       •   Sawyer X <xsawyerx@cpan.org>
248

COPYRIGHT AND LICENSE

250       This software is copyright (c) 2011 by Randy Stauner.
251
252       This is free software; you can redistribute it and/or modify it under
253       the same terms as the Perl 5 programming language system itself.
254
255
256
257perl v5.38.0                      2023-07-20                 Dist::Metadata(3)