Module: Vcard

Defined in:
lib/vcard/bnf.rb,
lib/vcard.rb,
lib/vcard/field.rb,
lib/vcard/vcard.rb,
lib/vcard/errors.rb,
lib/vcard/dirinfo.rb,
lib/vcard/version.rb,
lib/vcard/attachment.rb,
lib/vcard/enumerator.rb,
lib/vcard/configuration.rb

Overview

This library is free software; you can redistribute it and/or modify it under the same terms as the ruby language itself.

Defined Under Namespace

Modules: Attachment, Bnf Classes: Configuration, DirectoryInfo, Enumerator, InvalidEncodingError, Unencodeable, UnsupportedError, Vcard

Constant Summary collapse

VERSION = 
"0.2.16"

Class Method Summary collapse

Class Method Details

.array_datetime_to_time(dtarray) ⇒ Object

:nodoc:



98
99
100
101
102
103
104
 
# File 'lib/vcard.rb', line 98

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

.configuration ⇒ Object 



290
291
292
 
# File 'lib/vcard.rb', line 290

def self.configuration
  @configuration ||= Configuration.new
end

.configure {|configuration| ... } ⇒ Object

Yields:



294
295
296
 
# File 'lib/vcard.rb', line 294

def self.configure
  yield configuration
end

.decode(card) ⇒ Object

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



233
234
235
 
# File 'lib/vcard.rb', line 233

def self.decode(card) #:nodoc:
  unfold(card).map { |line| DirectoryInfo::Field.decode(line) }
end

.decode_date(v) ⇒ Object

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

Raises:



62
63
64
65
 
# File 'lib/vcard.rb', line 62

def self.decode_date(v) # :nodoc:
  raise ::Vcard::InvalidEncodingError, "date not valid (#{v})" unless v =~ Bnf::DATE
  [$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.



146
147
148
149
150
151
 
# File 'lib/vcard.rb', line 146

def self.decode_date_list(v) # :nodoc:
  decode_list(v) do |date|
    date.strip!
    decode_date(date) if date.length > 0
  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]

Raises:



112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/vcard.rb', line 112

def self.decode_date_time(v) # :nodoc:
  raise ::Vcard::InvalidEncodingError, "date-time '#{v}' not valid" unless match = Bnf::DATE_TIME.match(v)
  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.



162
163
164
165
166
167
 
# File 'lib/vcard.rb', line 162

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

.decode_date_time_to_datetime(v) ⇒ Object

:nodoc:



124
125
126
127
128
 
# File 'lib/vcard.rb', line 124

def self.decode_date_time_to_datetime(v) #:nodoc:
  year, month, day, hour, min, sec = 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.



68
69
70
 
# File 'lib/vcard.rb', line 68

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

Raises:



137
138
139
140
 
# File 'lib/vcard.rb', line 137

def self.decode_integer(v) # :nodoc:
  raise ::Vcard::InvalidEncodingError, "integer not valid (#{v})" unless v =~ Bnf::INTEGER
  v.to_i
end

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

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



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/vcard.rb', line 50

def self.decode_list(value, sep = ",") # :nodoc:
  list = []

  value.split(sep).each 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.



179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/vcard.rb', line 179

def self.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.



203
204
205
206
207
208
 
# File 'lib/vcard.rb', line 203

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

.decode_time(v) ⇒ Object

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

Raises:



91
92
93
94
95
96
 
# File 'lib/vcard.rb', line 91

def self.decode_time(v) # :nodoc:
  raise ::Vcard::InvalidEncodingError, "time '#{v}' not valid" unless match = Bnf::TIME.match(v)
  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.



154
155
156
157
158
159
 
# File 'lib/vcard.rb', line 154

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

.decode_time_to_time(v) ⇒ Object

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



107
108
109
 
# File 'lib/vcard.rb', line 107

def self.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”.



76
77
78
 
# File 'lib/vcard.rb', line 76

def self.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”



86
87
88
 
# File 'lib/vcard.rb', line 86

def self.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



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

def self.encode_paramtext(value)
  if value =~ Bnf::ALL_SAFECHARS
    value
  else
    raise ::Vcard::Unencodable, "paramtext #{value.inspect}"
  end
end

.encode_paramvalue(value) ⇒ Object 



221
222
223
224
225
226
227
228
229
 
# File 'lib/vcard.rb', line 221

def self.encode_paramvalue(value)
  if value =~ Bnf::ALL_SAFECHARS
    value
  elsif value =~ Bnf::ALL_QSAFECHARS
    %Q{"#{value}"}
  else
    raise ::Vcard::Unencodable, "param-value #{value.inspect}"
  end
end

.encode_text(v) ⇒ Object

:nodoc:



191
192
193
 
# File 'lib/vcard.rb', line 191

def self.encode_text(v) #:nodoc:
  v.to_str.gsub(/[\\,;]/, '\\\\\0').gsub(/\r?\n/, "\\n")
end

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

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



196
197
198
199
200
 
# File 'lib/vcard.rb', line 196

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

.encode_time(d) ⇒ Object

Encode a Date object as “yyyymmdd”.



81
82
83
 
# File 'lib/vcard.rb', line 81

def self.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…).



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/vcard.rb', line 243

def self.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].



275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/vcard.rb', line 275

def self.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 then 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.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/vcard.rb', line 26

def self.unfold(card) #:nodoc:
    unfolded = []

    prior_line = nil
    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 prior_line && (prior_line =~ Bnf::UNTERMINATED_QUOTED_PRINTABLE)
        # Strip the trailing = off prior line, then append current line
        unfolded[-1] = prior_line[0, prior_line.length-1] + line
      elsif line =~ /^$/
      else
        unfolded << line
      end
      prior_line = unfolded[-1]
    end

    unfolded
end