vpim 0.16 → 0.17

data/lib/vpim/agent/plist.rb

@@ -0,0 +1,86 @@
+# http://www2a.biglobe.ne.jp/~seki/ruby/src/plist.rb
+require 'rexml/document'
+require 'time'
+
+class Plist #:nodoc:
+   def self.file_to_plist(fname)
+     File.open(fname) do |fp|
+       doc = REXML::Document.new(fp)
+       return self.new.visit(REXML::XPath.match(doc, '/plist/')[0])
+     end
+   end
+
+   def initialize
+     setup_method_table
+   end
+
+   def visit(node)
+     visit_one(node.elements[1])
+   end
+
+   def visit_one(node)
+     choose_method(node.name).call(node)
+   end
+
+   def visit_null(node)
+     p node if $DEBUG
+     nil
+   end
+
+   def visit_dict(node)
+     dict = {}
+     es =  node.elements.to_a
+     while key = es.shift
+       next unless key.name == 'key'
+       dict[key.text] = visit_one(es.shift)
+     end
+     dict
+   end
+
+   def visit_array(node)
+     node.elements.collect do |x|
+       visit_one(x)
+     end
+   end
+
+   def visit_integer(node)
+     node.text.to_i
+   end
+
+   def visit_real(node)
+     node.text.to_f
+   end
+
+   def visit_string(node)
+     node.text.to_s
+   end
+
+   def visit_date(node)
+     Time.parse(node.text.to_s)
+   end
+
+   def visit_true(node)
+     true
+   end
+
+   def visit_false(node)
+     false
+   end
+
+   private
+   def choose_method(name)
+     @method.fetch(name, method(:visit_null))
+   end
+
+   def setup_method_table
+     @method = {}
+     @method['dict'] = method(:visit_dict)
+     @method['integer'] = method(:visit_integer)
+     @method['real'] = method(:visit_real)
+     @method['string'] = method(:visit_string)
+     @method['date'] = method(:visit_date)
+     @method['true'] = method(:visit_true)
+     @method['false'] = method(:visit_false)
+     @method['array'] = method(:visit_array)
+   end
+end

data/lib/vpim/date.rb

@@ -1,7 +1,5 @@
 =begin
-  $Id: date.rb,v 1.8 2004/11/17 05:06:27 sam Exp $
-
-  Copyright (C) 2005 Sam Roberts
+  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

data/lib/vpim/date.rb~

@@ -0,0 +1,198 @@
+=begin
+  $Id: date.rb,v 1.8 2004/11/17 05:06:27 sam Exp $
+
+  Copyright (C) 2005 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
+
+require 'date'
+
+# Extensions to the standard library Date.
+class Date
+
+  TIME_START = Date.new(1970, 1, 1)
+  SECS_PER_DAY = 24 * 60 * 60
+
+  # Converts this object to a Time object, or throws an ArgumentError if
+  # conversion is not possible because it is before the start of epoch.
+  def to_time
+    raise ArgumentError, 'date is before the start of system time' if self < TIME_START
+    days = self - TIME_START
+
+    Time.at((days * SECS_PER_DAY).to_i)
+  end
+
+  # If wday responds to to_str, convert it to the wday number by searching for
+  # a wday that matches, using as many characters as are in wday to do the
+  # comparison. wday must be 2 or more characters long in order to be a unique
+  # match, other than that, "mo", "Mon", and "MonDay" are all valid strings
+  # for wday 1.
+  #
+  # This method can be called on a valid wday, and it will return it. Perhaps
+  # it should be called by default inside the Date#new*() methods so that
+  # non-integer wday arguments can be used? Perhaps a similar method should
+  # exist for months? But with months, we all know January is 1, who can
+  # remember where Date chooses to start its wday count!
+  #
+  # Examples:
+  #  Date.bywday(2004, 2, Date.str2wday('TU')) => the first Tuesday in
+  #    February
+  #  Date.bywday(2004, 2, Date.str2wday(2)) => the same day, but notice
+  #    that a valid wday integer can be passed right through.
+  #   
+  def Date.str2wday(wdaystr)
+    return wdaystr unless wdaystr.respond_to? :to_str
+
+    str = wdaystr.to_str.upcase
+    if str.length < 2
+      raise ArgumentError, 'wday #{wday} is not long enough to be a unique weekday name'
+    end
+
+    wday = Date::DAYNAMES.map { |n| n.slice(0, str.length).upcase }.index(str)
+
+    return wday if wday
+
+    raise ArgumentError, 'wday #{wdaystr} was not a recognizable weekday name'
+  end
+
+  
+  # Create a new Date object for the date specified by year +year+, month
+  # +mon+, and day-of-the-week +wday+.
+  #
+  # The nth, +n+, occurrence of +wday+ within the period will be generated
+  # (+n+ defaults to 1).  If +n+ is positive, the nth occurence from the
+  # beginning of the period will be returned, if negative, the nth occurrence
+  # from the end of the period will be returned.
+  #
+  # The period is a year, unless +month+ is non-nil, in which case it is just
+  # that month.
+  #
+  # Examples:
+  # - Date.bywday(2004, nil, 1, 9) => the ninth Sunday of 2004
+  # - Date.bywday(2004, nil, 1) => the first Sunday of 2004
+  # - Date.bywday(2004, nil, 1, -2) => the second last Sunday of 2004
+  # - Date.bywday(2004, 12, 1) => the first sunday in the 12th month of 2004
+  # - Date.bywday(2004, 2, 2, -1) => last Tuesday in the 2nd month in 2004
+  # - Date.bywday(2004, -2, 3, -2) => second last Wednesday in the second last month of 2004
+  #
+  # Compare this to Date.new, which allows a Date to be created by
+  # day-of-the-month, mday, to Date.new2, which allows a Date to be created by
+  # day-of-the-year, yday, and to Date.neww, which allows a Date to be created
+  # by day-of-the-week, but within a specific week.
+  def Date.bywday(year, mon, wday, n = 1, sg=Date::ITALY)
+    # Normalize mon to 1-12.
+    if mon
+      if mon > 12 ||  mon == 0 || mon < -12
+         raise ArgumentError, "mon #{mon} must be 1-12 or negative 1-12"
+      end
+      if mon < 0
+        mon = 13 + mon
+      end
+    end
+    if wday < 0 || wday > 6
+      raise ArgumentError, 'wday must be in range 0-6, or a weekday name'
+    end
+
+    # Determine direction of indexing.
+    inc = n <=> 0
+    if inc == 0
+      raise ArgumentError, 'n must be greater or less than zero'
+    end
+
+    # if !mon, n is index into year, but direction of search is determined by
+    # sign of n
+    d = Date.new(year, mon ? mon : inc, inc, sg)
+
+    while d.wday != wday
+      d += inc
+    end
+
+    # Now we have found the first/last day with the correct wday, search
+    # for nth occurrence, by jumping by n.abs-1 weeks forward or backward.
+    d += 7 * (n.abs - 1) * inc
+
+    if d.year != year
+      raise ArgumentError, 'n is out of bounds of year'
+    end
+    if mon && d.mon != mon
+      raise ArgumentError, 'n is out of bounds of month'
+    end
+    d
+  end
+end
+
+# DateGen generates arrays of dates matching simple criteria.
+class DateGen
+  # Generate an array of dates on +wday+ (the day-of-week,
+  # 0-6, where 0 is Sunday).
+  #
+  # If +n+ is specified, only the nth occurrence of +wday+ within the period
+  # will be generated.  If +n+ is positive, the nth occurence from the
+  # beginning of the period will be returned, if negative, the nth occurrence
+  # from the end of the period will be returned.
+  #
+  # The period is a year, unless +month+ is non-nil, in which case it is just
+  # that month.
+  #
+  # Examples:
+  # - DateGen.bywday(2004, nil, 1, 9) => the ninth Sunday in 2004
+  # - DateGen.bywday(2004, nil, 1) => all Sundays in 2004
+  # - DateGen.bywday(2004, nil, 1, -2) => second last Sunday in 2004
+  # - DateGen.bywday(2004, 12, 1) => all sundays in December 2004
+  # - DateGen.bywday(2004, 2, 2, -1) => last Tuesday in February in 2004
+  # - DateGen.bywday(2004, -2, 3, -2) => second last Wednesday in November of 2004
+  #
+  # Compare to Date.bywday(), which allows a single Date to be created with
+  # similar criteria.
+  def DateGen.bywday(year, month, wday, n = nil)
+    seed = Date.bywday(year, month, wday, n ? n : 1)
+
+    dates = [ seed ]
+
+    return dates if n
+
+    succ = seed.clone
+
+    # Collect all matches until we're out of the year (or month, if specified)
+    loop do
+      succ += 7
+
+      break if succ.year != year
+      break if month && succ.month != seed.month
+
+      dates.push succ
+    end
+    dates.sort!
+    dates
+  end
+
+  # Generate an array of dates on +mday+ (the day-of-month, 1-31). For months
+  # in which the +mday+ is not present, no date will be generated.
+  #
+  # The period is a year, unless +month+ is non-nil, in which case it is just
+  # that month.
+  #
+  # Compare to Date.new(), which allows a single Date to be created with
+  # similar criteria.
+  def DateGen.bymonthday(year, month, mday)
+    months = month ? [ month ] : 1..12
+    dates = [ ]
+
+    months.each do |m|
+      begin
+        dates << Date.new(year, m, mday)
+      rescue ArgumentError
+        # Don't generate dates for invalid combinations (Feb 29, when it's not
+        # a leap year, for example).
+        #
+        # TODO - should we raise when month is out of range, or mday can never
+        # be in range (32)?
+      end
+    end
+    dates
+  end
+end
+

data/lib/vpim/dirinfo.rb

@@ -1,7 +1,5 @@
 =begin
-  $Id: dirinfo.rb,v 1.19 2004/11/17 05:06:27 sam Exp $
-
-  Copyright (C) 2005 Sam Roberts
+  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
@@ -100,6 +98,7 @@ module Vpim
     # The value of the first field named +name+, or nil if no
     # match is found.
     def [](name)
+      enum_by_name(name).each { |f| return f.value if f.value != ''}
       enum_by_name(name).each { |f| return f.value }
       nil
     end
@@ -136,10 +135,18 @@ module Vpim
 
     # Returns an Enumerator for each Field for which #name?(+name+) is true.
     #
-    # For example, to get an Array of all the email addresses in the card, you
-    # could do:
+    # An Enumerator supports all the methods of Enumerable, so it allows iteration,
+    # collection, mapping, etc.
+    #
+    # Examples:
+    #
+    # Print all the nicknames in a card:
+    #  
+    #   card.enum_by_name('NICKNAME') { |f| puts f.value }
+    #
+    # Print an Array of the preferred email addresses in the card:
     #
-    #   card.enum_by_name('email').collect { |f| f.value }
+    #   pref_emails = card.enum_by_name('EMAIL').select { |f| f.pref? }
     def enum_by_name(name)
       Enumerator.new(self, Proc.new { |field| field.name?(name) })
     end
@@ -148,15 +155,15 @@ module Vpim
     #
     # For example, to print all the fields, sorted by group, you could do:
     #
-    #  card.groups.sort.each do |group|
-    #    card.enum_by_group(group).each do |field|
-    #    puts "#{group} -> #{field.name}"
-    #    end
-    #  end
+    #   card.groups.sort.each do |group|
+    #     card.enum_by_group(group).each do |field|
+    #       puts "#{group} -> #{field.name}"
+    #     end
+    #   end
     #
     # or to get an array of all the fields in group 'agroup', you could do:
     # 
-    #  card.enum_by_group('agroup').to_a
+    #   card.enum_by_group('agroup').to_a
     def enum_by_group(group)
       Enumerator.new(self, Proc.new { |field| field.group?(group) })
     end
@@ -166,9 +173,15 @@ module Vpim
       Enumerator.new(self, cond )
     end
 
+    # Force card to be reencoded from the fields.
+    def dirty #:nodoc:
+      #string = nil
+    end
+
     # Append +field+ to the fields. Note that it won't be literally appended
     # to the fields, it will be inserted before the closing END field.
     def push(field)
+      dirty
       @fields[-1,0] = field
       self
     end
@@ -190,6 +203,25 @@ module Vpim
       self
     end
 
+    # Delete +field+.
+    #
+    # Warning: You can't delete BEGIN: or END: fields, but other
+    # profile-specific fields can be deleted, including mandatory ones. For
+    # vCards in particular, in order to avoid destroying them, I suggest
+    # creating a new Vcard, and copying over all the fields that you still
+    # want, rather than using #delete. This is easy with Maker::Vcard#copy, see
+    # the Maker::Vcard examples.
+    def delete(field)
+      case
+      when field.name?('BEGIN'), field.name?('END')
+        raise ArgumentError, 'Cannot delete BEGIN or END fields.'
+      else
+        @fields.delete field
+      end
+
+      self
+    end
+
     # The string encoding of the DirectoryInfo. See Field#encode for information
     # about the width parameter.
     def encode(width=nil)
@@ -208,14 +240,14 @@ module Vpim
       unless @fields.first
         raise "No fields to check"
       end
-      unless @fields.first.name? "begin"
+      unless @fields.first.name? 'BEGIN'
         raise "Needs BEGIN, found: #{@fields.first.encode nil}"
       end
-      unless @fields.last.name? "end"
+      unless @fields.last.name? 'END'
         raise "Needs END, found: #{@fields.last.encode nil}"
       end
       unless @fields.last.value? @fields.first.value
-        raise "BEGIN/END mismatch: (#{@fields.first.value.downcase} != #{@fields.last.value.downcase}"
+        raise "BEGIN/END mismatch: (#{@fields.first.value} != #{@fields.last.value}"
       end
       if profile
         if ! @fields.first.value? profile

data/lib/vpim/dirinfo.rb~

@@ -0,0 +1,242 @@
+=begin
+  $Id: dirinfo.rb,v 1.19 2004/11/17 05:06:27 sam Exp $
+
+  Copyright (C) 2005 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
+
+require 'vpim/enumerator'
+require 'vpim/field'
+require 'vpim/rfc2425'
+require 'vpim/vpim'
+
+module Vpim
+  # An RFC 2425 directory info object.
+  #
+  # A directory information object is a sequence of fields. The basic
+  # structure of the object, and the way in which it is broken into fields
+  # is common to all profiles of the directory info type.
+  #
+  # A vCard, for example, is a specialization of a directory info object.
+  #
+  #  [RFC2425] the directory information framework (ftp://ftp.ietf.org/rfc/rfc2425.txt)
+  class DirectoryInfo
+    include Enumerable
+
+    private_class_method :new
+
+    # Initialize a DirectoryInfo object from +fields+. If +profile+ is
+    # specified, check the BEGIN/END fields.
+    def initialize(fields, profile = nil) #:nodoc:
+      if fields.detect { |f| ! f.kind_of? DirectoryInfo::Field }
+        raise ArgumentError, 'fields must be an array of DirectoryInfo::Field objects'
+      end
+
+      @string = nil # this is used as a flag to indicate that recoding will be necessary
+      @fields = fields
+
+      check_begin_end(profile) if profile
+    end
+
+    # Decode +card+ into a DirectoryInfo object.
+    #
+    # +card+ may either be a something that is convertible to a string using
+    # #to_str or an array of objects that can be joined into a string using
+    # #join("\n"), or an IO object (which will be read to end-of-file).
+    #
+    # The lines in the string may be delimited using IETF (CRLF) or Unix (LF) conventions.
+    #
+    # A DirectoryInfo is mutable, you can add new fields to it, see
+    # Vpim::DirectoryInfo::Field#create() for how to create a new Field.
+    #
+    # TODO: I don't believe this is ever used, maybe I can remove it.
+    def DirectoryInfo.decode(card) #:nodoc:
+      if card.respond_to? :to_str
+        string = card.to_str
+      elsif card.kind_of? Array
+        string = card.join("\n")
+      elsif card.kind_of? IO
+        string = card.read(nil)
+      else
+        raise ArgumentError, "DirectoryInfo cannot be created from a #{card.type}"
+      end
+
+      fields = Vpim.decode(string)
+
+      new(fields)
+    end
+
+    # Create a new DirectoryInfo object. The +fields+ are an optional array of
+    # DirectoryInfo::Field objects to add to the new object, between the
+    # BEGIN/END.  If the +profile+ string is not nil, then it is the name of
+    # the directory info profile, and the BEGIN:+profile+/END:+profile+ fields
+    # will be added.
+    #
+    # A DirectoryInfo is mutable, you can add new fields to it using #push(),
+    # and see Field#create().
+    def DirectoryInfo.create(fields = [], profile = nil)
+
+      if profile
+        p = profile.to_str
+        f = [ Field.create('BEGIN', p) ]
+        f.concat fields
+        f.push Field.create('END', p)
+        fields = f
+      end
+      
+      new(fields, profile)
+    end
+
+    # The first field named +name+, or nil if no
+    # match is found.
+    def field(name)
+      enum_by_name(name).each { |f| return f }
+      nil
+    end
+
+    # The value of the first field named +name+, or nil if no
+    # match is found.
+    def [](name)
+      enum_by_name(name).each { |f| return f.value if f.value != ''}
+      enum_by_name(name).each { |f| return f.value }
+      nil
+    end
+
+    # An array of all the values of fields named +name+, converted to text
+    # (using Field#to_text()).
+    #
+    # TODO - call this #texts(), as in the plural?
+    def text(name)
+      enum_by_name(name).map { |f| f.to_text }
+    end
+
+    # Array of all the Field#group()s.
+    def groups
+      @fields.collect { |f| f.group } .compact.uniq
+    end
+
+    # All fields, frozen.
+    def fields #:nodoc:
+      @fields.dup.freeze
+    end
+
+    # Yields for each Field for which +cond+.call(field) is true. The
+    # (default) +cond+ of nil is considered true for all fields, so
+    # this acts like a normal #each() when called with no arguments.
+    def each(cond = nil) # :yields: Field
+      @fields.each do |field|
+         if(cond == nil || cond.call(field))
+           yield field
+         end
+      end
+      self
+    end
+
+    # Returns an Enumerator for each Field for which #name?(+name+) is true.
+    #
+    # An Enumerator supports all the methods of Enumerable, so it allows iteration,
+    # collection, mapping, etc.
+    #
+    # Examples:
+    #
+    # Print all the nicknames in a card:
+    #  
+    #   card.enum_by_name('nickname') { |f| puts f.value }
+    #
+    # Get an Array of the preferred email addresses in the card:
+    #
+    #   card.enum_by_name('email').collect { |f| f.pref? ? f.value : nil }.compact
+    # FIXME - make sure this works!
+    def enum_by_name(name)
+      Enumerator.new(self, Proc.new { |field| field.name?(name) })
+    end
+
+    # Returns an Enumerator for each Field for which #group?(+group+) is true.
+    #
+    # For example, to print all the fields, sorted by group, you could do:
+    #
+    #  card.groups.sort.each do |group|
+    #    card.enum_by_group(group).each do |field|
+    #    puts "#{group} -> #{field.name}"
+    #    end
+    #  end
+    #
+    # or to get an array of all the fields in group 'agroup', you could do:
+    # 
+    #  card.enum_by_group('agroup').to_a
+    def enum_by_group(group)
+      Enumerator.new(self, Proc.new { |field| field.group?(group) })
+    end
+
+    # Returns an Enumerator for each Field for which +cond+.call(field) is true.
+    def enum_by_cond(cond)
+      Enumerator.new(self, cond )
+    end
+
+    # Append +field+ to the fields. Note that it won't be literally appended
+    # to the fields, it will be inserted before the closing END field.
+    def push(field)
+      @fields[-1,0] = field
+      self
+    end
+
+    alias << push
+
+    # Push +field+ onto the fields, unless there is already a field
+    # with this name.
+    def push_unique(field)
+      push(field) unless @fields.detect { |f| f.name? field.name }
+      self
+    end
+
+    # Append +field+ to the end of all the fields. This isn't usually what you
+    # want to do, usually a DirectoryInfo's first and last fields are a
+    # BEGIN/END pair, see #push().
+    def push_end(field)
+      @fields << field
+      self
+    end
+
+    def delete(field)
+    end
+
+    # The string encoding of the DirectoryInfo. See Field#encode for information
+    # about the width parameter.
+    def encode(width=nil)
+      unless @string
+        @string = @fields.collect { |f| f.encode(width) } . join ""
+      end
+      @string
+    end
+
+    alias to_s encode
+
+    # Check that the DirectoryInfo object is correctly delimited by a BEGIN
+    # and END, that their profile values match, and if +profile+ is specified, that 
+    # they are the specified profile.
+    def check_begin_end(profile=nil) #:nodoc:
+      unless @fields.first
+        raise "No fields to check"
+      end
+      unless @fields.first.name? "begin"
+        raise "Needs BEGIN, found: #{@fields.first.encode nil}"
+      end
+      unless @fields.last.name? "end"
+        raise "Needs END, found: #{@fields.last.encode nil}"
+      end
+      unless @fields.last.value? @fields.first.value
+        raise "BEGIN/END mismatch: (#{@fields.first.value.downcase} != #{@fields.last.value.downcase}"
+      end
+      if profile
+        if ! @fields.first.value? profile
+          raise "Mismatched profile"
+        end
+      end
+      true
+    end
+  end
+end
+