1Parse::CPAN::Meta(3) User Contributed Perl Documentation Parse::CPAN::Meta(3)
2
6 Parse::CPAN::Meta - Parse META.yml and META.json CPAN metadata files
7
9 version 2.150010
10
12 #############################################
13 # In your file
14 ---
16 name: My-Distribution
17 version: 1.23
18 resources:
19 homepage: "http://example.com/dist/My-Distribution"
20 #############################################
23 # In your program
24 use Parse::CPAN::Meta;
26 my $distmeta = Parse::CPAN::Meta->load_file('META.yml');
28 # Reading properties
30 my $name = $distmeta->{name};
31 my $version = $distmeta->{version};
32 my $homepage = $distmeta->{resources}{homepage};
33
35 Parse::CPAN::Meta is a parser for META.json and META.yml files, using
36 JSON::PP and/or CPAN::Meta::YAML.
37 Parse::CPAN::Meta provides three methods: "load_file",
39 "load_json_string", and "load_yaml_string". These will read and
40 deserialize CPAN metafiles, and are described below in detail.
41 Parse::CPAN::Meta provides a legacy API of only two functions, based on
43 the YAML functions of the same name. Wherever possible, identical
44 calling semantics are used. These may only be used with YAML sources.
45 All error reporting is done with exceptions (die'ing).
47 Note that META files are expected to be in UTF-8 encoding, only. When
49 converted string data, it must first be decoded from UTF-8.
50
52 load_file
53 my $metadata_structure = Parse::CPAN::Meta->load_file('META.json');
54 my $metadata_structure = Parse::CPAN::Meta->load_file('META.yml');
56 This method will read the named file and deserialize it to a data
58 structure, determining whether it should be JSON or YAML based on the
59 filename. The file will be read using the ":utf8" IO layer.
60 load_yaml_string
62 my $metadata_structure = Parse::CPAN::Meta->load_yaml_string($yaml_string);
63 This method deserializes the given string of YAML and returns the first
65 document in it. (CPAN metadata files should always have only one
66 document.) If the source was UTF-8 encoded, the string must be decoded
67 before calling "load_yaml_string".
68 load_json_string
70 my $metadata_structure = Parse::CPAN::Meta->load_json_string($json_string);
71 This method deserializes the given string of JSON and the result. If
73 the source was UTF-8 encoded, the string must be decoded before calling
74 "load_json_string".
75 load_string
77 my $metadata_structure = Parse::CPAN::Meta->load_string($some_string);
78 If you don't know whether a string contains YAML or JSON data, this
80 method will use some heuristics and guess. If it can't tell, it
81 assumes YAML.
82 yaml_backend
84 my $backend = Parse::CPAN::Meta->yaml_backend;
85 Returns the module name of the YAML serializer. See "ENVIRONMENT" for
87 details.
88 json_backend
90 my $backend = Parse::CPAN::Meta->json_backend;
91 Returns the module name of the JSON serializer. If
93 "CPAN_META_JSON_BACKEND" is set, this will be whatever that's set to.
94 If not, this will either be JSON::PP or JSON. If "PERL_JSON_BACKEND"
95 is set, this will return JSON as further delegation is handled by the
96 JSON module. See "ENVIRONMENT" for details.
97 json_decoder
99 my $decoder = Parse::CPAN::Meta->json_decoder;
100 Returns the module name of the JSON decoder. Unlike "json_backend",
102 this is not necessarily a full JSON-style module, but only something
103 that will provide a "decode_json" subroutine. If
104 "CPAN_META_JSON_DECODER" is set, this will be whatever that's set to.
105 If not, this will be whatever has been selected as "json_backend". See
106 "ENVIRONMENT" for more notes.
107
109 For maintenance clarity, no functions are exported by default. These
110 functions are available for backwards compatibility only and are best
111 avoided in favor of "load_file".
112 Load
114 my @yaml = Parse::CPAN::Meta::Load( $string );
115 Parses a string containing a valid YAML stream into a list of Perl data
117 structures.
118 LoadFile
120 my @yaml = Parse::CPAN::Meta::LoadFile( 'META.yml' );
121 Reads the YAML stream from a file instead of a string.
123
125 CPAN_META_JSON_DECODER
126 By default, JSON::PP will be used for deserializing JSON data. If the
127 "CPAN_META_JSON_DECODER" environment variable exists, this is expected
128 to be the name of a loadable module that provides a "decode_json"
129 subroutine, which will then be used for deserialization. Relying only
130 on the existence of said subroutine allows for maximum compatibility,
131 since this API is provided by all of JSON::PP, JSON::XS,
132 Cpanel::JSON::XS, JSON::MaybeXS, JSON::Tiny, and Mojo::JSON.
133 CPAN_META_JSON_BACKEND
135 By default, JSON::PP will be used for deserializing JSON data. If the
136 "CPAN_META_JSON_BACKEND" environment variable exists, this is expected
137 to be the name of a loadable module that provides the JSON API, since
138 downstream code expects to be able to call "new" on this class. As
139 such, while JSON::PP, JSON::XS, Cpanel::JSON::XS and JSON::MaybeXS will
140 work for this, to use Mojo::JSON or JSON::Tiny for decoding requires
141 setting "CPAN_META_JSON_DECODER".
142 PERL_JSON_BACKEND
144 If the "CPAN_META_JSON_BACKEND" environment variable does not exist,
145 and if "PERL_JSON_BACKEND" environment variable exists, is true and is
146 not "JSON::PP", then the JSON module (version 2.5 or greater) will be
147 loaded and used to interpret "PERL_JSON_BACKEND". If JSON is not
148 installed or is too old, an exception will be thrown. Note that at the
149 time of writing, the only useful values are 1, which will tell JSON to
150 guess, or JSON::XS - if you want to use a newer JSON module, see
151 "CPAN_META_JSON_BACKEND".
152 PERL_YAML_BACKEND
154 By default, CPAN::Meta::YAML will be used for deserializing YAML data.
155 If the "PERL_YAML_BACKEND" environment variable is defined, then it is
156 interpreted as a module to use for deserialization. The given module
157 must be installed, must load correctly and must implement the "Load()"
158 function or an exception will be thrown.
159
161 • David Golden <dagolden@cpan.org>
162 • Ricardo Signes <rjbs@cpan.org>
164 • Adam Kennedy <adamk@cpan.org>
166
168 This software is copyright (c) 2010 by David Golden, Ricardo Signes,
169 Adam Kennedy and Contributors.
170 This is free software; you can redistribute it and/or modify it under
172 the same terms as the Perl 5 programming language system itself.
173perl v5.36.0 2022-07-22 Parse::CPAN::Meta(3)