virginity 0.3.31

data/lib/virginity/vcard/field.rb

@@ -0,0 +1,22 @@
+require 'virginity/vcard/base_field'
+
+module Virginity
+
+  # Basic field, if we don't know anything about it, we assume it can at least handle text encoding
+  class Field < BaseField
+    include FieldValues::Text
+
+    field_register.default = self
+  end
+
+
+  # monkey patch ContentLine to make a #to_field method
+  class ContentLine
+    # convert to a vcard-field (see Field)
+    def to_field
+      Field.parse(self)
+    end
+  end
+
+
+end

data/lib/virginity/vcard/field/params.rb

@@ -0,0 +1,93 @@
+module Virginity
+
+  module Params
+    module Type
+
+
+      class TypeArray < SerializingArray
+        def initialize(field)
+          @field = field
+          super(@field.params("TYPE").map { |p| p.value }.uniq)
+        end
+
+#           def reload!
+#             @array = Array.new(@field.params("TYPE").map { |p| p.value }.uniq)
+#             self
+#           end
+
+        def rewrite!
+          @field.params("TYPE").each {|t| @field.params.delete t }
+          @array.each do |type|
+            @field.params << Param.new('TYPE', type)
+          end
+        end
+
+        # Locations are a subset of all the TYPE-params
+        LOCATIONS = { "CELL" => "Mobile", "HOME" => "Home", "OTHER" => "Other", "WORK" => "Work" }
+        def locations
+          @array.select { |t| LOCATIONS.keys.include?(t)}
+        end
+
+        def locations=(locs)
+          locations.each {|l| delete(l) }
+          locs.each { |l| self << l }
+        end
+      end
+
+
+      def types
+        TypeArray.new(self)
+      end
+
+      def types=(array)
+        types.replace(array)
+      end
+
+      def type=(str)
+        self.types = str.split(/ /)
+      end
+
+      def add_type(thing)
+        t = types
+        t << thing unless t.include? thing
+      end
+
+      def remove_type(thing)
+        types.delete(thing)
+      end
+
+      # =============================
+      # Preferred
+      def preferred?
+        types.include? 'PREF'
+      end
+
+      def preferred=(val)
+        if val
+          add_type 'PREF'
+        else
+          remove_type 'PREF'
+        end
+      end
+
+      # =============================
+      # Location handling:
+      def locations
+        types.locations
+      end
+
+      def locations=(array)
+        types.locations = array
+      end
+
+      def location
+        locations.join(" ")
+      end
+
+      def location=(str)
+        self.locations = str.split(/ /)
+      end
+    end
+
+  end
+end

data/lib/virginity/vcard/field_values.rb

@@ -0,0 +1,10 @@
+require 'virginity/vcard/field_values/binary.rb'
+require 'virginity/vcard/field_values/boolean.rb'
+require 'virginity/vcard/field_values/case_insensitive_value.rb'
+require 'virginity/vcard/field_values/date.rb'
+require 'virginity/vcard/field_values/integer.rb'
+require 'virginity/vcard/field_values/separated_text.rb'
+require 'virginity/vcard/field_values/structured_text.rb'
+require 'virginity/vcard/field_values/optional_structured_text.rb'
+require 'virginity/vcard/field_values/text.rb'
+require 'virginity/vcard/field_values/uri.rb'

data/lib/virginity/vcard/field_values/binary.rb

@@ -0,0 +1,22 @@
+module Virginity
+  module FieldValues
+
+    module Binary
+      def binary
+        Base64.decode64(@value)
+      end
+
+      def binary=(s)
+        @params.delete_if { |p| p.key == "ENCODING" }
+        @params << Param.new("ENCODING", "b")
+        b64 = Base64.encode64(s)
+        b64.delete!("\n") # can return nil... bah, but probably faster than #delete without an exclamation mark
+        @value = b64
+      end
+
+      def sha1
+        Digest::SHA1.hexdigest(@value)
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/boolean.rb

@@ -0,0 +1,14 @@
+module Virginity
+  module FieldValues
+
+    module Boolean
+      def boolean
+        (@value.downcase == "true")
+      end
+
+      def boolean=(b)
+        @value = b ? "true" : "false"
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/case_insensitive_value.rb

@@ -0,0 +1,13 @@
+module Virginity
+  module FieldValues
+
+    module CaseInsensitiveValue
+      def ==(other)
+        group == other.group &&
+          has_name?(other.name) &&
+          params == other.params &&
+          (raw_value.casecmp(other.raw_value) == 0)
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/date.rb

@@ -0,0 +1,16 @@
+require 'date'
+
+module Virginity
+  module FieldValues
+
+    module DateValue
+      def date
+        Date.parse(text)
+      end
+
+      def date=(d)
+        self.text = d.to_s
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/integer.rb

@@ -0,0 +1,15 @@
+module Virginity
+  module FieldValues
+
+    module Integer
+      def integer
+        @value.to_i
+      end
+
+      def integer=(i)
+        @value = @integer.to_s
+      end
+    end
+
+  end
+end

data/lib/virginity/vcard/field_values/optional_structured_text.rb

@@ -0,0 +1,35 @@
+module Virginity
+  module FieldValues
+
+    class OptionalStructuredText < StructuredText
+      def self.define(components)
+        m = super
+
+        m.module_eval <<-RUBY, __FILE__, __LINE__+1
+          def reencode!(options = {})
+            v = values
+
+            v.pop while v.last.empty?
+
+            @value = EncodingDecoding::encode_structured_text(v)
+          end
+        RUBY
+
+        components.each_with_index do |component, idx|
+          m.module_eval <<-RUBY, __FILE__, __LINE__+1
+            def #{component}=(new_value)
+              structure = values
+              structure[#{idx}] = new_value.to_s
+
+              structure.pop while structure.size > 0 && (structure.last.nil? || structure.last.empty?)
+
+              @value = EncodingDecoding::encode_structured_text(structure)
+            end
+          RUBY
+        end
+
+        m
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/separated_text.rb

@@ -0,0 +1,59 @@
+require 'reactive_array'
+require 'digest/sha1'
+
+module Virginity
+  module FieldValues
+
+    module SeparatedText
+
+
+      class TextList < SerializingArray
+        def initialize(field)
+          @field = field # a reference to the original Field
+          super(EncodingDecoding::decode_text_list(@field.raw_value))
+          save_sha1!
+        end
+
+        def sha1
+          Digest::SHA1.hexdigest(@field.raw_value)
+        end
+
+        def save_sha1!
+          @sha1 = sha1
+        end
+
+        def needs_refresh?
+          @sha1 != sha1
+        end
+
+        def rewrite!
+          @array.delete_if {|v| v.empty? }
+          @field.raw_value = EncodingDecoding::encode_text_list(@array)
+          save_sha1!
+        end
+      end
+
+
+      def values
+        if (@textlist.needs_refresh? rescue true)
+          @textlist = TextList.new(self)
+        else
+          @textlist
+        end
+      end
+
+      def values=(a)
+        values.replace(a)
+      end
+
+      def reencode!
+        values.rewrite!
+      end
+
+      def subset_of?(other)
+        values.all? { |v| other.values.include? v }
+      end
+    end
+
+  end
+end

data/lib/virginity/vcard/field_values/structured_text.rb

@@ -0,0 +1,71 @@
+module Virginity
+  module FieldValues
+
+    class StructuredText
+      def self.define(components)
+        m = Module.new
+        m.const_set("COMPONENTS", components)
+        m.module_eval <<-RUBY
+          def components
+            COMPONENTS
+          end
+
+          def values
+            EncodingDecoding::decode_structured_text(@value, COMPONENTS.size)
+          end
+
+          def empty?
+            values.all? {|v| v.empty? }
+          end
+
+          def reencode!(options={})
+            v = values
+            unless options[:variable_number_of_fields]
+              v.pop while v.size > components.size
+              v.push(nil) while v.size < components.size
+            else
+              v.pop while v.last.empty?
+            end
+            @value = EncodingDecoding::encode_structured_text(v)
+          end
+
+          def [](component)
+            raise "which component? \#\{component\}?? I only know \#\{components.inspect\}" unless components.include? component.to_sym
+            send("\#\{component\}".to_sym)
+          end
+
+          def []=(component, new_value)
+            raise "which component? \#\{component\}?? I only know \#\{components.inspect\}" unless components.include? component.to_sym
+            send("\#\{component\}=", new_value)
+          end
+        RUBY
+
+        components.each_with_index do |component, idx|
+          m.module_eval <<-RUBY
+            def #{component}
+              values[#{idx}]
+            end
+
+            def #{component}=(new_value)
+              structure = values
+              structure[#{idx}] = new_value.to_s
+              @value = EncodingDecoding::encode_structured_text(structure)
+            end
+
+            def subset_of?(other_field)
+              components.all? do |component|
+                send(component).empty? or send(component) == other_field.send(component)
+              end
+            end
+
+            def superset_of?(other_field)
+              other_field.subset_of?(self)
+            end
+          RUBY
+        end
+        m
+      end
+    end
+
+  end
+end

data/lib/virginity/vcard/field_values/text.rb

@@ -0,0 +1,23 @@
+module Virginity
+  module FieldValues
+
+    module Text
+      def text
+        EncodingDecoding::decode_text(@value)
+      end
+
+      def text=(s)
+        @params.delete_if { |p| p.key == "ENCODING" }
+        @value = EncodingDecoding::encode_text(s)
+      end
+
+      def reencode!
+        self.text = text
+      end
+
+      def value_to_xml
+        xml_element("text", text.strip)
+      end
+    end
+  end
+end

data/lib/virginity/vcard/field_values/uri.rb

@@ -0,0 +1,15 @@
+module Virginity
+  module FieldValues
+
+    # needs module Text
+    module Uri
+      def uri
+        URI::parse(text)
+      end
+
+      def uri=(new_uri)
+        self.text = new_uri.to_s
+      end
+    end
+  end
+end

data/lib/virginity/vcard/fields.rb

@@ -0,0 +1,284 @@
+require "virginity/vcard/field"
+require "virginity/vcard/field/params"
+require "base64"
+
+module Virginity
+
+  # BEGIN or END
+  #
+  # We don't do much with them
+  class BeginEnd < BaseField
+    include FieldValues::CaseInsensitiveValue
+    # value MUST be "VCARD"
+    register_for :BEGIN, :END
+  end
+
+
+  class Profile < BaseField
+    register_for :PROFILE
+  end
+
+
+  # Text fields, see FieldValues::Text for safe encoding/decoding methods
+  class TextField < BaseField
+    include FieldValues::Text
+    register_for :CLASS, :FN, :LABEL, :MAILER, :NOTE, :PRODID, :ROLE, 'SORT-STRING', :TITLE, :UID, :VERSION, :'X-PHONETIC-LAST-NAME', :'X-PHONETIC-FIRST-NAME'
+  end
+
+
+  # A BDAY in a vCard can be a free form text-value or a date. This class provides methods for both cases.
+  class Birthday < BaseField
+    include FieldValues::Text
+    include FieldValues::DateValue
+    register_for :BDAY
+  end
+
+
+  class Anniversary < BaseField
+    include FieldValues::Text
+    include FieldValues::DateValue
+    register_for "X-ANNIVERSARY"
+  end
+
+
+  # Instant messaging fields are defined in rfc 2427. They have a scheme and an address. If an IMPP is not 'clean' one can still get/set the value by using the methods from FieldValues::Text and FieldValues::Uri
+  class Impp < BaseField
+    include FieldValues::Text
+    include FieldValues::Uri
+    include Params::Type
+    register_for :IMPP
+#       include LocationHandling
+#       include PurposeHandling
+#       include PreferenceHandling
+#       PURPOSE_SETS = { "personal" => "Personal", "business" => "Business" }
+#       HUMAN_DESCRIPTION = "instant messaging"
+
+#       def initialize(content_line=ContentLine.new("IMPP:"))
+#         super
+#         @cline.name = "IMPP"
+#       end
+
+    def scheme
+      # every piece of text before the first colon, if there is a colon present
+      text.match(/^(.*?):/) # Note the use of "*?" for non greedy matching of the colon!
+      $1 || ""
+    end
+
+    def address
+      # everything after the first colon if that colon is present, otherwise the whole text
+      text.match(/^.*?:(.*)$|^(.*)$/)
+      $1 || $2
+    end
+
+    def scheme=(s)
+      self.text = "#{s}:#{address}"
+    end
+
+    def address=(s)
+      self.text = "#{self.scheme}:#{s}"
+    end
+
+    def raw_value
+      scheme.empty? && address.empty? ? "" : @value
+    end
+  end
+
+
+  # OS X AddressBook does not use the IMPP fields. Instead Apple chose to use their own proprietary format. This format is handles by CustomImField
+  class CustomImField < BaseField
+    include FieldValues::Text
+    PROTOCOL_TRANSLATION_TABLE = {
+      :aim => "X-AIM",
+      :msn => "X-MSN",
+      :ymsgr => "X-YAHOO",
+      :skype => "X-SKYPE",
+      :qq => "X-QQ",
+      :gtalk => "X-GOOGLE TALK",
+      :icq => "X-ICQ",
+      :xmpp => "X-JABBER",
+    }
+    PROTOCOL_TRANSLATION_TABLE.values.each { |protocol| register_for protocol }
+    PROTOCOL_TRANSLATION_INVERSE_TABLE = Hash[PROTOCOL_TRANSLATION_TABLE.map { |k, v| [v, k] }]
+
+    # convert a standard IMPP field to a Custom IM field. Only schemes defined in PROTOCOL_TRANSLATION_TABLE are supported.
+    def self.from_impp(impp)
+      nm = PROTOCOL_TRANSLATION_TABLE[impp.scheme.to_sym]
+      raise "unknown scheme #{impp.scheme} for #{impp.text.inspect}" if nm.nil?
+      x = Field.parse("#{nm}:")
+      x.params = Param::deep_copy(impp.params)
+      x.text = impp.address
+      x
+    end
+
+    def protocol
+      PROTOCOL_TRANSLATION_INVERSE_TABLE[name]
+    end
+
+    # convert to a standard IMPP field
+    def to_impp
+      impp = Field.parse("IMPP:")
+      impp.params = Param::deep_copy(@params)
+      impp.text = "#{protocol}:#{text}"
+      impp
+    end
+  end
+
+
+  # handle ORG fields.
+  #
+  # An Org has an orgname, a unit1 and a unit2. We stick to this simple
+  # definition for now since it is widely used. The vCard specs seem to
+  # specify an unlimited amount of units
+  class Org < BaseField
+    register_for :ORG
+    include FieldValues::StructuredText.define([:orgname, :unit1, :unit2])
+
+    def shortened
+      [orgname, unit1, unit2].join(" ").strip
+    end
+
+#       def ==(other)
+#         super ||
+#           has_name?(other.name) &&
+#           values == other.try(:values) && self.class === other && self.group == other.group
+#       end
+  end
+
+
+  # SeparatedField handles an array of text values
+  class SeparatedField < BaseField
+    include FieldValues::SeparatedText
+    register_for :CATEGORIES, :NICKNAME
+
+    def unpacked
+      values.map do |text|
+        self.class.new(name, EncodingDecoding::encode_text_list([text]), params, group)
+      end
+    end
+  end
+
+
+  # telephone number
+  #
+  # provides the easy getter/setter #number and generators for random numbers
+  class Tel < BaseField
+    include FieldValues::Text
+    include Params::Type
+    # include Params::Type::Preference
+    register_for :TEL
+    COMPARISON_REGEX = /[^\+\*\#\/\,\w]/u # anything that is NOT a plus, a star, a hash, a slash, a comma, or 0-9/a-z/A-Z is insignificant
+
+    alias_method :number, :text
+    alias_method :number=, :text=
+
+    def self.random_number(length = 10)
+      # (1..length).map { rand(10).to_s }.join
+      # only 555-0100 through 555-0199 are now specifically reserved for fictional use
+      random_part = 100 + (rand(99) + 1)
+      "555-0#{random_part}"
+    end
+
+    def self.at_random
+      new("TEL", random_number)
+    end
+
+    def significant_chars
+      # it's a phone number (but people could store alphanumeric stuff here) so I opt to remove all dashes and spaces
+      # I leave the plus since we don't know with what prefix to replace it with, see: http://en.wikipedia.org/wiki/List_of_international_call_prefixes
+      number.gsub(COMPARISON_REGEX, "")
+    end
+    alias_method :normalized_number, :significant_chars
+
+  end
+
+
+  class Email < BaseField
+    include FieldValues::Text
+    include Params::Type
+    register_for :EMAIL
+    alias_method :address, :text
+    alias_method :address=, :text=
+  end
+
+
+  class Adr < BaseField
+    include FieldValues::StructuredText.define([:pobox, :extended, :street, :locality, :region, :postal_code, :country])
+    include Params::Type
+    register_for :ADR
+    NAME = "ADR"
+  end
+
+
+  class Url < BaseField
+    include FieldValues::Text
+    include FieldValues::Uri
+    # URLs officialy don't have TYPE params,
+    # but everyone and their dog thinks they do.
+    # So we decided to support them too.
+    # Conclusion: no-one reads the RFC
+    include Params::Type
+    register_for :URL
+  end
+
+
+  class Name < BaseField
+    PARTS = %w(family given additional prefix suffix)
+    include FieldValues::StructuredText.define(PARTS)
+    register_for :N
+  end
+
+
+  class Photo < BaseField
+    include FieldValues::Text
+    include FieldValues::Binary
+    include FieldValues::Uri
+    register_for :LOGO, :PHOTO
+
+    def is_binary?
+      @params.detect {|p| p.key == "ENCODING" and p.value =~ /B/i }
+    end
+
+    def is_url?
+      !is_binary?
+    end
+  end
+
+
+  class Sound < BaseField
+    include FieldValues::Binary
+    include FieldValues::Text
+    include FieldValues::Uri
+    register_for :SOUND
+  end
+
+
+  class Key < BaseField
+    include FieldValues::Binary
+    include FieldValues::Text
+    register_for :KEY
+  end
+
+  class Gender < BaseField
+    register_for :GENDER
+    PARTS = %w(sex identity)
+    include FieldValues::OptionalStructuredText.define(PARTS)
+
+    {male: 'M', female: 'F', other: 'O', none: 'N', unknown: 'U'}.each do |name, letter|
+      class_eval <<-RUBY
+      def #{name}?
+        sex == "#{letter}"
+      end
+
+      def #{name}=(v)
+        raise "Only true is acceptable" unless v
+        self.sex = "#{letter}"
+      end
+      RUBY
+    end
+
+    def neither?
+      sex !~ /^[MFNOU]$/
+    end
+  end
+
+end