Debian Codegraph @

upstream/opensuse-tumbleweed/man3/CPAN::Meta::Requirements::Range.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::Range 3pm"
61 .TH CPAN::Meta::Requirements::Range 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::Range \- 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::Range;
75 \&
76 \& my $range = CPAN::Meta::Requirements::Range\->with_minimum(1);
77 \&
78 \& $range = $range\->with_maximum(\*(Aqv2.2\*(Aq);
79 \&
80 \& my $stringified = $range\->as_string;
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 A CPAN::Meta::Requirements::Range object models a set of version constraints like
85 those specified in the \fIMETA.yml\fR or \fIMETA.json\fR files in CPAN distributions,
86 and as defined by CPAN::Meta::Spec;
87 It can be built up by adding more and more constraints, and it will reduce them
88 to the simplest representation.
89 .PP
90 Logically impossible constraints will be identified immediately by thrown
91 exceptions.
92 .SH METHODS
93 .IX Header "METHODS"
94 .SS with_string_requirement
95 .IX Subsection "with_string_requirement"
96 .Vb 2
97 \& $req\->with_string_requirement(\*(Aq>= 1.208, <= 2.206\*(Aq);
98 \& $req\->with_string_requirement(v1.208);
99 .Ve
100 .PP
101 This method parses the passed in string and adds the appropriate requirement.
102 A version can be a Perl "v\-string". It understands version ranges as described
103 in the "Version Ranges" in CPAN::Meta::Spec. For example:
104 .IP 1.3 4
105 .IX Item "1.3"
106 .PD 0
107 .IP ">= 1.3" 4
108 .IX Item ">= 1.3"
109 .IP "<= 1.3" 4
110 .IX Item "<= 1.3"
111 .IP "== 1.3" 4
112 .IX Item "== 1.3"
113 .IP "!= 1.3" 4
114 .IX Item "!= 1.3"
115 .IP "> 1.3" 4
116 .IX Item "> 1.3"
117 .IP "< 1.3" 4
118 .IX Item "< 1.3"
119 .IP ">= 1.3, != 1.5, <= 2.0" 4
120 .IX Item ">= 1.3, != 1.5, <= 2.0"
121 .PD
122 A version number without an operator is equivalent to specifying a minimum
123 (\f(CW\*(C`>=\*(C'\fR). Extra whitespace is allowed.
124 .SS with_range
125 .IX Subsection "with_range"
126 .Vb 1
127 \& $range\->with_range($other_range)
128 .Ve
129 .PP
130 This creates a new range object that is a merge two others.
131 .SS with_exact_version
132 .IX Subsection "with_exact_version"
133 .Vb 1
134 \& $range\->with_exact_version( $version );
135 .Ve
136 .PP
137 This sets the version required to \fIexactly\fR the given
138 version. No other version would be considered acceptable.
139 .PP
140 This method returns the version range object.
141 .SS with_minimum
142 .IX Subsection "with_minimum"
143 .Vb 1
144 \& $range\->with_minimum( $version );
145 .Ve
146 .PP
147 This adds a new minimum version requirement. If the new requirement is
148 redundant to the existing specification, this has no effect.
149 .PP
150 Minimum requirements are inclusive. \f(CW$version\fR is required, along with any
151 greater version number.
152 .PP
153 This method returns the version range object.
154 .SS with_maximum
155 .IX Subsection "with_maximum"
156 .Vb 1
157 \& $range\->with_maximum( $version );
158 .Ve
159 .PP
160 This adds a new maximum version requirement. If the new requirement is
161 redundant to the existing specification, this has no effect.
162 .PP
163 Maximum requirements are inclusive. No version strictly greater than the given
164 version is allowed.
165 .PP
166 This method returns the version range object.
167 .SS with_exclusion
168 .IX Subsection "with_exclusion"
169 .Vb 1
170 \& $range\->with_exclusion( $version );
171 .Ve
172 .PP
173 This adds a new excluded version. For example, you might use these three
174 method calls:
175 .PP
176 .Vb 2
177 \& $range\->with_minimum( \*(Aq1.00\*(Aq );
178 \& $range\->with_maximum( \*(Aq1.82\*(Aq );
179 \&
180 \& $range\->with_exclusion( \*(Aq1.75\*(Aq );
181 .Ve
182 .PP
183 Any version between 1.00 and 1.82 inclusive would be acceptable, except for
184 1.75.
185 .PP
186 This method returns the requirements object.
187 .SS as_struct
188 .IX Subsection "as_struct"
189 .Vb 1
190 \& $range\->as_struct( $module );
191 .Ve
192 .PP
193 This returns a data structure containing the version requirements. This should
194 not be used for version checks (see "accepts_module" instead).
195 .SS as_string
196 .IX Subsection "as_string"
197 .Vb 1
198 \& $range\->as_string;
199 .Ve
200 .PP
201 This returns a string containing the version requirements in the format
202 described in CPAN::Meta::Spec. This should only be used for informational
203 purposes such as error messages and should not be interpreted or used for
204 comparison (see "accepts" instead).
205 .SS accepts
206 .IX Subsection "accepts"
207 .Vb 1
208 \& my $bool = $range\->accepts($version);
209 .Ve
210 .PP
211 Given a version, this method returns true if the version specification
212 accepts the provided version. In other words, given:
213 .PP
214 .Vb 1
215 \& \*(Aq>= 1.00, < 2.00\*(Aq
216 .Ve
217 .PP
218 We will accept 1.00 and 1.75 but not 0.50 or 2.00.
219 .SS is_simple
220 .IX Subsection "is_simple"
221 This method returns true if and only if the range is an inclusive minimum
222 \&\-\- that is, if their string expression is just the version number.
223 .SH AUTHORS
224 .IX Header "AUTHORS"
225 .IP \(bu 4
226 David Golden <[email protected]>
227 .IP \(bu 4
228 Ricardo Signes <[email protected]>
229 .SH "COPYRIGHT AND LICENSE"
230 .IX Header "COPYRIGHT AND LICENSE"
231 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
232 .PP
233 This is free software; you can redistribute it and/or modify it under
234 the same terms as the Perl 5 programming language system itself.