Module: Vpim

Included in:
Icalendar
Defined in:
lib/vpim/vpim.rb,
lib/vpim/repo.rb,
lib/vpim/view.rb,
lib/vpim/field.rb,
lib/vpim/rrule.rb,
lib/vpim/vcard.rb,
lib/vpim/vtodo.rb,
lib/vpim/vevent.rb,
lib/vpim/address.rb,
lib/vpim/dirinfo.rb,
lib/vpim/rfc2425.rb,
lib/vpim/rfc2425.rb,
lib/vpim/version.rb,
lib/vpim/duration.rb,
lib/vpim/vjournal.rb,
lib/vpim/agent/ics.rb,
lib/vpim/icalendar.rb,
lib/vpim/agent/base.rb,
lib/vpim/attachment.rb,
lib/vpim/enumerator.rb,
lib/vpim/maker/vcard.rb,
lib/vpim/agent/atomize.rb,
lib/vpim/property/base.rb,
lib/vpim/agent/calendars.rb,
lib/vpim/property/common.rb,
lib/vpim/property/location.rb,
lib/vpim/property/priority.rb,
lib/vpim/property/resources.rb,
lib/vpim/property/recurrence.rb

Overview

Copyright © 2008 Sam Roberts

This library is free software; you can redistribute it and/or modify it
under the same terms as the ruby language itself, see the file COPYING for
details.

Defined Under Namespace

Modules: Agent, Attachment, Bnf, Maker, Methods, View Classes: DirectoryInfo, Duration, Enumerator, Icalendar, InvalidEncodingError, Repo, Rrule, Unencodeable, UnsupportedError, Vcard

Constant Summary collapse

PRODID = 
'-//Octet Cloud//vPim 13.11.11//EN'
VERSION = 
'13.11.11'

Class Method Summary collapse

Class Method Details

.array_datetime_to_time(dtarray) ⇒ Object

:nodoc:



157
158
159
160
161
162
163
164
165
 
# File 'lib/vpim/rfc2425.rb', line 157

def self.array_datetime_to_time(dtarray) #:nodoc:
  # We get [ year, month, day, hour, min, sec, usec, tz ]
  begin
    tz = (dtarray.pop == "Z") ? :gm : :local
    Time.send(tz, *dtarray)
  rescue ArgumentError => e
    raise Vpim::InvalidEncodingError, "#{tz} #{e} (#{dtarray.join(', ')})"
  end
end

.decode(card) ⇒ Object

Unfold the lines in card, then return an array of one Field object per line.



315
316
317
 
# File 'lib/vpim/rfc2425.rb', line 315

def Vpim.decode(card) #:nodoc:
    content = Vpim.unfold(card).collect { |line| DirectoryInfo::Field.decode(line) }
end

.decode_date(v) ⇒ Object

Convert a RFC 2425 date into an array of [year, month, day].



117
118
119
120
121
122
 
# File 'lib/vpim/rfc2425.rb', line 117

def Vpim.decode_date(v) # :nodoc:
  unless v =~ %r{^\s*#{Bnf::DATE}\s*$}
    raise Vpim::InvalidEncodingError, "date not valid (#{v})"
  end
  [$1.to_i, $2.to_i, $3.to_i]
end

.decode_date_list(v) ⇒ Object

Convert a RFC2425 date-list into an array of dates.



213
214
215
216
217
218
219
220
 
# File 'lib/vpim/rfc2425.rb', line 213

def Vpim.decode_date_list(v) # :nodoc:
  Vpim.decode_list(v) do |date|
    date.strip!
    if date.length > 0
      Vpim.decode_date(date)
    end
  end.compact
end

.decode_date_time(v) ⇒ Object

Convert a RFC 2425 date-time into an array of [year,mon,day,hour,min,sec,secfrac,timezone]



173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/vpim/rfc2425.rb', line 173

def Vpim.decode_date_time(v) # :nodoc:
  unless match = %r{^\s*#{Bnf::DATE}T#{Bnf::TIME}\s*$}.match(v)
    raise Vpim::InvalidEncodingError, "date-time '#{v}' not valid"
  end
  year, month, day, hour, min, sec, secfrac, tz = match.to_a[1..8]

  [
    # date
    year.to_i, month.to_i, day.to_i,
    # time
    hour.to_i, min.to_i, sec.to_i, secfrac ? secfrac.to_f : 0, tz
  ]
end

.decode_date_time_list(v) ⇒ Object

Convert a RFC 2425 date-time-list into an array of date-times.



233
234
235
236
237
238
239
240
 
# File 'lib/vpim/rfc2425.rb', line 233

def Vpim.decode_date_time_list(v) # :nodoc:
  Vpim.decode_list(v) do |datetime|
    datetime.strip!
    if datetime.length > 0
      Vpim.decode_date_time(datetime)
    end
  end.compact
end

.decode_date_time_to_datetime(v) ⇒ Object

:nodoc:



187
188
189
190
191
 
# File 'lib/vpim/rfc2425.rb', line 187

def Vpim.decode_date_time_to_datetime(v) #:nodoc:
  year, month, day, hour, min, sec, secfrac, tz = Vpim.decode_date_time(v)
  # TODO - DateTime understands timezones, so we could decode tz and use it.
  DateTime.civil(year, month, day, hour, min, sec, 0)
end

.decode_date_to_date(v) ⇒ Object

Convert a RFC 2425 date into a Date object.



125
126
127
 
# File 'lib/vpim/rfc2425.rb', line 125

def self.decode_date_to_date(v)
  Date.new(*decode_date(v))
end

.decode_integer(v) ⇒ Object

Convert an RFC2425 INTEGER value into an Integer



202
203
204
205
206
207
 
# File 'lib/vpim/rfc2425.rb', line 202

def Vpim.decode_integer(v) # :nodoc:
  unless match = %r{\s*#{Bnf::INTEGER}\s*}.match(v)
    raise Vpim::InvalidEncodingError, "integer not valid (#{v})"
  end
  v.to_i
end

.decode_list(value, sep = ',') ⇒ Object

Convert a sep-seperated list of values into an array of values.



106
107
108
109
110
111
112
113
114
 
# File 'lib/vpim/rfc2425.rb', line 106

def Vpim.decode_list(value, sep = ',') # :nodoc:
  list = []

  value.each_line(sep) do |item|
    item.chomp!(sep)
    list << yield(item)
  end
  list
end

.decode_text(v) ⇒ Object

Convert RFC 2425 text into a String. \ -> \ n -> NL N -> NL , -> , ; -> ;

I’ve seen double-quote escaped by iCal.app. Hmm. Ok, if you aren’t supposed to escape anything but the above, everything else is ambiguous, so I’ll just support it.



252
253
254
255
256
257
258
259
260
261
262
 
# File 'lib/vpim/rfc2425.rb', line 252

def Vpim.decode_text(v) # :nodoc:
  # FIXME - I think this should trim leading and trailing space
  v.gsub(/\\(.)/) do
    case $1
    when 'n', 'N'
      "\n"
    else
      $1
    end
  end
end

.decode_text_list(value, sep = ',') ⇒ Object

Convert a sep-seperated list of TEXT values into an array of values.



278
279
280
281
282
283
284
285
286
287
 
# File 'lib/vpim/rfc2425.rb', line 278

def Vpim.decode_text_list(value, sep = ',') # :nodoc:
  # Need to do in two stages, as best I can find.
  list = value.scan(/([^#{sep}\\]*(?:\\.[^#{sep}\\]*)*)#{sep}/).map do |v|
    Vpim.decode_text(v.first)
  end
  if value.match(/([^#{sep}\\]*(?:\\.[^#{sep}\\]*)*)$/)
    list << $1
  end
  list
end

.decode_time(v) ⇒ Object

Convert a RFC 2425 time into an array of [hour,min,sec,secfrac,timezone]



148
149
150
151
152
153
154
155
 
# File 'lib/vpim/rfc2425.rb', line 148

def Vpim.decode_time(v) # :nodoc:
  unless match = %r{^\s*#{Bnf::TIME}\s*$}.match(v)
    raise Vpim::InvalidEncodingError, "time '#{v}' not valid"
  end
  hour, min, sec, secfrac, tz = match.to_a[1..5]

  [hour.to_i, min.to_i, sec.to_i, secfrac ? secfrac.to_f : 0, tz]
end

.decode_time_list(v) ⇒ Object

Convert a RFC 2425 time-list into an array of times.



223
224
225
226
227
228
229
230
 
# File 'lib/vpim/rfc2425.rb', line 223

def Vpim.decode_time_list(v) # :nodoc:
  Vpim.decode_list(v) do |time|
    time.strip!
    if time.length > 0
      Vpim.decode_time(time)
    end
  end.compact
end

.decode_time_to_time(v) ⇒ Object

Convert a RFC 2425 time into an array of Time objects.



168
169
170
 
# File 'lib/vpim/rfc2425.rb', line 168

def Vpim.decode_time_to_time(v) # :nodoc:
  array_datetime_to_time(decode_date_time(v))
end

.encode_date(d) ⇒ Object

Encode a Date object as “yyyymmdd”.



133
134
135
 
# File 'lib/vpim/rfc2425.rb', line 133

def Vpim.encode_date(d) # :nodoc:
   "%0.4d%0.2d%0.2d" % [ d.year, d.mon, d.day ]
end

.encode_date_time(d) ⇒ Object

Encode a Time or DateTime object as “yyyymmddThhmmss”



143
144
145
 
# File 'lib/vpim/rfc2425.rb', line 143

def Vpim.encode_date_time(d) # :nodoc:
   "%0.4d%0.2d%0.2dT%0.2d%0.2d%0.2d" % [ d.year, d.mon, d.day, d.hour, d.min, d.sec ]
end

.encode_paramtext(value) ⇒ Object

param-value = paramtext / quoted-string paramtext = *SAFE-CHAR quoted-string = DQUOTE *QSAFE-CHAR DQUOTE



292
293
294
295
296
297
298
299
 
# File 'lib/vpim/rfc2425.rb', line 292

def Vpim.encode_paramtext(value)
  case value
  when %r{\A#{Bnf::SAFECHAR}*\z}
    value
  else
    raise Vpim::Unencodeable, "paramtext #{value.inspect}"
  end
end

.encode_paramvalue(value) ⇒ Object 



301
302
303
304
305
306
307
308
309
310
 
# File 'lib/vpim/rfc2425.rb', line 301

def Vpim.encode_paramvalue(value)
  case value
  when %r{\A#{Bnf::SAFECHAR}*\z}
    value
  when %r{\A#{Bnf::QSAFECHAR}*\z}
    '"' + value + '"'
  else
    raise Vpim::Unencodeable, "param-value #{value.inspect}"
  end
end

.encode_text(v) ⇒ Object

:nodoc:



264
265
266
 
# File 'lib/vpim/rfc2425.rb', line 264

def Vpim.encode_text(v) #:nodoc:
  v.to_str.gsub(/([\\,;\n])/) { $1 == "\n" ? "\\n" : "\\"+$1 }
end

.encode_text_list(v, sep = ",") ⇒ Object

v is an Array of String, or just a single String



269
270
271
272
273
274
275
 
# File 'lib/vpim/rfc2425.rb', line 269

def Vpim.encode_text_list(v, sep = ",") #:nodoc:
  begin
    v.to_ary.map{ |t| Vpim.encode_text(t) }.join(sep)
  rescue
    Vpim.encode_text(v)
  end
end

.encode_time(d) ⇒ Object

Encode a Date object as “yyyymmdd”.



138
139
140
 
# File 'lib/vpim/rfc2425.rb', line 138

def Vpim.encode_time(d) # :nodoc:
   "%0.4d%0.2d%0.2d" % [ d.year, d.mon, d.day ]
end

.expand(src) ⇒ Object

Expand an array of fields into its syntactic entities. Each entity is a sequence of fields where the sequences is delimited by a BEGIN/END field. Since BEGIN/END delimited entities can be nested, we build a tree. Each entry in the array is either a Field or an array of entries (where each entry is either a Field, or an array of entries…).



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/vpim/rfc2425.rb', line 325

def Vpim.expand(src) #:nodoc:
  # output array to expand the src to
  dst = []
  # stack used to track our nesting level, as we see begin/end we start a
  # new/finish the current entity, and push/pop that entity from the stack
  current = [ dst ]

  for f in src
    if f.name? 'BEGIN'
      e = [ f ]

      current.last.push(e)
      current.push(e)

    elsif f.name? 'END'
      current.last.push(f)

      unless current.last.first.value? current.last.last.value
        raise "BEGIN/END mismatch (#{current.last.first.value} != #{current.last.last.value})"
      end

      current.pop

    else
      current.last.push(f)
    end
  end

  dst
end

.outer_inner(fields) ⇒ Object

Split an array into an array of all the fields at the outer level, and an array of all the inner arrays of fields. Return the array [outer, inner].



359
360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/vpim/rfc2425.rb', line 359

def Vpim.outer_inner(fields) #:nodoc:
  # TODO - use Enumerable#partition
  # seperate into the outer-level fields, and the arrays of component
  # fields
  outer = []
  inner = []
  fields.each do |line|
    case line
    when Array; inner << line
    else;       outer << line
    end
  end
  return outer, inner
end

.unfold(card) ⇒ Object

Split on rn or n to get the lines, unfold continued lines (they start with ‘ ’ or t), and return the array of unfolded lines.

This also supports the (invalid) encoding convention of allowing empty lines to be inserted for readability - it does this by dropping zero-length lines.

Also supports an the QUOTED-PRINTABLE soft line-break as described here: en.wikipedia.org/wiki/Quoted-printable



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/vpim/rfc2425.rb', line 84

def Vpim.unfold(card) # :nodoc:
  unfolded = []
  # Ruby 1.9's String can no longer be iterated with #each, so the following
  # code, which used to work with String, or Array, or File, or anything else
  # which produced lines when iterated, now just works with String. Sucky.
  card.each_line do |line|
    line.chomp!
    # If it's a continuation line, add it to the last.
    # If it's an empty line, drop it from the input.
    if( line =~ /^[ \t]/ )
      unfolded[-1] << line[1, line.size-1]
    elsif (unfolded.last && unfolded.last =~ /;ENCODING=QUOTED-PRINTABLE:.*?=$/)
      unfolded.last << line
    elsif( line =~ /^$/ )
    else
      unfolded << line
    end
  end
  unfolded
end

.version ⇒ Object

Return the API version as a string.



15
16
17
 
# File 'lib/vpim/version.rb', line 15

def Vpim.version
  VERSION
end