← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libdata-ical-perl/quantal

« back to all changes in this revision

Viewing changes to lib/Data/ICal/Entry.pm

  • Committer: Bazaar Package Importer
  • Author(s): Jonathan Yu, Nathan Handler, gregor herrmann
  • Date: 2009-07-13 19:53:11 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20090713195311-i3yhxyumglrjgzjc
Tags: 0.16+dfsg-1
* New upstream release
  + Fixed escaping of backslash (\) characters
  + Always use CRLF as the newline character, per RFC 3445
* Added /me to Uploaders and Copyright
* Standards-Version 3.8.2 (no changes)
* Use shorter debhelper format
* debian/rules: Get around Module::Install 0.85 bug, which causes
  CPAN to be executed during build (ick!)

[ Nathan Handler ]
* debian/watch: Update to ignore development releases.

[ gregor herrmann ]
* debian/control: bump debhelper to 7.0.50 (override_* feature).

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/Data/ICal/Entry.pm
6
6
use Data::ICal::Property;
7
7
use Carp;
8
8
 
 
9
use constant CRLF => "\x0d\x0a";
 
10
 
9
11
=head1 NAME
10
12
 
11
13
Data::ICal::Entry - Represents an entry in an iCalendar file
12
14
 
13
 
 
14
15
=head1 SYNOPSIS
15
16
 
16
17
    my $vtodo = Data::ICal::Entry::Todo->new();
21
22
    $calendar->add_entry($vtodo);
22
23
 
23
24
    $event->add_entry($alarm); 
24
 
  
 
25
 
25
26
=head1 DESCRIPTION
26
27
 
27
 
A L<Data::ICal::Entry> object represents a single entry in an iCalendar file.
28
 
(Note that the iCalendar RFC refers to entries as "components".)  iCalendar
29
 
defines several types of entries, such as events and to-do lists; each of
30
 
these corresponds to a subclass of L<Data::ICal::Entry> (though only to-do
31
 
lists and events are currently implemented).  L<Data::ICal::Entry> should be treated
32
 
as an abstract base class -- all objects created should be of its subclasses.
33
 
The entire calendar itself (the L<Data::ICal> object) is also represented
 
28
A L<Data::ICal::Entry> object represents a single entry in an
 
29
iCalendar file.  (Note that the iCalendar RFC refers to entries as
 
30
"components".)  iCalendar defines several types of entries, such as
 
31
events and to-do lists; each of these corresponds to a subclass of
 
32
L<Data::ICal::Entry> (though only to-do lists and events are currently
 
33
implemented).  L<Data::ICal::Entry> should be treated as an abstract
 
34
base class -- all objects created should be of its subclasses.  The
 
35
entire calendar itself (the L<Data::ICal> object) is also represented
34
36
as a L<Data::ICal::Entry> object.
35
37
 
36
 
Each entry has an entry type (such as C<VCALENDAR> or C<VEVENT>), a series
37
 
of "properties", and possibly some sub-entries.  (Only the root L<Data::ICal>
38
 
object can have sub-entries, except for alarm entries contained in events and
39
 
to-dos (not yet implemented).)
 
38
Each entry has an entry type (such as C<VCALENDAR> or C<VEVENT>), a
 
39
series of "properties", and possibly some sub-entries.  (Only the root
 
40
L<Data::ICal> object can have sub-entries, except for alarm entries
 
41
contained in events and to-dos (not yet implemented).)
40
42
 
41
43
=head1 METHODS
42
44
 
50
52
 
51
53
sub new {
52
54
    my $class = shift;
53
 
    my $self = $class->SUPER::new;
54
 
    $self->set(properties => {});
55
 
    $self->set(entries => []);
 
55
    my $self  = $class->SUPER::new;
 
56
    $self->set( properties => {} );
 
57
    $self->set( entries    => [] );
56
58
    return $self;
57
59
}
58
60
 
59
 
=head2 as_string
60
 
 
61
 
Returns the entry as an appropriately formatted string (with trailing newline).
62
 
 
63
 
Properties are returned in alphabetical order, with multiple properties of the same name
64
 
returned in the order added.  (Property order is unimportant
65
 
in iCalendar, and this makes testing easier.)
 
61
=head2 as_string [ crlf => C<CRLF> ]
 
62
 
 
63
Returns the entry as an appropriately formatted string (with trailing
 
64
newline).
 
65
 
 
66
Properties are returned in alphabetical order, with multiple
 
67
properties of the same name returned in the order added.  (Property
 
68
order is unimportant in iCalendar, and this makes testing easier.)
66
69
 
67
70
If any mandatory property is missing, issues a warning.
68
71
 
 
72
The string to use as a newline can optionally be specified by giving
 
73
the a C<crlf> argument, which defaults to C<\x0d\x0a>, per RFC 2445
 
74
spec; this option is primarily for backwards compatability with
 
75
versions of this module before 0.16.
 
76
 
69
77
=cut
70
78
 
71
79
sub as_string {
72
80
    my $self = shift;
73
 
    my %args = (@_);
74
 
    my $output = $self->header;
 
81
    my %args = (
 
82
        crlf => CRLF,
 
83
        @_
 
84
    );
 
85
    my $output = $self->header(%args);
75
86
 
76
87
    for my $name (
77
88
        $self->mandatory_unique_properties,
80
91
    {
81
92
        carp "Mandatory property for " . ( ref $self ) . " missing: $name"
82
93
            unless $self->properties->{$name}
83
 
            and @{ $self->properties->{$name} };
 
94
                and @{ $self->properties->{$name} };
84
95
    }
85
96
 
86
97
    for my $name ( sort keys %{ $self->properties } ) {
91
102
    for my $entry ( @{ $self->entries } ) {
92
103
        $output .= $entry->as_string(%args);
93
104
    }
94
 
    $output .= $self->footer;
 
105
    $output .= $self->footer(%args);
95
106
 
96
107
    return $output;
97
108
}
98
109
 
99
110
=head2 add_entry $entry
100
111
 
101
 
Adds an entry to this entry.  (According to the standard, this should only be called
102
 
on either a to-do or event entry with an alarm entry, or on a calendar entry (L<Data::ICal>)
103
 
with a to-do, event, journal, timezone, or free/busy entry.)
 
112
Adds an entry to this entry.  (According to the standard, this should
 
113
only be called on either a to-do or event entry with an alarm entry,
 
114
or on a calendar entry (L<Data::ICal>) with a to-do, event, journal,
 
115
timezone, or free/busy entry.)
104
116
 
105
 
Returns true if the entry was successfully added, and false otherwise (perhaps because you
106
 
tried to add an entry of an invalid type, but this check hasn't been implemented yet). 
 
117
Returns true if the entry was successfully added, and false otherwise
 
118
(perhaps because you tried to add an entry of an invalid type, but
 
119
this check hasn't been implemented yet).
107
120
 
108
121
=cut
109
122
 
127
140
 
128
141
=head2 properties
129
142
 
130
 
Returns a reference to the hash of properties of this entry.  The keys are property names and
131
 
the values are array references containing L<Data::ICal::Property> objects.
 
143
Returns a reference to the hash of properties of this entry.  The keys
 
144
are property names and the values are array references containing
 
145
L<Data::ICal::Property> objects.
132
146
 
133
147
=cut
134
148
 
136
150
 
137
151
=head2 property
138
152
 
139
 
Given a property name returns a reference to the array of L<Data::ICal::Property> objects.
 
153
Given a property name returns a reference to the array of
 
154
L<Data::ICal::Property> objects.
140
155
 
141
156
=cut
142
157
 
148
163
 
149
164
=head2 add_property $propname => $propval
150
165
 
151
 
Creates a new L<Data::ICal::Property> object with name C<$propname> and value
152
 
C<$propval> and adds it to the event.
 
166
Creates a new L<Data::ICal::Property> object with name C<$propname>
 
167
and value C<$propval> and adds it to the event.
153
168
 
154
 
If the property is not known to exist for that object type and does not begin
155
 
with C<X->, issues a warning.
 
169
If the property is not known to exist for that object type and does
 
170
not begin with C<X->, issues a warning.
156
171
 
157
172
If the property is known to be unique, replaces the original property.
158
173
 
159
 
To specify parameters for the property, let C<$propval> be a two-element array reference
160
 
where the first element is the property value and the second element is a hash reference.
161
 
The keys of the hash are parameter names; the values should be either strings or array references
162
 
of strings, depending on whether the parameter should have one or multiple (to be comma-separated)
163
 
values.
 
174
To specify parameters for the property, let C<$propval> be a
 
175
two-element array reference where the first element is the property
 
176
value and the second element is a hash reference.  The keys of the
 
177
hash are parameter names; the values should be either strings or array
 
178
references of strings, depending on whether the parameter should have
 
179
one or multiple (to be comma-separated) values.
164
180
 
165
181
Examples of setting parameters:
166
182
 
174
190
    my $prop = lc shift;
175
191
    my $val  = shift;
176
192
 
177
 
 
178
193
    return unless defined $prop;
179
 
    
 
194
 
180
195
    unless ( $self->is_property($prop) or $prop =~ /^x-/i ) {
181
196
        carp "Unknown property for " . ( ref $self ) . ": $prop";
182
197
    }
192
207
    my ( $prop_value, $param_hash ) = @$val;
193
208
 
194
209
    my $p = Data::ICal::Property->new( $prop => $prop_value, $param_hash );
195
 
    $p->vcal10( $self-> vcal10 );
196
 
    
 
210
    $p->vcal10( $self->vcal10 );
 
211
 
197
212
    push @{ $self->properties->{$prop} }, $p;
198
213
}
199
214
 
200
215
=head2 add_properties $propname1 => $propval1, [$propname2 => $propname2, ...]
201
216
 
202
 
Convenience function to call C<add_property> several times with a list of properties.
203
 
 
204
 
This method is guaranteed to call add C<add_property> on them in the order given, so that
205
 
unique properties given later in the call will take precedence over those given earlier.
206
 
(This is unrelated to the order of properties when the entry is rendered as a string, though.)
207
 
 
208
 
Parameters for the properties are specified in the same way as in C<add_property>.
 
217
Convenience function to call C<add_property> several times with a list
 
218
of properties.
 
219
 
 
220
This method is guaranteed to call add C<add_property> on them in the
 
221
order given, so that unique properties given later in the call will
 
222
take precedence over those given earlier.  (This is unrelated to the
 
223
order of properties when the entry is rendered as a string, though.)
 
224
 
 
225
Parameters for the properties are specified in the same way as in
 
226
C<add_property>.
209
227
 
210
228
=cut
211
229
 
226
244
 
227
245
=head2 mandatory_unique_properties 
228
246
 
229
 
Subclasses should override this method (which returns an empty list by default)
230
 
to provide a list of lower case strings identifying the properties which must appear exactly
231
 
once in the subclass's entry type.
 
247
Subclasses should override this method (which returns an empty list by
 
248
default) to provide a list of lower case strings identifying the
 
249
properties which must appear exactly once in the subclass's entry
 
250
type.
232
251
 
233
252
=cut
234
253
 
236
255
 
237
256
=head2 mandatory_repeatable_properties 
238
257
 
239
 
Subclasses should override this method (which returns an empty list by default)
240
 
to provide a list of lower case strings identifying the properties which must appear at least
241
 
once in the subclass's entry type.
 
258
Subclasses should override this method (which returns an empty list by
 
259
default) to provide a list of lower case strings identifying the
 
260
properties which must appear at least once in the subclass's entry
 
261
type.
242
262
 
243
263
=cut
244
264
 
246
266
 
247
267
=head2 optional_unique_properties 
248
268
 
249
 
Subclasses should override this method (which returns an empty list by default)
250
 
to provide a list of lower case strings identifying the properties which must appear at most
251
 
once in the subclass's entry type.
 
269
Subclasses should override this method (which returns an empty list by
 
270
default) to provide a list of lower case strings identifying the
 
271
properties which must appear at most once in the subclass's entry
 
272
type.
252
273
 
253
274
=cut
254
275
 
256
277
 
257
278
=head2 optional_repeatable_properties
258
279
 
259
 
Subclasses should override this method (which returns an empty list by default)
260
 
to provide a list of lower case strings identifying the properties which may appear zero,
261
 
one, or more times in the subclass's entry type.
 
280
Subclasses should override this method (which returns an empty list by
 
281
default) to provide a list of lower case strings identifying the
 
282
properties which may appear zero, one, or more times in the subclass's
 
283
entry type.
262
284
 
263
285
=cut
264
286
 
266
288
 
267
289
=head2 is_property $name
268
290
 
269
 
Returns a boolean value indicating whether or not the property C<$name> is known to the class
270
 
(that is, if it's listed in C<(mandatory/optional)_(unique/repeatable)_properties>).
 
291
Returns a boolean value indicating whether or not the property
 
292
C<$name> is known to the class (that is, if it's listed in
 
293
C<(mandatory/optional)_(unique/repeatable)_properties>).
271
294
 
272
295
=cut
273
296
 
282
305
 
283
306
=head2 is_mandatory $name
284
307
 
285
 
Returns a boolean value indicating whether or not the property C<$name> is known to the class as mandatory
286
 
(that is, if it's listed in C<mandatory_(unique/repeatable)_properties>).
 
308
Returns a boolean value indicating whether or not the property
 
309
C<$name> is known to the class as mandatory (that is, if it's listed
 
310
in C<mandatory_(unique/repeatable)_properties>).
287
311
 
288
312
=cut
289
313
 
296
320
 
297
321
=head2 is_optional $name
298
322
 
299
 
Returns a boolean value indicating whether or not the property C<$name> is known to the class as optional
300
 
(that is, if it's listed in C<optional_(unique/repeatable)_properties>).
 
323
Returns a boolean value indicating whether or not the property
 
324
C<$name> is known to the class as optional (that is, if it's listed in
 
325
C<optional_(unique/repeatable)_properties>).
301
326
 
302
327
=cut
303
328
 
310
335
 
311
336
=head2 is_unique $name
312
337
 
313
 
Returns a boolean value indicating whether or not the property C<$name> is known to the class as unique
314
 
(that is, if it's listed in C<(mandatory/optional)_unique_properties>).
 
338
Returns a boolean value indicating whether or not the property
 
339
C<$name> is known to the class as unique (that is, if it's listed in
 
340
C<(mandatory/optional)_unique_properties>).
315
341
 
316
342
=cut
317
343
 
324
350
 
325
351
=head2 is_repeatable $name
326
352
 
327
 
Returns a boolean value indicating whether or not the property C<$name> is known to the class as repeatable
328
 
(that is, if it's listed in C<(mandatory/optional)_repeatable_properties>).
 
353
Returns a boolean value indicating whether or not the property
 
354
C<$name> is known to the class as repeatable (that is, if it's listed
 
355
in C<(mandatory/optional)_repeatable_properties>).
329
356
 
330
357
=cut
331
358
 
338
365
 
339
366
=head2 ical_entry_type
340
367
 
341
 
Subclasses should override this method to provide the identifying type name of the entry
342
 
(such as C<VCALENDAR> or C<VTODO>).
 
368
Subclasses should override this method to provide the identifying type
 
369
name of the entry (such as C<VCALENDAR> or C<VTODO>).
343
370
 
344
371
=cut
345
372
 
347
374
 
348
375
=head2 vcal10 [$bool]
349
376
 
350
 
Gets or sets a boolean saying whether this entry should be interpreted as vCalendar
351
 
1.0 (as opposed to iCalendar 2.0).  Generally, you can just set this on your
352
 
main L<Data::ICal> object when you construct it; C<add_entry> automatically makes
353
 
sure that sub-entries end up with the same value as their parents.
 
377
Gets or sets a boolean saying whether this entry should be interpreted
 
378
as vCalendar 1.0 (as opposed to iCalendar 2.0).  Generally, you can
 
379
just set this on your main L<Data::ICal> object when you construct it;
 
380
C<add_entry> automatically makes sure that sub-entries end up with the
 
381
same value as their parents.
354
382
 
355
383
=cut
356
384
 
364
392
 
365
393
sub header {
366
394
    my $self = shift;
367
 
    return 'BEGIN:' . $self->ical_entry_type . "\n";
 
395
    my %args = (
 
396
        crlf => CRLF,
 
397
        @_
 
398
    );
 
399
    return 'BEGIN:' . $self->ical_entry_type . $args{crlf};
368
400
}
369
401
 
370
402
=head2 footer
375
407
 
376
408
sub footer {
377
409
    my $self = shift;
378
 
    return 'END:' . $self->ical_entry_type . "\n";
 
410
    my %args = (
 
411
        crlf => CRLF,
 
412
        @_
 
413
    );
 
414
    return 'END:' . $self->ical_entry_type . $args{crlf};
379
415
}
380
416
 
381
417
# mapping of event types to class (under the Data::Ical::Event namespace)
391
427
 
392
428
=head2 parse_object
393
429
 
394
 
Translate a L<Text::vFile::asData> sub object into the appropriate 
 
430
Translate a L<Text::vFile::asData> sub object into the appropriate
395
431
L<Data::iCal::Event> subtype.
396
432
 
397
433
=cut 
414
450
    } elsif ( my $sub = $self->can( '_parse_' . lc($type) ) ) {
415
451
        $new_self = $self->$sub($object);
416
452
 
417
 
        # bitch
 
453
        # complain
418
454
    } else {
419
455
        warn "Can't parse type $type yet";
420
456
        return;
497
533
                $occurence->{value} =~ s/\\([;,\\])/$1/g;
498
534
                $occurence->{value} =~ s/\\n/\n/ig;
499
535
            }
500
 
            
 
536
 
501
537
            # handle optional params and 'normal' key/value pairs
502
538
            # TODO: line wrapping?
503
539
            if ( $occurence->{param} ) {
513
549
 
514
550
=head1 AUTHOR
515
551
 
516
 
Jesse Vincent  C<< <jesse@bestpractical.com> >> with David Glasser and Simon Wistow
517
 
 
 
552
Jesse Vincent C<< <jesse@bestpractical.com> >> with David Glasser,
 
553
Simon Wistow, and Alex Vandiver
518
554
 
519
555
=head1 LICENCE AND COPYRIGHT
520
556
 
521
 
Copyright (c) 2005, Best Practical Solutions, LLC.  All rights reserved.
 
557
Copyright (c) 2005 - 2009, Best Practical Solutions, LLC.  All rights reserved.
522
558
 
523
559
This module is free software; you can redistribute it and/or
524
560
modify it under the same terms as Perl itself. See L<perlartistic>.