rwdaddresses 1.01 → 1.02

data/extras/vpim/rrule.rb

@@ -0,0 +1,482 @@
+=begin
+  $Id: rrule.rb,v 1.18 2005/01/23 22:19:48 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/rfc2425'
+require 'vpim/date'
+require 'vpim/time'
+require 'vpim/vpim'
+
+=begin
+require 'pp'
+
+$debug = ENV['DEBUG']
+
+def debug(*objs)
+  if $debug
+    pp(*objs)
+    print '  (', caller(1)[0], ')', "\n"
+  end
+end
+=end
+
+module Vpim
+
+  # Implements the iCalendar recurence rule syntax. See etc/rrule.txt for the
+  # syntax description and examples from RFC 2445. The description is pretty
+  # hard to understand, but the examples are more helpful.
+  #
+  # The implementation is pretty complete, but still lacks support for:
+  #
+  # TODO - BYWEEKLY, BYWEEKNO, WKST: rules that recur by the week, or are
+  # limited to particular weeks, not hard, but not trivial, I'll do it for the
+  # next release
+  #
+  # TODO - BYHOUR, BYMINUTE, BYSECOND: trivial to do, but I don't have an
+  # immediate need for them, I'll do it for the next release
+  #
+  # TODO - BYSETPOS: limiting to only certain recurrences in a set (what does
+  # -1, last occurence, mean for an infinitely occuring rule?)
+  #
+  # TODO - new API? -> Rrule#infinite?
+  #
+  # == Examples
+  #
+  # - link:rrule.txt: utility for printing recurrence rules
+  class Rrule
+    include Enumerable
+
+    # The recurrence rule, +rrule+, specifies how to generate a set of times
+    # from a start time, +dtstart+ (which must the first of the set of
+    # recurring times). If +rrule+ is nil, the set contains only +dtstart+.
+    def initialize(dtstart, rrule = nil)
+      # dtstart must be in local time, they say, but I think that really
+      # means must be in a particular timezone
+
+      # Note: DTSTART is always in the recurrence set
+       @dtstart = dtstart
+       @rrule = rrule
+
+       # Freq is mandatory, but must occur only once.
+       @freq = nil
+   
+       # Both Until and Count must not occur, neither is OK.
+       @until = nil
+       @count = nil
+   
+       # Interval is optional, but defaults to 1.
+       @interval = 1
+
+       # WKST defines what day a week begins on, the default is monday.
+       @wkst = 'MO'
+   
+       # Recurrence can modified by these.
+       @by = {}
+  
+       if @rrule
+         @rrule.scan(/([^;=]+)=([^;=]+)/) do |key,value|
+           key.upcase!
+           value.upcase!
+
+           case key
+           when 'FREQ'
+             @freq = value.upcase
+
+           when 'UNTIL'
+             if @count
+               raise "found UNTIL, but COUNT already specified"
+             end
+             @until = Rrule.time_from_rfc2425(value)
+
+           when 'COUNT'
+             if @until
+               raise "found COUNT, but UNTIL already specified"
+             end
+             @count = value.to_i
+
+           when 'INTERVAL'
+             @interval = value.to_i
+             if @interval < 1
+               raise "interval must be a positive integer"
+             end
+
+           when 'WKST'
+             # TODO - check value is MO-SU
+             @wkst = value
+
+           else
+             @by[key] = value
+           end
+         end
+
+         if !@freq
+           # TODO - this shouldn't be an arg error, but a FormatError, its not the
+           # caller's fault!
+           raise ArgumentError, "recurrence rule lacks a frequency"
+         end
+       end
+    end
+
+    # Return an Enumerable, it's #each() will yield over all occurences up to
+    # (and not including) time +dountil+.
+    def each_until(dountil)
+      Vpim::Enumerator.new(self, dountil)
+    end
+
+    # Yields for each +ytime+ in the recurring set of events.
+    #
+    # Warning: the set may be infinite! If you need an upper bound on the
+    # number of occurences, you need to implement a count, or pass a time,
+    # +dountil+, which will not be iterated past (i.e. all times yielded will be
+    # less than +dountil+).
+    #
+    # Also, iteration will not currently continue past the limit of a Time
+    # object, which is some time in 2037 with 32-bit time_t's common on
+    # most systems.
+    def each(dountil = nil) #:yield: ytime
+      t = @dtstart.clone
+      count = 1
+
+      # Time.to_a => [ sec, min, hour, day, month, year, wday, yday, isdst, zone ]
+
+      # Every event occurs at least once, at its start time, but only if the start
+      # time is earlier than 'dountil'...
+      if !@rrule
+        if !dountil || t < dountil
+          yield t
+        end
+        return self
+      end
+
+      loop do
+        # Build the set of times to yield within this interval (and after
+        # DTSTART)
+
+        days  = DaySet.new(t)
+        hour  = nil
+        min   = nil
+        sec   = nil
+
+        # Need to make a Dates class, and make month an instance of it, and add
+        # the "intersect" operator.
+
+        case @freq
+          #when 'YEARLY' then
+          # Don't need to keep track of year, all occurences are within t's
+          # year.
+          when 'MONTHLY'  then  days.month = t.month #month = { t.month => nil }
+  #       when 'WEEKLY'   then  days.mday = t.month, t.mday
+          # TODO - WEEKLY
+          when 'DAILY'    then  days.mday = t.month, t.mday #month = { t.month => [ t.mday ] }
+          when 'HOURLY'   then  hour  = [t.hour]
+          when 'MINUTELY' then  min   = [t.min]
+          when 'SECONDLY' then  sec   = [t.sec]
+        end
+
+        # Process the BY* modifiers in RFC defined order:
+        #  BYMONTH, BYWEEKNO, BYYEARDAY, BYMONTHDAY, BYDAY,
+        #  BYHOUR, BYMINUTE, BYSECOND and BYSETPOS
+        
+        if @by['BYMONTH']
+          bymon = @by['BYMONTH'].split(',')
+          bymon = bymon.collect { |m| m.to_i }
+  #        debug bymon
+
+          # In yearly, at  this point, month will always be nil. At other
+          # frequencies, it will not.
+          days.intersect_bymon(bymon)
+
+  #        debug days
+        end
+
+        # TODO - BYWEEKNO
+
+        if @by['BYYEARDAY']
+          byyday = @by['BYYEARDAY'].scan(/,?([+-]?[1-9]\d*)/)
+  #        debug byyday
+          dates = byyearday(t.year, byyday)
+          days.intersect_dates(dates)
+        end
+
+        if @by['BYMONTHDAY']
+          bymday = @by['BYMONTHDAY'].scan(/,?([+-]?[1-9]\d*)/)
+  #        debug bymday
+          # Generate all days matching this for all months. For yearly, this
+          # is what we want, for anything of monthly or higher frequency, it
+          # is too many days, but that's OK, since  the month will already
+          # be specified and intersection will eliminate the out-of-range
+          # dates.
+          dates = bymonthday(t.year, bymday)
+  #        debug dates
+          days.intersect_dates(dates)
+  #        debug days
+        end
+
+        if @by['BYDAY']
+          byday = @by['BYDAY'].scan(/,?([+-]?[1-9]?\d*)?(SU|MO|TU|WE|TH|FR|SA)/i)
+  #        debug byday
+
+          # BYDAY means different things in different frequencies. The +n+
+          # is only meaningful when freq is yearly or monthly.
+
+          case @freq
+            when 'YEARLY'
+              dates = byday_in_yearly(t.year, byday)
+            when 'MONTHLY'
+              dates = byday_in_monthly(t.year, t.month, byday)
+            when 'WEEKLY'
+              # dates = byday_in_weekly(t.year, wkstart, t.month, t.day, byday)
+            when 'DAILY', 'HOURLY', 'MINUTELY', 'SECONDLY'
+              # Reuse the bday_in_monthly. Current day is already specified,
+              # so this will just eliminate the current day if its no allowed
+              # in BYDAY.
+              dates = byday_in_monthly(t.year, t.month, byday)
+          end
+
+  #        debug dates
+          days.intersect_dates(dates)
+  #        debug days
+        end
+
+        # TODO - BYHOUR, BYMINUTE, BYSECOND
+        
+        # TODO - BYSETPOS
+
+        # Yield the time, if we haven't gone over COUNT, or past UNTIL, or past
+        # the end of representable time.
+
+        hour   = [@dtstart.hour]   if !hour 
+        min    = [@dtstart.min]    if !min  
+        sec    = [@dtstart.sec]    if !sec 
+
+  #      debug days
+
+        days.each do |m,d|
+            hour.each do |h|
+              min.each do |n|
+                sec.each do |s|
+                  if(@count && (count > @count))
+                    return self
+                  end
+                  y = Time.local(t.year, m, d, h, n, s, 0)
+
+                  next if y.hour != h
+
+                  # The generated set can sometimes generate results earlier
+                  # than the DTSTART, skip them.
+                  next if y < @dtstart
+
+                  # We are done if current time is past @until.
+                  if @until && (y > @until)
+                    return self
+                  end
+                  # We are also done if current time is past the
+                  # caller-requested until.
+                  if dountil && (y > dountil)
+                    return self
+                  end
+                  yield y
+                  count += 1
+                end
+              end
+            end
+        end
+
+
+        # Add @interval to @freq component
+
+        # Note - when we got past representable time, the error is:
+        #   time out of range (ArgumentError)
+        # Finish when we see this.
+        begin
+          case @freq
+            when 'YEARLY' then
+              t = t.plus_year(@interval)
+
+            when 'MONTHLY' then
+              t = t.plus_month(@interval)
+
+            when 'WEEKLY' then
+              t = t.plus_day(@interval * 7)
+
+            when 'DAILY' then
+              t = t.plus_day(@interval)
+
+            when 'HOURLY' then
+              t += @interval * 60 * 60
+
+            when 'MINUTELY' then
+              t += @interval * 60
+
+            when 'SECONDLY' then
+              t += @interval
+
+            when nil
+              return self
+          end
+        rescue ArgumentError
+          return self if $!.message =~ /^time out of range$/
+
+          raise ArgumentError, "#{$!.message} while adding interval to #{t.inspect}"
+        end
+
+        return self if dountil && (t > dountil)
+      end
+    end
+
+    class DaySet #:nodoc:
+
+      def initialize(ref)
+        @ref = ref # Need to know because leap years have an extra day, and to get
+                     # our defaults.
+        @month = nil
+        @week = nil
+      end
+
+      def month=(mon)
+        @month = { mon => nil }
+      end
+
+      def week=(week)
+        @week = week
+      end
+
+      def mday=(pair)
+        @month = { pair[0] => [ pair[1] ] }
+      end
+
+      def intersect_bymon(bymon) #:nodoc:
+        if !@month
+          @month = {}
+          bymon.each do |m|
+            @month[m] = nil
+          end
+        else
+          @month.delete_if { |m, days| ! bymon.include? m }
+        end
+      end
+
+      def intersect_dates(dates) #:nodoc:
+        if dates
+          # If no months are in the dayset, add all the ones in dates
+          if !@month
+            @month = {}
+
+            dates.each do |d|
+              @month[d.mon] = nil
+            end
+          end
+
+          # In each month,
+          #   if there are days,
+          #     eliminate those not in dates
+          #   otherwise
+          #     add all those in dates
+          @month.each do |mon, days|
+            days_in_mon = dates.find_all { |d| d.mon == mon }
+            days_in_mon = days_in_mon.collect { |d| d.day }
+
+            if days
+              days_in_mon = days_in_mon & days
+            end
+            @month[mon] = days_in_mon
+          end
+        end
+      end
+
+      def each
+        @month  = { @ref.month => [ @ref.mday ] } if !@month
+        @month.each_key do |m|
+          @month[m] = [@ref.day] if !@month[m]
+          # FIXME - if @ref.day is 31, and the month doesn't have 32 days, we'll
+          # generate invalid dates here, check for that, and eliminate them
+        end
+
+        @month.keys.sort.each do |m|
+          @month[m].sort.each do |d|
+            yield m, d
+          end
+        end
+      end
+    end
+
+    def self.time_from_rfc2425(str) #:nodoc:
+      # With ruby1.8 we can use DateTime to do this quick-n-easy:
+      #  dt = DateTime.parse(str)
+      #  Time.local(dt.year, dt.month, dt.day, dt.hour, dt.min, dt.sec, 0)
+
+      # The time can be a DATE or a DATE-TIME, the latter always has a 'T' in it.
+
+      if str =~ /T/
+        d = Vpim.decode_date_time(str)
+        # We get [ year, month, day, hour, min, sec, usec, tz ]
+        if(d.pop == "Z")
+          t = Time.gm(*d)
+        else
+          t = Time.local(*d)
+        end
+      else
+        d = Vpim.decode_date(str)
+        # We get [ year, month, day ]
+        # FIXME - I have to choose gm or local, though neither makes much
+        # sense. This is a bit of a hack - what we should really do is return
+        # an instance of Date, and Time should allow itself to be compared to
+        # Date... This hack will give odd results when comparing times, because
+        # it will create a Time on the right date but whos time is 00:00:00.
+        t = Time.local(*d)
+      end
+      if t.month != d[1] || t.day != d[2] || (d[3] && t.hour != d[3])
+        raise Vpim::InvalidEncodingError, "Error - datetime does not exist"
+      end
+      t
+    end
+
+    def bymonthday(year, bymday) #:nodoc:
+      dates = []
+
+      bymday.each do |mday|
+        dates |= DateGen.bymonthday(year, nil, mday[0].to_i)
+      end
+      dates.sort!
+      dates
+    end
+
+    def byyearday(year, byyday) #:nodoc:
+      dates = []
+
+      byyday.each do |yday|
+        dates << Date.new2(year, yday[0].to_i)
+      end
+      dates.sort!
+      dates
+    end
+
+    def byday_in_yearly(year, byday) #:nodoc:
+      byday_in_monthly(year, nil, byday)
+    end
+
+    def byday_in_monthly(year, mon, byday) #:nodoc:
+      dates = []
+
+      byday.each do |rule|
+        if rule[0].empty?
+          n = nil
+        else
+          n = rule[0].to_i
+        end
+        dates |= DateGen.bywday(year, mon, Date.str2wday(rule[1]), n)
+      end
+      dates.sort!
+      dates
+    end
+
+  end
+
+end
+

data/extras/vpim/time.rb

@@ -0,0 +1,42 @@
+=begin
+  $Id: time.rb,v 1.5 2005/02/02 02:55:59 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 builtin Time allowing addition to Time by multiples of other
+# intervals than a second.
+
+class Time
+    # Returns a new Time, +years+ later than this time. Feb 29 of a
+    # leap year will be rounded up to Mar 1 if the target date is not a leap
+    # year.
+    def plus_year(years)
+      Time.local(year + years, month, day, hour, min, sec, usec)
+    end
+
+    # Returns a new Time, +months+ later than this time. The day will be
+    # rounded down if it is not valid for that month.
+    # 31 plus 1 month will be on Feb 28!
+    def plus_month(months)
+      d = Date.new(year, month, day)
+      d >>= months
+      Time.local(d.year, d.month, d.day, hour, min, sec, usec)
+    end
+
+    # Returns a new Time, +days+ later than this time.
+    # Does this do as I expect over DST? What if the hour doesn't exist
+    # in the next day, due to DST changes?
+    def plus_day(days)
+      d = Date.new(year, month, day)
+      d += days
+      Time.local(d.year, d.month, d.day, hour, min, sec, usec)
+    end
+end
+

data/extras/vpim/vcard.rb

@@ -0,0 +1,151 @@
+=begin
+  $Id: vcard.rb,v 1.13 2004/12/05 03:16:33 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 'extras/vpim/dirinfo'
+require 'extras/vpim/vpim'
+
+module Vpim
+  # A vCard, a specialization of a directory info object.
+  #
+  # The vCard format is specified by:
+  # - 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.
+  #
+  # For information about:
+  # - 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
+  #
+  # 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, to 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?
+  #
+  # = Example
+  #
+  # 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
+  #
+  # New! Use the Vpim::Maker::Vcard to make vCards!
+  class Vcard < DirectoryInfo
+
+    private_class_method :new
+
+    # 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 = [] )
+      fields.unshift Field.create('VERSION', "3.0")
+      super(fields, 'VCARD')
+    end
+
+    # Decode a collection of vCards into an array of Vcard objects.
+    #
+    # +card+ can be either a String or an IO object.
+    #
+    # Since vCards are self-delimited (by a BEGIN:vCard and an END:vCard),
+    # multiple vCards can be concatenated into a single directory info object.
+    # They may or may not be related. For example, AddressBook.app (the OS X
+    # contact manager) will export multiple selected cards in this format.
+    #
+    # The card data must be UTF-8 (ASCII is valid UTF-8) or UCS-2 (2 byte
+    # Unicode). All valid vCards must begin with "BEGIN:VCARD", and the UCS-2
+    # encoding of 'B' is a the nul character (0x00) followed by the ASCII
+    # value of 'B', so the input is considered to be UCS-2 if the first
+    # character in the string is nul, and converted to UTF-8.
+    #
+    # If you know that you have only one vCard, then you can decode that
+    # single vCard by doing something like:
+    #
+    #   vcard = Vcard.decode(card_data).first
+    def Vcard.decode(card)
+      if card.respond_to? :to_str
+        string = card.to_str
+      elsif card.kind_of? IO
+        string = card.read(nil)
+      else
+        raise ArgumentError, "Vcard.decode cannot be called with a #{card.type}"
+      end
+
+      # The card representation can be either UTF-8, or UCS-2. If its
+      # UCS-2, then the first byte will be 0, so check for this, and convert
+      # if necessary.
+      #
+      # We know it's 0, because the first character in a vCard must be the 'B'
+      # of "BEGIN:VCARD", and in UCS-2 all ascii are encoded as a 0 byte
+      # followed by the ASCII byte, UNICODE is great.
+      if string[0] == 0
+        string = string.unpack('n*').pack('U*')
+      end
+
+      entities = Vpim.expand(Vpim.decode(string))
+
+      # Since all vCards must have a begin/end, the top-level should consist
+      # entirely of entities/arrays, even if its a single vCard.
+      if entities.detect { |e| ! e.kind_of? Array }
+        raise "Not a valid vCard"
+      end
+
+      vcards = []
+
+      for e in entities
+        vcards.push(new(e.flatten, 'VCARD'))
+      end
+
+      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.
+    def [](name, type=nil)
+      fields = enum_by_name(name).find_all { |f| type == nil || f.type?(type) }
+
+      # limit to preferred, if possible
+      pref = fields.find_all { |f| f.pref? }
+
+      if(pref.first)
+        fields = pref
+      end
+
+      fields.first ? fields.first.value : nil
+    end
+  end
+end
+