view release on metacpan or  search on metacpan

Schedule.pm  view on Meta::CPAN

our %EXPORT_TAGS = ( 'all' => [ qw( parse_time ) ] );
our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
our @EXPORT = qw(new);

#<?echo "our \$VERSION = '$Meta->{version}';"!>#+
our $VERSION = '1.21';#-

# non-exported package globals
use vars qw( $REweekday3 $REmonth3 $RE1st );
$RE1st = qr/first|second|third|fourth|fifth|last|1st|2nd|3rd|4th|5th/;
$REweekday3 = qr/Mon|Tue|Wed|Thu|Fri|Sat|Sun/;
$REmonth3 = qr/Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec/;

=head1 NAME

Calendar::Schedule - manage calendar schedules

=head1 SYNOPSIS

    use Calendar::Schedule qw/:all/;

    my $TTable = Calendar::Schedule->new();

    # manually adding an entry
    $TTable->add_entry('2003-09-09 Tue 18-20 Some meeting');
                              
    # reading entries from a file
    $TTable->add_entries_from("$ENV{'HOME'}/.calendar");

    # producing entries in HTML tables, one table per week
    $TTable->set_first_week('now');
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();

    # for more examples, see EXAMPLES section

The file .calendar may look like this:

  # comments can start with #
  * lines starting with * are treated as general todo entries ...
  # empty lines are acceptable and ignored:

  Mon 9:00-10:00 this is a weekly entry
  Mon 13-14 a biweekly entry :biweekly :start Mar 8, 2004
  Mon,Wed,Fri 15:30-16:30 several-days-a-week entry
  Wed :biweekly garbage collection

  2004-03-06 Sat 14-16 fixed entry. The week day is redundant, but may\
        help to detect errors (error will be reported if a wrong\
        weekday is entered).  BTW, an entry can go for several lines as\
        long as there is a backslash at the end of each line.

  May   6      birthday (yearly entry)

  # more examples in "Example entries" section

=head1 DESCRIPTION

The module is created with a purpose to provide functionality for handling a
personal calendar schedule in a transparent and simple way.  The calendar
data is assumed to be kept in a plain file in a format easy to edit and
understand.  It was inspired by the C<calendar> program on older Unix-like
systems, which used C<~/.calendar> file to produce entries for each day
and send them in the morning by email.

Inspired by the C<~/.calendar> file, the format for recording scheduled
events is very simple, mostly contained in one line of text.

The module currently supports generation of HTML weekly tables with visual
representation of scheduled events.  The generated table is generated in
a simple HTML table, with a use of C<colspan> and C<rolspan> attributes to
represent overlapping events in parallel in the table.

=head2 Planned Future Work

In the development of the recording format for the event, there is an attempt
to model the data representation of the iCalendar standard (RFC2445).
Examples of the iCalendar fields are: DTSTART, DTEND, SUMMARY,
RRULE (e.g. RRULE:FREQ=WEEKLY, RRULE:FREQ=WEEKLY;INTERVAL=2 for
biweekly, RRULE:FREQ=WEEKLY;UNTIL=20040408 ) etc.
More examples:

  RRULE:FREQ=MONTHLY;BYDAY=TU;BYSETPOS=3

Every third Tuesday in a month.

=head1 EXAMPLES

First example:

    use Calendar::Schedule qw/:all/;

    my $TTable = Calendar::Schedule->new();

    # manually adding an entry
    $TTable->add_entry('2003-09-09 Tue 18-20 Some meeting');
                              
    # reading entries from a file
    $TTable->add_entries_from("$ENV{'HOME'}/.calendar");

    # producing entries in HTML tables
    $TTable->set_first_week('2003-12-15');
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();

Example with generating a weekly schedule (example2):

    use Calendar::Schedule;
    $TTable = Calendar::Schedule->new();
    $TTable->{'ColLabel'} = "%A";
    $TTable->add_entries(<<EOT
    Mon 15:30-16:30 Teaching (CSCI 3136)
    Tue 10-11:30 Teaching (ECMM 6014)
    Wed 13:30-14:30 DNLP
    Wed 15:30-16:30 Teaching (CSCI 3136) :until Apr 8, 2005
    Thu 10-11:30 Teaching (ECMM 6014)
    Thu 16-17 WIFL
    Fri 14:30-15:30 MALNIS
    Fri 15:30-16:30 Teaching (CSCI 3136)