Debian Codegraph @

upstream/mageia-cauldron/man3pm/Module::Metadata.3pm

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