root/trunk/antimatter/tim/Modules/SFLC/TimeTracker/Entry.pm

# Entry.pm                                                                 -*- Perl -*-
#  Basic Time Entry object
# Copyright (C) 2005, 2006   Software Freedom Law Center, Inc.
#  Author: Bradley M. Kuhn <bkuhn@softwarefreedom.org>
#
#  This software gives you freedom; it is licensed to you under version
#  3 of the GNU Affero General Public License.
#
#  This software is distributed WITHOUT ANY WARRANTY, without even the
#  implied warranties of MERCHANTABILITY and FITNESS FOR A PARTICULAR
#  PURPOSE.  See the GNU Affero General Public License for further
#  details.
#
# You should have received a copy of the GNU Affero General Public
# License, version 3 along with this software.  If not, see
# <http://www.gnu.org/licenses/>.

package SFLC::TimeTracker::Entry;

use strict;
use warnings;

require Exporter;
#use AutoLoader qw(AUTOLOAD);

our @ISA = qw(Exporter);

our @EXPORT_OK = qw(Create Initialize);

our @EXPORT = qw( );

our $VERSION = '0.01';

our $DATABASE;
use Carp;

use Date::Manip;

###############################################################################

=head1 NAME

SFLC::TimeTrack::Entry - Basic entry object for time tracker

=head1 SYNOPSIS

  use SFLC::TimeTrack::Entry;

  my $database = new SFLC::TimeTrack::Entry($database)

=head1 DESCRIPTION


=head2 EXPORT

None.

=head1 SEE ALSO

SFLC::TimeTrack::Input


=head1 EXTERNAL FUNCTIONS

=over

=cut

###############################################################################

=item new

usage: new($databse)

Instaniates a new object.

=head2 ARGUMENTS

=over

=item C<$method>

Storage method used.  Currently, the only valid C<$METHOD> is "MLDBM".  In
the future, I hope to implement a true database storage method.

=item C<$OPTION1>

For MLDBM, C<$option1> is the path to the file that will store the
completed time data.

=item C<$option2>

For MLDBM, C<$option2> is the path to the pending data (tasks started but
never closed).

=back

=cut

use strict;
use warnings;


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

  my $self = {};  bless $self, $class;

  $self->{needToComplete} = {};

  return $self;
}

sub Initialize {
  my($database) = shift;
  $DATABASE = $database;
}
sub neededList {
  my $self = shift;
  return keys %{$self->{needToComplete}};
}

sub isComplete {
  my $self = shift;
  return ( (keys %{$self->{needToComplete}}) == 0);
}

sub needs {
  my $self = shift;
  my $what = shift;
  if (not defined $what) {
    wantarray ? return $self->neededList() : return $self->isComplete();
 } else {
   return defined $self->{needToComplete}{$what};
 }
}
sub rebuildNeedComplete {
  my $self = shift;
  $self->{needToComplete} = {};
  if (not defined $self->{category} or $self->{category} =~ /^\s*$/) {
    $self->{needToComplete}{category} = 1;
  }

  if (defined $self->{startTime} and not defined $self->{endTime}) {
    $self->{needToComplete}{endTime} = 1;
  } elsif (defined $self->{amountTime} and not defined $self->{dateOccurred}) {
    $self->{needToComplete}{dateOccurred} = 1;
  } elsif (not defined $self->{amountTime} and defined $self->{dateOccurred}) {
    $self->{needToComplete}{amountTime} = 1;
  }
  if (defined $self->{startTime} and defined $self->{endTime} and 
      not defined $self->{amountTime}) {
    $self->{amountTime} = DateCalc($self->{startTime}, $self->{endTime});
    croak "unable to calculate date detla between $self->{startTime} $self->{endTime}"
      unless defined $self->{amountTime} and $self->{amountTime} !~ /^\s*$/;
    delete $self->{needToComplete}{amountTime};
  }
  if (defined $self->{startTime} and not defined $self->{dateOccurred}) {
    delete $self->{needToComplete}{dateOccurred};
    $self->{dateOccurred} = UnixDate($self->{startTime}, "%Y-%m-%d");
  }
}
sub set {
  my($self, $field, $value) = @_;

  unless ($field =~ /^endTime|startTime|dateOccurred|amountTime|category|lastReminded|note/) {
    carp "Unable to set field $field";
    return;
  }
  my $oldValue = $value;
  $value = $self->getDatabase()->getCategoryHandleForUserHandle($oldValue,
                                                     $self->{userHandle})
    if ($field eq "category");

  croak "$oldValue does not match to a category in the database"
    if not defined $value;

  $self->{$field} = $value;
  $self->rebuildNeedComplete;
  $self->{inDB} = $self->getDatabase()->updateEntry($self->{inDB}, $self);
}
sub get {
  my($self, $field) = @_;

  unless ($field =~ /^endTime|startTime|dateOccurred|amountTime|category|lastReminded|id|userHandle|note/) {
    carp "Unable to get field $field";
    return;
  }
  return ($field eq 'category' and defined $self->{'category'}) ?
    ($self->getDatabase()->getCategory($self->{'category'})) :
    $self->{$field};
}


sub remove {
  my($self, $field, $value) = @_;

  $self->{inDB} = $self->getDatabase()->removeEntry($self->{inDB}, $self);
}
sub getDatabase {
  return $DATABASE;
}
###############################################################################

=item Create

usage: Create($database, startTime => DATE_MANIP_VALUE,
                         endTime => DATE_MANIP_VALUE,
                         amountTime => DATE_MANIP_DELTA_VALUE,
                         dateOccurred => DATE_MANIP_VALUE,
                         userHandle => DB_USER_HANDLE,
                         category => DB_CATEGORY_HANDLE,
                         note => FREE_FORM_NOTE
                      )

Creates a new time entry, using values given, and returning the object.
'username' is required.  'category' is not required, but if given,
DB_CATEGORY_HANDLE must be a valid category handle returned by
SFLC::TimeTracker::DB.

All dates must already be prepared into canonical Date::Manip formats.
Note that 'amountTime' is a DELTA format.

If the following items are true, it will be placed in the "main" database:

=over


=item Either both startTime and  endTime are given (and are valid), or
             both amountTime and dateOccurred are given (and are valid).

=item username is valid.

=item category is given and is valid.

=back

Otherwise, then entry is inserted into the pending database.


The caller should request the array C<$object->needToComplete> for a list
of what is needed for completion.  If this list is empty, the entry is complete.


=cut

sub Create  {
  my(%values) = @_;

  my $self;
  $self = new SFLC::TimeTracker::Entry;
  $values{userHandle} = $self->getDatabase()->getUserHandle($values{username})
    if (defined $values{username} and not defined $values{userHandle});

  foreach my $req (qw/userHandle/) {
    croak "missing field $req for Entry creation" if not defined $values{$req};
  }

  foreach my $field (qw/startTime endTime amountTime userHandle/) {
    $self->{$field} = $values{$field} if defined $values{$field};
  }

  $self->{dateOccurred} = UnixDate($values{dateOccurred}, "%Y-%m-%d")
    if defined $values{dateOccurred};

  foreach my $val (qw/startTime endTime amountTime dateOccurred userHandle/) {
    $self->{$val} = undef if defined $self->{$val} and $self->{$val} =~ /^\s*$/;
  }

  $self->{category} = $values{category} if (defined $values{category});

  $self->rebuildNeedComplete;

  $self->{inDB} =  $self->isComplete() ? "main" : "pending";
  $self->{id} = $self->getDatabase()->insertEntry($self->{inDB}, $self);

  return $self;
}

1;
__END__

#
# Local variables:
# compile-command: "perl -I ../../../Modules -c Entry.pm"
# End: