Perl::MinimumVersion(3pm)

1Perl::MinimumVersion(3)User Contributed Perl DocumentatioPnerl::MinimumVersion(3)
2
3
4

NAME

6       Perl::MinimumVersion - Find a minimum required version of perl for Perl
7       code
8

SYNOPSIS

10         # Create the version checking object
11         $object = Perl::MinimumVersion->new( $filename );
12         $object = Perl::MinimumVersion->new( \$source  );
13         $object = Perl::MinimumVersion->new( $ppi_document );
14
15         # Find the minimum version
16         $version = $object->minimum_version;
17

DESCRIPTION

19       "Perl::MinimumVersion" takes Perl source code and calculates the mini‐
20       mum version of perl required to be able to run it. Because it is based
21       on PPI, it can do this without having to actually load the code.
22
23       Currently it tests both the syntax of your code, and the use of
24       explicit version dependencies such as "require 5.005".
25
26       Future plans are to also add support for tracing module dependencies.
27
28       Using "Perl::MinimumVersion" is dead simple, the synopsis pretty much
29       covers it.
30

METHODS

32       new
33
34         # Create the version checking object
35         $object = Perl::MinimumVersion->new( $filename );
36         $object = Perl::MinimumVersion->new( \$source  );
37         $object = Perl::MinimumVersion->new( $ppi_document );
38
39       The "new" constructor creates a new version checking object for a
40       PPI::Document. You can also provide the document to be read as a file
41       name, or as a "SCALAR" reference containing the code.
42
43       Returns a new "Perl::MinimumVersion" object, or "undef" on error.
44
45       Document
46
47       The "Document" accessor can be used to get the PPI::Document object
48       back out of the version checker.
49
50       minimum_version
51
52       The "minimum_version" method is the primary method for finding the min‐
53       imum perl version required based on "all" factors in the document.
54
55       At the present time, this is just syntax and explicit version checks,
56       as Perl::Depends is not yet completed.
57
58       Returns a version object, or "undef" on error.
59
60       minimum_explicit_version
61
62       The "minimum_explicit_version" method checks through Perl code for the
63       use of explicit version dependencies such as.
64
65         use 5.006;
66         require 5.005_03;
67
68       Although there is almost always only one of these in a file, if more
69       than one are found, the highest version dependency will be returned.
70
71       Returns a version object, false if no dependencies could be found, or
72       "undef" on error.
73
74       minimum_syntax_version $limit
75
76       The "minimum_syntax_version" method will explicitly test only the Docu‐
77       ment's syntax to determine it's minimum version, to the extent that
78       this is possible.
79
80       It takes an optional parameter of a version object defining the the
81       lowest known current value. For example, if it is already known that it
82       must be 5.006 or higher, then you can provide a param of qv(5.006) and
83       the method will not run any of the tests below this version. This
84       should provide dramatic speed improvements for large and/or complex
85       documents.
86
87       The limitations of parsing Perl mean that this method may provide
88       artifically low results, but should not artificially high results.
89
90       For example, if "minimum_syntax_version" returned 5.006, you can be
91       confident it will not run on anything lower, although there is a chance
92       that during actual execution it may use some untestable  feature that
93       creates a dependency on a higher version.
94
95       Returns a version object, false if no dependencies could be found, or
96       "undef" on error.
97
98       minimum_external_version
99
100       WARNING: This method has not been implemented. Any attempted use will
101       throw an exception
102
103       The "minimum_external_version" examines code for dependencies on other
104       external files, and recursively traverses the dependency tree applying
105       the same tests to those files as it does to the original.
106
107       Returns a "version" object, false if no dependencies could be found, or
108       "undef" on error.
109

BUGS

111       It's very early days, so this probably doesn't catch anywhere near
112       enough syntax cases, and I personally don't know enough of them.
113
114       However it is exceedingly easy to add a new syntax check, so if you
115       find something this is missing, copy and paste one of the existing 5
116       line checking functions, modify it to find what you want, and report it
117       to rt.cpan.org, along with the version needed.
118
119       I don't even need an entire diff... just the function and version.
120

TO DO

122       - Write lots more version checkers
123
124       - Write the explicit version checker
125
126       - Write the recursive module descend stuff
127

SUPPORT

129       All bugs should be filed via the CPAN bug tracker at
130
131       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Perl-MinimumVersion>
132
133       For other issues, or commercial enhancement or support, contact the
134       author.
135

AUTHORS

137       Adam Kennedy <adamk@cpan.org>
138

COPYRIGHT

143       Copyright (c) 2005, 2006 Adam Kennedy.
144
145       This program is free software; you can redistribute it and/or modify it
146       under the same terms as Perl itself.
147
148       The full text of the license can be found in the LICENSE file included
149       with this module.
150
151
152
153perl v5.8.8                       2007-07-17           Perl::MinimumVersion(3)