.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "iCal::Parser::SAX 3pm"
.TH iCal::Parser::SAX 3pm "2015-06-09" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
iCal::Parser::SAX \- Generate SAX events from an iCalendar
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use iCal::Parser::SAX;
\&  my $parser=iCal::Parser::SAX\->new(Handler=>SAXHandler,%args);
\&  $parser\->parse_uri($file);
\&  $parser\->parse_uris(@files);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module uses iCal::Parser to generates \s-1SAX\s0 events
for the calendar contents.
.PP
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).
.PP
The basic structure of the generated document (if output through
a simple output handler like \f(CW\*(C`XML::SAX::Writer\*(C'\fR), is as follows:
.PP
.Vb 10
\&  <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>
.Ve
.PP
Along with basics, such as converting calendar attributes
to lowercase elements (e.g., a \f(CW\*(C`DTSTART\*(C'\fR attribute in the input
would generate a sax event like \f(CW\*(C`element({Name=\*(C'\fR'dtstart'})>),
a number of other processes occur:
.IP "\(bu" 4
\&\f(CW\*(C`day\*(C'\fR 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 \f(CW\*(C`conflict\*(C'\fR, containing the number of concurrent
overlaps, is added to the element.
.IP "\(bu" 4
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.
.SH "METHODS"
.IX Header "METHODS"
Along with the standard \s-1SAX\s0 parsing methods \f(CW\*(C`parse_uri\*(C'\fR, \f(CW\*(C`parse_file\*(C'\fR, etc.),
the following methods are supported.
.SS "new(%args)"
.IX Subsection "new(%args)"
Create a new \s-1SAX\s0 parser. All arguments other than \f(CW\*(C`Handler\*(C'\fR and
\&\f(CW\*(C`no_escape\*(C'\fR are passed to iCal::Parser.
.PP
\fIArguments\fR
.IX Subsection "Arguments"
.IP "Handler" 4
.IX Item "Handler"
The \s-1SAX\s0 handler.
.IP "no_escape" 4
.IX Item "no_escape"
If not set, quotes, ampersands and apostrophes are converted to entites.
In any case < is converted to an entity, \f(CW\*(C`\e\en\*(C'\fR is converted to
the return entity and double backslashes (\f(CW\*(C`\e\e\*(C'\fR) are removed.
.SS "parse_uris(@uris)"
.IX Subsection "parse_uris(@uris)"
Pass all the input uris to \f(CW\*(C`iCal::Parser\*(C'\fR and generate
a combined output calendar.
.SS "parse_hash($hash)"
.IX Subsection "parse_hash($hash)"
Parse the hash returned from iCal::Parser::calendar directly.
.SH "AUTHOR"
.IX Header "AUTHOR"
Rick Frankel, cpan@rickster.com
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
\&\s-1LICENSE\s0 file included with this module.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
iCal::Parser, XML::SAX::Base