diff options
Diffstat (limited to 'upstream/debian-unstable/man3/CPAN::Meta::Requirements.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/CPAN::Meta::Requirements.3perl | 368 |
1 files changed, 368 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/CPAN::Meta::Requirements.3perl b/upstream/debian-unstable/man3/CPAN::Meta::Requirements.3perl new file mode 100644 index 00000000..120dc28e --- /dev/null +++ b/upstream/debian-unstable/man3/CPAN::Meta::Requirements.3perl @@ -0,0 +1,368 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "CPAN::Meta::Requirements 3perl" +.TH CPAN::Meta::Requirements 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +CPAN::Meta::Requirements \- a set of version requirements for a CPAN dist +.SH VERSION +.IX Header "VERSION" +version 2.140 +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use CPAN::Meta::Requirements; +\& +\& my $build_requires = CPAN::Meta::Requirements\->new; +\& +\& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208); +\& +\& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 2.602); +\& +\& $build_requires\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq); +\& +\& $METAyml\->{build_requires} = $build_requires\->as_string_hash; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +A CPAN::Meta::Requirements object models a set of version constraints like +those specified in the \fIMETA.yml\fR or \fIMETA.json\fR files in CPAN distributions, +and as defined by CPAN::Meta::Spec; +It can be built up by adding more and more constraints, and it will reduce them +to the simplest representation. +.PP +Logically impossible constraints will be identified immediately by thrown +exceptions. +.SH METHODS +.IX Header "METHODS" +.SS new +.IX Subsection "new" +.Vb 1 +\& my $req = CPAN::Meta::Requirements\->new; +.Ve +.PP +This returns a new CPAN::Meta::Requirements object. It takes an optional +hash reference argument. Currently, only one key is supported: +.IP \(bu 4 +\&\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. +.PP +All other keys are ignored. +.SS add_minimum +.IX Subsection "add_minimum" +.Vb 1 +\& $req\->add_minimum( $module => $version ); +.Ve +.PP +This adds a new minimum version requirement. If the new requirement is +redundant to the existing specification, this has no effect. +.PP +Minimum requirements are inclusive. \f(CW$version\fR is required, along with any +greater version number. +.PP +This method returns the requirements object. +.SS add_maximum +.IX Subsection "add_maximum" +.Vb 1 +\& $req\->add_maximum( $module => $version ); +.Ve +.PP +This adds a new maximum version requirement. If the new requirement is +redundant to the existing specification, this has no effect. +.PP +Maximum requirements are inclusive. No version strictly greater than the given +version is allowed. +.PP +This method returns the requirements object. +.SS add_exclusion +.IX Subsection "add_exclusion" +.Vb 1 +\& $req\->add_exclusion( $module => $version ); +.Ve +.PP +This adds a new excluded version. For example, you might use these three +method calls: +.PP +.Vb 2 +\& $req\->add_minimum( $module => \*(Aq1.00\*(Aq ); +\& $req\->add_maximum( $module => \*(Aq1.82\*(Aq ); +\& +\& $req\->add_exclusion( $module => \*(Aq1.75\*(Aq ); +.Ve +.PP +Any version between 1.00 and 1.82 inclusive would be acceptable, except for +1.75. +.PP +This method returns the requirements object. +.SS exact_version +.IX Subsection "exact_version" +.Vb 1 +\& $req\->exact_version( $module => $version ); +.Ve +.PP +This sets the version required for the given module to \fIexactly\fR the given +version. No other version would be considered acceptable. +.PP +This method returns the requirements object. +.SS add_requirements +.IX Subsection "add_requirements" +.Vb 1 +\& $req\->add_requirements( $another_req_object ); +.Ve +.PP +This method adds all the requirements in the given CPAN::Meta::Requirements +object to the requirements object on which it was called. If there are any +conflicts, an exception is thrown. +.PP +This method returns the requirements object. +.SS accepts_module +.IX Subsection "accepts_module" +.Vb 1 +\& my $bool = $req\->accepts_module($module => $version); +.Ve +.PP +Given an module and version, this method returns true if the version +specification for the module accepts the provided version. In other words, +given: +.PP +.Vb 1 +\& Module => \*(Aq>= 1.00, < 2.00\*(Aq +.Ve +.PP +We will accept 1.00 and 1.75 but not 0.50 or 2.00. +.PP +For modules that do not appear in the requirements, this method will return +true. +.SS clear_requirement +.IX Subsection "clear_requirement" +.Vb 1 +\& $req\->clear_requirement( $module ); +.Ve +.PP +This removes the requirement for a given module from the object. +.PP +This method returns the requirements object. +.SS requirements_for_module +.IX Subsection "requirements_for_module" +.Vb 1 +\& $req\->requirements_for_module( $module ); +.Ve +.PP +This returns a string containing the version requirements for a given module in +the format described in CPAN::Meta::Spec or undef if the given module has no +requirements. This should only be used for informational purposes such as error +messages and should not be interpreted or used for comparison (see +"accepts_module" instead). +.SS structured_requirements_for_module +.IX Subsection "structured_requirements_for_module" +.Vb 1 +\& $req\->structured_requirements_for_module( $module ); +.Ve +.PP +This returns a data structure containing the version requirements for a given +module or undef if the given module has no requirements. This should +not be used for version checks (see "accepts_module" instead). +.PP +Added in version 2.134. +.SS required_modules +.IX Subsection "required_modules" +This method returns a list of all the modules for which requirements have been +specified. +.SS clone +.IX Subsection "clone" +.Vb 1 +\& $req\->clone; +.Ve +.PP +This method returns a clone of the invocant. The clone and the original object +can then be changed independent of one another. +.SS is_simple +.IX Subsection "is_simple" +This method returns true if and only if all requirements are inclusive minimums +\&\-\- that is, if their string expression is just the version number. +.SS is_finalized +.IX Subsection "is_finalized" +This method returns true if the requirements have been finalized by having the +\&\f(CW\*(C`finalize\*(C'\fR method called on them. +.SS finalize +.IX Subsection "finalize" +This method marks the requirements finalized. Subsequent attempts to change +the requirements will be fatal, \fIif\fR they would result in a change. If they +would not alter the requirements, they have no effect. +.PP +If a finalized set of requirements is cloned, the cloned requirements are not +also finalized. +.SS as_string_hash +.IX Subsection "as_string_hash" +This returns a reference to a hash describing the requirements using the +strings in the CPAN::Meta::Spec specification. +.PP +For example after the following program: +.PP +.Vb 1 +\& my $req = CPAN::Meta::Requirements\->new; +\& +\& $req\->add_minimum(\*(AqCPAN::Meta::Requirements\*(Aq => 0.102); +\& +\& $req\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208); +\& +\& $req\->add_maximum(\*(AqLibrary::Foo\*(Aq => 2.602); +\& +\& $req\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq); +\& +\& $req\->add_exclusion(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.8\*(Aq); +\& +\& $req\->exact_version(\*(AqXyzzy\*(Aq => \*(Aq6.01\*(Aq); +\& +\& my $hashref = $req\->as_string_hash; +.Ve +.PP +\&\f(CW$hashref\fR would contain: +.PP +.Vb 6 +\& { +\& \*(AqCPAN::Meta::Requirements\*(Aq => \*(Aq0.102\*(Aq, +\& \*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq, +\& \*(AqModule::Bar\*(Aq => \*(Aq>= v1.2.3, != v1.2.8\*(Aq, +\& \*(AqXyzzy\*(Aq => \*(Aq== 6.01\*(Aq, +\& } +.Ve +.SS add_string_requirement +.IX Subsection "add_string_requirement" +.Vb 2 +\& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq); +\& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => v1.208); +.Ve +.PP +This method parses the passed in string and adds the appropriate requirement +for the given module. A version can be a Perl "v\-string". It understands +version ranges as described in the "Version Ranges" in CPAN::Meta::Spec. For +example: +.IP 1.3 4 +.IX Item "1.3" +.PD 0 +.IP ">= 1.3" 4 +.IX Item ">= 1.3" +.IP "<= 1.3" 4 +.IX Item "<= 1.3" +.IP "== 1.3" 4 +.IX Item "== 1.3" +.IP "!= 1.3" 4 +.IX Item "!= 1.3" +.IP "> 1.3" 4 +.IX Item "> 1.3" +.IP "< 1.3" 4 +.IX Item "< 1.3" +.IP ">= 1.3, != 1.5, <= 2.0" 4 +.IX Item ">= 1.3, != 1.5, <= 2.0" +.PD +A version number without an operator is equivalent to specifying a minimum +(\f(CW\*(C`>=\*(C'\fR). Extra whitespace is allowed. +.SS from_string_hash +.IX Subsection "from_string_hash" +.Vb 2 +\& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash ); +\& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash, \e%opts ); +.Ve +.PP +This is an alternate constructor for a CPAN::Meta::Requirements +object. It takes a hash of module names and version requirement +strings and returns a new CPAN::Meta::Requirements object. As with +add_string_requirement, a version can be a Perl "v\-string". Optionally, +you can supply a hash-reference of options, exactly as with the "new" +method. +.SH SUPPORT +.IX Header "SUPPORT" +.SS "Bugs / Feature Requests" +.IX Subsection "Bugs / Feature Requests" +Please report any bugs or feature requests through the issue tracker +at <https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements/issues>. +You will be notified automatically of any progress on your issue. +.SS "Source Code" +.IX Subsection "Source Code" +This is open source software. The code repository is available for +public review and contribution under the terms of the license. +.PP +<https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements> +.PP +.Vb 1 +\& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements.git +.Ve +.SH AUTHORS +.IX Header "AUTHORS" +.IP \(bu 4 +David Golden <dagolden@cpan.org> +.IP \(bu 4 +Ricardo Signes <rjbs@cpan.org> +.SH CONTRIBUTORS +.IX Header "CONTRIBUTORS" +.IP \(bu 4 +Ed J <mohawk2@users.noreply.github.com> +.IP \(bu 4 +Karen Etheridge <ether@cpan.org> +.IP \(bu 4 +Leon Timmermans <fawaka@gmail.com> +.IP \(bu 4 +robario <webmaster@robario.com> +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +This software is copyright (c) 2010 by David Golden and Ricardo Signes. +.PP +This is free software; you can redistribute it and/or modify it under +the same terms as the Perl 5 programming language system itself. |