Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kentnl/gentoo-perlmod-version

Convert arbitrary Perl Modules' versions into normalised Gentoo versions.
https://github.com/kentnl/gentoo-perlmod-version

Last synced: 4 days ago
JSON representation

Convert arbitrary Perl Modules' versions into normalised Gentoo versions.

Awesome Lists containing this project

README 

        
# NAME



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



# VERSION



version v0.8.2



# 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`](https://metacpan.org/pod/version) 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 



# COPYRIGHT AND LICENSE



This software is copyright (c) 2017 by Kent Fredric .



This is free software; you can redistribute it and/or modify it under

the same terms as the Perl 5 programming language system itself.