NAME

Gentoo::PerlMod::Version - Convert arbitrary Perl Modules' versions into normalized Gentoo versions.

VERSION

version v0.8.1

SYNOPSIS

use Gentoo::PerlMod::Version qw( :all );

# http://search.cpan.org/~gmpassos/XML-Smart-1.6.9/
say gentooize_version( '1.6.9' )  # 1.6.9

http://search.cpan.org/~pip/Math-BaseCnv-1.6.A6FGHKE/

say gentooize_version('1.6.A6FGHKE')   #  <-- death, this is awful

# -- Work-In-Progress Features --

say gentooize_version('1.6.A6FGHKE',{ lax => 1}) # <-- still death

say gentooize_version('1.6.A6FGHKE',{ lax => 2}) # 1.6.366.556.632.14  # <-- the best we can do.

say gentooize_version('1.9902-TRIAL')   #  <-- death, this is not so bad, but not a valid gentoo/stable version

say gentooize_version('1.9902-TRIAL', { lax => 1 })   #  1.990.200_rc # <-- -TRIAL gets nuked, 'rc' is added.

DESCRIPTION

This module acts as a reference implementation of how Gentoo maps CPAN and Perl versions, and transforms them into derived versions that are suitable for Gentoo dependency tracking.

Perl has several primary formats of versions, the most notable one being float style versions, in the form x.yyyyyyyyyyy where the number of y's are arbitrary, and are interpreted as a floating point value.

That is, 1.001 is NOT the same as 1.01 and 1.1

However, Gentoo's version scheme sees 1.001 similar to 1.001.000 which is similar to 1.1.0 and thus, similar to 1.1.

Obviously this will not do, because when somebody says they need >=1.05 (g:1.5) expecting 1.06 (g:1.6), but instead get 1.009 (g:1.9), things will break.

Hence, detection of these cases and normalizing them is essential:

1.001 -> 1.1.0
1.01  -> 1.10.0
1.1   -> 1.100.0
1.05  -> 1.50.0
1.06  -> 1.60.0
1.009 -> 1.9.0

1.9.0 < 1.50.0 < 1.60.0

The simplest use of this library is with the shipped tool, gentoo-perlmod-version.pl

gentoo-perlmod-version.pl --oneshot 1.06  # 1.6.0

FUNCTIONS

gentooize_version

my $normalized = gentooize_version( $weird_version )

gentooize_version tries hard to mangle a version that is part of a CPAN dist into a normalized form for Gentoo, which can be used as the version number of the ebuild, while storing the original upstream version in the ebuild.

CPAN: Foo-Bar-Baz 1.5
print gentooize_version('1.5');  # -> 1.500.0
-> dev-perl/Foo-Bar-Baz-1.500.0.ebuild
cat dev-perl/Foo-Bar-Baz-1.500.0.ebuild
# ...
# MODULE_VERSION="1.5"
# ...

Normal behavior accepts only sane non-testing versions, i.e.:

0.1         -> 0.001.0
0.001       -> 0.1.0
1.1         -> 1.001.0
1.123.13    -> 1.123.13

Etc.

This uses version.pm to read versions and to normalize them.

0.1    # 0.100.0
0.01   # 0.10.0
0.001  # 0.1.0
0.0001 # 0.0.100

So assuming Perl can handle your versions, they can be normalized.

lax level 1

my $normalized = gentooize_version( $werid_version, { lax => 1 } );

EXPERIMENTAL: This feature is still in flux, and the emitted versions may change.

This adds one layer of laxativity, and permits parsing and processing of "Developer Release" builds.

1.10-TRIAL  # 1.100.0_rc
1.11-TRIAL  # 1.110.0_rc
1.1_1       # 1.110.0_rc

lax level 2

my $normalized = gentooize_version( $werid_version, { lax => 2 } );

EXPERIMENTAL: This feature is still in flux, and the emitted versions may change.

This adds another layer of laxativity, and permits parsing and processing of packages with versions not officially supported by Perl.

This means versions such as

1.6.A       # 1.6.10
1.6.AA      # 1.6.370
1.6.AAA      # 1.6.370.10
1.6.AAAA      # 1.6.370.370

1.6.A6FGHKE # 1.6.366.556.632.14

This is performed by some really nasty tricks, and treats the ASCII portion like a set of pairs.

1.6.A6.FG.HK.E

And each ASCII pair is treated like a Base36 number.

0 -> 0
....
9 -> 9
A -> 10
...
Z -> 35

A6 is thus

10 * 36 + 6 => 366

As you can see, its really nasty, and hopefully its not needed.

ENVIRONMENT

This module recognizes the environment variable GENTOO_PERLMOD_VERSION_OPTS for a few features.

These are mostly useful for system wide or user-wide policies that may be applicable for using this module, depending on where it is used.

This field is split by white-space and each token has a meaning.

always_lax

GENTOO_PERLMOD_VERSION_OPTS+=" always_lax=0 "
GENTOO_PERLMOD_VERSION_OPTS+=" always_lax=1 "
GENTOO_PERLMOD_VERSION_OPTS+=" always_lax=2 "
GENTOO_PERLMOD_VERSION_OPTS+=" always_lax   "# same as always_lax=1
GENTOO_PERLMOD_VERSION_OPTS+=" -always_lax  "# unset always_lax

This environment setting, if specified, overrides any specification of "lax" in the code. If this specified more than once, the right-most one applies.

Specifying -always_lax will unset the setting, making it behave as if it had not been previously specified.

taint_safe

GENTOO_PERLMOD_VERSION_OPTS+=" taint_safe  " #on
GENTOO_PERLMOD_VERSION_OPTS+=" -taint_safe " #off

As it stands, this module only emits messages via STDOUT/STDERR when an error occurs. For diagnosis, sometimes user provided data can appear in this output.

Specifying this option will remove the information as specified by the user where possible, to eliminate this risk if this is a security issue for you.

It is not a guarantee of safety, but merely a tool you might find useful, depending on circumstances.

carp_debug

GENTOO_PERLMOD_VERSION_OPTS+=" carp_debug " #on
GENTOO_PERLMOD_VERSION_OPTS+=" -carp_debug " #off

Lots of information is passed to our internal carp proxy that could aid in debugging a future problem. To see this information instead of the simple message that is usually sent to Carp, enable this option.

Note: As values in the hashes that would be printed can come from users, carp_debug is ignored if taint_safe is on.

THANKS

Torsten Veller - Inspiration for this Module and all the work on Gentoo Perl.

Vincent Pit - For solving most of the real bugs in this code before people tried to use them.

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric <kentnl@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.