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

VERSION
    version 0.6.0

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.

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 behaviour 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 normalised.

   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 recognises 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) 2012 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.