############################################################################
# Copyright (c) 1998 Enno Derksen
# All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the same terms as Perl itself. 
############################################################################

package XML::XQL::Date;

use vars qw(@ISA);
@ISA = qw( XML::XQL::PrimitiveType );

use strict;
use Carp;

BEGIN
{
    # Date::Manip relies on setting of $TZ. 
    unless (defined $ENV{TZ})
    {
	$ENV{TZ} = "EST5EDT";
	warn "XML::XQL::Date - setting timezone \$ENV{TZ} to EST5EDT (east coast USA.) Set your TZ environment variable to avoid this message.";
    }
}
use Date::Manip;

BEGIN {
    # add date() implementation to XQL engine.
    XML::XQL::defineFunction ("date", \&XML::XQL::Date::date, 1, 1, 1);
};

use overload 
    'fallback' => 1,		# use default operators, if not specified
    '<=>' => \&compare,		# also takes care of <, <=, ==, != etc.
    'cmp' => \&compare,		# also takes care of le, lt, eq, ne, etc.
    '""'  => \&yyyymmddhhmmss;	# conversion to string uses yyyymmddhhmmss

sub new
{
    my $class = shift;

    my (%args);
    if (@_ < 2)
    {
	my $str = @_ ? $_[0] : "";
	%args = (String => $str);
    }
    else
    {
	%args = @_;
    }

    my $self = bless \%args, $class;

    if (@_ < 2)
    {
	my $date = $self->createInternal (@_ ? $_[0] : "now");
	$date = "" unless isValidDate ($date);
	$self->{Internal} = $date;
    }
    $self;
}

sub createInternal
{
    my ($self, $str) = @_;
    Date::Manip::ParseDate ($str);

# From Date::Manip:
#
# 2 digit years fall into the 100 year period given by [ CURR-N,
# CURR+(99-N) ] where N is 0-99.  Default behavior is 89, but other useful
# numbers might be 0 (forced to be this year or later) and 99 (forced to be
# this year or earlier).  It can also be set to "c" (current century) or
# "cNN" (i.e.  c18 forces the year to bet 1800-1899).  Also accepts the
# form cNNNN to give the 100 year period NNNN to NNNN+99.
#$Date::Manip::YYtoYYYY=89;

# Use this to force the current date to be set to this:
#$Date::Manip::ForceDate="";
}

sub isValidDate		# static method
{
    my ($date) = @_;
    return 0 unless defined $date;

    my $year = substr ($date, 0, 4) || 0;

    $year > 1500;
#?? arbitrary limit - years < 100 cause problems in Date::Manip
}

sub ymdhms
{
    my $self = shift;
    if (@_)
    {
	my ($y, $mon, $d, $h, $m, $s) = @;
#?? implement
    }
    else
    {
#?? test: x skips a character. Format: "YYYYMMDDhh:mm::ss"
	return () unless length $self->{Internal};
#	print "ymhds " . $self->{Internal} . "\n";
	unpack ("A4A2A2A2xA2xA2", $self->{Internal});
    }
}

sub yyyymmddhhmmss
{
    my ($self) = @_;
    my ($y, $mon, $d, $h, $m, $s) = $self->ymdhms;
    
    $y ? "$y-$mon-${d}T$h:$m:$s" : "";
    # using Date::Manip::UnixDate is a bit too slow for my liking
#?? could add support for other formats
}

sub xql_toString
{
#?? use $_[0]->{String} or 
    $_[0]->yyyymmddhhmmss;
}

sub xql_compare
{
    my ($self, $other) = @_;
    my $type = ref ($self);
    if (ref ($other) ne $type)
    {
	my $str = $other->xql_toString;
	# Allow users to plug in their own Date class
	$other = eval "new $type (\$str)";
#?? check result?
    }
#print "date::compare self=" . $self->{Internal} . " other=" . $other->{Internal}. "\n";
    $self->{Internal} cmp $other->{Internal};
}

sub xql_setSourceNode
{
    $_[0]->{SourceNode} = $_[1];
}

sub xql_sourceNode
{
    $_[0]->{SourceNode};
}

sub xql_setValue
{
    my ($self, $val) = @_;
    $self->{Internal} = $self->createInternal ($val);
    $self->{String} = $val;
}

# The XQL date() function
sub date	# static method
{
    my ($context, $listref, $text) = @_;

    $text = XML::XQL::toList ($text->solve ($context, $listref));
    my @result = ();
    for my $val (@$text)
    {
	# Using xql_new allows users to plug-in their own Date class
	my $date = XML::XQL::xql_new ("date", $val->xql_toString);
#	print "date $val " . XML::XQL::d($val) . " " . $date->xql_toString . "\n";
	push @result, $date;
    }
    \@result;
}

1; # module return code

__END__

=head1 NAME

XML::XQL::Date - Adds an XQL::Node type for representing and comparing dates and times

=head1 SYNOPSIS

 use XML::XQL;
 use XML::XQL::Date;

 my $query = new XML::XQL::Query (Expr => "doc//timestamp[. < date('12/31/1999')]");
 my @results = $query->solve ($doc);

=head1 DESCRIPTION

This package uses the L<Date::Manip> package to add an XQL node type 
(called XML::XQL::Date) that can be used to represent dates and times. 
The Date::Manip package can parse almost any date or time format imaginable.
(I tested it with Date::Manip 5.33 and I know for sure that it doesn't work 
with 5.20 or lower.)

It also adds the XQL B<date> function which creates an XML::XQL::Date 
object from a string. See L<XML::XQL::Tutorial> for a description of the date()
function.

You can plug in your own Date type, if you don't want to use Date::Manip 
 for some reason. See L<XML::XQL> and the XML::XQL::Date source file for
more details.