vpim 0.323 → 0.357

data/lib/vpim/property/location.rb

@@ -1,3 +1,11 @@
+=begin
+  Copyright (C) 2006 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.
+=end
+
 module Vpim
   class Icalendar
     module Property
@@ -10,7 +18,8 @@ module Vpim
 
         # Array of Float, +[ latitude, longitude]+.
         #
-        # North or equator is postive latitude, East of meridian is positive logitude.
+        # North of the equator is positive latitude, east of the meridian is
+        # positive longitude.
         #
         # See RFC2445 for more info... there are lots of special cases.
         def geo

data/lib/vpim/property/priority.rb

@@ -1,3 +1,11 @@
+=begin
+  Copyright (C) 2006 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.
+=end
+
 module Vpim
   class Icalendar
     module Property

data/lib/vpim/property/recurrence.rb

@@ -0,0 +1,47 @@
+=begin
+  Copyright (C) 2006 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.
+=end
+
+module Vpim
+  class Icalendar
+    module Property
+
+      # Occurrences are calculated from DTSTART: and RRULE:. If there is not
+      # RRULE:, the component recurs only once, at the start time.
+      #
+      # Limitations:
+      #
+      # Only a single RRULE: is currently supported, this is the most common
+      # case.
+      #
+      # Implementation of multiple RRULE:s, and RDATE:, EXRULE:, and EXDATE: is
+      # on the todo list.  Its not a very high priority, because I haven't seen
+      # calendars using the full range of recurrence features, and haven't
+      # received feedback from any users requesting these features. So, if you
+      # need it, contact me and implementation will get on the schedule.
+      module Recurrence
+        # The times this event occurs, as a Vpim::Rrule.
+        def occurences
+          start = dtstart
+          unless start
+            raise ArgumentError, "Components with no DTSTART: don't have occurences!"
+          end
+          Vpim::Rrule.new(start, propvalue('RRULE'))
+        end
+
+        # Check if this event overlaps with the time period later than or equal to +t0+, but
+        # earlier than +t1+.
+        def occurs_in?(t0, t1)
+          occurences.each_until(t1).detect { |t| tend = t + (duration || 0); tend > t0 }
+        end
+
+      end
+    end
+  end
+end
+
+

data/lib/vpim/property/resources.rb

@@ -1,3 +1,11 @@
+=begin
+  Copyright (C) 2006 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.
+=end
+
 module Vpim
   class Icalendar
     module Property

data/lib/vpim/rfc2425.rb

@@ -53,6 +53,9 @@ module Vpim
     # time-zone = "Z" / time-numzone
     # time-numzome = sign time-hour [":"] time-minute
     TIME = '(\d\d):?(\d\d):?(\d\d)(\.\d+)?(Z|[-+]\d\d:?\d\d)?'
+
+    # integer = (["+"] / "-") 1*DIGIT
+    INTEGER = '[-+]?\d+'
   end
 end
 
@@ -148,14 +151,23 @@ module Vpim
   # float
   #
   # float_list
-  #
-  # integer
+=begin
+=end
+
+  # Convert an RFC2425 INTEGER value into an Integer
+  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
+
   #
   # integer_list
   #
   # text_list
 
-  # Convert a RFC 2425 date-list into an array of dates.
+  # Convert a RFC2425 date-list into an array of dates.
   def Vpim.decode_date_list(v) # :nodoc:
     Vpim.decode_list(v) do |date|
       date.strip!
@@ -191,24 +203,49 @@ module Vpim
   # \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.
   def Vpim.decode_text(v) # :nodoc:
+    # FIXME - I think this should trim leading and trailing space
     v.gsub(/\\(.)/) do
       case $1
-      when '\\', ',', ';'
-        $1
       when 'n', 'N' 
         "\n"
       else
-        raise Vpim::InvalidEncodingError, "TEXT #{v.inspect} uses invalid escape sequence '\\#{$1}'"
+        $1
       end
     end
   end
+  
+  def Vpim.encode_text(v) #:nodoc:
+    v.to_str.gsub(/([.\n])/) do
+      case $1
+      when "\n"
+        "\\n"
+      when "\\", ",", ";"
+        "\\#{$1}"
+      else
+        $1
+      end
+    end
+  end
+
+  def Vpim.encode_text_list(v, sep = ",") #:nodoc:
+    v.to_ary.map{ |t| Vpim.encode_text(t) }.join(sep)
+  end
 
   # Convert a +sep+-seperated list of TEXT values into an array of values.
   def Vpim.decode_text_list(value, sep = ',') # :nodoc:
-    value.scan(/((?:(?:\\.)|[^#{sep}])+)#{sep}?/).map do |v|
+    # 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
 
 

data/lib/vpim/rrule.rb

@@ -135,7 +135,7 @@ module Vpim
     # less than +dountil+).
     #
     # Also, iteration will not currently continue past the limit of a Time
-    # object, which is some time in 2037 with the 32-bit time_t's common on
+    # object, which is some time in 2037 with the 32-bit time_t common on
     # most systems.
     def each(dountil = nil) #:yield: ytime
       t = @dtstart.clone

data/lib/vpim/vcard.rb

@@ -6,8 +6,12 @@
   details.
 =end
 
-require 'vpim/dirinfo'
 require 'vpim/vpim'
+require 'vpim/attachment'
+require 'vpim/dirinfo'
+
+require 'open-uri'
+require 'stringio'
 
 module Vpim
   # A vCard, a specialization of a directory info object.
@@ -16,9 +20,31 @@ module Vpim
   # - RFC2426: vCard MIME Directory Profile (vCard 3.0)
   # - RFC2425: A MIME Content-Type for Directory Information
   #
-  # This implements vCard 3.0, but it is also capable of decoding vCard 2.1.
+  # This implements vCard 3.0, but it is also capable of working with vCard 2.1
+  # if used with care.
+  #
+  # All line values can be accessed with Vcard#value, Vcard#values, or even by
+  # iterating through Vcard#lines. Line types that don't have specific support
+  # and non-standard line types ("X-MY-SPECIAL", for example) will be returned
+  # as a String, with any base64 or quoted-printable encoding removed. 
+  #
+  # Specific support exists to return more useful values for the standard vCard
+  # types, where appropriate.
+  #
+  # The wrapper functions (#birthday, #nicknames, #emails, etc.) exist
+  # partially as an API convenience, and partially as a place to document
+  # the values returned for the more complex types, like PHOTO and EMAIL.
+  #
+  # For types that do not sensibly occur multiple times (like BDAY or GEO),
+  # sometimes a wrapper exists only to return a single line, using #value.
+  # However, if you find the need, you can still call #values to get all the
+  # lines, and both the singular and plural forms will eventually be
+  # implemented.
   #
-  # For information about:
+  # If there is sufficient demand, specific support for vCard 2.1 could be
+  # implemented.
+  #
+  # For more information see:
   # - link:rfc2426.txt: vCard MIME Directory Profile (vCard 3.0)
   # - link:rfc2425.txt: A MIME Content-Type for Directory Information
   # - http://www.imc.org/pdi/pdiproddev.html: vCard 2.1 Specifications
@@ -26,17 +52,6 @@ module Vpim
   # vCards are usually transmitted in files with <code>.vcf</code>
   # extensions.
   #
-  # TODO - an open question is what exactly "vcard 2.1" support means. While I
-  # decode vCard 2.1 correctly, I don't encode it. Should I implement a
-  # transcoder, so vCards can be decoded from either version, and then written
-  # to either version? Maybe an option to Field#encode()?
-  #
-  # TODO - there are very few methods that Vcard has that DirectoryInfo
-  # doesn't. I could probably just do away with it entirely, but I suspect
-  # that there are methods that could be usefully added to Vcard, perhaps to
-  # get the email addresses, or the name, or perhaps to set fields, like
-  # email=. What would be useful?
-  #
   # = Examples
   #
   # - link:ex_mkvcard.txt: example of creating a vCard
@@ -51,18 +66,566 @@ module Vpim
   #   (small but) complete application contributed by Dane G. Avilla, thanks!
   # - link:vcf-to-ics.txt: example of how to create calendars of birthdays from vCards
   # - link:vcf-dump.txt: utility for dumping contents of .vcf files
-  #
-  # Here's an example of encoding a simple vCard using the low-level API:
-  #
-  #   card = Vpim::Vcard.create
-  #   card << Vpim::DirectoryInfo::Field.create('EMAIL', 'user.name@example.com', 'TYPE' => 'INTERNET' )
-  #   card << Vpim::DirectoryInfo::Field.create('URL', 'http://www.example.com/user' )
-  #   card << Vpim::DirectoryInfo::Field.create('FN', 'User Name' )
-  #   puts card.to_s
   class Vcard < DirectoryInfo
 
+    # Represents the value of an ADR field.
+    #
+    # #location, #preferred, and #delivery indicate information about how the
+    # address is to be used, the other attributes are parts of the address.
+    #
+    # Using values other than those defined for #location or #delivery is
+    # unlikely to be portable, or even conformant.
+    #
+    # All attributes are optional. #location and #delivery can be set to arrays
+    # of strings.
+    class Address
+      # post office box (String)
+      attr_accessor :pobox
+      # seldom used, its not clear what it is for (String)
+      attr_accessor :extended
+      # street address (String)
+      attr_accessor :street
+      # usually the city (String)
+      attr_accessor :locality
+      # usually the province or state (String)
+      attr_accessor :region
+      # postal code (String)
+      attr_accessor :postalcode
+      # country name (String)
+      attr_accessor :country
+      # home, work (Array of String): the location referred to by the address
+      attr_accessor :location
+      # true, false (boolean): where this is the preferred address (for this location)
+      attr_accessor :preferred
+      # postal, parcel, dom (domestic), intl (international) (Array of String): delivery
+      # type of this address
+      attr_accessor :delivery
+
+      # nonstandard types, their meaning is undefined (Array of String). These
+      # might be found during decoding, but shouldn't be set during encoding.
+      attr_reader :nonstandard
+
+      # Used to simplify some long and tedious code. These symbols are in the
+      # order required for the ADR field structured TEXT value, the order
+      # cannot be changed.
+      @@adr_parts = [
+        :@pobox,
+        :@extended,
+        :@street,
+        :@locality,
+        :@region,
+        :@postalcode,
+        :@country,
+      ]
+
+      # TODO
+      # - #location?
+      # - #delivery?
+      def initialize #:nodoc:
+        # TODO - Add #label to support LABEL. Try to find LABEL
+        # in either same group, or with sam params.
+        @@adr_parts.each do |part|
+          instance_variable_set(part, '')
+        end
+
+        @location = []
+        @preferred = false
+        @delivery = []
+        @nonstandard = []
+      end
+
+      def encode #:nodoc:
+        parts = @@adr_parts.map do |part|
+          instance_variable_get(part)
+        end
+
+        value = Vpim.encode_text_list(parts, ";")
+
+        params = [ @location, @delivery, @nonstandard ]
+        params << 'pref' if @preferred
+        params = params.flatten.compact.map { |s| s.to_str.downcase }.uniq
+
+        paramshash = {}
+
+        paramshash['TYPE'] = params if params.first
+
+        Vpim::DirectoryInfo::Field.create( 'ADR', value, paramshash)
+      end
+
+      def Address.decode(card, field) #:nodoc:
+        adr = new
+
+        parts = Vpim.decode_text_list(field.value_raw, ';')
+
+        @@adr_parts.each_with_index do |part,i|
+          adr.instance_variable_set(part, parts[i] || '')
+        end
+
+        params = field.pvalues('TYPE')
+
+        if params
+          params.each do |p|
+            p.downcase!
+            case p
+            when 'home', 'work'
+              adr.location << p
+            when 'postal', 'parcel', 'dom', 'intl'
+              adr.delivery << p
+            when 'pref'
+              adr.preferred = true
+            else
+              adr.nonstandard << p
+            end
+          end
+          # Strip duplicates
+          [ adr.location, adr.delivery, adr.nonstandard ].each do |a|
+            a.uniq!
+          end
+        end
+
+        adr
+      end
+    end
+
+    # Represents the value of an EMAIL field.
+    class Email < String
+      # true, false (boolean): whether this is the preferred email address
+      attr_accessor :preferred
+      # internet, x400 (String): the email address format, rarely specified
+      # since the default is 'internet'
+      attr_accessor :format
+      # home, work (Array of String): the location referred to by the address. The
+      # inclusion of location parameters in a vCard seems to be non-conformant,
+      # strictly speaking, but also seems to be widespread.
+      attr_accessor :location
+      # nonstandard types, their meaning is undefined (Array of String). These
+      # might be found during decoding, but shouldn't be set during encoding.
+      attr_reader :nonstandard
+
+      def initialize(email='') #:nodoc:
+        @preferred = false
+        @format = 'internet'
+        @location = []
+        @nonstandard = []
+        super(email)
+      end
+
+      def inspect #:nodoc:
+        s = "#<#{self.class.to_s}: #{to_str.inspect}"
+        s << ", pref" if preferred
+        s << ", #{format}" if format != 'internet'
+        s << ", " << @location.join(", ") if @location.first
+        s << ", #{@nonstandard.join(", ")}" if @nonstandard.first
+        s
+      end
+
+      def encode #:nodoc:
+        value = to_str.strip
+
+        if value.length < 1
+          raise InvalidEncodingError, "EMAIL must have a value"
+        end
+
+        params = [ @location, @nonstandard ]
+        params << @format if @format != 'internet'
+        params << 'pref'  if @preferred
+
+        params = params.flatten.compact.map { |s| s.to_str.downcase }.uniq
+
+        paramshash = {}
+
+        paramshash['TYPE'] = params if params.first
+
+        Vpim::DirectoryInfo::Field.create( 'EMAIL', value, paramshash)
+      end
+
+      def Email.decode(field) #:nodoc:
+        value = field.to_text.strip
+
+        if value.length < 1
+          raise InvalidEncodingError, "EMAIL must have a value"
+        end
+
+        eml = Email.new(value)
+
+        params = field.pvalues('TYPE')
+
+        if params
+          params.each do |p|
+            p.downcase!
+            case p
+            when 'home', 'work'
+              eml.location << p
+            when 'pref'
+              eml.preferred = true
+            when 'x400', 'internet'
+              eml.format = p
+            else
+              eml.nonstandard << p
+            end
+          end
+          # Strip duplicates
+          [ eml.location, eml.nonstandard ].each do |a|
+            a.uniq!
+          end
+        end
+
+        eml
+      end
+    end
+
+    # Represents the value of a TEL field.
+    # 
+    # The value is supposed to be a "X.500 Telephone Number" according to RFC
+    # 2426, but that standard is not freely available. Otherwise, anything that
+    # looks like a phone number should be OK.
+    class Telephone < String
+      # true, false (boolean): whether this is the preferred email address
+      attr_accessor :preferred
+      # home, work, cell, car, pager (Array of String): the location
+      # of the device
+      attr_accessor :location
+      # voice, fax, video, msg, bbs, modem, isdn, pcs (Array of String): the
+      # capabilities of the device
+      attr_accessor :capability
+      # nonstandard types, their meaning is undefined (Array of String). These
+      # might be found during decoding, but shouldn't be set during encoding.
+      attr_reader :nonstandard
+
+      def initialize(telephone='') #:nodoc:
+        @preferred = false
+        @location = []
+        @capability = []
+        @nonstandard = []
+        super(telephone)
+      end
+
+      def inspect #:nodoc:
+        s = "#<#{self.class.to_s}: #{to_str.inspect}"
+        s << ", pref" if preferred
+        s << ", " << @location.join(", ") if @location.first
+        s << ", " << @capability.join(", ") if @capability.first
+        s << ", #{@nonstandard.join(", ")}" if @nonstandard.first
+        s
+      end
+
+      def encode #:nodoc:
+        value = to_str.strip
+
+        if value.length < 1
+          raise InvalidEncodingError, "TEL must have a value"
+        end
+
+        params = [ @location, @capability, @nonstandard ]
+        params << 'pref'  if @preferred
+
+        params = params.flatten.compact.map { |s| s.to_str.downcase }.uniq
+
+        paramshash = {}
+
+        paramshash['TYPE'] = params if params.first
+
+        Vpim::DirectoryInfo::Field.create( 'TEL', value, paramshash)
+      end
+
+      def Telephone.decode(field) #:nodoc:
+        value = field.to_text.strip
+
+        if value.length < 1
+          raise InvalidEncodingError, "TEL must have a value"
+        end
+
+        tel = Telephone.new(value)
+
+        params = field.pvalues('TYPE')
+
+        if params
+          params.each do |p|
+            p.downcase!
+            case p
+            when 'home', 'work', 'cell', 'car', 'pager'
+              tel.location << p
+            when 'voice', 'fax', 'video', 'msg', 'bbs', 'modem', 'isdn', 'pcs'
+              tel.capability << p
+            when 'pref'
+              tel.preferred = true
+            else
+              tel.nonstandard << p
+            end
+          end
+          # Strip duplicates
+          [ tel.location, tel.capability, tel.nonstandard ].each do |a|
+            a.uniq!
+          end
+        end
+
+        tel
+      end
+    end
+
+    # The name from a vCard, including all the components of the N: and FN:
+    # fields.
+    class Name
+      # family name, from N
+      attr_accessor :family
+      # given name, from N
+      attr_accessor :given
+      # additional names, from N
+      attr_accessor :additional
+      # such as "Ms." or "Dr.", from N
+      attr_accessor :prefix
+      # such as "BFA", from N
+      attr_accessor :suffix
+      # full name, the FN field. FN is a formatted version of the N field,
+      # intended to be in a form more aligned with the cultural conventions of
+      # the vCard owner than +formatted+ is.
+      attr_accessor :fullname
+      # all the components of N formtted as "#{prefix} #{given} #{additional} #{family}, #{suffix}"
+      attr_reader   :formatted
+
+      # Override the attr reader to make it dynamic
+      remove_method :formatted
+      def formatted #:nodoc:
+        f = [ @prefix, @given, @additional, @family ].map{|i| i == '' ? nil : i.strip}.compact.join(' ')
+        if @suffix != ''
+          f << ', ' << @suffix
+        end
+        f
+      end
+
+      def initialize(n='', fn='') #:nodoc:
+        n = Vpim.decode_text_list(n, ';') do |item|
+          item.strip
+        end
+
+        @family     = n[0] || ""
+        @given      = n[1] || ""
+        @additional = n[2] || ""
+        @prefix     = n[3] || ""
+        @suffix     = n[4] || ""
+
+        # FIXME - make calls to #fullname fail if fn is nil
+        @fullname = (fn || "").strip
+      end
+
+      def encode #:nodoc:
+         Vpim::DirectoryInfo::Field.create('N',
+           Vpim.encode_text_list([ @family, @given, @additional, @prefix, @suffix ].map{|n| n.strip}, ';')
+           )
+      end
+      def encode_fn #:nodoc:
+        fn = @fullname.strip
+        if @fullname.length == 0
+          fn = formatted
+        end
+        Vpim::DirectoryInfo::Field.create('FN', fn)
+      end
+
+    end
+
+    def decode_invisible(field) #:nodoc:
+      nil
+    end
+
+    def decode_default(field) #:nodoc:
+      Line.new( field.group, field.name, field.value )
+    end
+
+    def decode_version(field) #:nodoc:
+      Line.new( field.group, field.name, (field.value.to_f * 10).to_i )
+    end
+
+    def decode_text(field) #:nodoc:
+      Line.new( field.group, field.name, Vpim.decode_text(field.value_raw) )
+    end
+
+    def decode_n(field) #:nodoc:
+      Line.new( field.group, field.name, Name.new(field.value, self['FN']).freeze )
+    end
+
+    def decode_date_or_datetime(field) #:nodoc:
+      date = nil
+      begin
+        date = Vpim.decode_date(field.value_raw)
+        date = Date.new(*date)
+      rescue Vpim::InvalidEncodingError
+        # FIXME - try and decode as DATE-TIME
+        raise
+      end
+      Line.new( field.group, field.name, date )
+    end
+
+    def decode_bday(field) #:nodoc:
+      begin
+        return decode_date_or_datetime(field)
+
+      rescue Vpim::InvalidEncodingError
+        if field.value =~ /(\d+)-(\d+)-(\d+)/
+          y = $1.to_i
+          m = $2.to_i
+          d = $3.to_i
+          if(y < 1900)
+            y = Time.now.year
+          end
+          Line.new( field.group, field.name, Date.new(y, m, d) )
+        else
+          raise
+        end
+      end
+    end
+
+    def decode_geo(field) #:nodoc:
+      geo = Vpim.decode_list(field.value_raw, ';') do |item| item.to_f end
+      Line.new( field.group, field.name, geo )
+    end
+
+    def decode_address(field) #:nodoc:
+      Line.new( field.group, field.name, Address.decode(self, field) )
+    end
+
+    def decode_email(field) #:nodoc:
+      Line.new( field.group, field.name, Email.decode(field) )
+    end
+
+    def decode_telephone(field) #:nodoc:
+      Line.new( field.group, field.name, Telephone.decode(field) )
+    end
+
+    def decode_list_of_text(field) #:nodoc:
+      Line.new( field.group, field.name,
+               Vpim.decode_text_list(field.value_raw).select{|t| t.length > 0}.uniq
+              )
+    end
+
+    def decode_structured_text(field) #:nodoc:
+      Line.new( field.group, field.name, Vpim.decode_text_list(field.value_raw, ';') )
+    end
+
+    def decode_uri(field) #:nodoc:
+      Line.new( field.group, field.name, Uri.new(field.value) )
+    end
+
+    def decode_agent(field) #:nodoc:
+      case field.kind
+      when 'text'
+        decode_text(field)
+      when 'uri'
+        decode_uri(field)
+      when 'vcard', nil
+        Line.new( field.group, field.name, Vcard.decode(Vpim.decode_text(field.value_raw)).first )
+      else
+        raise InvalidEncodingError, "AGENT type #{field.kind} is not allowed"
+      end
+    end
+
+    def decode_attachment(field) #:nodoc:
+      Line.new( field.group, field.name, Attachment.decode(field, 'binary', 'TYPE') )
+    end
+
+    @@decode = {
+      'BEGIN'      => :decode_invisible, # Don't return delimiter
+      'END'        => :decode_invisible, # Don't return delimiter
+      'FN'         => :decode_invisible, # Returned as part of N.
+
+      'ADR'        => :decode_address,
+      'AGENT'      => :decode_agent,
+      'BDAY'       => :decode_bday,
+      'CATEGORIES' => :decode_list_of_text,
+      'EMAIL'      => :decode_email,
+      'GEO'        => :decode_geo,
+      'KEY'        => :decode_attachment,
+      'LOGO'       => :decode_attachment,
+      'MAILER'     => :decode_text,
+      'N'          => :decode_n,
+      'NAME'       => :decode_text,
+      'NICKNAME'   => :decode_list_of_text,
+      'NOTE'       => :decode_text,
+      'ORG'        => :decode_structured_text,
+      'PHOTO'      => :decode_attachment,
+      'PRODID'     => :decode_text,
+      'PROFILE'    => :decode_text,
+      'REV'        => :decode_date_or_datetime,
+      'ROLE'       => :decode_text,
+      'SOUND'      => :decode_attachment,
+      'SOURCE'     => :decode_text,
+      'TEL'        => :decode_telephone,
+      'TITLE'      => :decode_text,
+      'UID'        => :decode_text,
+      'URL'        => :decode_uri,
+      'VERSION'    => :decode_version,
+    }
+
+    @@decode.default = :decode_default
+
+    # Cache of decoded lines/fields, so we don't have to decode a field more than once.
+    attr_reader :cache #:nodoc:
+
+    # An entry in a vCard. The #value object's type varies with the kind of
+    # line (the #name), and on how the line was encoded. The objects returned
+    # for a specific kind of line are often extended so that they support a
+    # common set of methods. The goal is to allow all types of objects for a
+    # kind of line to be treated with some uniformity, but still allow specific
+    # handling for the various value types if desired.
+    #
+    # See the specific methods for details.
+    class Line
+      attr_reader :group
+      attr_reader :name
+      attr_reader :value
+
+      def initialize(group, name, value) #:nodoc:
+        @group, @name, @value = (group||''), name.to_str, value
+      end
+
+      def self.decode(decode, card, field) #:nodoc:
+        card.cache[field] || (card.cache[field] = card.send(decode[field.name], field))
+      end
+    end
+
+    #@lines = {} FIXME - dead code
+
+    # Return line for a field
+    def f2l(field) #:nodoc:
+      Line.decode(@@decode, self, field)
+    end
+
+    # With no block, returns an Array of Line. If +name+ is specified, the
+    # Array will only contain the +Line+s with that +name+. The Array may be
+    # empty.
+    #
+    # If a block is given, each Line will be yielded instead of being returned
+    # in an Array.
+    def lines(name=nil) #:yield: Line
+      # FIXME - this would be much easier if #lines was #each, and there was a
+      # different #lines that returned an Enumerator that used #each
+      unless block_given?
+        map do |f|
+          if( !name || f.name?(name) )
+           f2l(f)
+          else
+            nil
+          end
+        end.compact
+      else
+        each do |f|
+          if( !name || f.name?(name) )
+            line = f2l(f)
+            if line
+              yield line
+            end
+          end
+        end
+        self
+      end
+    end
+
     private_class_method :new
 
+    def initialize(fields, profile) #:nodoc:
+      @cache = {}
+      super(fields, profile)
+    end
+
     # Create a vCard 3.0 object with the minimum required fields, plus any
     # +fields+ you want in the card (they can also be added later).
     def Vcard.create(fields = [] )
@@ -139,23 +702,12 @@ module Vpim
       vcards
     end
 
-    # The vCard version multiplied by 10 as an Integer.  If no VERSION field
-    # is present (which is non-conformant), nil is returned.  For example, a
-    # version 2.1 vCard would have a version of 21, and a version 3.0 vCard
-    # would have a version of 30.
-    def version
-      v = self["version"]
-      unless v
-        raise Vpim::InvalidEncodingError, 'Invalid vCard - it has no version field!'
-      end
-      v = v.to_f * 10
-      v = v.to_i
-    end
-
     # The value of the field named +name+, optionally limited to fields of
     # type +type+. If no match is found, nil is returned, if multiple matches
     # are found, the first match to have one of its type values be 'PREF'
     # (preferred) is returned, otherwise the first match is returned.
+    #
+    # FIXME - this will become an alias for #value.
     def [](name, type=nil)
       fields = enum_by_name(name).find_all { |f| type == nil || f.type?(type) }
 
@@ -174,103 +726,675 @@ module Vpim
       fields.first ? fields.first.value : nil
     end
 
-    # The name from a vCard, including all the components of the N: and FN:
-    # fields.
+    # Return the Line#value for a specific +name+, and optionally for a
+    # specific +type+.
+    #
+    # If no line with the +name+ (and, optionally, +type+) exists, nil is
+    # returned.
+    #
+    # If multiple lines exist, the order of preference is:
+    # - lines with values over lines without
+    # - lines with a type of 'pref' over lines without
+    # If multiple lines are equally preferred, then the first line will be
+    # returned.
+    #
+    # This is most useful when looking for a line that can not occur multiple
+    # times, or when the line can occur multiple times, and you want to pick
+    # the first preferred line of a specific type. See #values if you need to
+    # access all the lines.
+    #
+    # Note that the +type+ field parameter is used for different purposes by
+    # the various kinds of vCard lines, but for the addressing lines (ADR,
+    # LABEL, TEL, EMAIL) it is has a reasonably consistent usage. Each
+    # addressing line can occur multiple times, and a +type+ of 'pref'
+    # indicates that a particular line is the preferred line. Other +type+
+    # values tend to indicate some information about the location ('home',
+    # 'work', ...) or some detail about the address ('cell', 'fax', 'voice',
+    # ...). See the methods for the specific types of line for information
+    # about supported types and their meaning.
+    def value(name, type = nil)
+      v = nil
 
-    class Name
-      # family name from N:
-      attr_reader :family
-      # given name from N:
-      attr_reader :given
-      # additional names from N:
-      attr_reader :additional
-      # such as "Ms." or "Dr.", from N:
-      attr_reader :prefix
-      # such as "BFA", from N:
-      attr_reader :suffix
-      # all the components of N: formtted as "#{prefix} #{given} #{additional} #{family}, #{suffix}"
-      attr_reader :formatted
-      # full name, the FN: field, a formatted version of the N: field, probably
-      # in a form more align with the cultural conventions of the vCard owner
-      # than +formatted+ is
-      attr_reader :fullname
-
-      def initialize(n, fn) #:nodoc:
-        n = Vpim.decode_list(n, ';') do |item|
-          item.strip
-        end
+      fields = enum_by_name(name).find_all { |f| type == nil || f.type?(type) }
 
-        @family     = n[0] || ""
-        @given      = n[1] || ""
-        @additional = n[2] || ""
-        @prefix     = n[3] || ""
-        @suffix     = n[4] || ""
-        @formatted = [ @prefix, @given, @additional, @family ].map{|i| i == '' ? nil : i}.compact.join(' ')
-        if @suffix != ''
-          @formatted << ', ' << @suffix
-        end
+      valued = fields.select { |f| f.value != '' }
+      if valued.first
+        fields = valued
+      end
 
-        # FIXME - make calls to #fullname fail if fn is nil
-        @fullname = fn
+      pref = fields.select { |f| f.pref? }
+
+      if pref.first
+        fields = pref
+      end
+
+      if fields.first
+         line = Line.decode(@@decode, self, fields.first)
+
+         if line
+           return line.value
+         end
       end
 
+      nil
+    end
+
+    # A variant of #lines that only iterates over specific Line names. Since
+    # the name is known, only the Line#value is returned or yielded.
+    def values(name)
+      unless block_given?
+        lines(name).map { |line| line.value }
+      else
+        lines(name) { |line| yield line.value }
+      end
+    end
+
+    # The first ADR value of type +type+, a Address. Any of the location or
+    # delivery attributes of Address can be used as +type+. A wrapper around
+    # #value('ADR', +type+).
+    def address(type=nil)
+      value('ADR', type)
+    end
+
+    # The ADR values, an array of Address. If a block is given, the values are
+    # yielded. A wrapper around #values('ADR').
+    def addresses #:yield:address
+      values('ADR')
+    end
+
+    # The AGENT values. Each AGENT value is either a String, a Uri, or a Vcard.
+    # If a block is given, the values are yielded. A wrapper around
+    # #values('AGENT').
+    def agents #:yield:agent
+      values('AGENT')
+    end
+
+    # The BDAY value as either a Date or a DateTime, or nil if there is none.
+    #
+    # If the BDAY value is invalidly formatted, a feeble heuristic is applied
+    # to find the month and year, and return a Date in the current year.
+    def birthday
+      value('BDAY')
+    end
+
+    # The CATEGORIES values, an array of String. A wrapper around
+    # #value('CATEGORIES').
+    def categories
+      value('CATEGORIES')
+    end
+
+    # The first EMAIL value of type +type+, a Email. Any of the location
+    # attributes of Email can be used as +type+. A wrapper around
+    # #value('EMAIL', +type+).
+    def email(type=nil)
+      value('EMAIL', type)
+    end
+
+    # The EMAIL values, an array of Email. If a block is given, the values are
+    # yielded. A wrapper around #values('EMAIL').
+    def emails #:yield:email
+      values('EMAIL')
+    end
+
+    # The GEO value, an Array of two Floats, +[ latitude, longitude]+.  North
+    # of the equator is positive latitude, east of the meridian is positive
+    # longitude.  See RFC2445 for more info, there are lots of special cases
+    # and RFC2445's description is more complete thant RFC2426.
+    def geo
+      value('GEO')
+    end
+
+    # Return an Array of KEY Line#value, or yield each Line#value if a block
+    # is given. A wrapper around #values('KEY').
+    #
+    # KEY is a public key or authentication certificate associated with the
+    # object that the vCard represents. It is not commonly used, but could
+    # contain a X.509 or PGP certificate.
+    #
+    # See Attachment for a description of the value.
+    def keys(&proc) #:yield: Line.value
+      values('KEY', &proc)
+    end
+
+    # Return an Array of LOGO Line#value, or yield each Line#value if a block
+    # is given. A wrapper around #values('LOGO').
+    #
+    # LOGO is a graphic image of a logo associated with the object the vCard
+    # represents. Its not common, but would probably be equivalent to the logo
+    # on printed card.
+    #
+    # See Attachment for a description of the value.
+    def logos(&proc) #:yield: Line.value
+      values('LOGO', &proc)
     end
 
-    # Returns the +name+ fields, N: and FN:, as a Name.
+    ## MAILER
+
+    # The N and FN as a Name object.
+    #
+    # N is required for a vCards, this raises InvalidEncodingError if
+    # there is no N so it cannot return nil.
     def name
-      unless instance_variables.include? '@name'
-        @name = Name.new(self['N'], self['FN'])
+      value('N') || raise(Vpim::InvalidEncodingError, "Missing mandatory N field")
+    end
+
+    # The first NICKNAME value, nil if there are none.
+    def nickname
+      v = value('NICKNAME')
+      v = v.first if v
+      v
+    end
+
+    # The NICKNAME values, an array of String. The array may be empty.
+    def nicknames
+      values('NICKNAME').flatten.uniq
+    end
+
+    # The NOTE value, a String. A wrapper around #value('NOTE').
+    def note
+      value('NOTE')
+    end
+
+    # The ORG value, an Array of String. The first string is the organization,
+    # subsequent strings are departments within the organization. A wrapper
+    # around #value('ORG').
+    def org
+      value('ORG')
+    end
+
+    # Return an Array of PHOTO Line#value, or yield each Line#value if a block
+    # is given. A wrapper around #values('PHOTO').
+    #
+    # PHOTO is an image or photograph information that annotates some aspect of
+    # the object the vCard represents. Commonly there is one PHOTO, and it is a
+    # photo of the person identified by the vCard.
+    #
+    # See Attachment for a description of the value.
+    def photos(&proc) #:yield: Line.value
+      values('PHOTO', &proc)
+    end
+
+    ## PRODID
+
+    ## PROFILE
+
+    ## REV
+
+    ## ROLE
+
+    # Return an Array of SOUND Line#value, or yield each Line#value if a block
+    # is given. A wrapper around #values('SOUND').
+    #
+    # SOUND is digital sound content information that annotates some aspect of
+    # the vCard. By default this type is used to specify the proper
+    # pronunciation of the name associated with the vCard. It is not commonly
+    # used. Also, note that there is no mechanism available to specify that the
+    # SOUND is being used for anything other than the default.
+    #
+    # See Attachment for a description of the value.
+    def sounds(&proc) #:yield: Line.value
+      values('SOUND', &proc)
+    end
+
+    ## SOURCE
+
+    # The first TEL value of type +type+, a Telephone. Any of the location or
+    # capability attributes of Telephone can be used as +type+. A wrapper around
+    # #value('TEL', +type+).
+    def telephone(type=nil)
+      value('TEL', type)
+    end
+
+    # The TEL values, an array of Telephone. If a block is given, the values are
+    # yielded. A wrapper around #values('TEL').
+    def telephones #:yield:tel
+      values('TEL')
+    end
+
+    ## TITLE
+
+    ## UID
+
+    # The URL value, a Uri. A wrapper around #value('NOTE').
+    def url
+      value('URL')
+    end
+
+    # The VERSION multiplied by 10 as an Integer.  For example, a VERSION:2.1
+    # vCard would have a version of 21, and a VERSION:3.0 vCard would have a
+    # version of 30.
+    #
+    # VERSION is required for a vCard, this raises InvalidEncodingError if
+    # there is no VERSION so it cannot return nil.
+    def version
+      v = value('VERSION')
+      unless v
+        raise Vpim::InvalidEncodingError, 'Invalid vCard - it has no version field!'
       end
-      @name
+      v
     end
 
-    # Deprecated.
-    def nickname #:nodoc:
-      nn = self['NICKNAME']
-      if nn && nn == ''
-        nn = nil
+    # Make changes to a vCard.
+    #
+    # Yields a Vpim::Vcard::Maker that can be used to modify this vCard.
+    def make #:yield: maker
+      Vpim::Vcard::Maker.make2(self) do |maker|
+        yield maker
       end
-      nn
     end
 
-    # All the nicknames, [] if there are none.
-    def nicknames
-      enum_by_name('NICKNAME').select{|f| f.value != ''}.collect{|f| f.value}
+    # Delete +line+ if block yields true.
+    def delete_if #:nodoc: :yield: line
+      # Do in two steps to not mess up progress through the enumerator.
+      rm = []
+
+      each do |f|
+        line = f2l(f)
+        if line && yield(line)
+          rm << f
+
+          # Hack - because we treat N and FN as one field
+          if f.name? 'N'
+            rm << field('FN')
+          end
+        end
+      end
+
+      rm.each do |f|
+        @fields.delete( f )
+        @cache.delete( f )
+      end
+
     end
 
-    # Returns the birthday as a Date on success, nil if there was no birthday
-    # field, and raises an error if the birthday field could not be expressed
-    # as a recurring event.
+    # A class to make and make changes to vCards.
     #
-    # Also, I have a lot of vCards with dates that look like:
-    #   678-09-23
-    # The 678 is garbage, but 09-23 is really the birthday. This substitutes the
-    # current year for the 3 digit year, and then converts to a Date.
-    def birthday
-      bday = self.field('BDAY')
+    # It can be used to create completely new vCards using Vcard#make2.
+    #
+    # Its is also yielded from Vpim::Vcard#make, in which case it allows a kind
+    # of transactional approach to changing vCards, so their values can be
+    # validated after any changes have been made.
+    #
+    # Examples:
+    # - link:ex_mkvcard.txt: example of creating a vCard
+    # - link:ex_cpvcard.txt: example of copying and them modifying a vCard
+    # - link:ex_mkv21vcard.txt: example of creating version 2.1 vCard
+    # - link:ex_mkyourown.txt: example of adding support for new fields to Vcard::Maker
+    class Maker
+      # Make a vCard.
+      #
+      # Yields +maker+, a Vpim::Vcard::Maker which allows fields to be added to
+      # +card+, and returns +card+, a Vpim::Vcard.
+      #
+      # If +card+ is nil or not provided a new Vpim::Vcard is created and the
+      # fields are added to it.
+      #
+      # Defaults:
+      # - vCards must have both an N and an FN field, #make2 will fail if there
+      #   is no N field in the +card+ when your block is finished adding fields.
+      # - If there is an N field, but no FN field, FN will be set from the
+      #   information in N, see Vcard::Name#preformatted for more information.
+      # - vCards must have a VERSION field. If one does not exist when your block is
+      #   is finished it will be set to 3.0.
+      def self.make2(card = Vpim::Vcard.create, &block) # :yields: maker
+        new(nil, card).make(&block)
+      end
 
-      return nil unless bday
+      # Deprecated, use #make2.
+      #
+      # If set, the FN field will be set to +full_name+. Otherwise, FN will
+      # be set from the values in #name.
+      def self.make(full_name = nil, &block) # :yields: maker
+        new(full_name, Vpim::Vcard.create).make(&block)
+      end
 
-      begin
-        date = bday.to_date.first
+      def make # :nodoc:
+        yield self
+        unless @card['N']
+          raise Unencodeable, 'N field is mandatory'
+        end
+        fn = @card.field('FN')
+        if fn && fn.value.strip.length == 0
+          @card.delete(fn)
+          fn = nil
+        end
+        unless fn
+          @card << Vpim::DirectoryInfo::Field.create('FN', Vpim::Vcard::Name.new(@card['N'], '').formatted)
+        end
+        unless @card['VERSION']
+          @card << Vpim::DirectoryInfo::Field.create('VERSION', "3.0")
+        end
+        @card
+      end
 
-      rescue Vpim::InvalidEncodingError
-        if bday.value =~ /(\d+)-(\d+)-(\d+)/
-          y = $1.to_i
-          m = $2.to_i
-          d = $3.to_i
-          if(y < 1900)
-            y = Time.now.year
+      private
+
+      def initialize(full_name, card) # :nodoc:
+        @card = card || Vpim::Vcard::create
+        if full_name
+          @card << Vpim::DirectoryInfo::Field.create('FN', full_name.strip )
+        end
+      end
+
+      public
+
+      #     def add_name # :yield: n
+      #       # FIXME: Each attribute can currently only have a single String value.
+      #       # FIXME: Need to escape specials in the String.
+      #       x = Struct.new(:family, :given, :additional, :prefix, :suffix).new
+      #       yield x
+      #       @card << Vpim::DirectoryInfo::Field.create(
+      #         'N',
+      #         x.map { |s| s ? s.to_str : '' }
+      #         )
+      #       self
+      #     end
+      # Set with #name now.
+      # Use m.name do |n| n.fullname = foo end
+      def fullname=(fullname) #:nodoc: bacwards compat
+        if @card.field('FN')
+          raise Vpim::InvalidEncodingError, "Not allowed to add more than one FN field to a vCard."
+        end
+        @card << Vpim::DirectoryInfo::Field.create( 'FN', fullname );
+      end
+
+      # Set the name fields, N and FN.
+      #
+      # Attributes of +name+ are:
+      # - family: family name
+      # - given: given name
+      # - additional: additional names
+      # - prefix: such as "Ms." or "Dr."
+      # - suffix: such as "BFA", or "Sensei"
+      #
+      # +name+ is a Vcard::Name.
+      #
+      # All attributes are optional, though have all names be zero-length
+      # strings isn't really in the spirit of  things. FN's value will be set
+      # to Vcard::Name#formatted if Vcard::Name#fullname isn't given a specific
+      # value.
+      #
+      # Warning: This is the only mandatory field.
+      def name #:yield:name
+        x = begin
+              @card.name.dup
+            rescue
+              Vpim::Vcard::Name.new
+            end
+
+        fn = x.fullname
+
+        yield x
+
+        x.fullname.strip!
+
+        delete_if do |line|
+          line.name == 'N'
+        end
+
+        @card << x.encode
+        @card << x.encode_fn
+
+        self
+      end
+
+      alias :add_name :name #:nodoc: backwards compatibility
+
+      # Add an address field, ADR. +address+ is a Vpim::Vcard::Address.
+      def add_addr # :yield: address
+        x = Vpim::Vcard::Address.new
+        yield x
+        @card << x.encode
+        self
+      end
+
+      # Add a telephone field, TEL. +tel+ is a Vpim::Vcard::Telephone.
+      #
+      # The block is optional, its only necessary if you want to specify
+      # the optional attributes.
+      def add_tel(number) # :yield: tel
+        x = Vpim::Vcard::Telephone.new(number)
+        if block_given?
+          yield x
+        end
+        @card << x.encode
+        self
+      end
+
+      # Add an email field, EMAIL. +email+ is a Vpim::Vcard::Email.
+      #
+      # The block is optional, its only necessary if you want to specify
+      # the optional attributes.
+      def add_email(email) # :yield: email
+        x = Vpim::Vcard::Email.new(email)
+        if block_given?
+          yield x
+        end
+        @card << x.encode
+        self
+      end
+
+      # Set the nickname field, NICKNAME.
+      #
+      # It can be set to a single String or an Array of String.
+      def nickname=(nickname)
+        delete_if { |l| l.name == 'NICKNAME' }
+
+        @card << Vpim::DirectoryInfo::Field.create( 'NICKNAME', nickname );
+      end
+
+      # Add a birthday field, BDAY.
+      #
+      # +birthday+ must be a time or date object.
+      #
+      # Warning: It may confuse both humans and software if you add multiple
+      # birthdays.
+      def birthday=(birthday)
+        if !birthday.respond_to? :month
+          raise ArgumentError, 'birthday must be a date or time object.'
+        end
+        delete_if { |l| l.name == 'BDAY' }
+        @card << Vpim::DirectoryInfo::Field.create( 'BDAY', birthday );
+      end
+
+      # Add a note field, NOTE. The +note+ String can contain newlines, they
+      # will be escaped.
+      def add_note(note)
+        @card << Vpim::DirectoryInfo::Field.create( 'NOTE', Vpim.encode_text(note) );
+      end
+
+      # Add an instant-messaging/point of presence address field, IMPP. The address
+      # is a URL, with the syntax depending on the protocol.
+      #
+      # Attributes of IMPP are:
+      # - preferred: true - set if this is the preferred address
+      # - location: home, work, mobile - location of address
+      # - purpose: personal,business - purpose of communications
+      #
+      # All attributes are optional, and so is the block.
+      #
+      # The URL syntaxes for the messaging schemes is fairly complicated, so I
+      # don't try and build the URLs here, maybe in the future. This forces
+      # the user to know the URL for their own address, hopefully not too much
+      # of a burden.
+      #
+      # IMPP is defined in draft-jennings-impp-vcard-04.txt. It refers to the
+      # URI scheme of a number of messaging protocols, but doesn't give
+      # references to all of them:
+      # - "xmpp" indicates to use XMPP, draft-saintandre-xmpp-uri-06.txt
+      # - "irc" or "ircs" indicates to use IRC, draft-butcher-irc-url-04.txt
+      # - "sip" indicates to use SIP/SIMPLE, RFC 3261
+      # - "im" or "pres" indicates to use a CPIM or CPP gateway, RFC 3860 and RFC 3859
+      # - "ymsgr" indicates to use yahoo
+      # - "msn" might indicate to use Microsoft messenger
+      # - "aim" indicates to use AOL
+      #
+      def add_impp(url) # :yield: impp
+        params = {}
+
+        if block_given?
+          x = Struct.new( :location, :preferred, :purpose ).new
+
+          yield x
+
+          x[:preferred] = 'PREF' if x[:preferred]
+
+          types = x.to_a.flatten.compact.map { |s| s.downcase }.uniq
+
+          params['TYPE'] = types if types.first
+        end
+
+        @card << Vpim::DirectoryInfo::Field.create( 'IMPP', url, params)
+        self
+      end
+
+      # Add an X-AIM account name where +xaim+ is an AIM screen name.
+      #
+      # I don't know if this is conventional, or supported by anything other
+      # than AddressBook.app, but an example is:
+      #   X-AIM;type=HOME;type=pref:exampleaccount
+      #
+      # Attributes of X-AIM are:
+      # - preferred: true - set if this is the preferred address
+      # - location: home, work, mobile - location of address
+      #
+      # All attributes are optional, and so is the block.
+      def add_x_aim(xaim) # :yield: xaim
+        params = {}
+
+        if block_given?
+          x = Struct.new( :location, :preferred ).new
+
+          yield x
+
+          x[:preferred] = 'PREF' if x[:preferred]
+
+          types = x.to_a.flatten.compact.map { |s| s.downcase }.uniq
+
+          params['TYPE'] = types if types.first
+        end
+
+        @card << Vpim::DirectoryInfo::Field.create( 'X-AIM', xaim, params)
+        self
+      end
+
+
+      # Add a photo field, PHOTO.
+      #
+      # Attributes of PHOTO are:
+      # - image: set to image data to include inline
+      # - link: set to the URL of the image data
+      # - type: string identifying the image type, supposed to be an "IANA registered image format",
+      #     or a non-registered image format (usually these start with an x-)
+      #
+      # An error will be raised if neither image or link is set, or if both image
+      # and link is set.
+      #
+      # Setting type is optional for a link image, because either the URL, the
+      # image file extension, or a HTTP Content-Type may specify the type. If
+      # it's not a link, setting type is mandatory, though it can be set to an
+      # empty string, <code>''</code>, if the type is unknown.
+      #
+      # TODO - I'm not sure about this API. I'm thinking maybe it should be
+      # #add_photo(image, type), and that I should detect when the image is a
+      # URL, and make type mandatory if it wasn't a URL.
+      def add_photo # :yield: photo
+        x = Struct.new(:image, :link, :type).new
+        yield x
+        if x[:image] && x[:link]
+          raise Vpim::InvalidEncodingError, 'Image is not allowed to be both inline and a link.'
+        end
+
+        value = x[:image] || x[:link]
+
+        if !value
+          raise Vpim::InvalidEncodingError, 'A image link or inline data must be provided.'
+        end
+
+        params = {}
+
+        # Don't set type to the empty string.
+        params['TYPE'] = x[:type] if( x[:type] && x[:type].length > 0 )
+
+        if x[:link]
+          params['VALUE'] = 'URI'
+        else # it's inline, base-64 encode it
+          params['ENCODING'] = :b64
+          if !x[:type]
+            raise Vpim::InvalidEncodingError, 'Inline image data must have it\'s type set.'
           end
-          date = Date.new(y, m, d)
+        end
+
+        @card << Vpim::DirectoryInfo::Field.create( 'PHOTO', value, params )
+        self
+      end
+
+      # Add a URL field, URL.
+      def add_url(url)
+        @card << Vpim::DirectoryInfo::Field.create( 'URL', url.to_str );
+      end
+
+      # Add a Field, +field+.
+      def add_field(field)
+        fieldname = field.name.upcase
+        case
+        when [ 'BEGIN', 'END' ].include?(fieldname)
+          raise Vpim::InvalidEncodingError, "Not allowed to manually add #{field.name} to a vCard."
+
+        when [ 'VERSION', 'N', 'FN' ].include?(fieldname)
+          if @card.field(fieldname)
+            raise Vpim::InvalidEncodingError, "Not allowed to add more than one #{fieldname} to a vCard."
+          end
+          @card << field
+
         else
-          raise
+          @card << field
         end
       end
 
-      date
-    end
+      # Copy the fields from +card+ into self using #add_field. If a block is
+      # provided, each Field from +card+ is yielded. The block should return a
+      # Field to add, or nil.  The Field doesn't have to be the one yielded,
+      # allowing the field to be copied and modified (see Field#copy) before adding, or 
+      # not added at all if the block yields nil.
+      #
+      # The vCard fields BEGIN and END aren't copied, and VERSION, N, and FN are copied
+      # only if the card doesn't have them already.
+      def copy(card) # :yields: Field
+        card.each do |field|
+          fieldname = field.name.upcase
+          case
+          when [ 'BEGIN', 'END' ].include?(fieldname)
+            # Never copy these
+
+          when [ 'VERSION', 'N', 'FN' ].include?(fieldname) && @card.field(fieldname)
+            # Copy these only if they don't already exist.
+
+          else
+            if block_given?
+              field = yield field
+            end
+
+            if field
+              add_field(field)
+            end
+          end
+        end
+      end
+
+      # Delete +line+ if block yields true.
+      def delete_if #:yield: line
+        begin
+        @card.delete_if do |line|
+          yield line
+        end
+        rescue NoMethodError
+          # FIXME - this is a hideous hack, allowing a DirectoryInfo to
+          # be passed instead of a Vcard, and for it to almost work. Yuck.
+        end
+      end
 
+    end
   end
 end