NAME
Perl::Version::Bumper - Update use VERSION on any Perl code
SYNOPSIS
use Perl::Version::Bumper;
my $perv = Perl::Version::Bumper->new( version => 'v5.36' );
# bump a PPI::Document
my $bumped_ppi = $perv->bump_ppi($ppi_doc);
# bump source code
my $bumped_code = $perv->bump($code);
# bump the source of a file
$perv->bump_file($filename);
# safe versions (check the result compiles)
my $bumped_ppi = $perv->bump_ppi_safely($ppi_doc);
my $bumped_code = $perv->bump_safely($code);
$perv->bump_file_safely( $filename, $version_limit );DESCRIPTION
Perl::Version::Bumper can update Perl code to make it declare it uses a more recent version of the Perl language by way of use VERSION.
It takes care of removing unnecessary loading of feature and experimental warnings, and adds the use VERSION line at the top of the file (thus encouraging "line 1 semantics").
It also manages the removal of "compatibility" modules when the feature they provide a compatibility layer with is fully supported in the target Perl version.
If the code already declares a Perl version, it can only be bumped to a higher version.
The module exports a few helper functions. These are mostly used by support tools for this distribution, and are not meant for general use.
CONSTRUCTOR
new
my $perv = Perl::Version::Bumper->new( %attributes );
my $perv = Perl::Version::Bumper->new( \%attributes );Return a new Perl::Version::Bumper object.
ATTRIBUTES
version
The target version to bump to.
Defaults to the stable version less than or equal to the version of the currenly running perl.
The constructor accepts both forms of Perl versions, regular (e.g. v5.36) and floating-point (e.g. 5.036), and will turn it into a string suitable for use VERSION.
To protect against simple mistakes (e.g. passing 5.36 instead of v5.36), the constructor does some sanity checking, and checks that the given version:
is greater than or equal to
v5.10,is lower than the version of the Perl currently running,
is a stable Perl version.
The constructor will also drops any sub-version information (so v5.36.2 will be turned into v5.36).
CLASS METHODS
feature_version
Return the version (in numeric format) of the feature set recognized by this module. It is not possible to bump code over that version.
The current value of feature_version is: 5.040.
METHODS
version_num
Return the "version" attribute as a number.
bump_ppi
my $bumped_ppi_doc = $perv->bump_ppi($ppi_doc);Take a PPI::Document as input, and return a new PPI::Document with its declared version bumped to "version".
bump
my $bumped_code = $perv->bump($code);Take a string containing Perl code as input, bump the declared Perl version in the source code to "version", and return the new source code as a string.
bump_file
$perv->bump_file($filename);Bump the code of the file argument in-place.
Return a boolean indicating if the file content was modified or not.
SAFE METHODS
The "bump_ppi", "bump" and "bump_file" methods previously described modify the source code they're given, but give no garanties that the updated code will even compile.
To address this issue, "bump_ppi_safely", "bump_safely" and "bump_file_safely" methods work as the regular methods, but will only produce code that actually compiles.
Example of a safe bump
The following code uses multidimensional array emulation:
my %h; $h{ 1, 2 } = 3; # same as $foo{"1\x{1c}2"} = 3;"bump" will produce the following when trying to update it to v5.40:
use v5.40;
my %h; $h{ 1, 2 } = 3; # same as $foo{"1\x{1c}2"} = 3;Which fails to compile with the following error:
Multidimensional hash lookup is disabledIt's not possible to just bump this code up to v5.40 and expect it to work, because it uses multidimensional array emulation, and the feature that represents this (multidimensional) was disabled in v5.36. The actual cause for the error is that Perl v5.36 doesn't support multidimensional array emulation. This code will in fact fail to compile with all versions greater or equal to v5.36.
A safe way to try to bump this code to v5.40 is to try with v5.40, detect it fails to compile, try again with v5.38 and v5.36, which also fail, until we hit v5.34 which compiles just fine (because the multidimensional feature is still enabled in that bundle). Leaving us with the following code:
use v5.34;
my %h; $h{ 1, 2 } = 3; # same as $foo{"1\x{1c}2"} = 3;The code needs to be updated to not use multidimensional array emulation before it can safely be bumped past version v5.34.
bump_ppi_safely
my $bumped_ppi = $perv->bump_ppi_safely( $ppi_doc, $version_limit );Take a PPI::Document as input, and try to compile its content. If the compilation fails, return immediately.
Otherwise, continue with the process: bump its content, and try to compile that. Return as soon as compilation succeeds.
If compilation fails, decrease the target Perl version number, bump the content to that version, and try to compile that again. Keep decreasing the target version, all the way back to the currently declared version in the document, or $version_limit, whichever is more recent. Give up after the last compilation failure.
The return value is a new PPI::Document containing the result of the "safe bump" (its content might be the same as the original if there's no safe way to bump the code).
$version_limit is optional, and defaults to v5.10.
bump_safely
my $bumped_code = $perv->bump_safely($code, $version_limit);
my ( $bumped_code, $new_version ) = $perv->bump_safely($code);Safely bump the declared Perl version in the given source code to "version", and return the new source code as a string.
bump_file_safely
$perv->bump_file_safely( $filename, $version_limit );Safely bump the code of the file argument in-place. The file will not be modified if the code can't be bumped safely.
The return value is undef if the original didn't compile, false if all attempts to bump the file failed, and the actual (numerical) version number the file was bumped to in case of success.
EXPORTS
The following functions can be optionally exported. Be aware that they are mostly meant for internal use of the module and helper scripts.
version_fmt
my $v = version_fmt( $version );Return the given version (in string, v-string or float format) as a number.
This function will die if the given version is not a plausible Perl version number, i.e. is strictly lower than 5.010.
Note that all the following functions start by normalizing their argument by calling "version_fmt", meaning they will die in the same circumstances.
version_use
my $v = version_use( $version );Return the given version (in string, v-string or float format) as a string suitable for a use VERSION line.
stable_version
my $s = stable_version( $version );Return the closest stable version lower or equal to the given version, as a number.
stable_version_inc
my $n = stable_version_inc( $version );Return the stable version following the given version, as a number.
stable_version_dec
my $p = stable_version_dec( $version );Return the stable version preceding the given version, as a number.
ACKNOWLEDGMENT
This software was originally developed at Booking.com. With approval from Booking.com, this software was released as open source, for which the authors would like to express their gratitude.
AUTHOR
Philippe Bruhat (BooK) <book@cpan.org>
COPYRIGHT
Copyright 2024 Philippe Bruhat (BooK), all rights reserved.
LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.