vpim 0.16

data/lib/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/lib/vpim/vcard.rb

@@ -0,0 +1,210 @@
+=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 'vpim/dirinfo'
+require '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.
+    #
+    # Input data will be converted from unicode if it is detected. The heuristic
+    # is based on the first bytes in the string:
+    # - 0xEF 0xBB 0xBF: UTF-8 with a BOM, the BOM is stripped
+    # - 0xFE 0xFF: UTF-16 with a BOM (big-endian), the BOM is stripped and string
+    #   is converted to UTF-8
+    # - 0xFF 0xFE: UTF-16 with a BOM (little-endian), the BOM is stripped and string
+    #   is converted to UTF-8
+    # - 0x00 'B' or 0x00 'b': UTF-16 (big-endian), the string is converted to UTF-8
+    # - 'B' 0x00 or 'b' 0x00: UTF-16 (little-endian), the string is 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
+    #
+    # Note: Should the import encoding be remembered, so that it can be reencoded in
+    # the same format?
+    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
+
+      case string
+        when /^\xEF\xBB\xBF/
+          string = string.sub("\xEF\xBB\xBF", '')
+        when /^\xFE\xFF/
+          arr = string.unpack('n*')
+          arr.shift
+          string = arr.pack('U*')
+        when /^\xFF\xFE/
+          arr = string.unpack('v*')
+          arr.shift
+          string = arr.pack('U*')
+        when /^\x00\x62/i
+          string = string.unpack('n*').pack('U*')
+        when /^\x62\x00/i
+          string = string.unpack('v*').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
+
+    # The nickname or nil if there is none.
+    def nickname
+      nn = self['nickname']
+      if nn
+        nn = nn.sub(/^\s+/, '')
+        nn = nn.sub(/\s+$/, '')
+        nn = nil if nn == ''
+      end
+      nn
+    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.
+    #
+    # 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')
+
+      return nil unless bday
+
+      begin
+        date = bday.to_date.first
+
+      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
+          end
+          date = Date.new(y, m, d)
+        else
+          raise
+        end
+      end
+
+      date
+    end
+
+  end
+end
+

data/lib/vpim/vevent.rb

@@ -0,0 +1,381 @@
+=begin
+  $Id: vevent.rb,v 1.12 2005/01/21 04:09:55 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/dirinfo'
+require 'vpim/field'
+require 'vpim/rfc2425'
+require 'vpim/vpim'
+
+=begin
+A vTodo that is done:
+
+BEGIN:VTODO
+COMPLETED:20040303T050000Z
+DTSTAMP:20040304T011707Z
+DTSTART;TZID=Canada/Eastern:20030524T115238
+SEQUENCE:2
+STATUS:COMPLETED
+SUMMARY:Wash Car
+UID:E7609713-8E13-11D7-8ACC-000393AD088C
+END:VTODO
+
+BEGIN:VTODO
+DTSTAMP:20030909T015533Z
+DTSTART;TZID=Canada/Eastern:20030808T000000
+SEQUENCE:1
+SUMMARY:Renew Passport
+UID:EC76B256-BBE9-11D7-8401-000393AD088C
+END:VTODO
+
+
+=end
+
+module Vpim
+  class Icalendar
+    class Vtodo
+      def initialize(fields) #:nodoc:
+        @fields = fields
+
+        outer, inner = Vpim.outer_inner(fields)
+
+        @properties = Vpim::DirectoryInfo.create(outer)
+
+        @elements = inner
+
+        # TODO - don't get properties here, put the accessor in a module,
+        # which can cache the results.
+
+        @summary       = @properties.text('SUMMARY').first
+        @description   = @properties.text('DESCRIPTION').first
+        @comment       = @properties.text('COMMENT').first
+        @location      = @properties.text('LOCATION').first
+        @status        = @properties.text('STATUS').first
+        @uid           = @properties.text('UID').first
+        @priority      = @properties.text('PRIORITY').first
+
+        # See "TODO - fields" in dirinfo.rb
+        @dtstamp       = @properties.field('dtstamp')
+        @dtstart       = @properties.field('dtstart')
+        @dtend         = @properties.field('dtend')
+        @duration      = @properties.field('duration')
+        @due           = @properties.field('due')
+        @rrule         = @properties['rrule']
+
+        # Need to seperate status-handling out into a module...
+        @status_values = [ 'COMPLETED' ];
+
+      end
+
+      attr_reader :description, :summary, :comment, :location
+      attr_reader :properties, :fields # :nodoc:
+
+      # Create a new Vtodo object.
+      #
+      # If specified, +fields+ must be either an array of Field objects to
+      # add, or a Hash of String names to values that will be used to build
+      # Field objects. The latter is a convenient short-cut allowing the Field
+      # objects to be created for you when called like:
+      #
+      #   Vtodo.create('SUMMARY' => "buy mangos")
+      #
+      # TODO - maybe todos are usually created in a particular way? I can
+      # make it easier. Ideally, I would like to make it hard to encode an invalid
+      # Event.
+      def Vtodo.create(fields=[])
+        di = DirectoryInfo.create([], 'VTODO')
+
+        Vpim::DirectoryInfo::Field.create_array(fields).each { |f| di.push_unique f }
+
+        new(di.to_a)
+      end
+
+=begin
+I think that the initialization shouldn't be done in the #initialize, so, for example,
+  @status = @properties.text('STATUS').first
+should be in the method below.
+
+That way, I can construct a Vtodo by just including a module for each field that is allowed
+in a Vtodo, simply.
+=end
+      def status
+        if(!@status); return nil; end
+
+        s = @status.upcase
+
+        unless @status_values.include?(s)
+          raise Vpim::InvalidEncodingError, "Invalid status '#{@status}'"
+        end
+
+        s
+      end
+
+      # +priority+ is a number from 1 to 9, with 1 being the highest and 0
+      # meaning "no priority", equivalent to not specifying the PRIORITY field.
+      # Other values are reserved by RFC2446.
+      def priority
+        p = @priority ? @priority.to_i : 0
+
+        if( p < 0 || p > 9 )
+          raise Vpim::InvalidEncodingError, 'Invalid priority #{@priority} - it must be 0-9!'
+        end
+        p
+      end
+    end
+  end
+end
+
+module Vpim
+  class Icalendar
+    class Vevent
+      def initialize(fields) #:nodoc:
+        @fields = fields
+
+        outer, inner = Vpim.outer_inner(fields)
+
+        @properties = Vpim::DirectoryInfo.create(outer)
+
+        @elements = inner
+
+        # TODO - don't get properties here, put the accessor in a module,
+        # which can cache the results.
+
+        @summary       = @properties.text('SUMMARY').first
+        @description   = @properties.text('DESCRIPTION').first
+        @comment       = @properties.text('COMMENT').first
+        @location      = @properties.text('LOCATION').first
+        @status        = @properties.text('STATUS').first
+        @uid           = @properties.text('UID').first
+
+        # See "TODO - fields" in dirinfo.rb
+        @dtstamp       = @properties.field('dtstamp')
+        @dtstart       = @properties.field('dtstart')
+        @dtend         = @properties.field('dtend')
+        @duration      = @properties.field('duration')
+        @rrule         = @properties['rrule']
+
+        # Need to seperate status-handling out into a module...
+        @status_values = [ 'TENTATIVE', 'CONFIRMED', 'CANCELLED' ];
+
+      end
+
+      # Create a new Vevent object. All events must have a DTSTART field,
+      # specify it as either a Time or a Date in +start+, it defaults to "now"
+      # (is this useful?).
+      #
+      # If specified, +fields+ must be either an array of Field objects to
+      # add, or a Hash of String names to values that will be used to build
+      # Field objects. The latter is a convenient short-cut allowing the Field
+      # objects to be created for you when called like:
+      #
+      #   Vevent.create(Date.today, 'SUMMARY' => "today's event")
+      #
+      # TODO - maybe events are usually created in a particular way? With a
+      # start/duration or a start/end? Maybe I can make it easier. Ideally, I
+      # would like to make it hard to encode an invalid Event.
+      def Vevent.create(start = Time.now, fields=[])
+        dtstart = DirectoryInfo::Field.create('DTSTART', start)
+        di = DirectoryInfo.create([ dtstart ], 'VEVENT')
+
+        Vpim::DirectoryInfo::Field.create_array(fields).each { |f| di.push_unique f }
+
+        new(di.to_a)
+      end
+
+      # Creates a yearly repeating event, such as for a birthday.
+      def Vevent.create_yearly(date, summary)
+        create(
+          date,
+          'SUMMARY' => summary.to_str,
+          'RRULE' => 'FREQ=YEARLY'
+          )
+      end
+
+      attr_reader :description, :summary, :comment, :location
+      attr_reader :properties, :fields # :nodoc:
+
+      #--
+      # The methods below should be shared, somehow, by all calendar components, not just Events.
+      #++
+
+      # Accept an event invitation. The +invitee+ is the Address that wishes
+      # to accept the event invitation as confirmed.
+      def accept(invitee)
+        # The event created is identical to this one, but
+        # - without the attendees
+        # - with the invitee added with a PARTSTAT of ACCEPTED
+        invitee = invitee.copy
+        invitee.partstat = 'ACCEPTED'
+
+        fields = []
+
+        @properties.each_with_index do
+          |f,i|
+
+          # put invitee in as field[1]
+          fields << invitee.field if i == 1
+          
+          fields << f unless f.name? 'ATTENDEE'
+        end
+
+        Vevent.new(fields)
+      end
+
+      # Status values are not rejected during decoding. However, if the
+      # status is requested, and it's value is not one of the defined
+      # allowable values, an exception is raised.
+      def status
+        if(!@status); return nil; end
+
+        s = @status.upcase
+
+        unless @status_values.include?(s)
+          raise Vpim::InvalidEncodingError, "Invalid status '#{@status}'"
+        end
+
+        s
+      end
+
+      # TODO - def status? ...
+
+      # TODO - def status= ...
+
+      # The unique identifier of this calendar component, a string. It cannot be
+      # nil, if it is not found in the component, the calendar is malformed, and
+      # this method will raise an exception.
+      def uid
+        if(!@uid)
+          raise Vpim::InvalidEncodingError, 'Invalid component - no UID field was found!'
+        end
+
+        @uid
+      end
+
+      # The time stamp for this calendar component. Describe what this is....
+      # This field is required!
+      def dtstamp
+        if(!@dtstamp)
+          raise Vpim::InvalidEncodingError, 'Invalid component - no DTSTAMP field was found!'
+        end
+
+        @dtstamp.to_time.first
+      end
+
+      # The start time for this calendar component. Describe what this is....
+      # This field is required!
+      def dtstart
+        if(!@dtstart)
+          raise Vpim::InvalidEncodingError, 'Invalid component - no DTSTART field was found!'
+        end
+
+        @dtstart.to_time.first
+      end
+
+=begin
+      # Set the start time for the event to +start+, a Time object.
+      # TODO - def dtstart=(start) ... start should be allowed to be Time/Date/DateTime
+=end
+
+      # The duration in seconds of a Event, Todo, or Vfreebusy component, or
+      # for Alarms, the delay period prior to repeating the alarm. The
+      # duration is calculated from the DTEND and DTBEGIN fields if the
+      # DURATION field is not present. Durations of zero seconds are possible.
+      def duration
+        if(!@duration)
+          return nil unless @dtend
+
+          b = dtstart
+          e = dtend
+
+          return (e - b).to_i
+        end
+
+        Icalendar.decode_duration(@duration.value_raw)
+      end
+
+      # The end time for this calendar component. For an Event, if there is no
+      # end time, then nil is returned, and the event takes up no time.
+      # However, the end time will be calculated from the event duration, if
+      # present.
+      def dtend
+        if(@dtend)
+          @dtend.to_time.first
+        elsif duration
+            dtstart + duration
+        else
+          nil
+        end
+      end
+
+      # The recurrence rule, if any, for this event. Recurrence starts at the
+      # DTSTART time.
+      def rrule
+        @rrule
+      end
+
+      # The times this event occurs, as a Vpim::Rrule.
+      #
+      # Note: the event may occur only once.
+      #
+      # Note: occurences are currently calculated only from DTSTART and RRULE,
+      # no allowance for EXDATE or other fields is made.
+      def occurences
+        Vpim::Rrule.new(dtstart, @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
+
+      # Return the event organizer, an object of Icalendar::Address (or nil if
+      # there is no ORGANIZER field).
+      #
+      # TODO - verify that it is illegal for there to be more than one
+      # ORGANIZER, if more than one is allowed, this needs to return an array.
+      def organizer
+        unless instance_variables.include? "@organizer"
+          @organizer = @properties.field('ORGANIZER')
+
+          if @organizer
+            @organizer = Icalendar::Address.new(@organizer)
+          end
+        end
+        @organizer.freeze
+      end
+
+      # Return an array of attendees, an empty array if there are none. The
+      # attendees are objects of Icalendar::Address. If +uri+ is specified
+      # only the return the attendees with this +uri+.
+      def attendees(uri = nil)
+        unless instance_variables.include? "@attendees"
+          @attendees = @properties.enum_by_name('ATTENDEE').map { |a| Icalendar::Address.new(a).freeze }
+          @attendees.freeze
+        end
+        if uri
+          @attendees.select { |a| a == uri } .freeze
+        else
+          @attendees
+        end
+      end
+
+      # Return true if the +uri+, usually a mailto: URI, is an attendee.
+      def attendee?(uri)
+        attendees.include? uri
+      end
+
+      # CONTACT - value is text, parameters are ALTREP and LANGUAGE.
+      #
+      # textual contact information, or an altrep referring to a URI pointing
+      # at a vCard or LDAP entry...
+    end
+  end
+end
+