2 package Parse::CPAN::Meta;
3 # ABSTRACT: Parse META.yml and META.json CPAN metadata files
4 our $VERSION = '1.4409'; # VERSION
9 sub HAVE_UTF8 () { $] >= 5.007003 }
10 sub IO_LAYER () { $] >= 5.008001 ? ":utf8" : "" }
14 # The string eval helps hide this from Test::MinimumVersion
16 die "Failed to load UTF-8 support" if $@;
22 @Parse::CPAN::Meta::ISA = qw{ Exporter };
23 @Parse::CPAN::Meta::EXPORT_OK = qw{ Load LoadFile };
27 my ($class, $filename) = @_;
29 if ($filename =~ /\.ya?ml$/) {
30 return $class->load_yaml_string(_slurp($filename));
33 if ($filename =~ /\.json$/) {
34 return $class->load_json_string(_slurp($filename));
37 croak("file type cannot be determined by filename");
40 sub load_yaml_string {
41 my ($class, $string) = @_;
42 my $backend = $class->yaml_backend();
43 my $data = eval { no strict 'refs'; &{"$backend\::Load"}($string) };
45 croak $backend->can('errstr') ? $backend->errstr : $@
47 return $data || {}; # in case document was valid but empty
50 sub load_json_string {
51 my ($class, $string) = @_;
52 return $class->json_backend()->new->decode($string);
56 local $Module::Load::Conditional::CHECK_INC_HASH = 1;
57 if (! defined $ENV{PERL_YAML_BACKEND} ) {
58 _can_load( 'CPAN::Meta::YAML', 0.002 )
59 or croak "CPAN::Meta::YAML 0.002 is not available\n";
60 return "CPAN::Meta::YAML";
63 my $backend = $ENV{PERL_YAML_BACKEND};
65 or croak "Could not load PERL_YAML_BACKEND '$backend'\n";
67 or croak "PERL_YAML_BACKEND '$backend' does not implement Load()\n";
73 local $Module::Load::Conditional::CHECK_INC_HASH = 1;
74 if (! $ENV{PERL_JSON_BACKEND} or $ENV{PERL_JSON_BACKEND} eq 'JSON::PP') {
75 _can_load( 'JSON::PP' => 2.27103 )
76 or croak "JSON::PP 2.27103 is not available\n";
80 _can_load( 'JSON' => 2.5 )
81 or croak "JSON 2.5 is required for " .
82 "\$ENV{PERL_JSON_BACKEND} = '$ENV{PERL_JSON_BACKEND}'\n";
88 open my $fh, "<" . IO_LAYER, "$_[0]"
89 or die "can't open $_[0] for reading: $!";
90 return do { local $/; <$fh> };
94 my ($module, $version) = @_;
95 (my $file = $module) =~ s{::}{/}g;
97 return 1 if $INC{$file};
98 return 0 if exists $INC{$file}; # prior load failed
99 eval { require $file; 1 }
101 if ( defined $version ) {
102 eval { $module->VERSION($version); 1 }
108 # Kept for backwards compatibility only
109 # Create an object from a file
111 require CPAN::Meta::YAML;
112 my $object = CPAN::Meta::YAML::LoadFile(shift)
113 or die CPAN::Meta::YAML->errstr;
117 # Parse a document from a string.
119 require CPAN::Meta::YAML;
120 my $object = CPAN::Meta::YAML::Load(shift)
121 or die CPAN::Meta::YAML->errstr;
135 Parse::CPAN::Meta - Parse META.yml and META.json CPAN metadata files
143 #############################################
147 name: My-Distribution
150 homepage: "http://example.com/dist/My-Distribution"
153 #############################################
156 use Parse::CPAN::Meta;
158 my $distmeta = Parse::CPAN::Meta->load_file('META.yml');
161 my $name = $distmeta->{name};
162 my $version = $distmeta->{version};
163 my $homepage = $distmeta->{resources}{homepage};
167 B<Parse::CPAN::Meta> is a parser for F<META.json> and F<META.yml> files, using
168 L<JSON::PP> and/or L<CPAN::Meta::YAML>.
170 B<Parse::CPAN::Meta> provides three methods: C<load_file>, C<load_json_string>,
171 and C<load_yaml_string>. These will read and deserialize CPAN metafiles, and
172 are described below in detail.
174 B<Parse::CPAN::Meta> provides a legacy API of only two functions,
175 based on the YAML functions of the same name. Wherever possible,
176 identical calling semantics are used. These may only be used with YAML sources.
178 All error reporting is done with exceptions (die'ing).
180 Note that META files are expected to be in UTF-8 encoding, only. When
181 converted string data, it must first be decoded from UTF-8.
183 =for Pod::Coverage HAVE_UTF8 IO_LAYER
189 my $metadata_structure = Parse::CPAN::Meta->load_file('META.json');
191 my $metadata_structure = Parse::CPAN::Meta->load_file('META.yml');
193 This method will read the named file and deserialize it to a data structure,
194 determining whether it should be JSON or YAML based on the filename. On
195 Perl 5.8.1 or later, the file will be read using the ":utf8" IO layer.
197 =head2 load_yaml_string
199 my $metadata_structure = Parse::CPAN::Meta->load_yaml_string($yaml_string);
201 This method deserializes the given string of YAML and returns the first
202 document in it. (CPAN metadata files should always have only one document.)
203 If the source was UTF-8 encoded, the string must be decoded before calling
206 =head2 load_json_string
208 my $metadata_structure = Parse::CPAN::Meta->load_json_string($json_string);
210 This method deserializes the given string of JSON and the result.
211 If the source was UTF-8 encoded, the string must be decoded before calling
216 my $backend = Parse::CPAN::Meta->yaml_backend;
218 Returns the module name of the YAML serializer. See L</ENVIRONMENT>
223 my $backend = Parse::CPAN::Meta->json_backend;
225 Returns the module name of the JSON serializer. This will either
226 be L<JSON::PP> or L<JSON>. Even if C<PERL_JSON_BACKEND> is set,
227 this will return L<JSON> as further delegation is handled by
228 the L<JSON> module. See L</ENVIRONMENT> for details.
232 For maintenance clarity, no functions are exported. These functions are
233 available for backwards compatibility only and are best avoided in favor of
238 my @yaml = Parse::CPAN::Meta::Load( $string );
240 Parses a string containing a valid YAML stream into a list of Perl data
245 my @yaml = Parse::CPAN::Meta::LoadFile( 'META.yml' );
247 Reads the YAML stream from a file instead of a string.
251 =head2 PERL_JSON_BACKEND
253 By default, L<JSON::PP> will be used for deserializing JSON data. If the
254 C<PERL_JSON_BACKEND> environment variable exists, is true and is not
255 "JSON::PP", then the L<JSON> module (version 2.5 or greater) will be loaded and
256 used to interpret C<PERL_JSON_BACKEND>. If L<JSON> is not installed or is too
257 old, an exception will be thrown.
259 =head2 PERL_YAML_BACKEND
261 By default, L<CPAN::Meta::YAML> will be used for deserializing YAML data. If
262 the C<PERL_YAML_BACKEND> environment variable is defined, then it is interpreted
263 as a module to use for deserialization. The given module must be installed,
264 must load correctly and must implement the C<Load()> function or an exception
267 =for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
271 =head2 Bugs / Feature Requests
273 Please report any bugs or feature requests through the issue tracker
274 at L<http://rt.cpan.org/Public/Dist/Display.html?Name=Parse-CPAN-Meta>.
275 You will be notified automatically of any progress on your issue.
279 This is open source software. The code repository is available for
280 public review and contribution under the terms of the license.
282 L<https://github.com/Perl-Toolchain-Gang/Parse-CPAN-Meta>
284 git clone https://github.com/Perl-Toolchain-Gang/Parse-CPAN-Meta.git
292 Adam Kennedy <adamk@cpan.org>
296 David Golden <dagolden@cpan.org>
306 Joshua ben Jore <jjore@cpan.org>
310 Neil Bowers <neil@bowers.com>
314 Ricardo Signes <rjbs@cpan.org>
318 Steffen Mueller <smueller@cpan.org>
322 =head1 COPYRIGHT AND LICENSE
324 This software is copyright (c) 2013 by Adam Kennedy and Contributors.
326 This is free software; you can redistribute it and/or modify it under
327 the same terms as the Perl 5 programming language system itself.