• NAME
• SYNOPSIS
• DESCRIPTION
• EXAMPLES
• Conflicts
• STATE VARIABLES
• METHODS
• AUTHOR

NAME

Calendar::Schedule - for managing calendar schedules

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
    $TTable->set_first_week('now');
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();
    print "<p>\n" . $TTable->generate_table();

    # etc.  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 fine to:

  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

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

  May   6      birthday (yearly entry)

DESCRIPTION

Description ...

Attempted to match the internal data representation with the iCalendar standard (RFC2445). Examples of the iCalendar fields: DTSTART, DTEND, SUMMARY, RRULE (e.g. RRULE:FREQ=WEEKLY, RRULE:FREQ=WEEKLY;INTERVAL=2 for biweekly, RRULE:FREQ=WEEKLY;UNTIL=20040408 ) etc.

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)
    EOT
    );
    print "<p>\n" . $TTable->generate_table();

This will produce the following HTML code (if run before Apr 8, 2005):

	Monday	Tuesday	Wednesday	Thursday	Friday	Saturday	Sunday
08:00
10:00		Teaching (ECMM 6014)		Teaching (ECMM 6014)
11:30
12:00
13:30			DNLP
14:30					MALNIS
15:30	Teaching (CSCI 3136)		Teaching (CSCI 3136)		Teaching (CSCI 3136)
16:00				WIFL
16:30
17:00

Conflicts

Time conflicts are handled by producing several columns in a table for the same day. For example, the following code (example3):

    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)
    Wed 15-16 meeting
    Wed 15:30-18 another meeting

    EOT
    );
    print "<p>\n" . $TTable->generate_table();

will produce the following table (if run before Apr 8, 2005):

	Monday	Tuesday	Wednesday			Thursday	Friday	Saturday	Sunday
08:00
10:00		Teaching (ECMM 6014)				Teaching (ECMM 6014)
11:30
12:00
13:30			DNLP
14:30							MALNIS
15:00				meeting
15:30	Teaching (CSCI 3136)		Teaching (CSCI 3136)		another meeting		Teaching (CSCI 3136)
16:00						WIFL
16:30
17:00
18:00

STATE VARIABLES

StartTime

Start time for various uses. Usually it is the the beginning of the first interesting week.

METHODS

new()

Creates a new Calendar::Schedule object and returns it.

set_first_week(time)

sets start time at the last Monday before given date. see parse_time =cut sub set_first_week { my $self = shift; my $arg = shift; my $starttime = &parse_time($arg);

    $self->{'StartTime'} = $self->{'ContextTime'} =
        &find_week_start($starttime);
}

set_ColLabel(pattern)

sets strftime pattern for column (day) labels. The default pattern is ``%A<br>%Y-%m-%d'', which produces labels like:

  Friday
  2003-12-19

In order to have just a weekday name, use ``%A''.

parse_time(time_specification[,prefix])

Parses time specification and returns the calendar time (see mktime in Perl). The functions dies if the time cannot be completely recognized. If prefix is set to true (1), then only a prefix of the string can be a time specification. If prefix is set to 1, then in an array context it will return a 2-element list: the calendar time and the remainder of the string. Format examples:

  2004-03-17
  now
  Mar 8, 2004
  1-Jul-2005

add_entries_from(file_name)

Adds entries from a file. See method add_entries and add_entry for format explanation.

add_entries(list_of_entries)

Adds more entries. Each entry may contain several entries separated by a new-line, except if the line ends with \. Empty lines and lines that start with \s*# are ignored. See add_entry for further explanation of format.

add_entry(list_of_entries)

Adds more entries. It is different from add_entries because this method does not break entries on new-lines, although it does accept a list of entries as arguments.

Examples:

  $TTable->add_entry('Mon 8-17', 'Labour Day');
  $TTable->add_entry('2003-09-09 Tue 18-20 Some meeting');

More format examples:

  Wed 3-4:30pm meeting
  Mon,Wed,Fri 15:30-16:30 meeting (product team)
  Mon 13-14 seminar :biweekly :start Mar 8, 2004
  Tue,Thu 10-11:30 Class (ECMM 6014) Location: MCCAIN ARTS&SS 2022 :until Apr 8, 2004

find_next_time(time_spec[,start_time])

Finds next time starting from start_time according to time_spec specification and returns it. If the start_time is not given, the variable StartTime is used.

Examples:

    $t = $schedule->find_next_time("23:59", $t);

generate_table()

Returns a weekly table in HTML. Starts with NextTableTime (or StartTime if NextTableTime does not exist), and updates NextTableTime so that consecutive call produces a new table.

AUTHOR

Copyright 2003-2004 Vlado Keselj www.cs.dal.ca/~vlado

This script is provided ``as is'' without expressed or implied warranty. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The latest version can be found at http://www.cs.dal.ca/~vlado/srcperl/.