Debian Codegraph @

upstream/debian-unstable/man3/Parse::CPAN::Meta.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Parse::CPAN::Meta 3perl"
58 .TH Parse::CPAN::Meta 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Parse::CPAN::Meta \- Parse META.yml and META.json CPAN metadata files
65 .SH VERSION
66 .IX Header "VERSION"
67 version 2.150010
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 2
71 \& #############################################
72 \& # In your file
73 \&
74 \& \-\-\-
75 \& name: My\-Distribution
76 \& version: 1.23
77 \& resources:
78 \& homepage: "http://example.com/dist/My\-Distribution"
79 \&
80 \&
81 \& #############################################
82 \& # In your program
83 \&
84 \& use Parse::CPAN::Meta;
85 \&
86 \& my $distmeta = Parse::CPAN::Meta\->load_file(\*(AqMETA.yml\*(Aq);
87 \&
88 \& # Reading properties
89 \& my $name = $distmeta\->{name};
90 \& my $version = $distmeta\->{version};
91 \& my $homepage = $distmeta\->{resources}{homepage};
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 \&\fBParse::CPAN::Meta\fR is a parser for \fIMETA.json\fR and \fIMETA.yml\fR files, using
96 JSON::PP and/or CPAN::Meta::YAML.
97 .PP
98 \&\fBParse::CPAN::Meta\fR provides three methods: \f(CW\*(C`load_file\*(C'\fR, \f(CW\*(C`load_json_string\*(C'\fR,
99 and \f(CW\*(C`load_yaml_string\*(C'\fR. These will read and deserialize CPAN metafiles, and
100 are described below in detail.
101 .PP
102 \&\fBParse::CPAN::Meta\fR provides a legacy API of only two functions,
103 based on the YAML functions of the same name. Wherever possible,
104 identical calling semantics are used. These may only be used with YAML sources.
105 .PP
106 All error reporting is done with exceptions (die'ing).
107 .PP
108 Note that META files are expected to be in UTF\-8 encoding, only. When
109 converted string data, it must first be decoded from UTF\-8.
110 .SH METHODS
111 .IX Header "METHODS"
112 .SS load_file
113 .IX Subsection "load_file"
114 .Vb 1
115 \& my $metadata_structure = Parse::CPAN::Meta\->load_file(\*(AqMETA.json\*(Aq);
116 \&
117 \& my $metadata_structure = Parse::CPAN::Meta\->load_file(\*(AqMETA.yml\*(Aq);
118 .Ve
119 .PP
120 This method will read the named file and deserialize it to a data structure,
121 determining whether it should be JSON or YAML based on the filename.
122 The file will be read using the ":utf8" IO layer.
123 .SS load_yaml_string
124 .IX Subsection "load_yaml_string"
125 .Vb 1
126 \& my $metadata_structure = Parse::CPAN::Meta\->load_yaml_string($yaml_string);
127 .Ve
128 .PP
129 This method deserializes the given string of YAML and returns the first
130 document in it. (CPAN metadata files should always have only one document.)
131 If the source was UTF\-8 encoded, the string must be decoded before calling
132 \&\f(CW\*(C`load_yaml_string\*(C'\fR.
133 .SS load_json_string
134 .IX Subsection "load_json_string"
135 .Vb 1
136 \& my $metadata_structure = Parse::CPAN::Meta\->load_json_string($json_string);
137 .Ve
138 .PP
139 This method deserializes the given string of JSON and the result.
140 If the source was UTF\-8 encoded, the string must be decoded before calling
141 \&\f(CW\*(C`load_json_string\*(C'\fR.
142 .SS load_string
143 .IX Subsection "load_string"
144 .Vb 1
145 \& my $metadata_structure = Parse::CPAN::Meta\->load_string($some_string);
146 .Ve
147 .PP
148 If you don't know whether a string contains YAML or JSON data, this method
149 will use some heuristics and guess. If it can't tell, it assumes YAML.
150 .SS yaml_backend
151 .IX Subsection "yaml_backend"
152 .Vb 1
153 \& my $backend = Parse::CPAN::Meta\->yaml_backend;
154 .Ve
155 .PP
156 Returns the module name of the YAML serializer. See "ENVIRONMENT"
157 for details.
158 .SS json_backend
159 .IX Subsection "json_backend"
160 .Vb 1
161 \& my $backend = Parse::CPAN::Meta\->json_backend;
162 .Ve
163 .PP
164 Returns the module name of the JSON serializer. If \f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR
165 is set, this will be whatever that's set to. If not, this will either
166 be JSON::PP or JSON. If \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR is set,
167 this will return JSON as further delegation is handled by
168 the JSON module. See "ENVIRONMENT" for details.
169 .SS json_decoder
170 .IX Subsection "json_decoder"
171 .Vb 1
172 \& my $decoder = Parse::CPAN::Meta\->json_decoder;
173 .Ve
174 .PP
175 Returns the module name of the JSON decoder. Unlike "json_backend", this
176 is not necessarily a full JSON\-style module, but only something that will
177 provide a \f(CW\*(C`decode_json\*(C'\fR subroutine. If \f(CW\*(C`CPAN_META_JSON_DECODER\*(C'\fR is set,
178 this will be whatever that's set to. If not, this will be whatever has
179 been selected as "json_backend". See "ENVIRONMENT" for more notes.
180 .SH FUNCTIONS
181 .IX Header "FUNCTIONS"
182 For maintenance clarity, no functions are exported by default. These functions
183 are available for backwards compatibility only and are best avoided in favor of
184 \&\f(CW\*(C`load_file\*(C'\fR.
185 .SS Load
186 .IX Subsection "Load"
187 .Vb 1
188 \& my @yaml = Parse::CPAN::Meta::Load( $string );
189 .Ve
190 .PP
191 Parses a string containing a valid YAML stream into a list of Perl data
192 structures.
193 .SS LoadFile
194 .IX Subsection "LoadFile"
195 .Vb 1
196 \& my @yaml = Parse::CPAN::Meta::LoadFile( \*(AqMETA.yml\*(Aq );
197 .Ve
198 .PP
199 Reads the YAML stream from a file instead of a string.
200 .SH ENVIRONMENT
201 .IX Header "ENVIRONMENT"
202 .SS CPAN_META_JSON_DECODER
203 .IX Subsection "CPAN_META_JSON_DECODER"
204 By default, JSON::PP will be used for deserializing JSON data. If the
205 \&\f(CW\*(C`CPAN_META_JSON_DECODER\*(C'\fR environment variable exists, this is expected to
206 be the name of a loadable module that provides a \f(CW\*(C`decode_json\*(C'\fR subroutine,
207 which will then be used for deserialization. Relying only on the existence
208 of said subroutine allows for maximum compatibility, since this API is
209 provided by all of JSON::PP, JSON::XS, Cpanel::JSON::XS,
210 JSON::MaybeXS, JSON::Tiny, and Mojo::JSON.
211 .SS CPAN_META_JSON_BACKEND
212 .IX Subsection "CPAN_META_JSON_BACKEND"
213 By default, JSON::PP will be used for deserializing JSON data. If the
214 \&\f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR environment variable exists, this is expected to
215 be the name of a loadable module that provides the JSON API, since
216 downstream code expects to be able to call \f(CW\*(C`new\*(C'\fR on this class. As such,
217 while JSON::PP, JSON::XS, Cpanel::JSON::XS and JSON::MaybeXS will
218 work for this, to use Mojo::JSON or JSON::Tiny for decoding requires
219 setting "CPAN_META_JSON_DECODER".
220 .SS PERL_JSON_BACKEND
221 .IX Subsection "PERL_JSON_BACKEND"
222 If the \f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR environment variable does not exist, and if
223 \&\f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR environment variable exists, is true and is not
224 "JSON::PP", then the JSON module (version 2.5 or greater) will be loaded and
225 used to interpret \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR. If JSON is not installed or is too
226 old, an exception will be thrown. Note that at the time of writing, the only
227 useful values are 1, which will tell JSON to guess, or JSON::XS \- if
228 you want to use a newer JSON module, see "CPAN_META_JSON_BACKEND".
229 .SS PERL_YAML_BACKEND
230 .IX Subsection "PERL_YAML_BACKEND"
231 By default, CPAN::Meta::YAML will be used for deserializing YAML data. If
232 the \f(CW\*(C`PERL_YAML_BACKEND\*(C'\fR environment variable is defined, then it is interpreted
233 as a module to use for deserialization. The given module must be installed,
234 must load correctly and must implement the \f(CWLoad()\fR function or an exception
235 will be thrown.
236 .SH AUTHORS
237 .IX Header "AUTHORS"
238 .IP \(bu 4
239 David Golden <[email protected]>
240 .IP \(bu 4
241 Ricardo Signes <[email protected]>
242 .IP \(bu 4
243 Adam Kennedy <[email protected]>
244 .SH "COPYRIGHT AND LICENSE"
245 .IX Header "COPYRIGHT AND LICENSE"
246 This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
247 .PP
248 This is free software; you can redistribute it and/or modify it under
249 the same terms as the Perl 5 programming language system itself.