VCS::LibCVS::FileRevision - A specific revision of a file managed by CVS.

  VCS::LibCVS

#
# 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::FileRevision;

use strict;
use Carp;

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

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

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

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

# $self->{BranchNumber}     VCS::LibCVS::Datum::RevisionNumber
#                The Branch revision number is stored in order to determine the
#                predecessor correctly.  This is necessary since a revision is
#                exists on all branches which sprout from it, as well as the
#                one to which it was first committed.  eg. revision 1.2 is on
#                branch 1, as well as branch 1.2.2.
# $self->{File}             VCS::LibCVS::RepositoryFile of this revision
# $self->{LogMessage}       VCS::LibCVS::Datum::LogMessage (fetched on demand)
# $self->{RevisionNumber}   VCS::LibCVS::Datum::RevisionNumber

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

sub new {
  my $class = shift;
  my ($file, $revision, $branch) = @_;
  my $that = bless {}, $class;

  $that->{File} = $file;
  $that->{RevisionNumber} = $revision;
  if (! defined $branch) {
    $branch = $revision->branch_of();
  }
  $that->{BranchNumber} = $branch;

  return $that;
}

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

sub get_revision_number {
  return shift->{RevisionNumber};
}

sub get_file {
  return shift->{File};
}

sub get_file_branch {
  my $self = shift;
  return $self->{File}->get_branch($self->{RevisionNumber}->branch_of());
}

sub get_log_message {
  return shift->_get_log_message()->get_text();
}

sub get_committer {
  return shift->_get_log_message()->{Author};
}

sub get_time {
  my $self = shift;

  return VCS::LibCVS::parse_date($self->_get_log_message()->{Date});
}

sub get_time_string {
  return shift->_get_log_message()->{Date};
}

sub is_dead {
  return shift->_get_log_message()->{State} eq "dead";
}

# This function could use stdout mode ("-p") to avoid getting all the entries
# and stuff, but it would then receive the file as a series of "M" messages.
# This format of output worries me.

sub get_contents {
  my $self = shift;

  # Check if the file contents have been cached
  my ($cache, $c_key);
  if ($VCS::LibCVS::Cache_FileRevision_Contents_by_Repository) {
    $cache = $self->get_file->get_repository->{FileRevisionContentsCache};
    $c_key = $self->get_file->get_name.":".$self->{RevisionNumber}->as_string;
    return ($cache->{$c_key}) if ($cache->{$c_key});
  }

  # Specify which revision to get the contents of
  my $arg = [ "-r" . $self->{RevisionNumber}->as_string() ];

  # Generate and issue the command
  my $command = VCS::LibCVS::Command->new({},"update",$arg, [$self->get_file]);
  $command->issue($self->get_file()->get_repository());

  # The file is returned in an Updated response, as a FileContents Datum
  my @resps = $command->get_responses("VCS::LibCVS::Client::Response::Updated");
  confess "Not 1 Updated for " . $self->get_file->get_name unless (@resps == 1);

  # Cache and return the results
  if ($VCS::LibCVS::Cache_FileRevision_Contents_by_Repository) {
    ($cache->{$c_key}) = $resps[0]->data()->[3];
  }
  return $resps[0]->data()->[3];
}

sub get_predecessor {
  my $self = shift;
  my $pre_rev = $self->{RevisionNumber}->get_predecessor();
  if ( defined $pre_rev) {
    return VCS::LibCVS::FileRevision->new($self->{File}, $pre_rev);
  } else {
    return;
  }
}

sub get_successor {
  my $self = shift;

  # First determine the successor revision number.  If this revision is on a
  # branch which sprouts from it, then its successor's revision number has two
  # extra fields, and can't be determined directly from
  # Datum::RevisionNumber->get_successor(), so handle that case differently.

  my $suc_rev_num;
  if ($self->{BranchNumber}->equals($self->{RevisionNumber}->branch_of())) {
    $suc_rev_num = $self->{RevisionNumber}->get_successor();
  } else {
    $suc_rev_num = $self->{BranchNumber}->first_revision_of();
  }

  if (defined $self->{File}->_get_log_messages()->{$suc_rev_num->as_string()}) {
    return VCS::LibCVS::FileRevision->new($self->{File}, $suc_rev_num);
  } else {
    return;
  }
}

sub compare {
  my $self = shift;
  my $other = shift;

  if (! $self->{File}->equals($other->{File})) {
    confess "Can only compare revisions of the same file";
  }
  return $self->{RevisionNumber}->compare($other->{RevisionNumber});
}

sub equals {
  my $self = shift;
  my $other = shift;

  if (! $self->{File}->equals($other->{File})) {
    confess "Can only compare revisions of the same file";
  }
  return $self->{RevisionNumber}->equals($other->{RevisionNumber});
}

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

# get the Datum::LogMessage object for this particular file revision the
# difference between this and get_log_message is the return type.  I don't
# think it's appropriate for the external API to return a Datum::LogMessage
# object.

sub _get_log_message {
  my $self = shift;
  if (!defined $self->{LogMessage}) {
    my $rev_num_str = $self->{RevisionNumber}->as_string();
    $self->{LogMessage} = $self->{File}->_get_log_messages()->{$rev_num_str};
  }
  return $self->{LogMessage};
}

# Returns an Entry, like from the Entries file for this FileRevision.

sub _get_entry {
  my $self = shift;
  my $name = $self->{File}->get_name({'no_dir' => 1});
  my $revnum = $self->{RevisionNumber}->as_string();
  my $date = "Wed Jan 31 02:14:08 1973";
  return VCS::LibCVS::Datum::Entry->new("/$name/$revnum/$date//");
}

1;