1Module::Metadata(3) User Contributed Perl Documentation Module::Metadata(3)
2
6 Module::Metadata - Gather package and POD information from perl module
7 files
8
10 version 1.000037
11
13 use Module::Metadata;
14 # information about a .pm file
16 my $info = Module::Metadata->new_from_file( $file );
17 my $version = $info->version;
18 # CPAN META 'provides' field for .pm files in a directory
20 my $provides = Module::Metadata->provides(
21 dir => 'lib', version => 2
22 );
23
25 This module provides a standard way to gather metadata about a .pm file
26 through (mostly) static analysis and (some) code execution. When
27 determining the version of a module, the $VERSION assignment is
28 "eval"ed, as is traditional in the CPAN toolchain.
29
31 "new_from_file($filename, collect_pod => 1, decode_pod => 1)"
32 Constructs a "Module::Metadata" object given the path to a file.
33 Returns undef if the filename does not exist.
34 "collect_pod" is a optional boolean argument that determines whether
36 POD data is collected and stored for reference. POD data is not
37 collected by default. POD headings are always collected.
38 If the file begins by an UTF-8, UTF-16BE or UTF-16LE byte-order mark,
40 then it is skipped before processing, and the content of the file is
41 also decoded appropriately starting from perl 5.8.
42 Alternatively, if "decode_pod" is set, it will decode the collected pod
44 sections according to the "=encoding" declaration.
45 "new_from_handle($handle, $filename, collect_pod => 1, decode_pod => 1)"
47 This works just like "new_from_file", except that a handle can be
48 provided as the first argument.
49 Note that there is no validation to confirm that the handle is a handle
51 or something that can act like one. Passing something that isn't a
52 handle will cause a exception when trying to read from it. The
53 "filename" argument is mandatory or undef will be returned.
54 You are responsible for setting the decoding layers on $handle if
56 required.
57 "new_from_module($module, collect_pod => 1, inc => \@dirs, decode_pod =>
59 1)"
60 Constructs a "Module::Metadata" object given a module or package name.
61 Returns undef if the module cannot be found.
62 In addition to accepting the "collect_pod" and "decode_pod" arguments
64 as described above, this method accepts a "inc" argument which is a
65 reference to an array of directories to search for the module. If none
66 are given, the default is @INC.
67 If the file that contains the module begins by an UTF-8, UTF-16BE or
69 UTF-16LE byte-order mark, then it is skipped before processing, and the
70 content of the file is also decoded appropriately starting from perl
71 5.8.
72 "find_module_by_name($module, \@dirs)"
74 Returns the path to a module given the module or package name. A list
75 of directories can be passed in as an optional parameter, otherwise
76 @INC is searched.
77 Can be called as either an object or a class method.
79 "find_module_dir_by_name($module, \@dirs)"
81 Returns the entry in @dirs (or @INC by default) that contains the
82 module $module. A list of directories can be passed in as an optional
83 parameter, otherwise @INC is searched.
84 Can be called as either an object or a class method.
86 "provides( %options )"
88 This is a convenience wrapper around "package_versions_from_directory"
89 to generate a CPAN META "provides" data structure. It takes key/value
90 pairs. Valid option keys include:
91 version (required)
93 Specifies which version of the CPAN::Meta::Spec should be used as
94 the format of the "provides" output. Currently only '1.4' and '2'
95 are supported (and their format is identical). This may change in
96 the future as the definition of "provides" changes.
97 The "version" option is required. If it is omitted or if an
99 unsupported version is given, then "provides" will throw an error.
100 dir Directory to search recursively for .pm files. May not be
102 specified with "files".
103 files
105 Array reference of files to examine. May not be specified with
106 "dir".
107 prefix
109 String to prepend to the "file" field of the resulting output. This
110 defaults to lib, which is the common case for most CPAN
111 distributions with their .pm files in lib. This option ensures the
112 META information has the correct relative path even when the "dir"
113 or "files" arguments are absolute or have relative paths from a
114 location other than the distribution root.
115 For example, given "dir" of 'lib' and "prefix" of 'lib', the return
117 value is a hashref of the form:
118 {
120 'Package::Name' => {
121 version => '0.123',
122 file => 'lib/Package/Name.pm'
123 },
124 'OtherPackage::Name' => ...
125 }
126 "package_versions_from_directory($dir, \@files?)"
128 Scans $dir for .pm files (unless @files is given, in which case looks
129 for those files in $dir - and reads each file for packages and
130 versions, returning a hashref of the form:
131 {
133 'Package::Name' => {
134 version => '0.123',
135 file => 'Package/Name.pm'
136 },
137 'OtherPackage::Name' => ...
138 }
139 The "DB" and "main" packages are always omitted, as are any "private"
141 packages that have leading underscores in the namespace (e.g.
142 "Foo::_private")
143 Note that the file path is relative to $dir if that is specified. This
145 must not be used directly for CPAN META "provides". See the "provides"
146 method instead.
147 "log_info (internal)"
149 Used internally to perform logging; imported from Log::Contextual if
150 Log::Contextual has already been loaded, otherwise simply calls warn.
151
153 "name()"
154 Returns the name of the package represented by this module. If there is
155 more than one package, it makes a best guess based on the filename. If
156 it's a script (i.e. not a *.pm) the package name is 'main'.
157 "version($package)"
159 Returns the version as defined by the $VERSION variable for the package
160 as returned by the "name" method if no arguments are given. If given
161 the name of a package it will attempt to return the version of that
162 package if it is specified in the file.
163 "filename()"
165 Returns the absolute path to the file. Note that this file may not
166 actually exist on disk yet, e.g. if the module was read from an in-
167 memory filehandle.
168 "packages_inside()"
170 Returns a list of packages. Note: this is a raw list of packages
171 discovered (or assumed, in the case of "main"). It is not filtered for
172 "DB", "main" or private packages the way the "provides" method does.
173 Invalid package names are not returned, for example "Foo:Bar". Strange
174 but valid package names are returned, for example "Foo::Bar::", and are
175 left up to the caller on how to handle.
176 "pod_inside()"
178 Returns a list of POD sections.
179 "contains_pod()"
181 Returns true if there is any POD in the file.
182 "pod($section)"
184 Returns the POD data in the given section.
185 "is_indexable($package)" or "is_indexable()"
187 Available since version 1.000020.
188 Returns a boolean indicating whether the package (if provided) or any
190 package (otherwise) is eligible for indexing by PAUSE, the Perl Authors
191 Upload Server. Note This only checks for valid "package" declarations,
192 and does not take any ownership information into account.
193
195 Bugs may be submitted through the RT bug tracker
196 <https://rt.cpan.org/Public/Dist/Display.html?Name=Module-Metadata> (or
197 bug-Module-Metadata@rt.cpan.org <mailto:bug-Module-
198 Metadata@rt.cpan.org>).
199 There is also a mailing list available for users of this distribution,
201 at <http://lists.perl.org/list/cpan-workers.html>.
202 There is also an irc channel available for users of this distribution,
204 at "#toolchain" on "irc.perl.org" <irc://irc.perl.org/#toolchain>.
205
207 Original code from Module::Build::ModuleInfo by Ken Williams
208 <kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
209 Released as Module::Metadata by Matt S Trout (mst)
211 <mst@shadowcat.co.uk> with assistance from David Golden (xdg)
212 <dagolden@cpan.org>.
213
215 • Karen Etheridge <ether@cpan.org>
216 • David Golden <dagolden@cpan.org>
218 • Vincent Pit <perl@profvince.com>
220 • Matt S Trout <mst@shadowcat.co.uk>
222 • Chris Nehren <apeiron@cpan.org>
224 • Tomas Doran <bobtfish@bobtfish.net>
226 • Olivier Mengué <dolmen@cpan.org>
228 • Graham Knop <haarg@haarg.org>
230 • tokuhirom <tokuhirom@gmail.com>
232 • Tatsuhiko Miyagawa <miyagawa@bulknews.net>
234 • Christian Walde <walde.christian@googlemail.com>
236 • Leon Timmermans <fawaka@gmail.com>
238 • Peter Rabbitson <ribasushi@cpan.org>
240 • Steve Hay <steve.m.hay@googlemail.com>
242 • Jerry D. Hedden <jdhedden@cpan.org>
244 • Craig A. Berry <cberry@cpan.org>
246 • Craig A. Berry <craigberry@mac.com>
248 • David Mitchell <davem@iabyn.com>
250 • David Steinbrunner <dsteinbrunner@pobox.com>
252 • Edward Zborowski <ed@rubensteintech.com>
254 • Gareth Harper <gareth@broadbean.com>
256 • James Raspass <jraspass@gmail.com>
258 • Chris 'BinGOs' Williams <chris@bingosnet.co.uk>
260 • Josh Jore <jjore@cpan.org>
262 • Kent Fredric <kentnl@cpan.org>
264
266 Original code Copyright (c) 2001-2011 Ken Williams. Additional code
267 Copyright (c) 2010-2011 Matt Trout and David Golden. All rights
268 reserved.
269 This library is free software; you can redistribute it and/or modify it
271 under the same terms as Perl itself.
272perl v5.32.1 2021-01-27 Module::Metadata(3)