VCS::LibCVS::Datum::RevisionNumber - A CVS revision number.

  VCS::LibCVS::Datum

#
# Copyright (c) 2003,2004,2005 Alexander Taler (dissent@0--0.org)
#
# All rights reserved. This program is free software; you can redistribute it
# and/or modify it under the same terms as Perl itself.
#

package VCS::LibCVS::Datum::RevisionNumber;

use strict;
use Carp;

###############################################################################
# Class constants
###############################################################################

use constant REVISION => '$Header: /cvsroot/libcvs-perl/libcvs-perl/VCS/LibCVS/Datum/RevisionNumber.pm,v 1.16 2005/10/10 12:52:12 dissent Exp $ ';

use vars ('@ISA');
@ISA = ("VCS::LibCVS::Datum");

# COMPARE_* constants are documented in compare() routine
use constant COMPARE_EQUAL => 0;
use constant COMPARE_ANCESTOR => 1;
use constant COMPARE_DESCENDANT => 2;
use constant COMPARE_INCOMPARABLE => 3;
use constant COMPARE_POSSIBLE_ANCESTOR => 4;
use constant COMPARE_POSSIBLE_DESCENDANT => 5;

###############################################################################
# Class variables
###############################################################################

###############################################################################
# Private variables
###############################################################################

# $self->{Number} is the number as a string, with magic branch numbers
#                 converted to regular branch numbers.
# $self->{IsBranch} true if it's a branch revision number

###############################################################################
# Class routines
###############################################################################

sub new {
  my ($class, $num) = @_;
  my $that = bless {}, $class;

  # 0 may only appear by itself, or as the first field or the second to last
  confess "Bad revision number $num"
    unless ($num =~ /^0$|^(0\.)?([1-9][0-9]*\.)*(0\.)?[1-9][0-9]*$/);

  # Convert magic branch numbers to regular ones by removing the 0 in the
  # second to last place, unless it's the first number.
  $num =~ s/\.0(\.[0-9])*$/$1/;
  $that->{Number} = $num;

  # It's a branch if there are an odd number of fields
  $that->{IsBranch} = ($that->_depth() % 2);

  return $that;
}

###############################################################################
# Instance routines
###############################################################################

sub as_string {
  my $self = shift;
  return $self->{Number};
}

sub equals {
  my $self = shift;
  return 0 unless $self->SUPER::equals(@_);
  my $other = shift;
  return $self->{Number} eq $other->{Number};
}

sub is_branch {
  my $self = shift;
  return $self->{IsBranch};
}

sub is_trunk {
  my $self = shift;
  return ($self->_depth() == 1);
}

sub is_import_branch {
  my $self = shift;
  return (   $self->{IsBranch}
          && ($self->_depth() >= 3)
          && ($self->_last_field() % 2 == 1));
}

sub branch_of {
  my $self = shift;
  confess "No branch_of() for a branch RevisionNumber" if $self->is_branch();
  return $self->_subrevision();
}

sub base_of {
  my $self = shift;
  confess "Only branch revisions have a base" unless $self->is_branch();
  confess "Main branch has no base" if $self->_depth == 1;
  return $self->_subrevision();
}

sub first_revision_of {
  my $self = shift;
  confess "Only branches have a first revision" unless $self->is_branch();
  return VCS::LibCVS::Datum::RevisionNumber->new($self->as_string() . ".1");
}

sub get_predecessor {
  my $self = shift;
  if ($self->is_branch()) {
    confess "Branches don't have predecessors.";
  }
  if ($self->_last_field != 1) {
    my $rvstr = $self->_subrevision_string() . "." . ($self->_last_field() - 1);
    return VCS::LibCVS::Datum::RevisionNumber->new($rvstr);
  } else {
    if ($self->branch_of()->is_trunk()) {
      return;
    } else {
      return $self->branch_of()->base_of();
    }
  }
}

sub get_successor {
  my $self = shift;
  if ($self->is_branch()) {
    confess "Branches don't have successors.";
  }
  my $rvstr = $self->_subrevision_string() . "." . ($self->_last_field() + 1);
  return VCS::LibCVS::Datum::RevisionNumber->new($rvstr);
}

sub compare {
  my ($self, $other) = @_;

  if (!ref($other)) {
    $other = new VCS::LibCVS::Datum::RevisionNumber($other);
  }

  # Check revision numbers that are of the same depth.
  # Since they are of the same depth, they are either both branches, or both
  # revisions
  if ($self->_depth() == $other->_depth()) {
    # Check for trivial equality
    if ($self->equals($other)) {
      return COMPARE_EQUAL;
    }
    # Branches of the same depth that sprout from different revisions are
    # incomparable.  If they sprout from the same revision they are possibly
    # related.
    if ($self->is_branch()) {
      if (! $self->base_of()->equals($other->base_of())) {
        return COMPARE_INCOMPARABLE;
      } else {
        return ($other->_last_field > $self->_last_field)
          ? COMPARE_POSSIBLE_DESCENDANT : COMPARE_POSSIBLE_ANCESTOR;
      }
    }
    # For revisions, check that they are on the same branch, then check their
    # last field
    if ($self->branch_of()->equals($other->branch_of)) {
      return ($other->_last_field > $self->_last_field)
        ? COMPARE_DESCENDANT : COMPARE_ANCESTOR;
    }
    # They are revisions on different branches
    return COMPARE_INCOMPARABLE;
  }

  # The revision numbers are of different depths

  # Reduce the deep revision to the same depth as the shallow revision, and
  # then compare them.
  my $shallow_rev = ($self->_depth > $other->_depth) ? $other : $self;
  my $deep_rev = ($self->_depth > $other->_depth) ? $self : $other;
  # $less_deep_rev is the ancestor of $deep_rev with the same depth as
  # $shallow_rev
  my $less_deep_rev = $deep_rev;
  while ($shallow_rev->_depth() != $less_deep_rev->_depth()) {
    $less_deep_rev = $less_deep_rev->_subrevision();
  }

  # Compare $shallow_rev and $less_deep_rev
  my $result = $shallow_rev->compare($less_deep_rev);

  # Adjust $result to be correct for $shallow_rev->compare($deep_rev)
  # eg $shallow_rev is 1.6, $deep_rev is 1.6.4.3
  $result = COMPARE_DESCENDANT if ($result == COMPARE_EQUAL);

  # eg $shallow_rev is 1.4, $deep_rev is 1.6.4.3
  $result = COMPARE_DESCENDANT if ($result == COMPARE_DESCENDANT);

  # eg $shallow_rev is 1.8, $deep_rev is 1.6.4.3
  $result = COMPARE_INCOMPARABLE if ($result == COMPARE_ANCESTOR);

  $result = COMPARE_INCOMPARABLE if ($result == COMPARE_INCOMPARABLE);

  # Adjust $result to be correct for $self->compare($other)
  # Only COMPARE_DESCENDANT and COMPARE_INCOMPARABLE are possible
  if (($self->_depth > $other->_depth) && $result == COMPARE_DESCENDANT) {
    $result = COMPARE_ANCESTOR;
  }
  return $result;
}

###############################################################################
# Private routines
###############################################################################

# Create new revision number with one less field, as a string
sub _subrevision_string {
  my $self = shift;
  my ($sub_num) = ($self->{Number} =~ /^(.*)\.[0-9]+$/);
  return $sub_num;
}

# Create new RevisionNumber with one less field
sub _subrevision {
  return VCS::LibCVS::Datum::RevisionNumber->new(shift->_subrevision_string());
}

# Get the depth of the revision, ie. the number of fields.
sub _depth {
  my $self = shift;
  my $depth = (my @t = split(/\./, "$self->{Number}"));
  return $depth;
}

# The last field of this revision number
sub _last_field {
  my $self = shift;
  my ($self_field) = ($self->{Number} =~ /.*\.([0-9]+)/);
  return $self_field;
}

1;