#!/usr/bin/perl -w
# vi:sts=4:shiftwidth=4
# -*- Mode: perl -*-
#======================================================================
#
# This package is free software and is provided "as is" without
# express or implied warranty.  It may be used, redistributed and/or
# modified under the same terms as perl itself. ( Either the Artistic
# License or the GPL. )
#
# $Id: Todo.pm,v 1.16 2001/07/09 20:52:57 lotr Exp $
#
# (C) COPYRIGHT 2000-2001, Reefknot developers.
#
# See the AUTHORS file included in the distribution for a full list.
#======================================================================

=head1 NAME

Net::ICal::Todo -- Todo class

=cut

package Net::ICal::Todo;
use strict;

use base qw(Net::ICal::ETJ);

use Net::ICal::Util qw(add_validation_error);
# TODO: work on this documentation.

=head1 SYNOPSIS

  use Net::ICal::Todo;
  my $c = new Net::ICal::Todo();

=begin testing

use Net::ICal::Todo;

=end testing

=head1 DESCRIPTION

Net::ICal::Todo represents something someone needs to get done.   

=head1 BASIC METHODS

=head2 new($args)

Construct a new Todo. Parameters are in a hash.
Meaningful parameters are:

=head2 REQUIRED

=over 4

=item * organizer - a Net::ICal::Attendee for who's organizing this meeting. 

=back

=head2 OPTIONAL

=over 4

=item * dtstart - a Net::ICal::Time for when this Todo starts.

=item * duration - a Net::ICal::Duration; how long this thing will take
to do. 

=item * alarms - an array of Net::ICal::Alarm objects; reminders about
doing this item. 

=item * class - PUBLIC, PRIVATE, or CONFIDENTIAL - the creator's intention
about who should see this Todo.

=item * created - a Net::ICal::Time saying when this object was created.

=item * description - a hash with at least a content key, maybe an altrep 
and a language key. Content is a description of this Todo. 

=item * dtstamp - when this Todo was created. Will be set to the current 
time unless otherwise specified.

=item * geo - a pair of real numbers--- the latitude and longitude of 
this Todo.

=item * last_modified - a Net::ICal::Time specifying the last time this 
object was changed.

=item * location - a hash for where this Todo is taking place. The 
content key points to a string about the location; the altrep key gives 
an alternate representation, for example a URL.

=item * priority - a number from 0 (undefined) to 1 (highest) to 
9 (lowest) representing how important this event is.

=item * status - NEEDS-ACTION, IN-PROGRESS, COMPLETED, or CANCELLED; 
the status of this todo item.

=item * summary - a one-line summary of this Todo. If you need more 
space, use the description parameter.

=item * uid - a globally unique identifier for this event. Will be created
automagically.

=item * url - a URL for this Todo. Optional.

=item * attach - a Net::ICal::Attach - attached file for this Todo. 

=item * attendee - who's going to be at this meeting; an array of 
Net::ICal::Attendee objects.

=item * categories - what categories this event falls into. Make up 
your own categories. Optional.

=item * comment - a hash like that for description (above), comments 
on this Todo item.

=item * contact - a string describing who to contact about this Todo.

=item * request_status - how successful we've been at scheduling this Todo 
so far. Values can be integers separated by periods. 1.x.y is a preliminary 
success, 2.x.y is a complete successful request, 3.x.y is a failed request 
because of bad iCal format, 4.x.y is a calendar server failure. 

=item * related_to - an array of other Event, Todo, or Journal objects this 
Todo is related to. 

=item * resources - resources (such as an overhead projector) required for 
doing this task.

=item * sequence - an integer that starts at 0 when this object is 
created and is incremented every time the object is changed. 

=back

=head2 RECURRING TASKS

=over 4

=item * recurrence_id - if this task occurs multiple times, which occurrence of
it is this particular task?

=item * rdate - an array of Net::ICal::Time objects describing repeated occurrences
of this task. 

=item * rrule - an array of Net::ICal::Recurrence objects telling when
this task repeats. 

=item * exdate - a Net::ICal::Time giving a single-date exception to a 
recurring task.

=item * exrule - an array of  Net::ICal::Recurrence objects giving a 
recurring exception to a recurring task.

=back

=for testing
ok($c = Net::ICal::Todo->new , "Simple creation should return an object");

=cut

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

    my $self = &_create ($class, %args);
    return undef unless (defined $self);
    $self->_init;
    return undef unless ($self->validate);

    return $self;
}

=pod

=head2 $class->validate

Validates the properties of a Todo.  Returns 1 for success, undef for
failure.

TODO: make sure that this object has the bare minimum requirements
specified by the RFC.

=for testing
ok( $c->validate , "Simple todo should pass");

=cut

sub validate {
    my ($self) = @_;

    if (defined $self->due and $self->duration) {
	add_validation_error ($self, "Can't have both due and duration in one Todo");
    }
    if ($self->dtstart and $self->due) { # 4.8.2.3
	my $foo = $self->dtstart->compare ($self->due);
	if ($self->dtstart->compare ($self->due) > 0) {
	add_validation_error ($self, "the due time must not be earlier than the dtstart time");
	}
    }
    if ($self->completed and $self->completed !~ /Z$/) { # 4.8.2.1
	add_validation_error ($self, "The completed date/time MUST be a UTC value");
    }

    return $self->SUPER::validate;
}

=pod

=head1 DEVELOPER METHODS

The following methods are probably not of interest to you unless you are
a Reefknot developer.

=head2 $c->_create(%args)

Class::MethodMapper creation routine.

=for testing
#ok($c->_create(%args), "Simple _create call");

=cut

sub _create {
    my ($class, %args) = @_;

    # don't pass in the %args just yet, as we don't have a complete
    # map
    my $self = $class->SUPER::_create ('VTODO');

    # add new elements to the map. 
    my $map = {	
	completed => { # 4.8.2.1
	    type => 'parameter',
	    doc => 'the time this to-do was completed',
	    domain => 'ref',
	    options => 'Net::ICal::Time',
	    value => undef,
	},
	percent_complete => { # RFC2445 4.8.1.8 - optional in a VTODO 
	    type => 'parameter',
	    doc => 'how completed this task is',
	    value => undef, 
	},
	due => { # RFC2445 4.8.2.3 - optional in a VTODO 
	    type => 'parameter',
	    doc => 'when this has to be done',
	    domain => 'ref',
	    options => 'Net::ICal::Time',
	    value => undef, 

	},
    };
    # add the extra map item definitions
    $self->set_map (%$map);
    
    # now fill in the map values
    $self->set (%args);

    return $self;
}

1;

=head1 SEE ALSO

More documentation pointers can be found in L<Net::ICal>.

=cut