VCS::LibCVS::Datum - a piece of CVS data

 $mode = VCS::LibCVS::Datum::Mode->new("u=rw,g=rw,o=r");
 $rq = VCS::LibCVS::Client::Request::Modified->new(["file",$mode,$file]);

  VCS::LibCVS::Datum::DirectoryName
  VCS::LibCVS::Datum::Entry
  VCS::LibCVS::Datum::FileContents
  VCS::LibCVS::Datum::FileMode
  VCS::LibCVS::Datum::FileName
  VCS::LibCVS::Datum::PathName
  VCS::LibCVS::Datum::Root
  VCS::LibCVS::Datum::String
  VCS::LibCVS::Datum::TagSpec
  VCS::LibCVS::Datum::Time

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

use strict;
use Carp;

use VCS::LibCVS::Datum::DirectoryName;
use VCS::LibCVS::Datum::Entry;
use VCS::LibCVS::Datum::FileContents;
use VCS::LibCVS::Datum::FileMode;
use VCS::LibCVS::Datum::FileName;
use VCS::LibCVS::Datum::LogMessage;
use VCS::LibCVS::Datum::PathName;
use VCS::LibCVS::Datum::RevisionNumber;
use VCS::LibCVS::Datum::Root;
use VCS::LibCVS::Datum::String;
use VCS::LibCVS::Datum::TagSpec;
use VCS::LibCVS::Datum::Time;

# Datum provides some generic facilities to help the implementation of its
# simpler subclasses; those which consist of a predetermined number of lines
# which can be named.  To use these facilities a subclass of Datum overrides
# the _data_names() routine, which returns a list of names used as keys into
# the private hash.  All the routines defined in Datum use this facility.

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

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

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

# These are specified by _data_names().
# Each of them is a single line of text, without a terminating newline.

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

sub new {
  my ($class, $arg_data) = @_;

  # if the argument is already an object of the right type, just return it
  return $arg_data if (UNIVERSAL::isa($arg_data, $class));

  my $that = bless {}, $class;

  # if the argument is an iohandle, read in the right number of lines, and
  # overwrite $arg_data with that.
  if (UNIVERSAL::isa($arg_data, "IO::Handle")) {
    my @arg_data = map { $arg_data->getline(); } $that->_data_names();
    $arg_data = \@arg_data;
  }

  # a scalar is good if one line is needed, otherwise expect an array ref
  if (!ref($arg_data)) {
    confess "Datum needs multiple lines" if (@{[$that->_data_names]} != 1);
    $that->_add_line(($that->_data_names)[0], $arg_data);

  } elsif (ref($arg_data) eq "ARRAY") {
    confess "Wrong number of lines" if (@{[$that->_data_names]} != @$arg_data);
    foreach my $n ($that->_data_names) {$that->_add_line($n, shift @$arg_data)}

  } else {
    confess "Wrong type for data of Arg:" . ref($arg_data);
  }

  return $that;
}

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

sub as_string {
  my $self = shift;
  my $as_string = $self->as_protocol_string();
  chomp $as_string;
  return $as_string;
}

sub protocol_print {
  my ($self, $ioh) = @_;
  $ioh->print($self->as_protocol_string());
}

sub as_protocol_string {
  my $self = shift;
  my $p_string = "";
  foreach my $name ($self->_data_names) { $p_string .= $self->{$name} . "\n"; }
  return $p_string;
}

sub equals {
  my $self = shift;
  my $other = shift;
  return 0 if ref($self) ne ref($other);
  foreach my $key ($self->_data_names()) {
    return 0 if $self->{$key} ne $other->{$key};
  }
  return 1;
}

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

# Returns a list of strings, which are names of the keys in the $self hash
# which hold the lines of the Datum.  If the Datum is something other than a
# list of lines, the empty list will be returned.
sub _data_names {
  return ();
}

# Add a single named line to the internal hash, ensuring that it contains no
# newlines
sub _add_line {
  my ($self, $name, $line) = @_;
  chomp($line);
  confess "Embedded newline in Datum line: $name: $line" if $line =~ /\n/;
  return $self->{$name} = $line;
}

1;