class Tilia::VObject::Parameter

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.

Attributes

name[RW]

Parameter name.

@return [String]

no_name[RW]

vCard 2.1 allows parameters to be encoded without a name.

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

@return [Boolean]

value[W]

Updates the current value.

This may be either a single, or multiple strings in an array.

@param [String|array] value

@return [void]

Public Class Methods

guess_parameter_name_by_value(value) click to toggle source

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.

@param [String] value

@return [String]

# 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
new(root, name, value = nil) click to toggle source

Sets up the object.

It's recommended to use the create

factory method instead.

@param [String] name @param [String] value

# 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

Public Instance Methods

==(other) click to toggle source

TODO: document

Calls superclass method Tilia::VObject::Node#==
# 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) click to toggle source

Adds a value to this parameter.

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

@param [String|array] part

@return [void]

# 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() { |value| ... } click to toggle source
# File lib/tilia/v_object/parameter.rb, line 305
def each
  @value.each do |value|
    yield(value)
  end
end
has(value) click to toggle source

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'.

@param [String] value

@return [Boolean]

# 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() click to toggle source
# File lib/tilia/v_object/parameter.rb, line 311
def iterator
  return @iterator if @iterator

  @iterator = @value || []
end
json_serialize() click to toggle source

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

@return [array]

# File lib/tilia/v_object/parameter.rb, line 282
def json_serialize
  @value
end
parts() click to toggle source

Returns all values for this parameter.

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

@return [array]

# 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) click to toggle source

Sets multiple values for this parameter.

@param [array] value

@return [void]

# File lib/tilia/v_object/parameter.rb, line 175
def parts=(value)
  @value = value
end
serialize() click to toggle source

Turns the object back into a serialized blob.

@return [String]

# 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() click to toggle source

Called when this object is being cast to a string.

@return [String]

# File lib/tilia/v_object/parameter.rb, line 301
def to_s
  value.to_s
end
value() click to toggle source

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).

@return [String, nil]

# File lib/tilia/v_object/parameter.rb, line 162
def value
  if @value.is_a?(Array)
    @value.join(',')
  else
    @value
  end
end
xml_serialize(writer) click to toggle source

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

@param [XmlWriter] writer XML writer.

@return [void]

# 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