4
package Data::ICal::Property;
6
use base qw/Class::Accessor/;
9
use MIME::QuotedPrint ();
11
our $VERSION = '0.06';
15
Data::ICal::Property - Represents a property on an entry in an iCalendar file
20
A L<Data::ICal::Property> object represents a single property on an
21
entry in an iCalendar file. Properties have parameters in addition to their value.
23
You shouldn't need to create L<Data::ICal::Property> values directly -- just use
24
C<add_property> in L<Data::ICal::Entry>.
26
The C<encoding> parameter value is only interpreted by L<Data::ICal> in the
27
C<decoded_value> and C<encode> methods: all other methods access
28
the encoded version directly (if there is an encoding).
30
Currently, the only supported encoding is C<QUOTED-PRINTABLE>.
36
=head2 new $key, $value, [$parameter_hash]
38
Creates a new L<Data::ICal::Property> with key C<$key> and value C<$value>.
40
If C<$parameter_hash> is provided, sets the property's parameters to it.
41
The parameter hash should have keys equal to the names of the parameters (case
42
insensitive; parameter hashes should not contain two different keys which are
43
the same when converted to upper case); the values should either be a string
44
if the parameter has a single value or an array reference of strings if
45
the parameter has multiple values.
57
$self->parameters( shift || {} );
63
Gets or sets the key name of this property.
67
Gets or sets the value of this property.
69
=head2 parameters [$param_hash]
71
Gets or sets the parameter hash reference of this property.
72
Parameter keys are converted to upper case.
76
Gets or sets a boolean saying whether this should be interpreted as vCalendar
77
1.0 (as opposed to iCalendar 2.0). Generally, you can just set this on your
78
main L<Data::ICal> object when you construct it; C<add_entry> automatically makes
79
sure that sub-entries end up with the same value as their parents, and
80
C<add_property> makes sure that properties end up with the same value as
85
__PACKAGE__->mk_accessors(qw(key value _parameters vcal10));
93
while (my ($k, $v) = each %$params) {
94
$new_params->{uc $k} = $v;
96
$self->_parameters($new_params);
99
return $self->_parameters;
103
'QUOTED-PRINTABLE' => { encode => sub {
104
my $dec = shift ||'';
106
return MIME::QuotedPrint::encode($dec, '');
109
my $dec = MIME::QuotedPrint::decode(shift ||'');
118
Gets the value of this property, converted from the encoding specified in
119
its encoding parameter. (That is, C<value> will return the encoded version;
120
this will apply the encoding.) If the encoding is not specified or recognized, just returns
127
my $value = $self->value;
128
my $encoding = uc $self->parameters->{'ENCODING'};
130
if ($ENCODINGS{$encoding}) {
131
return $ENCODINGS{$encoding}{'decode'}->($value);
137
=head2 encode $encoding
139
Calls C<decoded_value> to get the current decoded value, then encodes it in C<$encoding>,
140
sets the value to that, and sets the encoding parameter to C<$encoding>. (C<$encoding> is
141
first converted to upper case.)
143
If C<$encoding> is undef, deletes the encoding parameter and sets the value to the decoded
144
value. Does nothing if the encoding is not recognized.
150
my $encoding = uc shift;
152
my $decoded_value = $self->decoded_value;
154
if (not defined $encoding) {
155
$self->value($decoded_value);
156
delete $self->parameters->{'ENCODING'};
157
} elsif ($ENCODINGS{$encoding}) {
158
$self->value( $ENCODINGS{$encoding}{'encode'}->($decoded_value) );
159
$self->parameters->{'ENCODING'} = $encoding;
163
=head2 as_string ARGS
165
Returns the property formatted as a string (including trailing newline).
167
Takes named arguments:
173
Defaults to true. pass in a false value if you need to generate non-rfc-compliant calendars.
182
my %args = ( fold => 1, @_ );
183
my $string = uc( $self->key )
184
. $self->_parameters_as_string . ":"
185
. $self->_value_as_string( $self->key ) . "\n";
187
# Assumption: the only place in an iCalendar that needs folding are property
189
if ( $args{'fold'} ) {
190
return $self->_fold($string);
198
=head2 _value_as_string
200
Returns the property's value as a string.
201
Comma and semicolon are not escaped when the value is recur type (the key is
204
Values are quoted according the iCal spec, unless
205
this is in vCal 1.0 mode.
211
sub _value_as_string {
214
my $value = defined($self->value()) ? $self->value() : '';
216
unless ($self->vcal10) {
217
$value =~ s/\\/\\/gs;
218
$value =~ s/\Q;/\\;/gs unless lc($key) eq 'rrule';
219
$value =~ s/,/\\,/gs unless lc($key) eq 'rrule';
220
$value =~ s/\n/\\n/gs;
221
$value =~ s/\\N/\\N/gs;
230
=head2 _parameters_as_string
232
Returns the property's parameters as a string. Properties are sorted alphabetically
239
sub _parameters_as_string {
242
for my $name ( sort keys %{ $self->parameters } ) {
243
my $value = $self->parameters->{$name};
246
. $self->_quoted_parameter_values(
247
ref $value ? @$value : $value );
254
=head2 _quoted_parameter_values @values
256
Quotes any of the values in C<@values> that need to be quoted and returns the quoted values
259
If any of the values contains a double-quote, erases it and emits a warning.
265
sub _quoted_parameter_values {
269
for my $val (@values) {
272
# Get all the way back to the user's code
273
local $Carp::CarpLevel = $Carp::CarpLevel + 1;
274
carp "Invalid parameter value (contains double quote): $val";
279
return join ',', map { /[;,:]/ ? qq("$_") : $_ } @values;
286
Returns C<$string> folded with newlines and leading whitespace so that each
287
line is at most 75 characters.
289
(Note that it folds at 75 characters, not 75 bytes as specified in the standard.)
291
If this is vCalendar 1.0 and encoded with QUOTED-PRINTABLE, folds with = instead.
301
my $quoted_printable = $self->vcal10 &&
302
uc $self->parameters->{'ENCODING'} eq 'QUOTED-PRINTABLE';
304
# We can't just use a s//g, because we need to include the added space/= and
305
# first character of the next line in the count for the next line.
307
if ($quoted_printable) {
308
# In old vcal, quoted-printable properties have different folding rules.
309
# But some interop tests suggest it's wiser just to not fold for vcal 1.0
310
# at all (in quoted-printable).
314
# while ( $string =~ /.{75}[^\n=]/ ) {
315
# $string =~ s/(.{75})([^\n=])/$1=\n$2/;
318
while ( $string =~ /(.{76})/ ) {
319
$string =~ s/(.{75})(.)/$1\n $2/;
added
removed
lib/Data/ICal/Property.pm
