vpim2 0.0.1

data/lib/plist.rb

@@ -0,0 +1,22 @@
+#--
+##############################################################
+# Copyright 2006, Ben Bleything <ben@bleything.net> and      #
+# Patrick May <patrick@hexane.org>                           #
+#                                                            #
+# Distributed under the MIT license.                         #
+##############################################################
+#++
+# = Plist
+#
+# This is the main file for plist.  Everything interesting happens in Plist and Plist::Emit.
+
+require 'base64'
+require 'cgi'
+require 'stringio'
+
+require 'plist/generator'
+require 'plist/parser'
+
+module Plist
+  VERSION = '3.0.0'
+end

data/lib/vpim.rb

@@ -0,0 +1,13 @@
+=begin
+  Copyright (C) 2008 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
+
+# the existence of this file is a hack to support users or rubygems
+
+require 'vpim/icalendar'
+require 'vpim/vcard'
+

data/lib/vpim/address.rb

@@ -0,0 +1,219 @@
+=begin
+  Copyright (C) 2008 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
+
+=begin
+
+Notes on a CAL-ADDRESS
+
+When used with ATTENDEE, the parameters are:
+  CN
+  CUTYPE
+  DELEGATED-FROM
+  DELEGATED-TO
+  DIR
+  LANGUAGE
+  MEMBER
+  PARTSTAT
+  ROLE
+  RSVP
+  SENT-BY
+
+When used with ORGANIZER, the parameters are:
+  CN
+  DIR
+  LANGUAGE
+  SENT-BY
+
+
+What I've seen in Notes invitations, and iCal responses:
+  ROLE
+  PARTSTAT
+  RSVP
+  CN
+
+Support these last 4, for now.
+
+=end
+
+module Vpim
+  class Icalendar
+    # Used to represent calendar fields containing CAL-ADDRESS values.
+    # The organizer or the attendees of a calendar event are examples of such
+    # a field.
+    #
+    # Example:
+    #
+    #   ORGANIZER;CN="A. Person":mailto:a_person@example.com
+    #
+    #   ATTENDEE;ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION
+    #    ;CN="Sam Roberts";RSVP=TRUE:mailto:SRoberts@example.com
+    #
+    class Address
+
+      # Create a copy of Address. If the original Address was frozen, this one
+      # won't be.
+      def copy
+        #Marshal.load(Marshal.dump(self))
+        self.dup.dirty
+      end
+
+      def dirty #:nodoc:
+        @field = nil
+        self
+      end
+
+      # Addresses in a CAL-ADDRESS are represented as a URI, usually a mailto URI.
+      attr_accessor :uri
+      # The common or displayable name associated with the calendar address, or
+      # nil if there is none.
+      attr_accessor :cn
+      # The participation role for the calendar user specified by the address.
+      #
+      # The standard roles are:
+      # - CHAIR Indicates chair of the calendar entity
+      # - REQ-PARTICIPANT Indicates a participant whose participation is required
+      # - OPT-PARTICIPANT Indicates a participant whose participation is optional
+      # - NON-PARTICIPANT Indicates a participant who is copied for information purposes only
+      #
+      # The default role is REQ-PARTICIPANT, returned if no ROLE parameter was
+      # specified.
+      attr_accessor :role
+      # The participation status for the calendar user specified by the
+      # property PARTSTAT, a String.
+      #
+      # These are the participation statuses for an Event:
+      # - NEEDS-ACTION Event needs action
+      # - ACCEPTED Event accepted
+      # - DECLINED Event declined
+      # - TENTATIVE Event tentatively accepted
+      # - DELEGATED Event delegated
+      #
+      # Default is NEEDS-ACTION.
+      #
+      # FIXME - make the default depend on the component type.
+      attr_accessor :partstat
+      # The value of the RSVP field, either +true+ or +false+. It is used to
+      # specify whether there is an expectation of a reply from the calendar
+      # user specified by the property value.
+      attr_accessor :rsvp
+
+      def initialize(field=nil) #:nodoc:
+        @field = field
+        @uri = ''
+        @cn = ''
+        @role = "REQ-PARTICIPANT"
+        @partstat = "NEEDS-ACTION"
+        @rsvp = false
+      end
+
+      # Create a new Address. It will encode as a +name+ property.
+      def self.create(uri='')
+        adr = new
+        adr.uri = uri.to_str
+        adr
+      end
+
+      def self.decode(field)
+        adr = new(field)
+        adr.uri = field.value
+
+        cn = field.param('CN')
+
+        if cn
+          adr.cn = cn.first
+        end
+
+        role = field.param('ROLE')
+
+        if role
+          adr.role = role.first.strip.upcase
+        end
+
+        partstat = field.param('PARTSTAT')
+
+        if partstat
+          adr.partstat = partstat.first.strip.upcase
+        end
+        
+        rsvp = field.param('RSVP')
+
+        if rsvp
+          adr.rsvp = case rsvp.first
+                     when /TRUE/i then true
+                     when /FALSE/i then false
+                     else raise InvalidEncodingError, "RSVP param value not TRUE/FALSE: #{rsvp}"
+                     end
+        end
+
+        adr.freeze
+      end
+
+      # Return a representation of this Address as a DirectoryInfo::Field.
+      def encode(name) #:nodoc:
+        if @field
+          # FIXME - set the field name, it could be different from cached
+          return @field
+        end
+
+        value = uri.to_str.strip
+
+        if value.empty?
+          raise Uencodeable, "Address#uri is zero-length"
+        end
+
+        params = {}
+
+        if cn.length > 0
+          params['CN'] = Vpim::encode_paramvalue(cn)
+        end
+
+        # FIXME - default value is different for non-vEvent
+        if role.length > 0 && role != 'REQ-PARTICIPANT'
+          params['ROLE'] = Vpim::encode_paramtext(role)
+        end
+
+        # FIXME - default value is different for non-vEvent
+        if partstat.length > 0 && partstat != 'NEEDS-ACTION'
+          params['PARTSTAT'] = Vpim::encode_paramtext(partstat)
+        end
+
+        if rsvp
+          params['RSVP'] = 'true'
+        end
+
+        Vpim::DirectoryInfo::Field.create(name, value, params)
+      end
+
+      # Return true if the +uri+ is == to this address' URI. The comparison
+      # is case-insensitive (because email addresses and domain names are).
+      def ==(uri)
+        # TODO - could I use a URI library?
+        Vpim::Methods.casecmp?(self.uri.to_str, uri.to_str)
+      end
+
+      # A string representation of an address, using the common name, and the
+      # URI. The URI protocol is stripped if it's "mailto:".
+      def to_s
+        u = uri
+        u = u.gsub(/^mailto: */i, '')
+
+        if cn.length > 0
+          "#{cn.inspect} <#{uri}>"
+        else
+          uri
+        end
+      end
+
+      def inspect #:nodoc:
+        "#<Vpim::Icalendar::Address:cn=#{cn.inspect} status=#{partstat} rsvp=#{rsvp} #{uri.inspect}>"
+      end
+
+    end
+  end
+end
+

data/lib/vpim/attachment.rb

@@ -0,0 +1,102 @@
+=begin
+  Copyright (C) 2008 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/icalendar'
+
+module Vpim
+
+  # Attachments are used by both iCalendar and vCard. They are either a URI or
+  # inline data, and their decoded value will be either a Uri or a Inline, as
+  # appropriate.
+  #
+  # Besides the methods specific to their class, both kinds of object implement
+  # a set of common methods, allowing them to be treated uniformly:
+  # - Uri#to_io, Inline#to_io: return an IO from which the value can be read.
+  # - Uri#to_s, Inline#to_s: return the value as a String.
+  # - Uri#format, Inline#format: the format of the value. This is supposed to
+  #   be an "iana defined" identifier (like "image/jpeg"), but could be almost
+  #   anything (or nothing) in practice.  Since the parameter is optional, it may
+  #   be "".
+  #
+  # The objects can also be distinguished by their class, if necessary.
+  module Attachment
+
+    # TODO - It might be possible to autodetect the format from the first few
+    # bytes of the value, and return the appropriate MIME type when format
+    # isn't defined.
+    #
+    # iCalendar and vCard put the format in different parameters, and the
+    # default kind of value is different.
+    def Attachment.decode(field, defkind, fmtparam) #:nodoc:
+      format = field.pvalue(fmtparam) || ''
+      kind = field.kind || defkind
+      case kind
+      when 'text'
+        Inline.new(Vpim.decode_text(field.value), format)
+      when 'uri'
+        Uri.new(field.value_raw, format)
+      when 'binary'
+        Inline.new(field.value, format)
+      else
+        raise InvalidEncodingError, "Attachment of type #{kind} is not allowed"
+      end
+    end
+
+    # Extends a String to support some of the same methods as Uri.
+    class Inline < String
+      def initialize(s, format) #:nodoc:
+        @format = format
+        super(s)
+      end
+
+      # Return an IO object for the inline data. See +stringio+ for more
+      # information.
+      def to_io
+        StringIO.new(self)
+      end
+
+      # The format of the inline data.
+      # See Attachment.
+      attr_reader :format
+    end
+
+    # Encapsulates a URI and implements some methods of String.
+    class Uri
+      def initialize(uri, format) #:nodoc:
+        @uri = uri
+        @format = format
+      end
+
+      # The URI value.
+      attr_reader :uri
+
+      # The format of the data referred to by the URI.
+      # See Attachment.
+      attr_reader :format
+
+      # Return an IO object from opening the URI.  See +open-uri+ for more
+      # information.
+      def to_io
+        open(@uri)
+      end
+
+      # Return the String from reading the IO object to end-of-data.
+      def to_s
+        to_io.read(nil)
+      end
+
+      def inspect #:nodoc:
+        s = "<#{self.class.to_s}: #{uri.inspect}>"
+        s << ", #{@format.inspect}" if @format
+        s
+      end
+    end
+
+  end
+end
+

data/lib/vpim/date.rb

@@ -0,0 +1,222 @@
+=begin
+  Copyright (C) 2008 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 vpim_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 occurrence 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.ordinal, which allows a Date to be created by
+  # day-of-the-year, yday, and to Date.commercial, 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
+
+  # Return the first day of the week for the specified date. Commercial weeks
+  # start on Monday, but the weekstart can be specified (as 0-6, where 0 is
+  # sunday, or in formate of Date.str2day).
+  def Date.weekstart(year, mon, day, weekstart="MO")
+    wkst = Date.str2wday(weekstart)
+    d = Date.new(year, mon, day)
+    until d.wday == wkst
+      d = d - 1
+    end
+    d
+  end
+end
+
+# DateGen generates arrays of dates matching simple criteria.
+class DateGen
+
+  # Generate an array of a week's dates, where week is specified by year, mon,
+  # day, and the weekstart (the day-of-week that is considered the "first" day
+  # of that week, 0-6, where 0 is sunday).
+  def DateGen.weekofdate(year, mon, day, weekstart)
+    d = Date.weekstart(year, mon, day, weekstart)
+    week = []
+    7.times do
+      week << d
+      d = d + 1
+    end
+    week
+  end
+
+  # 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 occurrence 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
+