Debian Codegraph @

upstream/debian-unstable/man3/Module::Metadata.3perl

raw
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.