=pod

=head1 NAME

Version::Semantic - Immutable SemVer scheme based version class

=head1 SYNOPSIS

  use Version::Semantic ();

  my $v_unstable = Version::Semantic->parse( '1.0.1-alpha' );
  my $v_testing  = Version::Semantic->parse( '1.0.1-beta' );
  my $v_stable   = Version::Semantic->parse( 'v1.0.1' );

  if ( $v_unstable < $v_testing and $v_testing < $v_stable ) {
    ...
  }

=head1 DESCRIPTION

This class defines immutable version objects that support the L<Semantic
Versioning (SemVer) Scheme|https://semver.org/spec/v2.0.0.html>.

The class has a C<parse()> factory method (a class method) to create
objects from their semantic version strings. The method accepts semantic
version strings that have a C<v> prefix (L<Is "v1.2.3" a semantic
version?|https://semver.org/spec/v2.0.0.html#is-v123-a-semantic-version>).

The C<semver_re()> class method provides the regular expression that is used
by the C<parse()> method. The C<parse()> method adds a C<\A> anchor at the
beginning and a C<\z> anchor at the end of the regular expression pattern.

The C<parse()> method returns C<undef>, if its string parameter (the first
parameter) cannot be parsed. The C<parse()> method croaks, if its string
parameter cannot be parse and if its options hash reference parameter (the
second parameter) has a C<fatal> boolean option that is true.

The class has a usual C<new()> constructor method (class method) to create
objects from their named attributes.

Each object has the required attributes C<major>, C<minor>, and
C<patch>.  Optional object attributes are C<prefix>, C<pre_release> and
C<build>. C<has_prefix()>, C<has_pre_release()> and C<has_build()> predicate
methods exist too.

The C<version_core()> object method returns the semantic version string of an
object with the C<v> prefix (if originally set) but without the pre-release
and the build extensions. The C<is_core()> predicate method indicates if a
version object has no pre-release extension and no build extension.

The C<to_string()> object method returns the semantic version string of an
object including the C<v> prefix (if originally set). The method is used to
overload the stringification C<""> operator.

The C<compare_to()> object method implements the L<SemVer precedence
rules|https://semver.org/spec/v2.0.0.html#spec-item-11>. This method is used
to overload the numeric comparison C<E<lt>=E<gt>> operator. This allows you
to compare version objects.

=head1 ABOUT PRE-RELEASES

Perl recognizes two version styles: decimal versions and dotted decimal
versions. The dotted decimal version style is the newer one. It matches the
SemVer scheme but doesn't allow pre-release and build extensions.

If the archive file of a Perl distribution has a name ending in C<TRIAL[0-9]*>
(before the file extension), it indicates that the distribution is a
pre-release. C<TRIAL[0-9]*> is a valid SemVer pre-release extension. For
obvious reasons such kind of pre-releases are also named "trial releases".
If L<ExtUtils::MakeMaker> (EUMM) is your installer, the DISTVNAME EUMM
attribute can be used to mark a distribution as a trial release (example value
"Foo-Bar-v1.0.1-TRIAL5").

=head1 INCREMENT

The C<increment()> object method increments a version object and returns the
new one. The method has two optional parameters. The first one specifies the
incrementation strategy. The following strategies are implemented: C<patch>
(the default), C<minor>, C<major>, and C<trial>. The second parameter
allows you to set or overwrite the C<pre_release> attribute for non-C<trial>
strategies. Example:

  # Leads to "v1.0.1-TRIAL5"
  my $v_trial = Version::Semantic->new(
    prefix => 'v',
    major  => 1,
    minor  => 0,
    patch  => 0
  )->increment( 'patch', 'TRIAL5' );

The C<trial> strategy can be applied to trial releases only. It increments
the trial release number ignoring any kind of formatting (leading zeros for
example). This strategy should be considered experimental.

Other Perl CPAN distributions that provide version object incrementation
implementations are L<Version::Next> and L<Perl::Version>.

=head1 SEE ALSO

=over 2

=item *

L<SemVer::V2::Strict>

=item *

L<SemVer>

=item *

L<Version::Dotted::Semantic>

=back

=head1 AUTHOR

Sven Willenbuecher <sven.willenbuecher@gmx.de>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Sven Willenbuecher.

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

=cut
