vpim 0.17 → 0.323

data/lib/vpim/vcard.rb~

@@ -1,232 +0,0 @@
-=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, 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?
-  #
-  # = 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) }
-
-      valued = fields.select { |f| f.value != '' }
-      if valued.first
-        fields = valued
-      end
-
-      # limit to preferred, if possible
-      pref = fields.select { |f| f.pref? }
-
-      if pref.first
-        fields = pref
-      end
-
-      fields.first ? fields.first.value : nil
-    end
-
-=begin
-TODO
-    def name
-      h = {} Create a Struct from the FN fields (maybe add the N field value, to?)
-
-      def h.to_s
-        concatenate the name fields nicely to make the name
-      end
-    end
-=end
-
-    # The nickname or nil if there is none.
-    def nickname
-      nn = self['nickname']
-      if nn && nn == ''
-        nn = nil
-      end
-      nn
-    end
-
-    # All the nicknames, [] if there are none.
-    def nicknames
-      nn = self['nickname']
-      if nn && nn == ''
-        nn = nil
-      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~

@@ -1,381 +0,0 @@
-=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
-