| 1 |
NAME |
| 2 |
Perl::MinimumVersion - Find a minimum required version of perl for Perl |
| 3 |
code |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
# Create the version checking object |
| 7 |
$object = Perl::MinimumVersion->new( $filename ); |
| 8 |
$object = Perl::MinimumVersion->new( \$source ); |
| 9 |
$object = Perl::MinimumVersion->new( $ppi_document ); |
| 10 |
|
| 11 |
# Find the minimum version |
| 12 |
$version = $object->minimum_version; |
| 13 |
|
| 14 |
DESCRIPTION |
| 15 |
"Perl::MinimumVersion" takes Perl source code and calculates the minimum |
| 16 |
version of perl required to be able to run it. Because it is based on |
| 17 |
PPI, it can do this without having to actually load the code. |
| 18 |
|
| 19 |
Currently it tests both the syntax of your code, and the use of explicit |
| 20 |
version dependencies such as "require 5.008". |
| 21 |
|
| 22 |
Future plans are to also add support for tracing module dependencies. |
| 23 |
|
| 24 |
Using "Perl::MinimumVersion" is dead simple, the synopsis pretty much |
| 25 |
covers it. |
| 26 |
|
| 27 |
The distribution comes with a script called perlver, which is the |
| 28 |
easiest way to run "Perl::MinimumVersion" on your code: |
| 29 |
|
| 30 |
% perlver lib/Foo/Bar.pm |
| 31 |
|
| 32 |
See the documentation for perlver for more details. |
| 33 |
|
| 34 |
METHODS |
| 35 |
new |
| 36 |
# Create the version checking object |
| 37 |
$object = Perl::MinimumVersion->new( $filename ); |
| 38 |
$object = Perl::MinimumVersion->new( \$source ); |
| 39 |
$object = Perl::MinimumVersion->new( $ppi_document ); |
| 40 |
|
| 41 |
The "new" constructor creates a new version checking object for a |
| 42 |
PPI::Document. You can also provide the document to be read as a file |
| 43 |
name, or as a "SCALAR" reference containing the code. |
| 44 |
|
| 45 |
Returns a new "Perl::MinimumVersion" object, or "undef" on error. |
| 46 |
|
| 47 |
Document |
| 48 |
The "Document" accessor can be used to get the PPI::Document object back |
| 49 |
out of the version checker. |
| 50 |
|
| 51 |
minimum_version |
| 52 |
The "minimum_version" method is the primary method for finding the |
| 53 |
minimum perl version required based on "all" factors in the document. |
| 54 |
|
| 55 |
At the present time, this is just syntax and explicit version checks, as |
| 56 |
Perl::Depends is not yet completed. |
| 57 |
|
| 58 |
Returns a version object, or "undef" on error. |
| 59 |
|
| 60 |
minimum_explicit_version |
| 61 |
The "minimum_explicit_version" method checks through Perl code for the |
| 62 |
use of explicit version dependencies such as. |
| 63 |
|
| 64 |
use 5.006; |
| 65 |
require 5.005_03; |
| 66 |
|
| 67 |
Although there is almost always only one of these in a file, if more |
| 68 |
than one are found, the highest version dependency will be returned. |
| 69 |
|
| 70 |
Returns a version object, false if no dependencies could be found, or |
| 71 |
"undef" on error. |
| 72 |
|
| 73 |
minimum_syntax_version $limit |
| 74 |
The "minimum_syntax_version" method will explicitly test only the |
| 75 |
Document's syntax to determine it's minimum version, to the extent that |
| 76 |
this is possible. |
| 77 |
|
| 78 |
It takes an optional parameter of a version object defining the lowest |
| 79 |
known current value. For example, if it is already known that it must be |
| 80 |
5.006 or higher, then you can provide a param of qv(5.006) and the |
| 81 |
method will not run any of the tests below this version. This should |
| 82 |
provide dramatic speed improvements for large and/or complex documents. |
| 83 |
|
| 84 |
The limitations of parsing Perl mean that this method may provide |
| 85 |
artificially low results, but should not artificially high results. |
| 86 |
|
| 87 |
For example, if "minimum_syntax_version" returned 5.006, you can be |
| 88 |
confident it will not run on anything lower, although there is a chance |
| 89 |
that during actual execution it may use some untestable feature that |
| 90 |
creates a dependency on a higher version. |
| 91 |
|
| 92 |
Returns a version object, false if no dependencies could be found, or |
| 93 |
"undef" on error. |
| 94 |
|
| 95 |
minimum_external_version |
| 96 |
WARNING: This method has not been implemented. Any attempted use will |
| 97 |
throw an exception |
| 98 |
|
| 99 |
The "minimum_external_version" examines code for dependencies on other |
| 100 |
external files, and recursively traverses the dependency tree applying |
| 101 |
the same tests to those files as it does to the original. |
| 102 |
|
| 103 |
Returns a "version" object, false if no dependencies could be found, or |
| 104 |
"undef" on error. |
| 105 |
|
| 106 |
version_markers |
| 107 |
This method returns a list of pairs in the form: |
| 108 |
|
| 109 |
($version, \@markers) |
| 110 |
|
| 111 |
Each pair represents all the markers that could be found indicating that |
| 112 |
the version was the minimum needed version. @markers is an array of |
| 113 |
strings. Currently, these strings are not as clear as they might be, but |
| 114 |
this may be changed in the future. In other words: don't rely on them as |
| 115 |
specific identifiers. |
| 116 |
|
| 117 |
BUGS |
| 118 |
Perl::MinimumVersion does a reasonable job of catching the best-known |
| 119 |
explicit version dependencies. |
| 120 |
|
| 121 |
However it is exceedingly easy to add a new syntax check, so if you find |
| 122 |
something this is missing, copy and paste one of the existing 5 line |
| 123 |
checking functions, modify it to find what you want, and report it to |
| 124 |
rt.cpan.org, along with the version needed. |
| 125 |
|
| 126 |
I don't even need an entire diff... just the function and version. |
| 127 |
|
| 128 |
TO DO |
| 129 |
Write lots more version checkers |
| 130 |
|
| 131 |
- Perl 5.10 operators and language structures |
| 132 |
|
| 133 |
- Three-argument open |
| 134 |
|
| 135 |
Write the explicit version checker |
| 136 |
|
| 137 |
Write the recursive module descend stuff |
| 138 |
|
| 139 |
_while_readdir for postfix while without brackets |
| 140 |
|
| 141 |
Check for more 5.12 features (currently only detecting "package NAME |
| 142 |
VERSION;", "...", and "use feature ':5.12'") |
| 143 |
|
| 144 |
SUPPORT |
| 145 |
All bugs should be filed via the CPAN bug tracker at |
| 146 |
|
| 147 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-MinimumVersion> |
| 148 |
|
| 149 |
For other issues, or commercial enhancement or support, contact the |
| 150 |
author. |
| 151 |
|
| 152 |
AUTHORS |
| 153 |
Adam Kennedy <[email protected]> |
| 154 |
|
| 155 |
SEE ALSO |
| 156 |
perlver - the command-line script for running "Perl::MinimumVersion" on |
| 157 |
your code. |
| 158 |
|
| 159 |
Perl::MinimumVersion::Fast - another module which does the same thing. |
| 160 |
It's a lot faster, but only supports Perl 5.8.1+. |
| 161 |
|
| 162 |
<http://ali.as/>, PPI, version |
| 163 |
|
| 164 |
REPOSITORY |
| 165 |
<https://github.com/neilbowers/Perl-MinimumVersion> |
| 166 |
|
| 167 |
COPYRIGHT |
| 168 |
Copyright 2005 - 2014 Adam Kennedy. |
| 169 |
|
| 170 |
This program is free software; you can redistribute it and/or modify it |
| 171 |
under the same terms as Perl itself. |
| 172 |
|
| 173 |
The full text of the license can be found in the LICENSE file included |
| 174 |
with this module. |
| 175 |
|