1Parse::CPAN::Meta(3)  User Contributed Perl Documentation Parse::CPAN::Meta(3)
2
3
4

NAME

6       Parse::CPAN::Meta - Parse META.yml and META.json CPAN metadata files
7

SYNOPSIS

9           #############################################
10           # In your file
11
12           ---
13           name: My-Distribution
14           version: 1.23
15           resources:
16             homepage: "http://example.com/dist/My-Distribution"
17
18
19           #############################################
20           # In your program
21
22           use Parse::CPAN::Meta;
23
24           my $distmeta = Parse::CPAN::Meta->load_file('META.yml');
25
26           # Reading properties
27           my $name     = $distmeta->{name};
28           my $version  = $distmeta->{version};
29           my $homepage = $distmeta->{resources}{homepage};
30

DESCRIPTION

32       Parse::CPAN::Meta is a parser for META.json and META.yml files, using
33       JSON::PP and/or CPAN::Meta::YAML.
34
35       Parse::CPAN::Meta provides three methods: "load_file",
36       "load_json_string", and "load_yaml_string".  These will read and
37       deserialize CPAN metafiles, and are described below in detail.
38
39       Parse::CPAN::Meta provides a legacy API of only two functions, based on
40       the YAML functions of the same name. Wherever possible, identical
41       calling semantics are used.  These may only be used with YAML sources.
42
43       All error reporting is done with exceptions (die'ing).
44
45       Note that META files are expected to be in UTF-8 encoding, only.  When
46       converted string data, it must first be decoded from UTF-8.
47

METHODS

49   load_file
50         my $metadata_structure = Parse::CPAN::Meta->load_file('META.json');
51
52         my $metadata_structure = Parse::CPAN::Meta->load_file('META.yml');
53
54       This method will read the named file and deserialize it to a data
55       structure, determining whether it should be JSON or YAML based on the
56       filename.  On Perl 5.8.1 or later, the file will be read using the
57       ":utf8" IO layer.
58
59   load_yaml_string
60         my $metadata_structure = Parse::CPAN::Meta->load_yaml_string($yaml_string);
61
62       This method deserializes the given string of YAML and returns the first
63       document in it.  (CPAN metadata files should always have only one
64       document.)  If the source was UTF-8 encoded, the string must be decoded
65       before calling "load_yaml_string".
66
67   load_json_string
68         my $metadata_structure = Parse::CPAN::Meta->load_json_string($json_string);
69
70       This method deserializes the given string of JSON and the result.  If
71       the source was UTF-8 encoded, the string must be decoded before calling
72       "load_json_string".
73
74   yaml_backend
75         my $backend = Parse::CPAN::Meta->yaml_backend;
76
77       Returns the module name of the YAML serializer. See "ENVIRONMENT" for
78       details.
79
80   json_backend
81         my $backend = Parse::CPAN::Meta->json_backend;
82
83       Returns the module name of the JSON serializer.  This will either be
84       JSON::PP or JSON.  Even if "PERL_JSON_BACKEND" is set, this will return
85       JSON as further delegation is handled by the JSON module.  See
86       "ENVIRONMENT" for details.
87

FUNCTIONS

89       For maintenance clarity, no functions are exported.  These functions
90       are available for backwards compatibility only and are best avoided in
91       favor of "load_file".
92
93   Load
94         my @yaml = Parse::CPAN::Meta::Load( $string );
95
96       Parses a string containing a valid YAML stream into a list of Perl data
97       structures.
98
99   LoadFile
100         my @yaml = Parse::CPAN::Meta::LoadFile( 'META.yml' );
101
102       Reads the YAML stream from a file instead of a string.
103

ENVIRONMENT

105   PERL_JSON_BACKEND
106       By default, JSON::PP will be used for deserializing JSON data. If the
107       "PERL_JSON_BACKEND" environment variable exists, is true and is not
108       "JSON::PP", then the JSON module (version 2.5 or greater) will be
109       loaded and used to interpret "PERL_JSON_BACKEND".  If JSON is not
110       installed or is too old, an exception will be thrown.
111
112   PERL_YAML_BACKEND
113       By default, CPAN::Meta::YAML will be used for deserializing YAML data.
114       If the "PERL_YAML_BACKEND" environment variable is defined, then it is
115       intepreted as a module to use for deserialization.  The given module
116       must be installed, must load correctly and must implement the "Load()"
117       function or an exception will be thrown.
118

SUPPORT

120       Bugs should be reported via the CPAN bug tracker at
121
122       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-CPAN-Meta>
123

AUTHOR

125       Adam Kennedy <adamk@cpan.org>
126

128       Copyright 2006 - 2010 Adam Kennedy.
129
130       This program is free software; you can redistribute it and/or modify it
131       under the same terms as Perl itself.
132
133       The full text of the license can be found in the LICENSE file included
134       with this module.
135
136
137
138perl v5.16.3                      2012-04-05              Parse::CPAN::Meta(3)
Impressum