NAME
    iCal::Parser::SAX - Generate SAX events from an iCalendar

SYNOPSIS
      use iCal::Parser::SAX;
      my $parser=iCal::Parser::SAX->new(Handler=>SAXHandler,%args);
      $parser->parse_uri($file);
      $parser->parse_uris(@files);

DESCRIPTION
    This module uses iCal::Parser to generates SAX events for the calendar
    contents.

    The xml document generated is designed for creating monthly calendars
    with weeks beginning on monday (e.g., by passing the output through an
    xsl styleheet).

    The basic structure of the generated document (if output through a
    simple output handler like `XML::SAX::Writer'), is as follows:

      <ical>
        <calendars>
         <calendar id="cal-id" index="n" name="..." description="..."/>
        </calendars>
        <events>
         <year year="YYYY">
           <month month="[1-12]">
             <week week="n">
               <day date="YYYY-MM-DD">
                 <event uid="event-id" idref="cal-id" [all-day="1"]>
                   <!-- ... -->
                 </event>
               </day>
             </week>
           </month>
        </events>
        <todos>
          <todo idref="cal-id" uid="...">
            <!--- ... -->
          </todo>
        </todos>
      </ical>

    Along with basics, such as converting calendar attributes to lowercase
    elements (e.g., a `DTSTART' attribute in the input would generate a sax
    event like `element({Name=''dtstart'})>), a number of other processes
    occur:

    *   `day' elements are are generated for each date within the months
        from the first month in the input to the last, even if there are no
        calendar events on that day. This guarantees a complete calendar
        month for further processing. If there is an overlap between two or
        more events, the attribute `conflict', containing the number of
        concurrent overlaps, is added to the element.

    *   If the beginning or end of the month does not start on a monday, or
        end on a sunday, the days from the previous (next) month month are
        duplicated within the first (last) week of the current month,
        including duplicate copies of any calendar events occuring on those
        days. This allows for displaying a monthly calendar the same way a
        program such as Apple's iCal would, with calendar events showing up
        if they fall within the overlapping days in the first or last week
        of a monthly calendar.

METHODS
    Along with the standard SAX parsing methods `parse_uri', `parse_file',
    etc.), the following methods are supported.

  new(%args)

    Create a new SAX parser. All arguments other than `Handler' and
    `no_escape' are passed to iCal::Parser.

    Arguments
    Handler
        The SAX handler.

    no_escape
        If not set, quotes, ampersands and apostrophes are converted to
        entites. In any case < is converted to an entity, `\\n' is converted
        to the return entity and double backslashes (`\\') are removed.

  parse_uris(@uris)

    Pass all the input uris to `iCal::Parser' and generate a combined output
    calendar.

  parse_hash($hash)

    Parse the hash returned from iCal::Parser::calendar directly.

AUTHOR
    Rick Frankel, cpan@rickster.com

COPYRIGHT
    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
    iCal::Parser, XML::SAX::Base

