This version has a few changes in the API.
Comments are welcome - module name, methods,
optimizations ...
http://www.geocities.com/fglock/DateTime-Event-
Spreadsheet-0.00_07.pl
- Flavio S. Glock
NAME
DateTime::Event::Spreadsheet - A collection of named DateTime events
SYNOPSIS
use DateTime::Event::Spreadsheet;
$dtes = DateTime::Event::Spreadsheet->new;
$dtes->set(
birthday => DateTime->new( year => 1964 )
);
print $dtes->get( 'birthday' )->datetime;
$dtes->set_function(
now => sub { DateTime->now }
);
print $dtes->get( 'now' )->datetime;
DESCRIPTION
DateTime::Event::Spreadsheet is a class for representing a collection of
DateTime events and the relations between them.
For example, a Spreadsheet could be used to store business hours
information, together with holidays.
Spreadsheet cells may contain functions (Perl subroutines). The cell
values are automatically updated.
For example, a cell could be tied to a database value, and other cells
would be automatically updated when that value changes.
Each event or function is stored in a Spreadsheet cell. All cells have
names (or keys), such as "A1", "B10", or "birthday".
A Spreadsheet may contain any combination of DateTime::* objects,
including DateTime::Event::*, DateTime::Set, DateTime::Span,
DateTime::SpanSet, other Spreadsheets, and Perl subroutines.
USAGE
Error Checking
Reference loops in 'functions' may cause the program to die when
executing "get()".
A cell may contain any type of DateTime::* objects. Exceptions are
handled by the object into the cell.
Methods
* new
This is the Spreadsheet constructor. It takes no parameters.
* keys
Each cell in the Spreadsheet has a "key". "keys()" returns the list
of all existing cell keys. Empty cells are included.
* next( $dt )
* current( $dt )
* previous( $dt )
* closest( $dt )
my ( $result, @matched_keys ) = $dtes->next( $base_date );
Returns the DateTime that best fits the function, and the list of
cells that contain it.
* clone
Returns a replica of the Spreadsheet.
"clone" is useful if you want to modify a Spreadsheet, but you want
to keep a copy of the current state.
Cell Methods
* set
my $dt = DateTime->now;
$dtes->set(
now => $dt->clone
);
Sets a cell contents. A unique "key" must be provided. Setting the
same "key" again will overwrite the previous contents.
A cell may contain any type of DateTime::* object. Exceptions are
handled by the object into the cell.
* set_function
Assign a Perl subroutine reference to a cell. A unique "key" must be
provided. Setting the same "key" again will overwrite the previous
contents.
The function will only be executed at the time the cell receives a
"get()".
Exceptions are handled by the Perl subroutine.
This is an example of how to put a Perl subroutine in a cell:
$dtes->set_function(
now => sub { DateTime->now }
);
Other cells in the spreadsheet may be accessed from inside the
function using the "$_[0]->get( 'cell_name' )" notation:
$dtes->set(
later => sub { $_[0]->get( 'now' )->add( hours => 1 ) }
);
* get
my $value = $dtes->get( 'now' );
print $value->datetime;
Returns the cell value.
If the cell contains a function, "get()" will evaluate the function
and return the result.
* set_action
Assign a Perl subroutine reference to a cell. A unique "key" must be
provided. Setting the same "key" again will overwrite the previous
contents.
The function will only be executed at the time the cell receives a
"set()".
[TODO - example. See tests.]
Internal Methods
* _raw_cell
my $value = $dtes->_raw_cell( 'now' );
print $value->{value}->datetime;
Returns the raw, unprocessed cell contents, as a hash reference.
AUTHOR
Flavio S. Glock <[EMAIL PROTECTED]>
COPYRIGHT
Copyright (c) 2004 Flavio S. Glock. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same
terms as Perl itself.
The full text of the license can be found in the LICENSE file included
with this module.
SEE ALSO
Spreadsheet::Perl
[EMAIL PROTECTED] mailing list
http://datetime.perl.org/
CHANGES
0.00_07 2004-03-06
closest, clone - but no tests.
Pod revision.
0.00_06 2004-03-03
next/current/previous()
set($value) - warns if $value is a subroutine reference
keys() is a "documented" method
0.00_05 2004-03-02
Code cleanup, syntax is more perlish
See-also: Spreadsheet-Perl
0.00_04 2004-03-02
Reference loops cause the program to die.
0.00_03 2004-03-01
Separate set/set_function methods.
set_function no longer has a parameter list
'croak' instead of warn, for invalid parameters
set_action - allows for bidirectional functions (like Date::Tie)
0.00_02 2004-02-27
[EMAIL PROTECTED] release/RFC
Separate cell/get_cell accessors
0.00_01 2004-02-27
Initial program
TODO
- Test: Put a Spreadsheet inside another Spreadsheet cell.
- Test: if next, current, previous, closest match a spanset, it extracts
the nearest DateTime from the span.
- Whole-spreadsheet methods: - "Set" operations: "give me objects in the
spreadsheet that are inside a span"; iterator...
- closest() test
union, intersection, complement
contains, intersects
min, max, span, count
$span = $dtset->as_span( <see keys() for parameters> );
$set = $dtset->as_set( <see keys() for parameters> );
$spanset = $dtset->as_spanset( <see keys() for parameters> );
@keys = $dtset->keys( span => $dtspan );
iterator
- private variables a key that starts with "_" is "internal" and would
not be listed by keys() - "greppish" keys() - accept a qr// or a sub
reference
@keys = $dtset->keys( regex => qr/.../ );
- Memoization
- Cell locking ?
- add() without clone() may have side-effects! test & document! -
clone() test
