Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Parse::CPAN::Meta.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Parse::CPAN::Meta 3pm"
61 .TH Parse::CPAN::Meta 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Parse::CPAN::Meta \- Parse META.yml and META.json CPAN metadata files
68 .SH VERSION
69 .IX Header "VERSION"
70 version 2.150010
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& #############################################
75 \& # In your file
76 \&
77 \& \-\-\-
78 \& name: My\-Distribution
79 \& version: 1.23
80 \& resources:
81 \& homepage: "http://example.com/dist/My\-Distribution"
82 \&
83 \&
84 \& #############################################
85 \& # In your program
86 \&
87 \& use Parse::CPAN::Meta;
88 \&
89 \& my $distmeta = Parse::CPAN::Meta\->load_file(\*(AqMETA.yml\*(Aq);
90 \&
91 \& # Reading properties
92 \& my $name = $distmeta\->{name};
93 \& my $version = $distmeta\->{version};
94 \& my $homepage = $distmeta\->{resources}{homepage};
95 .Ve
96 .SH DESCRIPTION
97 .IX Header "DESCRIPTION"
98 \&\fBParse::CPAN::Meta\fR is a parser for \fIMETA.json\fR and \fIMETA.yml\fR files, using
99 JSON::PP and/or CPAN::Meta::YAML.
100 .PP
101 \&\fBParse::CPAN::Meta\fR provides three methods: \f(CW\*(C`load_file\*(C'\fR, \f(CW\*(C`load_json_string\*(C'\fR,
102 and \f(CW\*(C`load_yaml_string\*(C'\fR. These will read and deserialize CPAN metafiles, and
103 are described below in detail.
104 .PP
105 \&\fBParse::CPAN::Meta\fR provides a legacy API of only two functions,
106 based on the YAML functions of the same name. Wherever possible,
107 identical calling semantics are used. These may only be used with YAML sources.
108 .PP
109 All error reporting is done with exceptions (die\*(Aqing).
110 .PP
111 Note that META files are expected to be in UTF\-8 encoding, only. When
112 converted string data, it must first be decoded from UTF\-8.
113 .SH METHODS
114 .IX Header "METHODS"
115 .SS load_file
116 .IX Subsection "load_file"
117 .Vb 1
118 \& my $metadata_structure = Parse::CPAN::Meta\->load_file(\*(AqMETA.json\*(Aq);
119 \&
120 \& my $metadata_structure = Parse::CPAN::Meta\->load_file(\*(AqMETA.yml\*(Aq);
121 .Ve
122 .PP
123 This method will read the named file and deserialize it to a data structure,
124 determining whether it should be JSON or YAML based on the filename.
125 The file will be read using the ":utf8" IO layer.
126 .SS load_yaml_string
127 .IX Subsection "load_yaml_string"
128 .Vb 1
129 \& my $metadata_structure = Parse::CPAN::Meta\->load_yaml_string($yaml_string);
130 .Ve
131 .PP
132 This method deserializes the given string of YAML and returns the first
133 document in it. (CPAN metadata files should always have only one document.)
134 If the source was UTF\-8 encoded, the string must be decoded before calling
135 \&\f(CW\*(C`load_yaml_string\*(C'\fR.
136 .SS load_json_string
137 .IX Subsection "load_json_string"
138 .Vb 1
139 \& my $metadata_structure = Parse::CPAN::Meta\->load_json_string($json_string);
140 .Ve
141 .PP
142 This method deserializes the given string of JSON and the result.
143 If the source was UTF\-8 encoded, the string must be decoded before calling
144 \&\f(CW\*(C`load_json_string\*(C'\fR.
145 .SS load_string
146 .IX Subsection "load_string"
147 .Vb 1
148 \& my $metadata_structure = Parse::CPAN::Meta\->load_string($some_string);
149 .Ve
150 .PP
151 If you don\*(Aqt know whether a string contains YAML or JSON data, this method
152 will use some heuristics and guess. If it can\*(Aqt tell, it assumes YAML.
153 .SS yaml_backend
154 .IX Subsection "yaml_backend"
155 .Vb 1
156 \& my $backend = Parse::CPAN::Meta\->yaml_backend;
157 .Ve
158 .PP
159 Returns the module name of the YAML serializer. See "ENVIRONMENT"
160 for details.
161 .SS json_backend
162 .IX Subsection "json_backend"
163 .Vb 1
164 \& my $backend = Parse::CPAN::Meta\->json_backend;
165 .Ve
166 .PP
167 Returns the module name of the JSON serializer. If \f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR
168 is set, this will be whatever that\*(Aqs set to. If not, this will either
169 be JSON::PP or JSON. If \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR is set,
170 this will return JSON as further delegation is handled by
171 the JSON module. See "ENVIRONMENT" for details.
172 .SS json_decoder
173 .IX Subsection "json_decoder"
174 .Vb 1
175 \& my $decoder = Parse::CPAN::Meta\->json_decoder;
176 .Ve
177 .PP
178 Returns the module name of the JSON decoder. Unlike "json_backend", this
179 is not necessarily a full JSON\-style module, but only something that will
180 provide a \f(CW\*(C`decode_json\*(C'\fR subroutine. If \f(CW\*(C`CPAN_META_JSON_DECODER\*(C'\fR is set,
181 this will be whatever that\*(Aqs set to. If not, this will be whatever has
182 been selected as "json_backend". See "ENVIRONMENT" for more notes.
183 .SH FUNCTIONS
184 .IX Header "FUNCTIONS"
185 For maintenance clarity, no functions are exported by default. These functions
186 are available for backwards compatibility only and are best avoided in favor of
187 \&\f(CW\*(C`load_file\*(C'\fR.
188 .SS Load
189 .IX Subsection "Load"
190 .Vb 1
191 \& my @yaml = Parse::CPAN::Meta::Load( $string );
192 .Ve
193 .PP
194 Parses a string containing a valid YAML stream into a list of Perl data
195 structures.
196 .SS LoadFile
197 .IX Subsection "LoadFile"
198 .Vb 1
199 \& my @yaml = Parse::CPAN::Meta::LoadFile( \*(AqMETA.yml\*(Aq );
200 .Ve
201 .PP
202 Reads the YAML stream from a file instead of a string.
203 .SH ENVIRONMENT
204 .IX Header "ENVIRONMENT"
205 .SS CPAN_META_JSON_DECODER
206 .IX Subsection "CPAN_META_JSON_DECODER"
207 By default, JSON::PP will be used for deserializing JSON data. If the
208 \&\f(CW\*(C`CPAN_META_JSON_DECODER\*(C'\fR environment variable exists, this is expected to
209 be the name of a loadable module that provides a \f(CW\*(C`decode_json\*(C'\fR subroutine,
210 which will then be used for deserialization. Relying only on the existence
211 of said subroutine allows for maximum compatibility, since this API is
212 provided by all of JSON::PP, JSON::XS, Cpanel::JSON::XS,
213 JSON::MaybeXS, JSON::Tiny, and Mojo::JSON.
214 .SS CPAN_META_JSON_BACKEND
215 .IX Subsection "CPAN_META_JSON_BACKEND"
216 By default, JSON::PP will be used for deserializing JSON data. If the
217 \&\f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR environment variable exists, this is expected to
218 be the name of a loadable module that provides the JSON API, since
219 downstream code expects to be able to call \f(CW\*(C`new\*(C'\fR on this class. As such,
220 while JSON::PP, JSON::XS, Cpanel::JSON::XS and JSON::MaybeXS will
221 work for this, to use Mojo::JSON or JSON::Tiny for decoding requires
222 setting "CPAN_META_JSON_DECODER".
223 .SS PERL_JSON_BACKEND
224 .IX Subsection "PERL_JSON_BACKEND"
225 If the \f(CW\*(C`CPAN_META_JSON_BACKEND\*(C'\fR environment variable does not exist, and if
226 \&\f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR environment variable exists, is true and is not
227 "JSON::PP", then the JSON module (version 2.5 or greater) will be loaded and
228 used to interpret \f(CW\*(C`PERL_JSON_BACKEND\*(C'\fR. If JSON is not installed or is too
229 old, an exception will be thrown. Note that at the time of writing, the only
230 useful values are 1, which will tell JSON to guess, or JSON::XS \- if
231 you want to use a newer JSON module, see "CPAN_META_JSON_BACKEND".
232 .SS PERL_YAML_BACKEND
233 .IX Subsection "PERL_YAML_BACKEND"
234 By default, CPAN::Meta::YAML will be used for deserializing YAML data. If
235 the \f(CW\*(C`PERL_YAML_BACKEND\*(C'\fR environment variable is defined, then it is interpreted
236 as a module to use for deserialization. The given module must be installed,
237 must load correctly and must implement the \f(CWLoad()\fR function or an exception
238 will be thrown.
239 .SH AUTHORS
240 .IX Header "AUTHORS"
241 .IP \(bu 4
242 David Golden <[email protected]>
243 .IP \(bu 4
244 Ricardo Signes <[email protected]>
245 .IP \(bu 4
246 Adam Kennedy <[email protected]>
247 .SH "COPYRIGHT AND LICENSE"
248 .IX Header "COPYRIGHT AND LICENSE"
249 This software is copyright (c) 2010 by David Golden, Ricardo Signes, Adam Kennedy and Contributors.
250 .PP
251 This is free software; you can redistribute it and/or modify it under
252 the same terms as the Perl 5 programming language system itself.