doc.txt

iCal : An interface to iCal/vCal files

_iCal : An interface to iCal/vCal files_
==========================================

By Jay McCarthy (jay at kenyamountain dot com)

Keywords: _io_, _formats_, _pim__

Introduction
============

I wanted to write some code to munch my Apple iCal [1] files, which are in the iCalendar/vCalendar format. [2]

_ical-parser.ss_
---------------

This file contains the iCal parser and lexer. It is based on the libicalvcal yacc parser. Due to the functional nature of 'parser-tools', there's some gross stuff going on with the lexer.

If you have a problem with a file, first send the file to me, then try 'totally-lex'-ing it with the lexer then looking at the token stream separate from the parser errors.

Note: Including source location with the tokens is disabled because it takes a very long time to run on my machine.

_ical.ss_
-----------

This is the main file for the library. Require it like this:

> (require (planet "ical.ss" ("jaymccarthy" "ical.plt" 1)))

It provides the follow procedures:

> (ical->x-exprs/port port) :: filestream or string port -> (listof x-expr)

Reads the iCal at the given port, returning a list of x-expr objects, one for each top-level vObject in the file.

> (ical->x-exprs/file filename) :: filename -> (listof x-expr)

The obvious wrapper on ical->x-exprs/port.

> (ical->x-exprs/string string) :: string -> (listof x-expr)

The obvious wrapper on ical->x-exprs/port.

> (x-exprs->ical x-expr) :: (listof x-expr) -> string

Returns the given list of x-exprs as an iCal formatted string that can be printed to a file to generate an iCal file.

Examples
========

See the code in the tests/ directory.

Notes and Limitations
=====================

I've tested reading Apple iCal [1] files in and then printing them out and iCal continues to accept them. But your mileage may vary when using it with other front-ends.

I plan on creating an extension of this library that makes it easier to make changes to the iCal, but for now you can convert to SXML and use SXLT if you want.

History
=======

v1.0 :: April 5th, 2005
        * Initial revision

References
==========

1. Apple iCal
   http://www.apple.com/ical/

2. RFC 2445 - Internet Calendaring and Scheduling Core Specification (iCalendar)
   http://www.faqs.org/rfcs/rfc2445.html