Debian Codegraph @

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