Class: Tilia::VObject::Parameter

Inherits:
Node
  • Object
show all
Defined in:
lib/tilia/v_object/parameter.rb

Overview

VObject Parameter.

This class represents a parameter. A parameter is always tied to a property. In the case of:

DTSTART;VALUE=DATE:20101108

VALUE=DATE would be the parameter name and value.

Constant Summary

Constants inherited from Node

Node::PROFILE_CALDAV, Node::PROFILE_CARDDAV, Node::REPAIR

Instance Attribute Summary collapse

Attributes inherited from Node

#parent

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Node

#[], #[]=, #delete, #destroy, #key?, #size, #validate

Constructor Details

#initialize(root, name, value = nil) ⇒ Parameter

Sets up the object.

It’s recommended to use the create

factory method instead.

Parameters:

  • name (String)
  • value (String) (defaults to: nil) 


33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/tilia/v_object/parameter.rb', line 33

def initialize(root, name, value = nil)
  @no_name = false
  @name = (name || '').upcase
  @root = root

  if name.nil?
    @no_name = true
    @name = self.class.guess_parameter_name_by_value(value)
  else
    @name = name.upcase
  end

  # If guess_parameter_name_by_value returns an empty string
  # above, we're actually dealing with a parameter that has no value.
  # In that case we have to move the value to the name.
  if @name == ''
    @no_name = false
    @name = value.upcase
  else
    self.value = value
  end
end

Instance Attribute Details

#name ⇒ String

Parameter name.

Returns:

  • (String) 


13
14
15
 
# File 'lib/tilia/v_object/parameter.rb', line 13

def name
  @name
end

#no_name ⇒ Boolean

vCard 2.1 allows parameters to be encoded without a name.

We can deduce the parameter name based on it’s value.

Returns:

  • (Boolean) 


20
21
22
 
# File 'lib/tilia/v_object/parameter.rb', line 20

def no_name
  @no_name
end

#value ⇒ String?

Returns the current value.

This method will always return a string, or null. If there were multiple values, it will automatically concatenate them (separated by comma).

Returns:

  • (String, nil) 


162
163
164
165
166
167
168
 
# File 'lib/tilia/v_object/parameter.rb', line 162

def value
  if @value.is_a?(Array)
    @value.join(',')
  else
    @value
  end
end

Class Method Details

.guess_parameter_name_by_value(value) ⇒ String

Try to guess property name by value, can be used for vCard 2.1 nameless parameters.

Figuring out what the name should have been. Note that a ton of these are rather silly in 2014 and would probably rarely be used, but we like to be complete.

Parameters:

  • value (String)

Returns:

  • (String) 


65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
 
# File 'lib/tilia/v_object/parameter.rb', line 65

def self.guess_parameter_name_by_value(value)
  value ||= ''
  case value.upcase
  # Encodings
  when '7-BIT',
      'QUOTED-PRINTABLE',
      'BASE64'
    'ENCODING'
  # Common types
  when 'WORK',
      'HOME',
      'PREF',

      # Delivery Label Type
      'DOM',
      'INTL',
      'POSTAL',
      'PARCEL',

      # Telephone types
      'VOICE',
      'FAX',
      'MSG',
      'CELL',
      'PAGER',
      'BBS',
      'MODEM',
      'CAR',
      'ISDN',
      'VIDEO',

      # EMAIL types (lol)
      'AOL',
      'APPLELINK',
      'ATTMAIL',
      'CIS',
      'EWORLD',
      'INTERNET',
      'IBMMAIL',
      'MCIMAIL',
      'POWERSHARE',
      'PRODIGY',
      'TLX',
      'X400',

      # Photo / Logo format types
      'GIF',
      'CGM',
      'WMF',
      'BMP',
      'DIB',
      'PICT',
      'TIFF',
      'PDF',
      'PS',
      'JPEG',
      'MPEG',
      'MPEG2',
      'AVI',
      'QTIME',

      # Sound Digital Audio Type
      'WAVE',
      'PCM',
      'AIFF',

      # Key types
      'X509',
      'PGP'
    'TYPE'

  # Value types
  when 'INLINE',
      'URL',
      'CONTENT-ID',
      'CID'
    'VALUE'
  else
    ''
  end
end

Instance Method Details

#==(other) ⇒ Object

TODO: document



318
319
320
321
322
323
324
 
# File 'lib/tilia/v_object/parameter.rb', line 318

def ==(other)
  if other.is_a?(String)
    to_s == other
  else
    super(other)
  end
end

#add_value(part) ⇒ void

This method returns an undefined value.

Adds a value to this parameter.

If the argument is specified as an array, all items will be added to the parameter value list.

Parameters:

  • part (String|array) 


202
203
204
205
206
207
208
209
210
 
# File 'lib/tilia/v_object/parameter.rb', line 202

def add_value(part)
  if @value.nil?
    @value = part
  else
    @value = [@value] unless @value.is_a?(Array)
    part = [part] unless part.is_a?(Array)
    @value.concat(part)
  end
end

#each ⇒ Object 



305
306
307
308
309
 
# File 'lib/tilia/v_object/parameter.rb', line 305

def each
  @value.each do |value|
    yield(value)
  end
end

#has(value) ⇒ Boolean

Checks if this parameter contains the specified value.

This is a case-insensitive match. It makes sense to call this for for instance the TYPE parameter, to see if it contains a keyword such as ‘WORK’ or ‘FAX’.

Parameters:

  • value (String)

Returns:

  • (Boolean) 


221
222
223
224
225
226
227
 
# File 'lib/tilia/v_object/parameter.rb', line 221

def has(value)
  value = value.downcase
  results = (@value.is_a?(Array) ? @value : [@value]).select do |entry|
    entry.downcase == value
  end
  results.any?
end

#iterator ⇒ Object 



311
312
313
314
315
 
# File 'lib/tilia/v_object/parameter.rb', line 311

def iterator
  return @iterator if @iterator

  @iterator = @value || []
end

#json_serialize ⇒ array

This method returns an array, with the representation as it should be encoded in JSON. This is used to create jCard or jCal documents.

Returns:

  • (array) 


282
283
284
 
# File 'lib/tilia/v_object/parameter.rb', line 282

def json_serialize
  @value
end

#parts ⇒ array

Returns all values for this parameter.

If there were no values, an empty array will be returned.

Returns:

  • (array) 


184
185
186
187
188
189
190
191
192
 
# File 'lib/tilia/v_object/parameter.rb', line 184

def parts
  if @value.is_a?(Array)
    @value
  elsif @value.nil?
    []
  else
    [@value]
  end
end

#parts=(value) ⇒ void

This method returns an undefined value.

Sets multiple values for this parameter.

Parameters:

  • value (array) 


175
176
177
 
# File 'lib/tilia/v_object/parameter.rb', line 175

def parts=(value)
  @value = value
end

#serialize ⇒ String

Turns the object back into a serialized blob.

Returns:

  • (String) 


232
233
234
235
236
237
238
239
240
241
242
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
271
272
273
274
275
276
 
# File 'lib/tilia/v_object/parameter.rb', line 232

def serialize
  value = parts

  return "#{@name}=" if value.size == 0

  if @root.document_type == Document::VCARD21 && @no_name
    return value.join(';')
  end

  result = value.inject('') do |keep, item|
    keep += ',' unless keep == ''

    # If there's no special characters in the string, we'll use the simple
    # format.
    #
    # The list of special characters is defined as:
    #
    # Any character except CONTROL, DQUOTE, ";", ":", ","
    #
    # by the iCalendar spec:
    # https://tools.ietf.org/html/rfc5545#section-3.1
    #
    # And we add ^ to that because of:
    # https://tools.ietf.org/html/rfc6868
    #
    # But we've found that iCal (7.0, shipped with OSX 10.9)
    # severaly trips on + characters not being quoted, so we
    # added + as well.
    if !(item.to_s =~ /(?: [\n":;\^,\+] )/x)
      keep + item.to_s
    else
      # Enclosing in double-quotes, and using RFC6868 for encoding any
      # special characters
      keep += '"' + item.to_s.gsub(
        /[\^\n"]/,
        '^'  => '^^',
        "\n" => '^n',
        '"'  => '^\''
      )
      keep + '"'
    end
  end

  "#{@name}=#{result}"
end

#to_s ⇒ String

Called when this object is being cast to a string.

Returns:

  • (String) 


301
302
303
 
# File 'lib/tilia/v_object/parameter.rb', line 301

def to_s
  value.to_s
end

#xml_serialize(writer) ⇒ void

This method returns an undefined value.

This method serializes the data into XML. This is used to create xCard or xCal documents.

Parameters:

  • writer (Xml\Writer) —

    XML writer.



292
293
294
295
296
 
# File 'lib/tilia/v_object/parameter.rb', line 292

def xml_serialize(writer)
  @value.split(',').each do |value|
    writer.write_element('text', value)
  end
end