File Coverage

blib/lib/version/Normal.pm

Criterion	Covered	Total	%
statement	22	24	91.6
branch	1	2	50.0
condition	7	12	58.3
subroutine	6	6	100.0
pod	0	2	0.0
total	36	46	78.2

package version::Normal;
$version::Normal::VERSION = '0.1.1';
# ABSTRACT: More normal forms for version objects
use 5.012;
use warnings;

use version 0.77 ();

sub version::normal2 {
    &_check_version;

    my @v = @{ $_[0]{version} };
    pop @v while @v > 2 && !$v[-1];    # drop trailing 0's

    push @v, 0 while @v < 2;           # at least 2 parts

    return sprintf 'v%vd', pack 'U*', @v;
}

sub version::normal3 {
    &_check_version;

    my @v = @{ $_[0]{version} };
    pop @v while @v > 3 && !$v[-1];    # drop trailing 0's

    push @v, 0 while @v < 3;           # at least 3 parts

    return sprintf '%vd', pack 'U*', @v;
}

sub _check_version {
    ref( $_[0] )
      && eval { exists $_[0]{version} }
      && ref( $_[0]{version} ) eq 'ARRAY'
      and return;

    require Carp;
    Carp::croak("Invalid version object");
}

1;

#pod =encoding utf8
#pod
#pod =head1 SYNOPSIS
#pod
#pod     use version::Normal;
#pod
#pod     # 'v0.400'
#pod     version->parse('0.4')->normal2;
#pod
#pod     # '0.400.0'
#pod     version->parse('0.4')->normal3;
#pod
#pod =head1 DESCRIPTION
#pod
#pod B
#pod
#pod This module loads the L module and adds two methods to its objects.
#pod Those methods implement normal forms akin to the standard C method.
#pod
#pod Furthermore, these normal forms have the following property:
#pod
#pod     NORMAL(v1) = NORMAL(v2)   if   v1 == v2
#pod
#pod Notice that this property does not hold for C.
#pod For example, for two version numbers like C<'v1.0.0'>
#pod and C<'v1.0.0.0'> which satisfy
#pod
#pod     version->parse('v1.0.0') == version->parse('v1.0.0.0')
#pod
#pod the following table of results can be computed
#pod
#pod     V                               'v1.0.0'         'v1.0.0.0'
#pod
#pod     version->parse(V)->normal()     'v1.0.0'    ≠    'v1.0.0.0'
#pod     version->parse(V)->normal2()    'v1.0'      =    'v1.0'
#pod     version->parse(V)->normal3()    '1.0.0'     =    '1.0.0'
#pod
#pod =head1 METHODS
#pod
#pod L implements the following methods
#pod and installs them into L namespace.
#pod
#pod =head2 normal2
#pod
#pod     $string = $version->normal2();
#pod
#pod Returns a string with a normalized dotted-decimal form with a leading-v,
#pod at least 2 components, and no superfluous trailing 0.
#pod
#pod Some examples are:
#pod
#pod     V          version->parse(V)->normal2()
#pod
#pod     0.1        v0.100
#pod     v0.1       v0.1
#pod     v1         v1.0
#pod     0.010      v0.10
#pod     1.010      v1.10
#pod     0.3.10     v0.3.10
#pod     v0.0.0.0   v0.0
#pod     v0.1.0.0   v0.1
#pod
#pod This form looks good when describing the version of a software
#pod component for humans to read
#pod (eg. at C file, C<--version> output, etc.)
#pod
#pod =head2 normal3
#pod
#pod     $string = $version->normal3();
#pod
#pod Returns a string with a normalized dotted-decimal form with no leading-v,
#pod at least 3 components, and no superfluous trailing 0.
#pod
#pod Some examples are:
#pod
#pod     V          version->parse(V)->normal3()
#pod
#pod     0.1        0.100.0
#pod     v0.1       0.1.0
#pod     v1         1.0.0
#pod     0.010      0.10.0
#pod     1.010      1.10.0
#pod     0.3.10     0.3.10
#pod     v0.0.0.0   0.0.0
#pod     v0.1.0.0   0.1.0
#pod
#pod This form is appropriate for distribution tarball names
#pod (like C<"version-Normal-0.1.0.tar.gz">) – only digits and dots
#pod and no need for special interpretation of a leading-v.
#pod
#pod =head1 SEE ALSO
#pod
#pod L
#pod
#pod =head1 ACKNOWLEDGEMENTS
#pod
#pod The development of this library has been partially sponsored
#pod by Connectivity, Inc.
#pod
#pod =cut

__END__