Debian Codegraph @

upstream/opensuse-tumbleweed/man3/CPAN::Meta::Requirements.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 "CPAN::Meta::Requirements 3pm"
61 .TH CPAN::Meta::Requirements 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 CPAN::Meta::Requirements \- a set of version requirements for a CPAN dist
68 .SH VERSION
69 .IX Header "VERSION"
70 version 2.143
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& use CPAN::Meta::Requirements;
75 \&
76 \& my $build_requires = CPAN::Meta::Requirements\->new;
77 \&
78 \& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208);
79 \&
80 \& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 2.602);
81 \&
82 \& $build_requires\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq);
83 \&
84 \& $METAyml\->{build_requires} = $build_requires\->as_string_hash;
85 .Ve
86 .SH DESCRIPTION
87 .IX Header "DESCRIPTION"
88 A CPAN::Meta::Requirements object models a set of version constraints like
89 those specified in the \fIMETA.yml\fR or \fIMETA.json\fR files in CPAN distributions,
90 and as defined by CPAN::Meta::Spec.
91 It can be built up by adding more and more constraints, and it will reduce them
92 to the simplest representation.
93 .PP
94 Logically impossible constraints will be identified immediately by thrown
95 exceptions.
96 .SH METHODS
97 .IX Header "METHODS"
98 .SS new
99 .IX Subsection "new"
100 .Vb 1
101 \& my $req = CPAN::Meta::Requirements\->new;
102 .Ve
103 .PP
104 This returns a new CPAN::Meta::Requirements object. It takes an optional
105 hash reference argument. Currently, only one key is supported:
106 .IP \(bu 4
107 \&\f(CW\*(C`bad_version_hook\*(C'\fR \-\- if provided, when a version cannot be parsed into a version object, this code reference will be called with the invalid version string as first argument, and the module name as second argument. It must return a valid version object.
108 .PP
109 All other keys are ignored.
110 .SS add_minimum
111 .IX Subsection "add_minimum"
112 .Vb 1
113 \& $req\->add_minimum( $module => $version );
114 .Ve
115 .PP
116 This adds a new minimum version requirement. If the new requirement is
117 redundant to the existing specification, this has no effect.
118 .PP
119 Minimum requirements are inclusive. \f(CW$version\fR is required, along with any
120 greater version number.
121 .PP
122 This method returns the requirements object.
123 .SS add_maximum
124 .IX Subsection "add_maximum"
125 .Vb 1
126 \& $req\->add_maximum( $module => $version );
127 .Ve
128 .PP
129 This adds a new maximum version requirement. If the new requirement is
130 redundant to the existing specification, this has no effect.
131 .PP
132 Maximum requirements are inclusive. No version strictly greater than the given
133 version is allowed.
134 .PP
135 This method returns the requirements object.
136 .SS add_exclusion
137 .IX Subsection "add_exclusion"
138 .Vb 1
139 \& $req\->add_exclusion( $module => $version );
140 .Ve
141 .PP
142 This adds a new excluded version. For example, you might use these three
143 method calls:
144 .PP
145 .Vb 2
146 \& $req\->add_minimum( $module => \*(Aq1.00\*(Aq );
147 \& $req\->add_maximum( $module => \*(Aq1.82\*(Aq );
148 \&
149 \& $req\->add_exclusion( $module => \*(Aq1.75\*(Aq );
150 .Ve
151 .PP
152 Any version between 1.00 and 1.82 inclusive would be acceptable, except for
153 1.75.
154 .PP
155 This method returns the requirements object.
156 .SS exact_version
157 .IX Subsection "exact_version"
158 .Vb 1
159 \& $req\->exact_version( $module => $version );
160 .Ve
161 .PP
162 This sets the version required for the given module to \fIexactly\fR the given
163 version. No other version would be considered acceptable.
164 .PP
165 This method returns the requirements object.
166 .SS version_range_for_module
167 .IX Subsection "version_range_for_module"
168 .Vb 1
169 \& $req\->version_range_for_module( $another_req_object );
170 .Ve
171 .SS add_requirements
172 .IX Subsection "add_requirements"
173 .Vb 1
174 \& $req\->add_requirements( $another_req_object );
175 .Ve
176 .PP
177 This method adds all the requirements in the given CPAN::Meta::Requirements
178 object to the requirements object on which it was called. If there are any
179 conflicts, an exception is thrown.
180 .PP
181 This method returns the requirements object.
182 .SS accepts_module
183 .IX Subsection "accepts_module"
184 .Vb 1
185 \& my $bool = $req\->accepts_module($module => $version);
186 .Ve
187 .PP
188 Given an module and version, this method returns true if the version
189 specification for the module accepts the provided version. In other words,
190 given:
191 .PP
192 .Vb 1
193 \& Module => \*(Aq>= 1.00, < 2.00\*(Aq
194 .Ve
195 .PP
196 We will accept 1.00 and 1.75 but not 0.50 or 2.00.
197 .PP
198 For modules that do not appear in the requirements, this method will return
199 true.
200 .SS clear_requirement
201 .IX Subsection "clear_requirement"
202 .Vb 1
203 \& $req\->clear_requirement( $module );
204 .Ve
205 .PP
206 This removes the requirement for a given module from the object.
207 .PP
208 This method returns the requirements object.
209 .SS requirements_for_module
210 .IX Subsection "requirements_for_module"
211 .Vb 1
212 \& $req\->requirements_for_module( $module );
213 .Ve
214 .PP
215 This returns a string containing the version requirements for a given module in
216 the format described in CPAN::Meta::Spec or undef if the given module has no
217 requirements. This should only be used for informational purposes such as error
218 messages and should not be interpreted or used for comparison (see
219 "accepts_module" instead).
220 .SS structured_requirements_for_module
221 .IX Subsection "structured_requirements_for_module"
222 .Vb 1
223 \& $req\->structured_requirements_for_module( $module );
224 .Ve
225 .PP
226 This returns a data structure containing the version requirements for a given
227 module or undef if the given module has no requirements. This should
228 not be used for version checks (see "accepts_module" instead).
229 .PP
230 Added in version 2.134.
231 .SS required_modules
232 .IX Subsection "required_modules"
233 This method returns a list of all the modules for which requirements have been
234 specified.
235 .SS clone
236 .IX Subsection "clone"
237 .Vb 1
238 \& $req\->clone;
239 .Ve
240 .PP
241 This method returns a clone of the invocant. The clone and the original object
242 can then be changed independent of one another.
243 .SS is_simple
244 .IX Subsection "is_simple"
245 This method returns true if and only if all requirements are inclusive minimums
246 \&\-\- that is, if their string expression is just the version number.
247 .SS is_finalized
248 .IX Subsection "is_finalized"
249 This method returns true if the requirements have been finalized by having the
250 \&\f(CW\*(C`finalize\*(C'\fR method called on them.
251 .SS finalize
252 .IX Subsection "finalize"
253 This method marks the requirements finalized. Subsequent attempts to change
254 the requirements will be fatal, \fIif\fR they would result in a change. If they
255 would not alter the requirements, they have no effect.
256 .PP
257 If a finalized set of requirements is cloned, the cloned requirements are not
258 also finalized.
259 .SS as_string_hash
260 .IX Subsection "as_string_hash"
261 This returns a reference to a hash describing the requirements using the
262 strings in the CPAN::Meta::Spec specification.
263 .PP
264 For example after the following program:
265 .PP
266 .Vb 1
267 \& my $req = CPAN::Meta::Requirements\->new;
268 \&
269 \& $req\->add_minimum(\*(AqCPAN::Meta::Requirements\*(Aq => 0.102);
270 \&
271 \& $req\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208);
272 \&
273 \& $req\->add_maximum(\*(AqLibrary::Foo\*(Aq => 2.602);
274 \&
275 \& $req\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq);
276 \&
277 \& $req\->add_exclusion(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.8\*(Aq);
278 \&
279 \& $req\->exact_version(\*(AqXyzzy\*(Aq => \*(Aq6.01\*(Aq);
280 \&
281 \& my $hashref = $req\->as_string_hash;
282 .Ve
283 .PP
284 \&\f(CW$hashref\fR would contain:
285 .PP
286 .Vb 6
287 \& {
288 \& \*(AqCPAN::Meta::Requirements\*(Aq => \*(Aq0.102\*(Aq,
289 \& \*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq,
290 \& \*(AqModule::Bar\*(Aq => \*(Aq>= v1.2.3, != v1.2.8\*(Aq,
291 \& \*(AqXyzzy\*(Aq => \*(Aq== 6.01\*(Aq,
292 \& }
293 .Ve
294 .SS add_string_requirement
295 .IX Subsection "add_string_requirement"
296 .Vb 2
297 \& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq);
298 \& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => v1.208);
299 .Ve
300 .PP
301 This method parses the passed in string and adds the appropriate requirement
302 for the given module. A version can be a Perl "v\-string". It understands
303 version ranges as described in the "Version Ranges" in CPAN::Meta::Spec. For
304 example:
305 .IP 1.3 4
306 .IX Item "1.3"
307 .PD 0
308 .IP ">= 1.3" 4
309 .IX Item ">= 1.3"
310 .IP "<= 1.3" 4
311 .IX Item "<= 1.3"
312 .IP "== 1.3" 4
313 .IX Item "== 1.3"
314 .IP "!= 1.3" 4
315 .IX Item "!= 1.3"
316 .IP "> 1.3" 4
317 .IX Item "> 1.3"
318 .IP "< 1.3" 4
319 .IX Item "< 1.3"
320 .IP ">= 1.3, != 1.5, <= 2.0" 4
321 .IX Item ">= 1.3, != 1.5, <= 2.0"
322 .PD
323 A version number without an operator is equivalent to specifying a minimum
324 (\f(CW\*(C`>=\*(C'\fR). Extra whitespace is allowed.
325 .SS from_string_hash
326 .IX Subsection "from_string_hash"
327 .Vb 2
328 \& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash );
329 \& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash, \e%opts );
330 .Ve
331 .PP
332 This is an alternate constructor for a CPAN::Meta::Requirements
333 object. It takes a hash of module names and version requirement
334 strings and returns a new CPAN::Meta::Requirements object. As with
335 add_string_requirement, a version can be a Perl "v\-string". Optionally,
336 you can supply a hash\-reference of options, exactly as with the "new"
337 method.
338 .SH SUPPORT
339 .IX Header "SUPPORT"
340 .SS "Bugs / Feature Requests"
341 .IX Subsection "Bugs / Feature Requests"
342 Please report any bugs or feature requests through the issue tracker
343 at <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements/issues>.
344 You will be notified automatically of any progress on your issue.
345 .SS "Source Code"
346 .IX Subsection "Source Code"
347 This is open source software. The code repository is available for
348 public review and contribution under the terms of the license.
349 .PP
350 <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements>
351 .PP
352 .Vb 1
353 \& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements.git
354 .Ve
355 .SH AUTHORS
356 .IX Header "AUTHORS"
357 .IP \(bu 4
358 David Golden <[email protected]>
359 .IP \(bu 4
360 Ricardo Signes <[email protected]>
361 .SH CONTRIBUTORS
362 .IX Header "CONTRIBUTORS"
363 .IP \(bu 4
364 Ed J <[email protected]>
365 .IP \(bu 4
366 Graham Knop <[email protected]>
367 .IP \(bu 4
368 Karen Etheridge <[email protected]>
369 .IP \(bu 4
370 Leon Timmermans <[email protected]>
371 .IP \(bu 4
372 Paul Howarth <paul@city\-fan.org>
373 .IP \(bu 4
374 Ricardo Signes <[email protected]>
375 .IP \(bu 4
376 robario <[email protected]>
377 .IP \(bu 4
378 Tatsuhiko Miyagawa <[email protected]>
379 .IP \(bu 4
380 Tatsuhiko Miyagawa <[email protected]>
381 .SH "COPYRIGHT AND LICENSE"
382 .IX Header "COPYRIGHT AND LICENSE"
383 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
384 .PP
385 This is free software; you can redistribute it and/or modify it under
386 the same terms as the Perl 5 programming language system itself.