NAME

Changes::Version - Version string object class

SYNOPSIS

use Changes::Version;
my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
    qv => 1,
    debug => 2,
);
# or
my $v = Changes::Version->new( 'v0.1.2_3' );
# or
my $v = Changes::Version->new( 'v0.1.2_3', alpha => 4 );
# or
my $v = Changes::Version->new( 'v0.1.2_3', { alpha => 4 } );
# or
my $v = Changes::Version->new( major => 0, minor => 1, patch => 2, alpha => 3, qv => 1 );
# or
my $v = Changes::Version->new({ major => 0, minor => 1, patch => 2, alpha => 3, qv => 1 });
die( Changes::Version->error ) if( !defined( $v ) );
my $v = Changes::Version->parse( 'v1.2.3_4' );
die( Changes::Version->error ) if( !defined( $v ) );
my $type = $v->type;
$v->type( 'decimal' );
$v->padded(0);
$v->pretty(1);
$v->type( 'dotted' );
$v++;
# Updating 'minor'
say "$v"; # v1.3.0
$v += 2;
$v->default_frag( 'major' );
$v++;
say "$v"; # v2.0.0
$v->inc_patch;
say $v->is_alpha; # false
say $v->numify; # returns new Changes::Version object
say $v->normal; # returns new Changes::Version object
say $v->as_string; # same as say "$v";
# 5.0.6_2
say $v->format( "%R%d%A" );

VERSION

v0.2.2

DESCRIPTION

This class represents a software version based on perl's definition and providing for perl recommended dotted decimal and also decimal types. In the future, this will be expanded to other non-perl version formats.

It allows for parsing and manipulation of version objects.

CONSTRUCTOR

new

Provided with an optional version string and an optional hash or hash reference of options and this will instantiate a new Changes::Version object.

If an error occurs, it will return an error, so alway check for the definedness of the returned value.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
die( Changes::Version->error ) if( !defined( $v ) );

Note that if you do:

my $v = Changes::Version->new( ... ) || die( Changes::Version->error );

would be dangerous, because you would be assessing the return version object in a boolean context that could return false if the version was 0.

It supports the following options that can also be accessed or changed with their corresponding method.

alpha

Specifies the alpha fragment integer of the version. See "alpha" for more information.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
my $alpha = $v->alpha; # 4
$v->alpha(7);
say "$v"; # v1.2.3_7

beta

Specifies the beta fragment integer of the version. See "beta" for more information.

Currently unused and reserved for future release.
compat

Boolean. When enabled, this will ensure the version formatting is strictly compliant with the version module. Default to false.

default_frag

Specifies the fragment name or integer value used by overloaded operations.

my $v = Changes::Version->new( 'v1.2.3_4' );
my $default = $v->default_frag; # By default 'minor'
$v->default_frag( 'major' );
$v++; # Version is now v2.2.3_4

extra

Specifies the array reference of version fragments beyond patch

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 12,
    extra => [qw( 4 5 6 7 )],
);
say "$v"; # v1.2.3.4.5.6.7_12
my $a = $v->extra; # contains 4, 5, 6, 7

major

Specifies the major fragment of the version string.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
my $major = $v->major; # 1
say "$v"; # v1.2.3_4
$v->major(3);
say "$v"; # v3.0.0

minor

Specifies the minor fragment of the version string.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
my $minor = $v->minor; # 2
say "$v"; # v1.2.3_4
$v->minor(3);
say "$v"; # v1.3.0

original

Specifies an original version string. This is normally set by "parse" and used by "as_string" to bypass any formatting when nothing has been changed.

padded

Specifies whether version string of type decimal should be zero padded or not. Default to true.

my $v = Change::Version->new(
    major => 1,
    minor => 20,
    patch => 300,
    type => 'decimal',
);
say "$v"; # 1.020300
$v->padded(0);
say "$v"; # 1.0203

patch

Specifies the patch fragment of the version string.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
my $patch = $v->patch; # 3
say "$v"; # v1.2.3_4
$v->patch(7);
say "$v"; # v1.3.7

pretty

Specifies whether version string of type decimal should be formatted with an underscore (_) separating thousands in the fraction part.

my $v = Change::Version->new(
    major => 1,
    minor => 20,
    patch => 300,
    type => 'decimal',
    pretty => 1,
);
say "$v"; # 1.020_300
$v->pretty(0);
say "$v"; # 1.020300

qv

Specifies whether version string of type dotted should be formatted with the prefix v. Defaults to true.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
say "$v"; # v1.2.3_4
$v->qv(0);
say "$v"; # 1.2.3_4

rc

Specifies the release candidate value. This is currently unused and reserved for future release.
target

Specifies the target formatting for the version string. By default this is perl and is the only supported value for now. In future release, other format types will be supported, such as opensource.
type

Specifies the version type. Possible values are dotted for dotted decimal versions such as v1.2.3 or decimal for decimal versions such as 1.002003

parse

Provided with a version string, and this will parse it and return a new Changes::Version object.

Currently, only 2 version types are supported: dotted decimal and decimal

v1.2
1.2345.6
v1.23_4
1.2345
1.2345_01

are all legitimate version strings.

If an error occurred, this will return an error.

METHODS

alpha

Sets or gets the alpha fragment integer of the version.

Setting this to undef effectively removes it.

Returns a number object

as_string

Returns a version string properly formatted according to the type set with "type" and other parameters sets such as "qv", "padded" and "pretty"

Resulting value is cached, which means the second time this is called, the cached value will be returned for speed.

Any change to the version object parameters, and this will force the re-formatting of the version string.

For example:

my $v = Changes::Version->new( 'v1.2.3_4' );
# This is a version of type 'dotted' for dotted decimal
say "$v"; # v1.2.3_4
# Changing the patch level
$v->inc( 'patch' );
# Now forced to re-format
say "$v"; # v1.2.4
# No change, using the cache
say "$v"; # v1.2.4

beta

The beta fragment integer of the version. This is currently unused and reserved for future release of this class.

compat

Boolean. When enabled, this will ensure the version formatting is strictly compliant with the version module. Default to false.

dec

Provided with a version fragment, and an optiona integer, and this will decrease the version fragment value by as much. If no integer is provided, the default decrement is 1.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
say "$v"; # v1.2.3_4;
$v->dec( 'alpha' );
say "$v"; # v1.2.3_3;
$v->dec( 'patch', 2 );
say "$v"; # v1.2.1

my $v = Changes::Version->new( 'v1.2.3.4.5.6.7_8' );
# Decrease the 5th fragment
$v->dec(5);
say "$v"; # v1.2.3.4.4.0.0

Any change to a fragment value will reset the lower fragment values to zero. Thus:

changing the major value will reset minor and patch to 0 and alpha to undef
changing the minor value will reset patch to 0 and alpha to undef
changing the patch value will reset alpha to undef
changing the nth fragment value will reset all fragment value after that to 0

If you pass a fragment that is an integer and it is outside the maximum number of fragments, it will automatically expand the number of version fragments and initialise the intermediary fragments to 0. A fragment as an integer starts at 1.

Using the example above:

$v->dec(10);
say "$v"; # v1.2.3.4.5.6.7.0.0.0

The 10th element is set to 0 because it does not exist, so it cannot be decreased.

dec_alpha

This is a shortcut for calling "dec" on fragment alpha

dec_beta

This is a shortcut for calling "dec" on fragment beta

dec_major

This is a shortcut for calling "dec" on fragment major

dec_minor

This is a shortcut for calling "dec" on fragment minor

dec_patch

This is a shortcut for calling "dec" on fragment patch

default_frag

my $v = Changes::Version->new( 'v1.2.3_4' );
my $default = $v->default_frag; # By default 'minor'
$v->default_frag( 'major' );
$v++; # Version is now v2.2.3_4

String. Sets or gets the name or the integer value for the version fragment. Supported value can be major, minor. patch, alpha, or an integer.

Returns a scalar object

extra

Sets or gets an array reference of version fragments starting from 1 for major, 2 for minor, 3 for patch, etc. For example:

my $v = Changes::Version->new( 'v1.2.3.4.5.6.7_8' );
my $a = $v->extra; # contains 4, 5, 6, 7

Note that alpha is not accessible via digits, but only using "alpha"

You should not be accessing this directly.

Returns an array object

format

my $v = Changes::Version->parse( "5.0.6_2" );
say $v->format( "%R%d" ); # 5.0.6

This formats the version string. It takes a string representing a pattern, or an array reference of pattern elements and returns a regular string.

If an error occurred, it sets an error object and returns undef in scalar context, or an empty list in list context.

See also "pattern" to get or set a pattern used by "as_string"

inc

Same as "dec", but increasing instead of decreasing.

inc_alpha

This is a shortcut for calling "inc" on fragment alpha

inc_beta

This is a shortcut for calling "inc" on fragment beta

inc_major

This is a shortcut for calling "inc" on fragment major

inc_minor

This is a shortcut for calling "inc" on fragment minor

inc_patch

This is a shortcut for calling "inc" on fragment patch

is_alpha

Returns true if "alpha" has a value set.

is_qv

Returns true if "qv" is set to true, false otherwise.

major

Sets or gets the major fragment of the version string.

my $v = Changes::Version->new( 'v1.2.3_4' );
my $major = $v->major; # 1
$v->major(3);
say "$v"; # v3.2.3_4

Setting this to undef effectively removes it.

Returns a number object

minor

Sets or gets the minor fragment of the version string.

my $v = Changes::Version->new( 'v1.2.3_4' );
my $minor = $v->minor; # 2
$v->minor(3);
say "$v"; # v1.3.3_4

Setting this to undef effectively removes it.

Returns a number object

normal

Returns a new Changes::Version object as a normalised version, which is a dotted decimal format with the v prefix.

If an error occurred, an error is returned.

numify

Returns a new Changes::Version object as a number, which represent a decimal-type version

Contrary to version if there is an alpha value set, it will add it to the numified version.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
say $v->numify; # 1.002003_4

version would yields a different, albeit wrong result:

perl -Mversion -lE 'say version->parse("v1.2.3_4")->numify'

would wrongly return 1.002034 and not 1.002003_4

perl -Mversion -lE 'say version->parse("1.002034")->normal'

then yields v1.2.34

If an error occurred, an error is returned.

original

Sets or gets the original string. This is set by "parse"

Returns a scalar object

padded

Boolean. Sets or ges whether the resulting version string of type decimal should be '0' padded or not. Default to pad with zeroes decimal numbers.

For example:

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 30,
    type => 'decimal',
    padded => 1,
);
say "$v"; # 1.002030
$v->padded(0);
say "$v"; # 1.00203

Returns a boolean object

patch

Sets or gets the patch fragment of the version string.

my $v = Changes::Version->new( 'v1.2.3_4' );
my $patch = $v->patch; # 3
$v->patch(5);
say "$v"; # v1.3.5_4

Returns a number object

pattern

Sets or gets a format pattern. This returns a regular string, or undef if no pattern has been set.

pretty

Boolean. When enabled, this will render version number for decimal type a bit cleaner by separating blocks of 3 digits by an underscore (_). This does not work on dotted decimal version numbers such as v1.2.3 or on version that have an alpha set up.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 30,
    type => 'decimal',
);

Returns a boolean object

qv

Boolean. When enabled, this will prepend the dotted decimal version strings with v. This is true by default.

my $v = Changes::Version->new(
    major => 1,
    minor => 2,
    patch => 3,
    alpha => 4,
);
say "$v"; # v1.2.3_4
$v->qv(0);
say "$v"; # 1.2.3_4

Returns a boolean object

rc

Sets or gets the release candidate value. This is currently unused and reserved for future releases.

Returns a scalar object

satisfy

$v->satisfy( $predicate );

$v = Changes::Version->parse( '0.1.1' );
$v->satisfy( '0.1.1' ); # true
$v->satisfy( '0.1.1', '> 0, < 0.2, != 0.1.0' ); # true
$v = Changes::Version->parse( '0.2.4' );
$v->satisfy( '0.2.5..0.3.4' ); # false
# or, using it as a class function:
Changes::Version->satisfy( '0.1.1', '0.1.1' ); # true
Changes::Version->satisfy( '0.1.1', '> 0, < 0.2, != 0.1.0' ); # true
Changes::Version->satisfy( '0.2.4', '0.2.5..0.3.4' ); # false

Determines if a v-string satisfy a predicate. The predicate is a list of simple predicates, each one must be satisfied (that is, an and). Simple predicates takes one of three forms:

'0.1.2'       - exact match 
'>= 3.14.15'  - (relational operator) (v-string)
'5.6 .. 10.8' - meaning '>= 5.6, <= 10.8'

A grammar for predicates in Parse::RecDescent-like syntax is:

<p> : <p0> (',' <p>)*

<p0>: <v-string>                # the same as '==' <v-string>
  | <op> <v-string> 
  | <v-string> '..' <v-string>  # the same as ">= <v-string1>, <= <v-string2>"

<op>: '==' | '!=' | '<=' | '>=' | '<' | '>'

Spaces are irrelevant in predicates.

stringify

This is an alias for "as_string"

target

Sets or gets the target format. By default this is perl. This means that "as_string" will format the version string for perl. In future release of this class, other format wil be supported, such as opensource

Returns a scalar object

type

Sets or gets the version type. Currently, supported values are dotted for dotted decimal versions such as v1.2.3, and decimal for decimal versions such as 1.002003.

Returns a scalar object

OVERLOADED OPERATIONS

The following operations are overloaded, and internally relies on version to return the value. See also overload for more information.

Note that calling the version object with any operations other than those listed below will trigger a warning, if warnings are enabled with warnings and undef is return in scalar context or an empty list in list context.

stringification

Returns value from "as_string"
0+

Returns value from "numify"
<=>

Compares two versions. If the other version being compared is not a Changes::Version, it is made one before comparison actually occurs.

Note that, version core module states in its documentation that: "alpha" version objects (where the version string contains a trailing underscore segment) compare as less than the equivalent version without an underscore."
```
$bool = version->parse("1.23_45") < version->parse("1.2345"); # TRUE
```
However, as of perl v5.10, this is not true. The above will actually return false, not true. And so will the following:
```
perl -Mversion -lE 'say version->parse("v1.002003") > version->parse("v1.002003_4");'
```
This is on my bucket list of things to improve.
cmp

Same as above.
bool

+, -, *, /

When performing those operations, it will use the value of the fragment of the version set with "default_frag", which, by default, is minor.

It returns a new Changes::Version object reflecting the new version value. However, if the operation is swapped, with the version object on the right-hand side instead of the left-hand side, this will return a regular number.

my $vers = Changes::Version->new( 'v1.2.3_4' );
my $new_version_object = $vers + 2; # Now v1.4.3_4 (minor has been bumped up by 2)
$vers->default_frag( 'major' );
my $new_version_object = $vers + 2; # Now v3.2.3_4 (this time, 'major' was increased)

But, when swapped:

my $vers = Changes::Version->new( 'v1.2.3_4' );
my $n = 3 + $vers; # yields 5 (using the 'minor' fragment by default)
$vers->default_frag( 'major' );
my $n = 3 + $vers; # yields 4 (this time, using the 'major' fragment)

+=, -=, *=, /=

In this operations, it modifies the current object with the operand provided and returns the current object, instead of creating a new one.

my $vers = Changes::Version->new( 'v1.2.3_4' );
# By default, using the 'minor' fragment
$vers += 1; # version is now v2.2.3_4
$vers->default_frag( 'alpha' );
$vers /= 2; # version is now v1.2.3_2

++, --

When using those operations, it updates the current object directly and returns it. For example:

my $vers = Changes::Version->new( 'v1.2.3_4' );
# By default, using the 'minor' fragment
$vers++; # version is now v1.3.3_4

PATTERNS

The following patterns can be used to format the version string.

%A
```
my $v = Changes::Version->parse( "5.0.6_2" );
say $v->format( '%A' ); # _2
```
This will return the alpha version, if any, prepended with an underscore.

If there is no alpha version, it returns an empty string.
%a
```
my $v = Changes::Version->parse( "5.0.6_2" );
say $v->format( '%a' ); # 2
```
This will return the alpha fragment value, if any.

If there is no alpha fragment value, it returns an empty string.

%D

my $v = Changes::Version->parse( "5.0.6.1.2.3.4_2" );
say $v->format( '%D' ); # 0.6.1.2.3.4
my $v = Changes::Version->parse( "5.0.6" );
say $v->format( '%D' ); # 0.6

This will return the minor, patch, and any extra fragments.

This is designed for dotted-decimal types, and minor, and patch will always return a number, possibly 0

%d

my $v = Changes::Version->parse( "5.0.6.1.2.3.4_2" );
say $v->format( '%D' ); # .0.6.1.2.3.4
my $v = Changes::Version->parse( "5.0.6" );
say $v->format( '%D' ); # .0.6

This is similar to %D, but will prepend a dot if the value is not null.

This is designed so you can write:

my $v = Changes::Version->parse( "5.0.6.1.2.3.4_2" );
say $v->format( '%R%d%A' ); # 5.0.6.1.2.3.4_2
my $v = Changes::Version->parse( "5" );
say $v->format( '%R%d%A' ); # 5.0.0

%M
```
my $v = Changes::Version->parse( "5.2.6_3" );
say $v->format( '%M' ); # 2
```
This returns the minor part of the version.

If there is no minor fragment value, it returns an empty string.

%m

my $v = Changes::Version->parse( "5.2.6_3" );
say $v->format( '%m' ); # .2

This is similar to %M, but will prepend a dot if the value is not null.

%N
```
my $v = Changes::Version->parse( "5.2.6" ):
say $v->format( '%R.%N' ); # 5.002006
```
This returns the minor and patch value of a dotted-decimal version as numified version.

%n

my $v = Changes::Version->parse( "5.2.6" ):
say $v->format( '%R%n' ); # 5.002006
say $v->format( '%n' ); # .002006

This is similar to %N, but will prepend a dot if the value is not null.

%P

This returns the patch fragment value of the version, if any.

If there is no patch fragment value, it returns an empty string.
%R

This returns the major fragment value of the version, if any.

If there is no major fragment value, it returns an empty string.
%U
```
my $v = Changes::Version->parse( "5.2.6" ):
say $v->format( '%R.%U' ); # 5.002_006
say $v->format( '%U' ); # 002_006
```
This returns the minor and patch value of a dotted-decimal version as numified version using the underscore to separate the minor and the patch fragments.

%u

my $v = Changes::Version->parse( "5.2.6" ):
say $v->format( '%R%u' ); # 5.002_006
say $v->format( '%u' ); # .002_006

This is similar to %U, but will prepend a dot if the value is not null.

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

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

To install Changes, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Changes

CPAN shell

perl -MCPAN -e shell
install Changes

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

VERSION

DESCRIPTION

CONSTRUCTOR

new

parse

METHODS

alpha

as_string

beta

compat

dec

dec_alpha

dec_beta

dec_major

dec_minor

dec_patch

default_frag

extra

format

inc

inc_alpha

inc_beta

inc_major

inc_minor

inc_patch

is_alpha

is_qv

major

minor

normal

numify

original

padded

patch

pattern

pretty

qv

rc

satisfy

stringify

target

type

OVERLOADED OPERATIONS

PATTERNS

AUTHOR

SEE ALSO

COPYRIGHT & LICENSE

Module Install Instructions