VCS::LibCVS::Client::Request - a request in the CVS client protocol

  my $mode = VCS::LibCVS::Datum::Mode->new("u=rw,g=rw,o=r");
  my $mod_request = VCS::LibCVS::Client::Request::Modified->
                              new( [ "afile" , $mode, "/tmp/afile" ] );
  $client->submit_request($mod_request);

  VCS::LibCVS::Datum
  VCS::LibCVS::Client
  VCS::LibCVS::Client::Request::Requests
  VCS::LibCVS::Client::Request::Argument
  VCS::LibCVS::Client::Request::ArgumentUsingRequests

#
# 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::Client::Request;

use strict;
use Carp;

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

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

# Valid_requests is a list of all the requests in this implementation.
# A request registers itself here in its BEGIN block.  It is needed to populate
# the list of valid requests
use vars ('@Valid_requests');
@Valid_requests = ();

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

# It's a hash and keeps these variables:

# RequestName => The name of this request which should be sent to the server
#                Set in constructor
# Args        => A reference to an array of objects of type LibCVS::Datum
#                Set in constructor

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

# A request maintains an internal variable which is its name as it must send to
# the CVS server.  This name can be derived from the name of the class, by
# substituing _'s with -'s.  Rather than write constructors for each subtype, I
# do that substitution here, and set the variable.  It's a little nasty, but it
# works.

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

  # This class shouldn't be instantiated itself
  die "VCS::LibCVS::Client::Request is an abstract class" if
    $class eq "VCS::LibCVS::Client::Request";

  # Transform the final chunk of the classname into the protocol request name
  my $request_name = $class;
  $request_name =~ s/.*::(.*)/$1/;
  $request_name =~ s/_/-/g;

  my $that = bless {}, $class;
  $that->{RequestName} = $request_name;

  # Process the provided args.
  # For each passed parameter, call the constructor for the expected type of
  # arg.
  $args_data = [] if !defined($args_data);
  my @required_data = $that->required_data;
  confess "Wrong number of args" if (@required_data != @$args_data);
  my @args = map {
    "VCS::LibCVS::Datum::$_"->new(shift(@$args_data));
  } @required_data;
  $that->{Args} = \@args;

  return $that;
}

# The default is one simple Datum.  Most subclasses will override this.
sub required_data {
  my $self = shift;
  return "String";
}

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

# it doesn't use the as_string routine, because we will need to add streaming

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

  $ioh->print($self->{RequestName} . " ") || confess "print 1 to ioh failed";

  # Each Datum ends it submit with a newline.  So if there are none, add one
  ($ioh->print("\n") || confess "print 2 to ioh failed") if (!@$args);

  map { $_->protocol_print($ioh) || confess "print 3 to ioh failed"; } @$args;
}

sub as_protocol_string {
  my ($self) = @_;
  my $args = $self->{Args};

  my $string = $self->{RequestName} . " ";

  # Each Datum ends its submit with a newline.  So if there are none, add one
  $string .= "\n" if (!@$args);

  map { $string .= $_->as_protocol_string; } @$args;
  return $string;
}

# generally this is based on the capitalization of the first letter of the name
sub response_expected {
  my $self = shift;
  return ($self->{RequestName} =~ /^[a-z]/);
}

sub name {
  my $self = shift;
  return $self->{RequestName};
}

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

1;