package VCP::Revs ;

=head1 NAME

VCP::Revs - A collection of VCP::Rev objects.

=head1 SYNOPSIS

=head1 DESCRIPTION

Right now, all revs are kept in memory, but we will enable storing them to
disk and recovering them at some point so that we don't gobble huge
tracts of RAM.

=head1 METHODS

=over

=cut

$VERSION = 1 ;

use strict ;

use Carp ;
use VCP::Debug ":debug" ;
use VCP::Rev ;

use fields (
   'REVS',        ## The revs, sorted or not
   'SEEN',        ## A HASH of keys of form "filename,rev#"
) ;


=item new

=cut

sub new {
   my $class = CORE::shift ;
   $class = ref $class || $class ;

   my $self ;

   {
      no strict 'refs' ;
      $self = bless [ \%{"$class\::FIELDS"} ], $class ;
   }

   $self->{REVS} = [] ;
   $self->{SEEN} = {} ;

   return $self ;
}


=item add

   $revs->add( $rev ) ;
   $revs->add( $rev1, $rev2, ... ) ;

Adds a revision or revisions to the collection.

The ( name, rev_id, branch_id ) tuple must be unique, if a second rev
is C<add()>ed with the same values, an exception is thrown.

=cut

sub add {
   my VCP::Revs $self = CORE::shift ;

   if ( debugging $self || debugging scalar caller ) {
      debug( "vcp: queuing ", $_->as_string ) for @_ ;
   }

   for my $r ( @_ ) {
      my $uid = $r->uid;
      croak "Can't add same revision twice: '" . $r->as_string
         if $self->{SEEN}->{$uid} ;
      $self->{SEEN}->{$uid} = $r ;
      push @{$self->{REVS}}, $r ;
   }
}


=item get_base_version_rev

   my $bv_rev = $revs->get_base_version_rev( $r );

Return the revision that created the base version for a revision.

Throws an exception if $r's base_version is undefined or can't be
found.

=cut

sub get_base_version_rev {
   my VCP::Revs $self = shift;

   my ( $r ) = @_;

   my $bv_uid = $r->base_version_uid;

   Carp::confess "Revision has no base_version: ", $r->as_string, "\n"
      unless defined $bv_uid;
   die "Base version revision $bv_uid not found for ", $r->as_string, "\n"
      unless exists $self->{SEEN}->{$bv_uid};

   return $self->{SEEN}->{$bv_uid};
}


=item set

   $revs->set( $rev ) ;
   $revs->set( $rev1, $rev2, ... ) ;

Sets the list of revs.

=cut

sub set {
   my VCP::Revs $self = CORE::shift ;

   Carp::confess "undef passed" if grep !defined, @_;

   if ( debugging $self || debugging scalar caller ) {
      require UNIVERSAL;
      Carp::confess "unblessed ref passed" if grep !UNIVERSAL::can( $_, "as_string" ), @_;
      debug( "vcp: queuing ", $_->as_string ) for @_ ;
   }

   @{$self->{REVS}} = @_ ;
}


=item get

   @revs = $revs->get ;

Gets the list of revs.

=cut

sub get {
   my VCP::Revs $self = CORE::shift ;

   return @{$self->{REVS}} ;
}


=item sort

   # Using a custom sort function:
   $revs->sort( sub { ... } ) ;

Note: Don't use $a and $b in your sort function.  They're package globals
and that's not your package.  See L<VCP::Dest/rev_cmp_sub> for more details.

=cut

sub sort {
   my VCP::Revs $self = CORE::shift ;

   my ( $sort_func ) = @_ ;

   @{$self->{REVS}} = sort $sort_func, @{$self->{REVS}} ;
}


=item shift

   while ( $r = $revs->shift ) {
      ...
   }

Call L</sort> before calling this :-).

=cut

sub shift {
   my VCP::Revs $self = CORE::shift ;

   return shift @{$self->{REVS}} ;
}


=item as_array_ref

Returns an ARRAY ref of all revs.

=cut

sub as_array_ref {
   my VCP::Revs $self = CORE::shift ;

   return $self->{REVS} ;
}


=head1 SUBCLASSING

This class uses the fields pragma, so you'll need to use base and 
possibly fields in any subclasses.

=head1 COPYRIGHT

Copyright 2000, Perforce Software, Inc.  All Rights Reserved.

This module and the VCP package are licensed according to the terms given in
the file LICENSE accompanying this distribution, a copy of which is included in
L<vcp>.

=head1 AUTHOR

Barrie Slaymaker <barries@slaysys.com>

=cut

1