README
1NAME
2 CPAN::Meta::Requirements - a set of version requirements for a CPAN dist
3
4VERSION
5 version 2.140
6
7SYNOPSIS
8 use CPAN::Meta::Requirements;
9
10 my $build_requires = CPAN::Meta::Requirements->new;
11
12 $build_requires->add_minimum('Library::Foo' => 1.208);
13
14 $build_requires->add_minimum('Library::Foo' => 2.602);
15
16 $build_requires->add_minimum('Module::Bar' => 'v1.2.3');
17
18 $METAyml->{build_requires} = $build_requires->as_string_hash;
19
20DESCRIPTION
21 A CPAN::Meta::Requirements object models a set of version constraints
22 like those specified in the META.yml or META.json files in CPAN
23 distributions, and as defined by CPAN::Meta::Spec; It can be built up by
24 adding more and more constraints, and it will reduce them to the
25 simplest representation.
26
27 Logically impossible constraints will be identified immediately by
28 thrown exceptions.
29
30METHODS
31 new
32 my $req = CPAN::Meta::Requirements->new;
33
34 This returns a new CPAN::Meta::Requirements object. It takes an optional
35 hash reference argument. Currently, only one key is supported:
36
37 * "bad_version_hook" -- if provided, when a version cannot be parsed
38 into a version object, this code reference will be called with the
39 invalid version string as first argument, and the module name as
40 second argument. It must return a valid version object.
41
42 All other keys are ignored.
43
44 add_minimum
45 $req->add_minimum( $module => $version );
46
47 This adds a new minimum version requirement. If the new requirement is
48 redundant to the existing specification, this has no effect.
49
50 Minimum requirements are inclusive. $version is required, along with any
51 greater version number.
52
53 This method returns the requirements object.
54
55 add_maximum
56 $req->add_maximum( $module => $version );
57
58 This adds a new maximum version requirement. If the new requirement is
59 redundant to the existing specification, this has no effect.
60
61 Maximum requirements are inclusive. No version strictly greater than the
62 given version is allowed.
63
64 This method returns the requirements object.
65
66 add_exclusion
67 $req->add_exclusion( $module => $version );
68
69 This adds a new excluded version. For example, you might use these three
70 method calls:
71
72 $req->add_minimum( $module => '1.00' );
73 $req->add_maximum( $module => '1.82' );
74
75 $req->add_exclusion( $module => '1.75' );
76
77 Any version between 1.00 and 1.82 inclusive would be acceptable, except
78 for 1.75.
79
80 This method returns the requirements object.
81
82 exact_version
83 $req->exact_version( $module => $version );
84
85 This sets the version required for the given module to *exactly* the
86 given version. No other version would be considered acceptable.
87
88 This method returns the requirements object.
89
90 add_requirements
91 $req->add_requirements( $another_req_object );
92
93 This method adds all the requirements in the given
94 CPAN::Meta::Requirements object to the requirements object on which it
95 was called. If there are any conflicts, an exception is thrown.
96
97 This method returns the requirements object.
98
99 accepts_module
100 my $bool = $req->accepts_module($module => $version);
101
102 Given an module and version, this method returns true if the version
103 specification for the module accepts the provided version. In other
104 words, given:
105
106 Module => '>= 1.00, < 2.00'
107
108 We will accept 1.00 and 1.75 but not 0.50 or 2.00.
109
110 For modules that do not appear in the requirements, this method will
111 return true.
112
113 clear_requirement
114 $req->clear_requirement( $module );
115
116 This removes the requirement for a given module from the object.
117
118 This method returns the requirements object.
119
120 requirements_for_module
121 $req->requirements_for_module( $module );
122
123 This returns a string containing the version requirements for a given
124 module in the format described in CPAN::Meta::Spec or undef if the given
125 module has no requirements. This should only be used for informational
126 purposes such as error messages and should not be interpreted or used
127 for comparison (see "accepts_module" instead).
128
129 structured_requirements_for_module
130 $req->structured_requirements_for_module( $module );
131
132 This returns a data structure containing the version requirements for a
133 given module or undef if the given module has no requirements. This
134 should not be used for version checks (see "accepts_module" instead).
135
136 Added in version 2.134.
137
138 required_modules
139 This method returns a list of all the modules for which requirements
140 have been specified.
141
142 clone
143 $req->clone;
144
145 This method returns a clone of the invocant. The clone and the original
146 object can then be changed independent of one another.
147
148 is_simple
149 This method returns true if and only if all requirements are inclusive
150 minimums -- that is, if their string expression is just the version
151 number.
152
153 is_finalized
154 This method returns true if the requirements have been finalized by
155 having the "finalize" method called on them.
156
157 finalize
158 This method marks the requirements finalized. Subsequent attempts to
159 change the requirements will be fatal, *if* they would result in a
160 change. If they would not alter the requirements, they have no effect.
161
162 If a finalized set of requirements is cloned, the cloned requirements
163 are not also finalized.
164
165 as_string_hash
166 This returns a reference to a hash describing the requirements using the
167 strings in the CPAN::Meta::Spec specification.
168
169 For example after the following program:
170
171 my $req = CPAN::Meta::Requirements->new;
172
173 $req->add_minimum('CPAN::Meta::Requirements' => 0.102);
174
175 $req->add_minimum('Library::Foo' => 1.208);
176
177 $req->add_maximum('Library::Foo' => 2.602);
178
179 $req->add_minimum('Module::Bar' => 'v1.2.3');
180
181 $req->add_exclusion('Module::Bar' => 'v1.2.8');
182
183 $req->exact_version('Xyzzy' => '6.01');
184
185 my $hashref = $req->as_string_hash;
186
187 $hashref would contain:
188
189 {
190 'CPAN::Meta::Requirements' => '0.102',
191 'Library::Foo' => '>= 1.208, <= 2.206',
192 'Module::Bar' => '>= v1.2.3, != v1.2.8',
193 'Xyzzy' => '== 6.01',
194 }
195
196 add_string_requirement
197 $req->add_string_requirement('Library::Foo' => '>= 1.208, <= 2.206');
198 $req->add_string_requirement('Library::Foo' => v1.208);
199
200 This method parses the passed in string and adds the appropriate
201 requirement for the given module. A version can be a Perl "v-string". It
202 understands version ranges as described in the "Version Ranges" in
203 CPAN::Meta::Spec. For example:
204
205 1.3
206 >= 1.3
207 <= 1.3
208 == 1.3
209 != 1.3
210 > 1.3
211 < 1.3
212 >= 1.3, != 1.5, <= 2.0
213 A version number without an operator is equivalent to specifying a
214 minimum (">="). Extra whitespace is allowed.
215
216 from_string_hash
217 my $req = CPAN::Meta::Requirements->from_string_hash( \%hash );
218 my $req = CPAN::Meta::Requirements->from_string_hash( \%hash, \%opts );
219
220 This is an alternate constructor for a CPAN::Meta::Requirements object.
221 It takes a hash of module names and version requirement strings and
222 returns a new CPAN::Meta::Requirements object. As with
223 add_string_requirement, a version can be a Perl "v-string". Optionally,
224 you can supply a hash-reference of options, exactly as with the "new"
225 method.
226
227SUPPORT
228 Bugs / Feature Requests
229 Please report any bugs or feature requests through the issue tracker at
230 <https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements/issues>.
231 You will be notified automatically of any progress on your issue.
232
233 Source Code
234 This is open source software. The code repository is available for
235 public review and contribution under the terms of the license.
236
237 <https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements>
238
239 git clone https://github.com/Perl-Toolchain-Gang/CPAN-Meta-Requirements.git
240
241AUTHORS
242 * David Golden <dagolden@cpan.org>
243
244 * Ricardo Signes <rjbs@cpan.org>
245
246CONTRIBUTORS
247 * Ed J <mohawk2@users.noreply.github.com>
248
249 * Karen Etheridge <ether@cpan.org>
250
251 * Leon Timmermans <fawaka@gmail.com>
252
253 * robario <webmaster@robario.com>
254
255COPYRIGHT AND LICENSE
256 This software is copyright (c) 2010 by David Golden and Ricardo Signes.
257
258 This is free software; you can redistribute it and/or modify it under
259 the same terms as the Perl 5 programming language system itself.
260
261