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 use Module::Metadata;
11 # information about a .pm file
13 my $info = Module::Metadata->new_from_file( $file );
14 my $version = $info->version;
15 # CPAN META 'provides' field for .pm files in a directory
17 my $provides = Module::Metadata->provides(
18 dir => 'lib', version => 2
19 );
20
22 This module provides a standard way to gather metadata about a .pm file
23 through (mostly) static analysis and (some) code execution. When
24 determining the version of a module, the $VERSION assignment is
25 "eval"ed, as is traditional in the CPAN toolchain.
26
28 Class methods
29 "new_from_file($filename, collect_pod => 1)"
30 Constructs a "Module::Metadata" object given the path to a file.
31 Returns undef if the filename does not exist.
32 "collect_pod" is a optional boolean argument that determines
34 whether POD data is collected and stored for reference. POD data
35 is not collected by default. POD headings are always collected.
36 If the file begins by an UTF-8, UTF-16BE or UTF-16LE byte-order
38 mark, then it is skipped before processing, and the content of the
39 file is also decoded appropriately starting from perl 5.8.
40 "new_from_handle($handle, $filename, collect_pod => 1)"
42 This works just like "new_from_file", except that a handle can be
43 provided as the first argument.
44 Note that there is no validation to confirm that the handle is a
46 handle or something that can act like one. Passing something that
47 isn't a handle will cause a exception when trying to read from it.
48 The "filename" argument is mandatory or undef will be returned.
49 You are responsible for setting the decoding layers on $handle if
51 required.
52 "new_from_module($module, collect_pod => 1, inc => \@dirs)"
54 Constructs a "Module::Metadata" object given a module or package
55 name. Returns undef if the module cannot be found.
56 In addition to accepting the "collect_pod" argument as described
58 above, this method accepts a "inc" argument which is a reference to
59 an array of directories to search for the module. If none are
60 given, the default is @INC.
61 If the file that contains the module begins by an UTF-8, UTF-16BE
63 or UTF-16LE byte-order mark, then it is skipped before processing,
64 and the content of the file is also decoded appropriately starting
65 from perl 5.8.
66 "find_module_by_name($module, \@dirs)"
68 Returns the path to a module given the module or package name. A
69 list of directories can be passed in as an optional parameter,
70 otherwise @INC is searched.
71 Can be called as either an object or a class method.
73 "find_module_dir_by_name($module, \@dirs)"
75 Returns the entry in @dirs (or @INC by default) that contains the
76 module $module. A list of directories can be passed in as an
77 optional parameter, otherwise @INC is searched.
78 Can be called as either an object or a class method.
80 "provides( %options )"
82 This is a convenience wrapper around
83 "package_versions_from_directory" to generate a CPAN META
84 "provides" data structure. It takes key/value pairs. Valid option
85 keys include:
86 version (required)
88 Specifies which version of the CPAN::Meta::Spec should be used
89 as the format of the "provides" output. Currently only '1.4'
90 and '2' are supported (and their format is identical). This
91 may change in the future as the definition of "provides"
92 changes.
93 The "version" option is required. If it is omitted or if an
95 unsupported version is given, then "provides" will throw an
96 error.
97 dir Directory to search recursively for .pm files. May not be
99 specified with "files".
100 files
102 Array reference of files to examine. May not be specified with
103 "dir".
104 prefix
106 String to prepend to the "file" field of the resulting output.
107 This defaults to lib, which is the common case for most CPAN
108 distributions with their .pm files in lib. This option ensures
109 the META information has the correct relative path even when
110 the "dir" or "files" arguments are absolute or have relative
111 paths from a location other than the distribution root.
112 For example, given "dir" of 'lib' and "prefix" of 'lib', the return
114 value is a hashref of the form:
115 {
117 'Package::Name' => {
118 version => '0.123',
119 file => 'lib/Package/Name.pm'
120 },
121 'OtherPackage::Name' => ...
122 }
123 "package_versions_from_directory($dir, \@files?)"
125 Scans $dir for .pm files (unless @files is given, in which case
126 looks for those files in $dir - and reads each file for packages
127 and versions, returning a hashref of the form:
128 {
130 'Package::Name' => {
131 version => '0.123',
132 file => 'Package/Name.pm'
133 },
134 'OtherPackage::Name' => ...
135 }
136 The "DB" and "main" packages are always omitted, as are any
138 "private" packages that have leading underscores in the namespace
139 (e.g. "Foo::_private")
140 Note that the file path is relative to $dir if that is specified.
142 This must not be used directly for CPAN META "provides". See the
143 "provides" method instead.
144 "log_info (internal)"
146 Used internally to perform logging; imported from Log::Contextual
147 if Log::Contextual has already been loaded, otherwise simply calls
148 warn.
149 Object methods
151 "name()"
152 Returns the name of the package represented by this module. If
153 there are more than one packages, it makes a best guess based on
154 the filename. If it's a script (i.e. not a *.pm) the package name
155 is 'main'.
156 "version($package)"
158 Returns the version as defined by the $VERSION variable for the
159 package as returned by the "name" method if no arguments are given.
160 If given the name of a package it will attempt to return the
161 version of that package if it is specified in the file.
162 "filename()"
164 Returns the absolute path to the file.
165 "packages_inside()"
167 Returns a list of packages. Note: this is a raw list of packages
168 discovered (or assumed, in the case of "main"). It is not filtered
169 for "DB", "main" or private packages the way the "provides" method
170 does. Invalid package names are not returned, for example
171 "Foo:Bar". Strange but valid package names are returned, for
172 example "Foo::Bar::", and are left up to the caller on how to
173 handle.
174 "pod_inside()"
176 Returns a list of POD sections.
177 "contains_pod()"
179 Returns true if there is any POD in the file.
180 "pod($section)"
182 Returns the POD data in the given section.
183
185 Original code from Module::Build::ModuleInfo by Ken Williams
186 <kwilliams@cpan.org>, Randy W. Sims <RandyS@ThePierianSpring.org>
187 Released as Module::Metadata by Matt S Trout (mst)
189 <mst@shadowcat.co.uk> with assistance from David Golden (xdg)
190 <dagolden@cpan.org>.
191
193 Original code Copyright (c) 2001-2011 Ken Williams. Additional code
194 Copyright (c) 2010-2011 Matt Trout and David Golden. All rights
195 reserved.
196 This library is free software; you can redistribute it and/or modify it
198 under the same terms as Perl itself.
199perl v5.16.3 2013-09-11 Module::Metadata(3)