NAME

TDcal —

TDcal Perl programming library

SYNOPSIS

use TDcal;

use TDcal qw($tderr);

use TDcal qw($tdprog $tdvflag);

use TDcal qw($tdtzone);

use TDcal qw($tdadealerts $tdalerts $tddaemonsync $tddir $tdlperiod $tdtime24h $tdwesplit $tdwkstart);

use TDcal qw($tdauthor $tdcompany $tdemail $tdweb);

use TDcal qw($tdprodid);

use TDcal qw($tdhelpdir $tdicondir);

$tri =
tdrcload($rccal, $encoding);

$err =
tdrcsave($calref);

($cals_read, $cals_deleted, $eventcount) =
tdread($cals);

@cals =
tdcals();

$calref =
tdcalref($cal);

$event =
tdcalevent($cal, $id);

$val =
tdcalgetattrib($cal, $attrib);

$bool =
tdcalsetattrib($cal, $attrib, $value);

$err =
tdeventadd($cal, $newevent, $tzone);

$err =
tdeventdelete($cal, $id);

$event =
tdeventcopy($cal, $id);

$err =
tdeventmove($event, $new_start, $new_finish);

$evt_list =
tdeventtimes($calref, $id, $pstart, $pfinish);

$tag =
tdmktag($start, $cal, $id);

($start, $cal, $id) =
tdxtag($tag);

$evt_list =
tdlist($cals, $patt, $pstart, $pfinish);

$evt_list =
tdlist_filter($evt_list, $pstart, $pfinish);

$bool =
tdalldayevent($cal, $id);

$bool =
tdrepeatingevent($cal, $id);

$err =
tdicalimport($cal, $file, $encoding);

$ical =
tdicalexport($cals, $idlist);

$err =
tdeventloadmisc($cal, $id);

$err =
tdsync();

$cal =
tdgetactivecal();

tdsetvflag($prog, $vflag);

tdlog($prog, $module, $msgs);

$errstr =
tderrstr($msgs);

DESCRIPTION

TDcal is the Perl programming API for the TDcal(7) calendar system.

The TDcal API allows calendar applications to be developed. Programs can interface with the TDcal calendars and can discover and load calendars, add and delete events, list events occuring within date ranges, synchronize calendars with remote servers and manage new calendars discovered from remote servers.

PROGRAMMING API

All TDcal API functions use or return the following varibales:

$cals: a hashref naming a set of calendars, each key being a $cal calendar name.
@cals: a list of calendars.
$cal: a string naming a calendar.
$patt: a Perl regular expression.
$pstart, $pfinish: period date strings in the form ‘yyyymndd[hhmmss]’.
$event: a hashref pointing to an $event structure, see TDcal(7).
$id: a UID string naming a single event.
$idlist: an arrayref pointing to multiple event $id's.
$attrib: a string naming a calendar attribute.
$val: an arbitrary value response.
$bool: a boolean $true or $false value.
$err: an error indication response: undef to indicate an error or $true to indicate success.
$tri: a tri-value set to $error in the event of an error, zero to indicate nothing was done or a positive value in the event of success.

The TDcal library makes the following variables available for export:

$tderr is used to return error condition information. If any TDcal function returns an error indication, $tderr will contain one or multiple lines of error messages. These can be given to tdlog() to store in the log file or to tderrstr() which prepends the program name suitable for display to the user as standard error messages.

$tdprog contains the current program name and $tdvflag contains the verbose flag. These are both set using tdsetvflag() which is usually invoked early in an application. The program name is used in log and error messages and the verbose flag controls whether the library functions emit additional verbose messages on standard error.

$tdtzone is the local calendar timezone. It affects the times in which events are displayed to the user. Internally, TDcal stores all event times in ‘UTC’.

The following variables reflect the user's global configuration settings:

$tdadealerts: The time offsets in minutes for all-day event notifications.
$tdalerts: The time offsets in minutes for in-day event notifications.
$tddaemonsync: The time in minutes for the tdd(1) daemon server polls.
$tddir: The path of the user's calendar directory.
$tdlperiod: The number of days for which td(1) will display forthcoming events.
$tdtime24h: This is a boolean flag that controls whether times are displayed in 24-hour format even in locales where am/pm is the norm.
$tdwesplit: This is a boolean flag that controls if the tdg(1) calendar display shows the weekend split around the weekdays (i.e., Sun-Sat) or at the end of the week (i.e., Mon-Sun).
$tdwkstart: This determines the day on which the week starts. Mon = 1.

The following variables say a bit about the author and are used in help and about messages:

$tdauthor: The author's name.
$tdcompany: The author's company.
$tdemail: The author's email.
$tdweb: The TDcal web site.

$tdprodid is the RFC5545 iCalendar PRODID string that is included in all calendars exported by TDcal.

$tdhelpdir and $tdicondir are the paths of the directories containing the TDcal TDcal help files and icons, respectively.

These are the TDcal library functions:

tdrcload() initializes the calendar structures from the TDcal configuraton file named by $rcfile. With no argument, tdrcload() reads the main configuration file; with an argument, it reads the configuration file specified. Modification times of the config files are recorded and tdrcload() returns without doing anything if a config file is unchanged since it was last read - this allows it to be invoked from a repeating idle loop to reload the config files if they changed. The $encoding argument specifies the character set of the configuration file with ‘utf-8’ used if unset. tdrcload() returns a tri-value set to $error in the event that an error occurred, e.g., the configuration file does not exist or cannot be read, $false if all is OK but no configuration was read because nothing changed since last time, and $true if one or more configuration files were (re)read.

tdrcsave() saves a calendar's individual configuration file. There is no mechanism at the moment to save the main configuration file - this must be edited and updated using a text editor.

tdread() reads calendar cache files for the calendars learned from an earlier call to tdrcload() and initializes the event structures. It returns counts of the number of calendars successfully read, the number of calendars that were deleted and the total number events actually read. Note, however, that if tdrcload() is also invoked prior to tdread(), tdrcload() will remove any calendars that have been deleted so tdread() will no longer see them and will report 0 for $cals_deleted.

tdcals() returns a list of calendars. Each list value can be used as a $cal argument in the other functions.

tdcalref() returns a hashref to a calendar. This can be used as a $calref argument in the other functions.

tdcalevent() returns a hashref to an event. This can be used as a $event argument in the other functions.

tdcalgetattrib() and tdcalsetattrib() are used to get and set calendar attributes. Values for the $attrib argument correspond to calendar attributes specified in the configuration file read in using tdrcload() and also learned when synchronizing with a CalDAV server using tdsync(). Attributes are things like a calendar's color or tzone timezone.

tdeventadd() adds a new event to a calendar or updates an existing event.

tdeventdelete() deletes an event from a calendar.

tdeventcopy() copies the details of an event out of a calendar and returns a hashref to the copy. Any changes made to an event copy must be re-added to a calendar using tdeventadd().

tdeventmove() changes the start and finish times of an individual event such as returned by tdeventcopy(). If the event has repetition dates or exclusion dates, those are adjusted too. After calling tdeventmove(), the changed event must be re-added to a calendar using tdeventadd().

tdeventtimes() expands a single event and returns a hashref of event instances keyed by ‘tag’. That is, it expands an event to all its repetition instances within the period indicated by $pstart to $pfinish which are given in the UTC timezone.

tdmktag() and tdxtag() make and extract $tag values. Tags are strings containing an event instance's start time, its calendar name and its id and these tag strings are widely used as hash keys in to store event details.

tdlist() searches calendars and returns a hashref of events keyed by ‘tag’. Repeating events are evaluated to find all instances of the event within the desired search period; there may be multiple instances of an event present in the return value for repeating events. All of the arguments may have the undef value; if all four are undefined, tdlist() returns all events in all calendars. Providing a $cals argument limits the search to just those calendars. Providing a $patt argument limits the search to events whose summary or description matches the pattern (matched case-independently). Providing $pstart and $pfinish arguments restricts the result to events within the specified period and are given in the UTC timezone. Note that because repeating events without end COUNT or UNTIL specifiers continue infinitely into the future, tdlist() limits searches with an undefined $pfinish to 100 years in the future. To search beyond then, an explicit $pfinish value must be provided. tdlist() returns a hashref of events.

tdlist_filter() further filters an existing list returned by a prior call to tdlist(). Using tdlist_filter() on an existing list is faster than re-evaluating all events in a new search. For example, use tdlist() to get all events in a specific month, then use tdlist_filter() to get events for a specific day from the month list. tdlist_filter() also returns a hashref of events.

tdalldayevent() checks if an event is an all-day event.

trepeatingevent() checks if an event is a repeating event.

tdicalimport() parses an iCalendar file and imports all events found into the calendar. $cal must be a reference to a single calendar, $file names the file to be imported and $encoding names the character set of the input file with ‘utf-8’ used if unset.

tdicalexport() takes a list of event ids and produces an iCalendar file contining all the events. $cals must be a reference to one or more calendars which will be searched for the events. $idlist is an arrayref to a list of event ids to be included in the generated calendar. Using tdicalexport(), events can be exported from multiple calendars into a single new calendar. tdicalexport() returns the generated calendar in $ical which will be undef if errors were encountered.

tdeventloadmisc() reads an event's iCalendar file and loads additional details that are not also stored in the calendar's cache file. See the description of the $event hash, below, for what is currently loaded by this function. $cal must be a reference to a single calendar and $id is the id of the event to be loaded.

tdsync() synchronizes the referenced calendars with their remote servers. Events and storage directories calendars no longer present on their remote servers are removed locally. $cals is a reference to one or more calendars to be synchronized. Note that if a CalDAV collection is given, all calendars under that collection on the server will be synchronized.

tdgetactivecal() reutrns the calendar which has the ‘active’ attribute set. ‘active’ is an attribute flag that can be set on a calendar using tdcalsetattrib() to indicate the user's choice of active calendar, i.e., the calendar which new events should be created in.

tdsetvflag() sets the program name and the logging verbosity for TDcal library functions. $prog sets the program name which is used in error messages and in verbose logging messages. $vflag sets or clears verbose logging flag - typically this is used when the user provides a -v flag or other similar request for detailed messages.

tdlog() writes messages to the TDcal log file. $prog and $module indicate the source of the message and $msgs is a string containing one or more lines of messages to be logged. $msgs is split into lines of individual $msg messages and each message logged will be of the form:

yyyy/mn/dd hh:mm:ss $prog: $module $msg

If verbose mode is enabled, tdlog() also writes the same $msg messages to standard error but without the date and time.

tderrstr() takes a $msgs error string which may contain one or multiple lines of error messages and formats it by prepending the program name to each line. The program name is set using an earlier call to tdsetvflag(). Double newlines and also trailing newlines are removed from the formatted result. The formatted result is suitable for display to the user.

DATA STRUCTURES

$cal is a calendar name as listed in the TDcal configuration file or as learned from a CalDAV server.

To access calendar data, a reference to the calendar's individual hash is first obtained using: $calref = tdcalref($cal);. The calendar data can then be accessed using the following fields or using tdcalgetattrib() and tdcalsetattrib():

$calref->{active}: flag to indicate currently-active calendar
$calref->{adealerts}: flag to enable alerts for all-day events
$calref->{alerts}: the calendar's notification times
$calref->{cachemtime}: the modification time of the .cache file.
$calref->{charset}: the calendar's character set
$calref->{color}: the calendar's display color
$calref->{ctag}: server's change tag for this calendar
$calref->{dir}: the storage directory of the calendar
$calref->{events}->{$id}: an individual $event in a calendar
$calref->{hrefs}->{$href}: hashref used to map the server's hrefs to calendar ids
$calref->{name}: the name of the calendar
$calref->{noclean}: flag to indicate not to remove empty storage directories
$calref->{oauth}: OAuth refresh token
$calref->{oasvc}: OAuth service name
$calref->{pass}: password for CalDAV server access authorization
$calref->{readonly}: flag to indicate that the calendar is read-only
$calref->{type}: the calendar type: "local", "ical", "caldav", "caldav_cal"
$calref->{tzone}: the calendar's default timezone
$calref->{updfreq}: the calendar's update frequency in seconds
$calref->{url}: for ical and caldav calendars, the user's configured URL
$calref->{url_cal}: for caldav calendars, the calendar-specific URL received from the server
$calref->{url_homeset}: for caldav calendars, the calendar-home-set URL received from the server
$calref->{url_principal}: for caldav calendars, the calendar-principal URL received from the server
$calref->{user}: username for CalDAV server access authorization

$id is an event's id string. It can take any form, as determined by whatever software created the event in the first place. When generating new id strings, care must be taken to ensure that they are unique in the calendar across all hosts and clients. TDcal events' iCalendar data is stored in the calendar storage directory in spearate files named by the id. Filesystem characters in id names (e.g., ‘/’) are hex encoded before use.

$idlist is an arrayref of $id calendar ids:

$idlist->[0]: first $id
$idlist->[1]: second $id
...

$event is a hashref with the details of one event. An event reference is obtained using: $event = tdcalevent($cal, $id);. Event hashes have the following contents. These correspond to the event's iCalendar data records of the same (or similar) name:

$event->{created}: the date and time of the event's creation
$event->{description}: the event's description (blank if same as {summary})
$event->{dtstamp}: same as {last_modified}, if present
$event->{duration}: the event's duration in seconds
$event->{exdate}: the event's repetition exclusion dates
$event->{exrule}: the event's repetition exclusion rule (deprecated)
$event->{finish}: the event's finish time "yyyymndd" or "yyyymnddhhmmss" in UTC
$event->{id}: the event's unique UID
$event->{last_modified}: the date and time of the event's last modification
$event->{location}: the event's location
$event->{rdate}: the event's repetition inclusion dates
$event->{row_finish}: 15-minute finish slot on graphical display of events
$event->{row_start}: 15-minute start slot on graphical display of events
$event->{rrule}: the event's repetition inclusion rule
$event->{sequence}: the event's edit sequence number
$event->{start}: the event's start time "yyyymndd" or "yyyymnddhhmmss" in UTC
$event->{summary}: the event's summary (first line of {description})
$event->{tag}: unique tag string
$event->{tz_finish}: timezone of the event's {finish}
$event->{tz_start}: timezone of the event's {start}
$event->{valarm}->{0..N}: the iCalendar VALARM values, indexed from 0 upwards

Client-specific data can also stored. Clients typically use this field as a hashref with their own additional data items:

$event->{csd}: client-specific data

And some data obtained from the server:

$event->{etag}: the event's entity tag from the server
$event->{href}: the event's URL on the server
$event->{uptodate}: flag to show event is synchronized with server and saved locally

As well as iCalendar data that is not used by TDcal itself but which is saved and can be loaded by tdeventloadmisc() typically before an event is updated or exported:

$event->{attach}: the iCalendar ATTACH value
$event->{attendee}: the iCalendar ATTENDEE value
$event->{categories}: the iCalendar CATEGORIES value
$event->{class}: the iCalendar CLASS value
$event->{comment}: the iCalendar COMMENT value
$event->{completed}: the iCalendar COMPLETED value
$event->{contact}: the iCalendar CONTACT value
$event->{due}: the iCalendar DUE value
$event->{geo}: the iCalendar GEO value
$event->{method}: the iCalendar METHOD value
$event->{organizer}: the iCalendar ORGANIZER value
$event->{percent_complete}: the iCalendar PERCENT-COMPLETE value
$event->{priority}: the iCalendar PRIORITY value
$event->{recurrence_id}: the iCalendar RECURRENCE-ID value
$event->{related_to}: the iCalendar RELATED-TO value
$event->{resources}: the iCalendar RESOURCES value
$event->{status}: the iCalendar STATUS value
$event->{transp}: the iCalendar TRANSP value
$event->{url}: the iCalendar URL value

$evt_list is a hashref of $event events referenced by their $tag values:

$evt_list->{$tag}->{duration}: the duration of this event
$evt_list->{$tag}->{finish}: the finish of this event
$evt_list->{$tag}->{start}: the start of this event

$tag values are strings containing an event instance's start time, its calendar name and its ID. They are created using tdmktag() and extracted using tdxtag().

$pstart and $pfinish are date strings in the format ‘yyyymnddhhmmss’.

RETURN VALUE

Functions returning $tri return a tri-value: $error on error, zero to indicate nothing was done or a positive value in the event of success.

Functions returning $bool return a boolean $true or $false value.

Functions returning $err return $true on success, undef on error.

Functions returning $cals return a hashref of calendars.

Functions returning @cals return a list of calendars.

Functions returning $evt_list return a hashref of events indexed by ‘tag’.

The functions use an error return variable, $tderr to store one or multiple lines of error messages. It is intended that $tderr is either logged using tdlog() or formatted using tderrstr() and displayed to the user in the event of an error. It should be noted that several functions loop through calendars or through events and may return many lines of error messages in $tderr, possibly hundreds or even thousands for large calendars, so care should be taken when displaying any errors in a GUI to use a scrolling window.

ERRORS, LOGS and VERBOSE MODE

A note about the TDcal error handling, logging and verbose mode.

While many functions do set the $tderr error string variable, some do not.

The functions that make permanent changes to the calendar store, such as creating and removing calendar directories as well as creating, updating and removing events, and also the functions that perform network operations, all log what they are doing directly in the log file. These are status messages, not error messages. Of course, such operations can fail and error messages are then generated too. Errors from these functions are typically also logged directly to the log file rather than being returned to the caller in $tderr. In such cases, only an error return is given to the caller.

This proved necessary in order to be able to watch the log file and see the status messages and errors happening in real time. Returning errors to the caller meant long delays before errors are displayed (due to some functions looping to process multiple events or multiple calendars each with multiple events and also due to network timeouts sometimes taking a long time) and it meant that status messages and associated error messages ended up being displayed out of order. Having these functions enter their errors directly in the log was much more useful (and much simpler) than returning lists of status messages and errors.

It should also be noted that these functions are typically called by daemons that do not have a means of displaying errors to users and which would just log the error anyway.

FILES

See TDcal(7).

STANDARDS

See TDcal(7).

HISTORY

See TDcal(7).