IDS::DataSource - A data source for the IDS test framework.

package IDS::DataSource;
$IDS::DataSource::VERSION = "1.0";

use strict;
use warnings;
use Carp qw(cluck carp confess);
use IO::File;
use IDS::Utils qw(fh_or_stdout);

### It would be better to autoload the source based on what we need.
### However, for now we will load all possible ones.

use IDS::DataSource::HTTP;

$IDS::DataSource::VERSION     = "1.0";

# Part of the logic here seems kind of backwards, but we cannot load
# until parameters have been loaded.  Some of the parameters may affect
# how we load.
sub new {
    my $invocant = shift;
    my $class = ref($invocant) || $invocant;
    my $self = { };
    my $source;

    # necessary before we call handle_parameters.
    bless($self, $class);

    $self->default_parameters;
    $source = $self->handle_parameters(@_);

    $self->load($source) if defined($source);

    return $self;
}

sub parameters {
    my $self = shift;

    return (wantarray ? %{$self->{"params"}} : $self->{"params"})
        if ($#_ == -1);

    return ${$self->{"params"}}{$_[0]} if ($#_ == 0);

    if ($#_ == 1) {
	my $old = ${$self->{"params"}}{$_[0]};
	${$self->{"params"}}{$_[0]} = $_[1];
	return $old;
    }

    scalar(@_) % 2 != 0 and confess "odd > 1 number of parameters passed to ",
        *parameters{PACKAGE}, ".  See documentation for proper usage.\n";

    for (my $i = 0; $i < $#_; $i+=2) {
	${$self->{"params"}}{$_[$i]} = $_[$i+1];
    }

    return 1;
}

sub param_options {
    my $self = shift;

    return (
            "verbose!"        => \${$self->{"params"}}{"verbose"},
            "print_warnings!" => \${$self->{"params"}}{"print_warnings"},
	   );
}

sub handle_parameters {
    my $self = shift;
    my $loadfh;

    if (defined($_[0])) {
	# If we have a non-zero even number of arguments,  we have
	# nothing but parameters
	if (scalar(@_) % 2 == 0) {
	    undef $loadfh;
	} else {
	    $loadfh = shift;
	}
    }
    $self->parameters(@_);
    return $loadfh;
}

sub default_parameters {
    confess "IDS::source::default_parameters called; this function must be subclassed.\n";
}

sub load {
    confess "IDS::source::load called; this function must be subclassed.\n";
}

sub foreach {
    my $self  = shift;
    my $fh = shift or
	cluck *foreach{PACKAGE} . "::foreach called without a filehandle";
    my $func = shift or
        cluck *foreach{PACKAGE} . "::foreach called without function ref";
    my $obj = shift or
	cluck *foreach{PACKAGE} . "::foreach called without object";

    my $n = 0;
    while ($self->read_next($fh)) {
	$n++;
        &$func($obj, scalar $self->tokens);
    }
    return $n;
}

sub mesg {
    my $self  = shift;
    my $level  = shift;
    defined($level) or confess *mesg{PACKAGE} .
        "::mesg called without a level!";
    my $msg = shift or confess *mesg{PACKAGE} .
        "::mesg called without a message!";
    my $sep = shift;
    my $ref = shift;
    my $addendum;

    $addendum = defined($sep) && defined($ref) ? join($sep, @$ref) : "";

    my $fh = ${$self->{"params"}}{"msg_fh"};
    print $fh "$msg$addendum\n"
        if defined($fh) && ${$self->{"params"}}{"verbose"} >= $level;
}

sub warn {
    my $self  = shift;
    my $pmsg = shift or confess *warn{PACKAGE} .
        "::warn called without a print message";
    my $tref = shift or confess *warn{PACKAGE} .
        "::warn called without a token list ref";
    my $token = shift;
    defined($token) or confess *warn{PACKAGE} .
        "::warn called without a token";
    my $fh = ${$self->{"params"}}{"msg_fh"};

#    ${$self->{"params"}}{"print_warnings"} and carp "WARNING: $pmsg";
    print $fh "WARNING: $pmsg\n"
        if defined($fh) && ${$self->{"params"}}{"print_warnings"};

    push @$tref, $token 
	if ${$self->{"params"}}{"return_warnings"};
}

1;