OTRS Academy » Documentation » OTRS API Reference Perl » Kernel::System::Version

Kernel::System::Version

September 18, 2024

NAME

Kernel::System::Version – Semantic Version Representation.

DESCRIPTION

This module represents a version string (i.e. 1.1.1, 8.0.1-beta1, 3.1.10.rc.2, 10.55-1). It follows the SemVer (Semantic Versioning) approach with slight extensions.

Please see also:

https://semver.org https://tools.ietf.org/id/draft-claise-semver-00.html https://en.wikipedia.org/wiki/Software_versioning

It can be used to parse and modify versions, inspect the different version units, convert them to different structures and compare them.

SYNOPSIS

    my $Version = Kernel::System::Version->new('v3.1.10.beta-2_testing');

    my $Prefix                 = $Version->Prefix();                    # v
    my $Major                  = $Version->Major();                     # 3
    my $Minor                  = $Version->Minor();                     # 1
    my $Patch                  = $Version->Patch();                     # 10
    my $BuildDelimiter         = $Version->BuildDelimiter();            # .
    my $BuildName              = $Version->BuildName();                 # beta
    my $BuildRevisionDelimiter = $Version->BuildRevisionDelimiter();    # -
    my $BuildRevision          = $Version->BuildRevision();             # 2
    my $Suffix                 = $Version->Suffix();                    # _testing

    # Legacy Git refs (tags and branches, starting with rel-) are also supported.
    # Such strings (i.e. rel-8_0, rel-8_0_36 etc.) will be at first converted to
    # their version representation (rel- will be removed) and then parsed as a
    # version object.

    my $Version = Kernel::System::Version->new( Ref => 'rel-8_0_36' ); # will be converted to 8.0.36

    my $Prefix                 = $Version->Prefix();                    # undef
    my $Major                  = $Version->Major();                     # 8
    my $Minor                  = $Version->Minor();                     # 0
    my $Patch                  = $Version->Patch();                     # 36
    my $BuildDelimiter         = $Version->BuildDelimiter();            # undef
    my $BuildName              = $Version->BuildName();                 # undef
    my $BuildRevisionDelimiter = $Version->BuildRevisionDelimiter();    # undef
    my $BuildRevision          = $Version->BuildRevision();             # undef
    my $Suffix                 = $Version->Suffix();                    # undef

PUBLIC INTERFACE

has Prefix

Preserves the prefix part of the version string.

    my $Prefix = $Version->Prefix();

    $Version->Prefix('NewPrefix_');

    my $Bool = $Version->HasPrefix();

    $Version->ClearPrefix(); # remove prefix

has Major

Contains the major part of the version string.

    my $Major = $Version->Major();

    $Version->Major(9);

    my $Bool = $Version->HasMajor();

    $Version->ClearMajor(); # remove major

has Minor

Contains the minor part of the version string.

    my $Minor = $Version->Minor();

    $Version->Minor(0);

    my $Bool = $Version->HasMinor();

    $Version->ClearMinor(); # remove minor

has Patch

Contains the patch part of the version string.

    my $Patch = $Version->Patch();

    $Version->Patch(12);

    my $Bool = $Version->HasPatch();

    $Version->ClearPatch(); # remove patch

has BuildDelimiter

Contains the delimiter character between the main version part (i.e 8.0.1) and the build part (i.e. beta1).

    my $BuildDelimiter = $Version->BuildDelimiter();

    $Version->BuildDelimiter('.');

    my $Bool = $Version->HasBuildDelimiter();

    $Version->ClearBuildDelimiter(); # remove build delimiter

has BuildName

Contains the name of the build part of the version string.

    my $BuildName = $Version->BuildName();

    $Version->BuildName('alpha');

    my $Bool = $Version->HasBuildName();

    $Version->ClearBuildName(); # remove build name

has BuildRevisionDelimiter

Contains the delimiter character between the build name and the build revision part.

    my $BuildRevisionDelimiter = $Version->BuildRevisionDelimiter();

    $Version->BuildRevisionDelimiter('-');

    my $Bool = $Version->HasBuildRevisionDelimiter();

    $Version->ClearBuildRevisionDelimiter(); # remove build revision delimiter

has BuildRevision

Contains the revision of the build part of the version string.

    my $BuildRevision = $Version->BuildRevision();

    $Version->BuildRevision(2);

    my $Bool = $Version->HasBuildRevision();

    $Version->ClearBuildRevision(); # remove build revision

has BuildPriority

Contains the numeric priority of build revision names to be compared. During direct comparisons, that require numeric values (i.e. lower, greater etc.), the build name (if it exists) will be transformed into it's related numeric priority. Priorities can be added, deleted and requested.

    my $BetaPriority = $Version->GetBuildPriority('beta');  # 20

    $Version->AddBuildPriority( newprio => 40 );

    my $NewPriority = $Version->GetBuildPriority('newprio');  # 40

    $Version->DeleteBuildPriority('newprio');

has Suffix

Preserves the suffix part of the version string.

    my $Suffix = $Version->Suffix();

    $Version->Suffix('_AnotherSuffix');

    my $Bool = $Version->HasSuffix();

    $Version->ClearSuffix(); # remove suffix

BUILD()

Verifies if either parameter String or parameter Hash is set (probably during BUILDARGS) and triggers the parsing and object setup.

    # Build version using a string.
    my $Version = Kernel::System::Version->new( String => 'v8.1.10.beta-5_testing' );

    # Build version using a legacy ref name (tag or branch name).
    my $Version = Kernel::System::Version->new( Ref => 'rel-8_0' );         # results in 8.0
    my $Version = Kernel::System::Version->new( Ref => 'rel-8_0_36' );      # results in 8.0.36
    my $Version = Kernel::System::Version->new( Ref => 'rel-6_0_0_beta1' ); # results in 6.0.0-beta1

    # Build version using a hash reference.
    my $Version = Kernel::System::Version->new(
        Hash => {
            Prefix                 => 'v',
            Major                  => 8,
            Minor                  => 1,
            Patch                  => 10,
            BuildDelimiter         => '.',
            BuildName              => 'beta',
            BuildRevisionDelimiter => '-',
            BuildRevision          => 5,
            Suffix                 => '_testing',
        }
    );

    # Build version using a list of arguments.
    my $Version = Kernel::System::Version->new(
        Prefix                 => 'v',
        Major                  => 8,
        Minor                  => 1,
        Patch                  => 10,
        BuildDelimiter         => '.',
        BuildName              => 'beta',
        BuildRevisionDelimiter => '-',
        BuildRevision          => 5,
        Suffix                 => '_testing',
    );

BUILDARGS()

Tests for a single value as the new version string or hash and saves it to build parameter String or Hash for further processing.

    # Build version using a string.
    my $Version = Kernel::System::Version->new('v8.1.10.beta-5_testing');

    # Build version using a hash reference.
    my $Version = Kernel::System::Version->new(
        {
            Prefix                 => 'v',
            Major                  => 8,
            Minor                  => 1,
            Patch                  => 10,
            BuildDelimiter         => '.',
            BuildName              => 'beta',
            BuildRevisionDelimiter => '-',
            BuildRevision          => 5,
            Suffix                 => '_testing',
        }
    );

    # Build version using a list of arguments.
    my $Version = Kernel::System::Version->new(
        {
            Prefix                 => 'v',
            Major                  => 8,
            Minor                  => 1,
            Patch                  => 10,
            BuildDelimiter         => '.',
            BuildName              => 'beta',
            BuildRevisionDelimiter => '-',
            BuildRevision          => 5,
            Suffix                 => '_testing',
        }
    );

IncrementMajor()

Increment the major version and return the new value. If the major version is empty, it will not be incremented.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewMajor = $Version->IncrementMajor();  # 2024

    $Version->ToString();   # 2024.1.1

DecrementMajor()

Decrement the major version and return the new value. If the major version is empty, it will not be decremented. If the major version is already 0, it will not be decremented any further, but instead a 0 will be returned as the new value.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewMajor = $Version->DecrementMajor();  # 2022

    $Version->ToString();   # 2022.1.1

IncrementMinor()

Increment the minor version and return the new value. If the minor version is empty or a wildcard ( 'x' or 'X' ) exists, it will not be incremented.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewMinor = $Version->IncrementMinor();  # 2

    $Version->ToString();   # 2023.2.1

DecrementMinor()

Decrement the minor version and return the new value. If the minor version is already 0, it will not be decremented any further, but instead a 0 will be returned as the new value. If the minor version is empty or a wildcard ( 'x' or 'X' ) exist, it will not be decremented.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewMinor = $Version->DecrementMinor();  # 0

    $Version->ToString();   # 2023.0.1

IncrementPatch()

Increment the patch version and return the new value. If the patch version is empty or a wildcard ( 'x' or 'X' ) exists, it will not be incremented.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewPatch = $Version->IncrementPatch();  # 2

    $Version->ToString();   # 2023.1.2

DecrementPatch()

Decrement the patch version and return the new value. If the patch version is already 0, it will not be decremented any further, but instead a 0 will be returned as the new value. If the patch version is empty or a wildcard ( 'x' or 'X' ) exist, it will not be decremented.

    my $Version  = Kernel::System::Version->new('2023.1.1');
    my $NewPatch = $Version->DecrementPatch();  # 0

    $Version->ToString();   # 2023.1.0

IsGreater()

Compares if the own version object has a greater value than the given version string or object.

    my $True = Kernel::System::Version->new('2.0.0')->IsGreater('1.0.0');
    my $True = Kernel::System::Version->new('2.0.0') > Kernel::System::Version->new('1.0.0');
    my $True = Kernel::System::Version->new('2.0.0') gt Kernel::System::Version->new('1.0.0');

    if ( $OurVersionObject > $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject gt $ForeignVersionObject ) {
        # do something
    }

IsGreaterThanEqual()

Compares if the own version object has a greater or equal value than the given version string or object.

    my $True = Kernel::System::Version->new('2.0.0')->IsGreaterThanEqual('1.0.0');
    my $True = Kernel::System::Version->new('2.0.0')->IsGreaterThanEqual('2.0.0');

    my $True = Kernel::System::Version->new('2.0.0') >= Kernel::System::Version->new('1.0.0');
    my $True = Kernel::System::Version->new('2.0.0') >= Kernel::System::Version->new('2.0.0');
    my $True = Kernel::System::Version->new('2.0.0') ge Kernel::System::Version->new('2.0.0');

    if ( $OurVersionObject > $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject ge $ForeignVersionObject ) {
        # do something
    }

IsLower()

Compares if the own version object has a lower value than the given version string or object.

    my $True = Kernel::System::Version->new('1.0.0')->IsLower('2.0.0');
    my $True = Kernel::System::Version->new('1.0.0') < Kernel::System::Version->new('2.0.0');
    my $True = Kernel::System::Version->new('1.0.0') lt Kernel::System::Version->new('2.0.0');

    if ( $OurVersionObject < $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject lt $ForeignVersionObject ) {
        # do something
    }

IsLowerThanEqual()

Compares if the own version object has a lower or equal value than the given version string or object.

    my $True = Kernel::System::Version->new('1.0.0')->IsLowerThanEqual('2.0.0');
    my $True = Kernel::System::Version->new('2.0.0')->IsLowerThanEqual('2.0.0');

    my $True = Kernel::System::Version->new('1.0.0') <= Kernel::System::Version->new('2.0.0');
    my $True = Kernel::System::Version->new('2.0.0') <= Kernel::System::Version->new('2.0.0');
    my $True = Kernel::System::Version->new('2.0.0') le Kernel::System::Version->new('2.0.0');

    if ( $OurVersionObject <= $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject le $ForeignVersionObject ) {
        # do something
    }

IsEqual()

Compares if the own version object is equal to the given version string or object.

    my $True = Kernel::System::Version->new('1.0.0')->IsEqual('1.0.0');
    my $True = Kernel::System::Version->new('1.0.0') == Kernel::System::Version->new('1.0.0');
    my $True = Kernel::System::Version->new('1.0.0') eq Kernel::System::Version->new('1.0.0');

    if ( $OurVersionObject == $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject eq $ForeignVersionObject ) {
        # do something
    }

NotEqual()

Compares if the own version object is not equal to the given version string or object.

    my $True = Kernel::System::Version->new('1.0.0')->NotEqual('2.0.0');
    my $True = Kernel::System::Version->new('1.0.0') != Kernel::System::Version->new('2.0.0');
    my $True = Kernel::System::Version->new('1.0.0') ne Kernel::System::Version->new('2.0.0');

    if ( $OurVersionObject != $ForeignVersionObject ) {
        # do something
    }

    if ( $OurVersionObject ne $ForeignVersionObject ) {
        # do something
    }

Compare

Compares if the own version object is lower, equal or greater then the given version string or object.

    my $Cmp = Kernel::System::Version->new('1.0.0')->Compare('1.0.0');
    my $Cmp = Kernel::System::Version->new('1.0.0') cmp Kernel::System::Version->new('1.0.0');
    my $Cmp = Kernel::System::Version->new('1.0.0') <=> Kernel::System::Version->new('1.0.0');

Returns

    -1 - lower
     0 - equal
     1 - greater

IsStable()

Verifies if the current version is stable. A stable version must have a positive major part and must not have a build name (pre-release).

FromString()

Expects a version string to be parsed by method Parse and adds the elements to the attributes of this version object.

    my $Version = Kernel::System::Version->new();

    $Version->FromString('v8.1.10.beta-5_testing');

FromHash()

Expects a hash reference with version keys and values, which will be added to the attributes of this version object.

    my $Version = Kernel::System::Version->new();

    my %VersionHash = (
        Prefix                 => 'v',
        Major                  => 8,
        Minor                  => 1,
        Patch                  => 10,
        BuildDelimiter         => '.',
        BuildName              => 'beta',
        BuildRevisionDelimiter => '-',
        BuildRevision          => 5,
        Suffix                 => '_testing',
    );

    $Version->FromHash(\%VersionHash);

Parse()

Expects a version string or a legacy Git ref name to be parsed to it's elements.

    my $Version = Kernel::System::Version->new();
    my $Hash    = $Version->Parse('v8.1.10.beta5_testing');

A legacy Git ref name might be either a tag or branch name, that will be transformed to a valid version representation and setup this object with it.

    my $VersionString = Kernel::System::Version->new('rel-8_0_26')->ToString(); # '8.0.26'

    my $VersionString = Kernel::System::Version->new('rel-6_0_0_beta4')->ToString(); # '6.0.6-beta4'

    my $VersionString = Kernel::System::Version->new('rel-8_0')->ToString(); # 8.0

Returns a hash reference

    {
        Prefix                 => 'v',
        Major                  => 8,
        Minor                  => 1,
        Patch                  => 10,
        BuildDelimiter         => '.',
        BuildName              => 'beta',
        BuildRevisionDelimiter => '-',
        BuildRevision          => 5,
        Suffix                 => '_testing',
    }

FullBuildName()

Extends the build name with the build revision and the suffix as one string. If the build name and suffix of the version are empty the full build name will also be empty. This is used to store the version in the database.

    my $Version = Kernel::System::Version->new('v3.1.10.beta-2_testing');

    my $FullSuffix = $Version->FullBuildName();           # 'beta-2_testing'

ToBareString()

Converts the object to it's related string representation. If the version string originally contained a prefix and/or suffix part, it will not be included in the converted string.

    my $Version = Kernel::System::Version->new('v8.0.10.rc1_testing');

    $Version->Major(9);

    $Version->ToBareString(); # 9.0.10.rc1

ToString()

Converts the object to it's related string representation.

    my $Version = Kernel::System::Version->new('v8.0.10.rc1_testing');

    $Version->Major(9);

    my $Stringified  = $Version->ToString();                # 'v9.0.10.rc1_testing'
    my $Embedded     = "Version currently at $Version";     # "Version currently at v9.0.10.rc1_testing"
    my $Referenced   = "Version currently at ${Version}";   # "Version currently at v9.0.10.rc1_testing"
    my $Concatenated = 'Version currently at ' . $Version;  # "Version currently at v9.0.10.rc1_testing"

ToHash()

Converts the object to it's related hash reference.

    my $Version = Kernel::System::Version->new('v9.0.10.alpha-2_testing');
    my $Hash    = $Version->ToHash();

Returns a hash reference

    {
        Prefix                 => 'v',
        Major                  => 9,
        Minor                  => 0,
        Patch                  => 10,
        BuildDelimiter         => '-',
        BuildName              => 'alpha',
        BuildRevisionDelimiter => '-',
        BuildRevision          => 2,
        Suffix                 => '_testing',
    }

ToBoolean()

Converts the object to it's boolean representation. In order to convert to a boolean "True" (1), a major and a minor version have to be present, otherwise the boolean translates to "False" (empty string '').

    my $True  = Kernel::System::Version->new('v9.0.10.alpha-2_testing')->ToBoolean;
    my $True  = Kernel::System::Version->new('2023.1.1')->ToBoolean;
    my $False = Kernel::System::Version->new()->ToBoolean;

    my $Version = Kernel::System::Version->new('2023.1.1');

    if ($Version) {
        # do something
    }

PRIVATE INTERFACE

_HashToAttributes()

Uses a data hash reference, to setup the own object attributes.

_VersionToCompare()

Generates a hash reference containing prepared version values, that are feasible to be used in comparisons.

    my $Version = Kernel::System::Version->new('v8.0.10.rc1_testing');

    my $Hash = $Version->_VersionToCompare('v8.0.5-beta2_mysuffix');  # prepare version to compare later

Returns:

    {
        Major         => 8,
        Minor         => 0,
        Patch         => 5,
        Stable        => '',
        BuildPriority => 20,
        BuildRevision => 2,
    }
FacebookXEmailLinkedIn
Scroll to Top