| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Module::Metadata 3perl" |
| 58 |
.TH Module::Metadata 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Module::Metadata \- Gather package and POD information from perl module files |
| 65 |
.SH VERSION |
| 66 |
.IX Header "VERSION" |
| 67 |
version 1.000038 |
| 68 |
.SH SYNOPSIS |
| 69 |
.IX Header "SYNOPSIS" |
| 70 |
.Vb 1 |
| 71 |
\& use Module::Metadata; |
| 72 |
\& |
| 73 |
\& # information about a .pm file |
| 74 |
\& my $info = Module::Metadata\->new_from_file( $file ); |
| 75 |
\& my $version = $info\->version; |
| 76 |
\& |
| 77 |
\& # CPAN META \*(Aqprovides\*(Aq field for .pm files in a directory |
| 78 |
\& my $provides = Module::Metadata\->provides( |
| 79 |
\& dir => \*(Aqlib\*(Aq, version => 2 |
| 80 |
\& ); |
| 81 |
.Ve |
| 82 |
.SH DESCRIPTION |
| 83 |
.IX Header "DESCRIPTION" |
| 84 |
This module provides a standard way to gather metadata about a .pm file through |
| 85 |
(mostly) static analysis and (some) code execution. When determining the |
| 86 |
version of a module, the \f(CW$VERSION\fR assignment is \f(CW\*(C`eval\*(C'\fRed, as is traditional |
| 87 |
in the CPAN toolchain. |
| 88 |
.SH "CLASS METHODS" |
| 89 |
.IX Header "CLASS METHODS" |
| 90 |
.ie n .SS """new_from_file($filename, collect_pod => 1, decode_pod => 1)""" |
| 91 |
.el .SS "\f(CWnew_from_file($filename, collect_pod => 1, decode_pod => 1)\fP" |
| 92 |
.IX Subsection "new_from_file($filename, collect_pod => 1, decode_pod => 1)" |
| 93 |
Constructs a \f(CW\*(C`Module::Metadata\*(C'\fR object given the path to a file. Returns |
| 94 |
undef if the filename does not exist. |
| 95 |
.PP |
| 96 |
\&\f(CW\*(C`collect_pod\*(C'\fR is a optional boolean argument that determines whether POD |
| 97 |
data is collected and stored for reference. POD data is not collected by |
| 98 |
default. POD headings are always collected. |
| 99 |
.PP |
| 100 |
If the file begins by an UTF\-8, UTF\-16BE or UTF\-16LE byte-order mark, then |
| 101 |
it is skipped before processing, and the content of the file is also decoded |
| 102 |
appropriately starting from perl 5.8. |
| 103 |
.PP |
| 104 |
Alternatively, if \f(CW\*(C`decode_pod\*(C'\fR is set, it will decode the collected pod |
| 105 |
sections according to the \f(CW\*(C`=encoding\*(C'\fR declaration. |
| 106 |
.ie n .SS """new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)""" |
| 107 |
.el .SS "\f(CWnew_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)\fP" |
| 108 |
.IX Subsection "new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)" |
| 109 |
This works just like \f(CW\*(C`new_from_file\*(C'\fR, except that a handle can be provided |
| 110 |
as the first argument. |
| 111 |
.PP |
| 112 |
Note that there is no validation to confirm that the handle is a handle or |
| 113 |
something that can act like one. Passing something that isn't a handle will |
| 114 |
cause a exception when trying to read from it. The \f(CW\*(C`filename\*(C'\fR argument is |
| 115 |
mandatory or undef will be returned. |
| 116 |
.PP |
| 117 |
You are responsible for setting the decoding layers on \f(CW$handle\fR if |
| 118 |
required. |
| 119 |
.ie n .SS """new_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)""" |
| 120 |
.el .SS "\f(CWnew_from_module($module, collect_pod => 1, inc => \e@dirs, decode_pod => 1)\fP" |
| 121 |
.IX Subsection "new_from_module($module, collect_pod => 1, inc => @dirs, decode_pod => 1)" |
| 122 |
Constructs a \f(CW\*(C`Module::Metadata\*(C'\fR object given a module or package name. |
| 123 |
Returns undef if the module cannot be found. |
| 124 |
.PP |
| 125 |
In addition to accepting the \f(CW\*(C`collect_pod\*(C'\fR and \f(CW\*(C`decode_pod\*(C'\fR arguments as |
| 126 |
described above, this method accepts a \f(CW\*(C`inc\*(C'\fR argument which is a reference to |
| 127 |
an array of directories to search for the module. If none are given, the |
| 128 |
default is \f(CW@INC\fR. |
| 129 |
.PP |
| 130 |
If the file that contains the module begins by an UTF\-8, UTF\-16BE or |
| 131 |
UTF\-16LE byte-order mark, then it is skipped before processing, and the |
| 132 |
content of the file is also decoded appropriately starting from perl 5.8. |
| 133 |
.ie n .SS """find_module_by_name($module, \e@dirs)""" |
| 134 |
.el .SS "\f(CWfind_module_by_name($module, \e@dirs)\fP" |
| 135 |
.IX Subsection "find_module_by_name($module, @dirs)" |
| 136 |
Returns the path to a module given the module or package name. A list |
| 137 |
of directories can be passed in as an optional parameter, otherwise |
| 138 |
\&\f(CW@INC\fR is searched. |
| 139 |
.PP |
| 140 |
Can be called as either an object or a class method. |
| 141 |
.ie n .SS """find_module_dir_by_name($module, \e@dirs)""" |
| 142 |
.el .SS "\f(CWfind_module_dir_by_name($module, \e@dirs)\fP" |
| 143 |
.IX Subsection "find_module_dir_by_name($module, @dirs)" |
| 144 |
Returns the entry in \f(CW@dirs\fR (or \f(CW@INC\fR by default) that contains |
| 145 |
the module \f(CW$module\fR. A list of directories can be passed in as an |
| 146 |
optional parameter, otherwise \f(CW@INC\fR is searched. |
| 147 |
.PP |
| 148 |
Can be called as either an object or a class method. |
| 149 |
.ie n .SS "provides( %options )" |
| 150 |
.el .SS "\f(CWprovides( %options )\fP" |
| 151 |
.IX Subsection "provides( %options )" |
| 152 |
This is a convenience wrapper around \f(CW\*(C`package_versions_from_directory\*(C'\fR |
| 153 |
to generate a CPAN META \f(CW\*(C`provides\*(C'\fR data structure. It takes key/value |
| 154 |
pairs. Valid option keys include: |
| 155 |
.IP "version \fB(required)\fR" 4 |
| 156 |
.IX Item "version (required)" |
| 157 |
Specifies which version of the CPAN::Meta::Spec should be used as |
| 158 |
the format of the \f(CW\*(C`provides\*(C'\fR output. Currently only '1.4' and '2' |
| 159 |
are supported (and their format is identical). This may change in |
| 160 |
the future as the definition of \f(CW\*(C`provides\*(C'\fR changes. |
| 161 |
.Sp |
| 162 |
The \f(CW\*(C`version\*(C'\fR option is required. If it is omitted or if |
| 163 |
an unsupported version is given, then \f(CW\*(C`provides\*(C'\fR will throw an error. |
| 164 |
.IP dir 4 |
| 165 |
.IX Item "dir" |
| 166 |
Directory to search recursively for \fI.pm\fR files. May not be specified with |
| 167 |
\&\f(CW\*(C`files\*(C'\fR. |
| 168 |
.IP files 4 |
| 169 |
.IX Item "files" |
| 170 |
Array reference of files to examine. May not be specified with \f(CW\*(C`dir\*(C'\fR. |
| 171 |
.IP prefix 4 |
| 172 |
.IX Item "prefix" |
| 173 |
String to prepend to the \f(CW\*(C`file\*(C'\fR field of the resulting output. This defaults |
| 174 |
to \fIlib\fR, which is the common case for most CPAN distributions with their |
| 175 |
\&\fI.pm\fR files in \fIlib\fR. This option ensures the META information has the |
| 176 |
correct relative path even when the \f(CW\*(C`dir\*(C'\fR or \f(CW\*(C`files\*(C'\fR arguments are |
| 177 |
absolute or have relative paths from a location other than the distribution |
| 178 |
root. |
| 179 |
.PP |
| 180 |
For example, given \f(CW\*(C`dir\*(C'\fR of 'lib' and \f(CW\*(C`prefix\*(C'\fR of 'lib', the return value |
| 181 |
is a hashref of the form: |
| 182 |
.PP |
| 183 |
.Vb 7 |
| 184 |
\& { |
| 185 |
\& \*(AqPackage::Name\*(Aq => { |
| 186 |
\& version => \*(Aq0.123\*(Aq, |
| 187 |
\& file => \*(Aqlib/Package/Name.pm\*(Aq |
| 188 |
\& }, |
| 189 |
\& \*(AqOtherPackage::Name\*(Aq => ... |
| 190 |
\& } |
| 191 |
.Ve |
| 192 |
.ie n .SS """package_versions_from_directory($dir, \e@files?)""" |
| 193 |
.el .SS "\f(CWpackage_versions_from_directory($dir, \e@files?)\fP" |
| 194 |
.IX Subsection "package_versions_from_directory($dir, @files?)" |
| 195 |
Scans \f(CW$dir\fR for .pm files (unless \f(CW@files\fR is given, in which case looks |
| 196 |
for those files in \f(CW$dir\fR \- and reads each file for packages and versions, |
| 197 |
returning a hashref of the form: |
| 198 |
.PP |
| 199 |
.Vb 7 |
| 200 |
\& { |
| 201 |
\& \*(AqPackage::Name\*(Aq => { |
| 202 |
\& version => \*(Aq0.123\*(Aq, |
| 203 |
\& file => \*(AqPackage/Name.pm\*(Aq |
| 204 |
\& }, |
| 205 |
\& \*(AqOtherPackage::Name\*(Aq => ... |
| 206 |
\& } |
| 207 |
.Ve |
| 208 |
.PP |
| 209 |
The \f(CW\*(C`DB\*(C'\fR and \f(CW\*(C`main\*(C'\fR packages are always omitted, as are any "private" |
| 210 |
packages that have leading underscores in the namespace (e.g. |
| 211 |
\&\f(CW\*(C`Foo::_private\*(C'\fR) |
| 212 |
.PP |
| 213 |
Note that the file path is relative to \f(CW$dir\fR if that is specified. |
| 214 |
This \fBmust not\fR be used directly for CPAN META \f(CW\*(C`provides\*(C'\fR. See |
| 215 |
the \f(CW\*(C`provides\*(C'\fR method instead. |
| 216 |
.ie n .SS """log_info (internal)""" |
| 217 |
.el .SS "\f(CWlog_info (internal)\fP" |
| 218 |
.IX Subsection "log_info (internal)" |
| 219 |
Used internally to perform logging; imported from Log::Contextual if |
| 220 |
Log::Contextual has already been loaded, otherwise simply calls warn. |
| 221 |
.SH "OBJECT METHODS" |
| 222 |
.IX Header "OBJECT METHODS" |
| 223 |
.ie n .SS name() |
| 224 |
.el .SS \f(CWname()\fP |
| 225 |
.IX Subsection "name()" |
| 226 |
Returns the name of the package represented by this module. If there |
| 227 |
is more than one package, it makes a best guess based on the |
| 228 |
filename. If it's a script (i.e. not a *.pm) the package name is |
| 229 |
\&'main'. |
| 230 |
.ie n .SS version($package) |
| 231 |
.el .SS \f(CWversion($package)\fP |
| 232 |
.IX Subsection "version($package)" |
| 233 |
Returns the version as defined by the \f(CW$VERSION\fR variable for the |
| 234 |
package as returned by the \f(CW\*(C`name\*(C'\fR method if no arguments are |
| 235 |
given. If given the name of a package it will attempt to return the |
| 236 |
version of that package if it is specified in the file. |
| 237 |
.ie n .SS filename() |
| 238 |
.el .SS \f(CWfilename()\fP |
| 239 |
.IX Subsection "filename()" |
| 240 |
Returns the absolute path to the file. |
| 241 |
Note that this file may not actually exist on disk yet, e.g. if the module was read from an in-memory filehandle. |
| 242 |
.ie n .SS packages_inside() |
| 243 |
.el .SS \f(CWpackages_inside()\fP |
| 244 |
.IX Subsection "packages_inside()" |
| 245 |
Returns a list of packages. Note: this is a raw list of packages |
| 246 |
discovered (or assumed, in the case of \f(CW\*(C`main\*(C'\fR). It is not |
| 247 |
filtered for \f(CW\*(C`DB\*(C'\fR, \f(CW\*(C`main\*(C'\fR or private packages the way the |
| 248 |
\&\f(CW\*(C`provides\*(C'\fR method does. Invalid package names are not returned, |
| 249 |
for example "Foo:Bar". Strange but valid package names are |
| 250 |
returned, for example "Foo::Bar::", and are left up to the caller |
| 251 |
on how to handle. |
| 252 |
.ie n .SS pod_inside() |
| 253 |
.el .SS \f(CWpod_inside()\fP |
| 254 |
.IX Subsection "pod_inside()" |
| 255 |
Returns a list of POD sections. |
| 256 |
.ie n .SS contains_pod() |
| 257 |
.el .SS \f(CWcontains_pod()\fP |
| 258 |
.IX Subsection "contains_pod()" |
| 259 |
Returns true if there is any POD in the file. |
| 260 |
.ie n .SS pod($section) |
| 261 |
.el .SS \f(CWpod($section)\fP |
| 262 |
.IX Subsection "pod($section)" |
| 263 |
Returns the POD data in the given section. |
| 264 |
.ie n .SS "is_indexable($package) or is_indexable()" |
| 265 |
.el .SS "\f(CWis_indexable($package)\fP or \f(CWis_indexable()\fP" |
| 266 |
.IX Subsection "is_indexable($package) or is_indexable()" |
| 267 |
Available since version 1.000020. |
| 268 |
.PP |
| 269 |
Returns a boolean indicating whether the package (if provided) or any package |
| 270 |
(otherwise) is eligible for indexing by PAUSE, the Perl Authors Upload Server. |
| 271 |
Note This only checks for valid \f(CW\*(C`package\*(C'\fR declarations, and does not take any |
| 272 |
ownership information into account. |
| 273 |
.SH SUPPORT |
| 274 |
.IX Header "SUPPORT" |
| 275 |
Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Metadata> |
| 276 |
(or bug\-Module\[email protected] <mailto:[email protected]>). |
| 277 |
.PP |
| 278 |
There is also a mailing list available for users of this distribution, at |
| 279 |
<http://lists.perl.org/list/cpan\-workers.html>. |
| 280 |
.PP |
| 281 |
There is also an irc channel available for users of this distribution, at |
| 282 |
\&\f(CW\*(C`#toolchain\*(C'\fR on \f(CW\*(C`irc.perl.org\*(C'\fR <irc://irc.perl.org/#toolchain>. |
| 283 |
.SH AUTHOR |
| 284 |
.IX Header "AUTHOR" |
| 285 |
Original code from Module::Build::ModuleInfo by Ken Williams |
| 286 |
<[email protected]>, Randy W. Sims <[email protected]> |
| 287 |
.PP |
| 288 |
Released as Module::Metadata by Matt S Trout (mst) <[email protected]> with |
| 289 |
assistance from David Golden (xdg) <[email protected]>. |
| 290 |
.SH CONTRIBUTORS |
| 291 |
.IX Header "CONTRIBUTORS" |
| 292 |
.IP \(bu 4 |
| 293 |
Karen Etheridge <[email protected]> |
| 294 |
.IP \(bu 4 |
| 295 |
David Golden <[email protected]> |
| 296 |
.IP \(bu 4 |
| 297 |
Vincent Pit <[email protected]> |
| 298 |
.IP \(bu 4 |
| 299 |
Matt S Trout <[email protected]> |
| 300 |
.IP \(bu 4 |
| 301 |
Chris Nehren <[email protected]> |
| 302 |
.IP \(bu 4 |
| 303 |
Graham Knop <[email protected]> |
| 304 |
.IP \(bu 4 |
| 305 |
Olivier Mengué <[email protected]> |
| 306 |
.IP \(bu 4 |
| 307 |
Tomas Doran <[email protected]> |
| 308 |
.IP \(bu 4 |
| 309 |
Christian Walde <[email protected]> |
| 310 |
.IP \(bu 4 |
| 311 |
Craig A. Berry <[email protected]> |
| 312 |
.IP \(bu 4 |
| 313 |
Tatsuhiko Miyagawa <[email protected]> |
| 314 |
.IP \(bu 4 |
| 315 |
tokuhirom <[email protected]> |
| 316 |
.IP \(bu 4 |
| 317 |
Chris 'BinGOs' Williams <[email protected]> |
| 318 |
.IP \(bu 4 |
| 319 |
David Mitchell <[email protected]> |
| 320 |
.IP \(bu 4 |
| 321 |
David Steinbrunner <[email protected]> |
| 322 |
.IP \(bu 4 |
| 323 |
Edward Zborowski <[email protected]> |
| 324 |
.IP \(bu 4 |
| 325 |
Gareth Harper <[email protected]> |
| 326 |
.IP \(bu 4 |
| 327 |
James Raspass <[email protected]> |
| 328 |
.IP \(bu 4 |
| 329 |
Jerry D. Hedden <[email protected]> |
| 330 |
.IP \(bu 4 |
| 331 |
Josh Jore <[email protected]> |
| 332 |
.IP \(bu 4 |
| 333 |
Kent Fredric <[email protected]> |
| 334 |
.IP \(bu 4 |
| 335 |
Leon Timmermans <[email protected]> |
| 336 |
.IP \(bu 4 |
| 337 |
Peter Rabbitson <[email protected]> |
| 338 |
.IP \(bu 4 |
| 339 |
Steve Hay <[email protected]> |
| 340 |
.SH "COPYRIGHT & LICENSE" |
| 341 |
.IX Header "COPYRIGHT & LICENSE" |
| 342 |
Original code Copyright (c) 2001\-2011 Ken Williams. |
| 343 |
Additional code Copyright (c) 2010\-2011 Matt Trout and David Golden. |
| 344 |
All rights reserved. |
| 345 |
.PP |
| 346 |
This library is free software; you can redistribute it and/or |
| 347 |
modify it under the same terms as Perl itself. |