fraser-vpim-rails 0.658

data/lib/vpim/property/common.rb

@@ -0,0 +1,315 @@
+=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/address'
+require 'vpim/attachment'
+
+module Vpim
+  class Icalendar
+    module Property
+
+      # Properties common to Vevent, Vtodo, and Vjournal.
+      module Common
+
+        # This property defines the access classification for a calendar
+        # component.
+        #
+        # An access classification is only one component of the general
+        # security system within a calendar application. It provides a method
+        # of capturing the scope of the access the calendar owner intends for
+        # information within an individual calendar entry. The access
+        # classification of an individual iCalendar component is useful when
+        # measured along with the other security components of a calendar
+        # system (e.g., calendar user authentication, authorization, access
+        # rights, access role, etc.). Hence, the semantics of the individual
+        # access classifications cannot be completely defined by this memo
+        # alone. Additionally, due to the "blind" nature of most exchange
+        # processes using this memo, these access classifications cannot serve
+        # as an enforcement statement for a system receiving an iCalendar
+        # object.  Rather, they provide a method for capturing the intention of
+        # the calendar owner for the access to the calendar component.
+        #
+        # Property Name: CLASS
+        #
+        # Property Value: one of "PUBLIC", "PRIVATE", "CONFIDENTIAL", default
+        # is "PUBLIC" if no CLASS property is found.
+        def access_class
+          proptoken 'CLASS', ["PUBLIC", "PRIVATE", "CONFIDENTIAL"], "PUBLIC"
+        end
+
+        def created
+          proptime 'CREATED'
+        end
+
+        # Description of the calendar component, or nil if there is no
+        # description.
+        def description
+          proptext 'DESCRIPTION'
+        end
+
+        # Revision sequence number of the calendar component, or nil if there
+        # is no SEQUENCE; property.
+        def sequence
+          propinteger 'SEQUENCE'
+        end
+
+        # The time stamp for this calendar component.
+        def dtstamp
+          proptime 'DTSTAMP'
+        end
+
+        # The start time for this calendar component.
+        def dtstart
+          proptime 'DTSTART'
+        end
+
+        def lastmod
+          proptime 'LAST-MODIFIED'
+        end
+
+        # Return the event organizer, an object of Icalendar::Address (or nil if
+        # there is no ORGANIZER field).
+        def organizer
+          organizer = @properties.field('ORGANIZER')
+
+          if organizer
+            organizer = Icalendar::Address.decode(organizer)
+          end
+
+          organizer.freeze
+        end
+
+=begin
+recurid
+seq
+=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
+          case self
+          when Vpim::Icalendar::Vevent
+            proptoken 'STATUS', ['TENTATIVE', 'CONFIRMED', 'CANCELLED']
+
+          when Vpim::Icalendar::Vtodo
+            proptoken 'STATUS', ['NEEDS-ACTION', 'COMPLETED', 'IN-PROCESS', 'CANCELLED']
+
+          when Vpim::Icalendar::Vevent
+            proptoken 'STATUS', ['DRAFT', 'FINAL', 'CANCELLED']
+          end
+        end
+
+        # TODO - def status? ...
+
+        # TODO - def status= ...
+
+        # Summary description of the calendar component, or nil if there is no
+        # SUMMARY property.
+        def summary
+          proptext 'SUMMARY'
+        end
+
+        # The unique identifier of this calendar component, a string.
+        def uid
+          proptext 'UID'
+        end
+
+        def url
+          propvalue 'URL'
+        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)
+          attendees = @properties.enum_by_name('ATTENDEE').map { |a| Icalendar::Address.decode(a) }
+          attendees.freeze
+          if uri
+            attendees.select { |a| a == uri }
+          else
+            attendees
+          end
+        end
+
+        # Return true if the +uri+, usually a mailto: URI, is an attendee.
+        def attendee?(uri)
+          attendees.include? uri
+        end
+
+        # This property defines the categories for a calendar component.
+        #
+        # Property Name: CATEGORIES
+        #
+        # Value Type: TEXT
+        #
+        # Ruby Type: Array of String
+        #
+        # This property is used to specify categories or subtypes of the
+        # calendar component. The categories are useful in searching for a
+        # calendar component of a particular type and category.
+        def categories
+          proptextlistarray 'CATEGORIES'
+        end
+
+        def comments
+          proptextarray 'COMMENT'
+        end
+
+        def contacts
+          proptextarray 'CONTACT'
+        end
+
+        # An Array of attachments, see Attachment for more information.
+        def attachments
+          @properties.enum_by_name('ATTACH').map do |f|
+            attachment = Attachment.decode(f, 'uri', 'FMTTYPE')
+          end
+        end
+      end
+
+    end
+
+    module Set
+
+      # Properties common to Vevent, Vtodo, and Vjournal.
+      module Common
+
+        # Set the access class of the component, see Icalendar::Property::Common#access_class.
+        def access_class(token)
+          set_token 'CLASS', ["PUBLIC", "PRIVATE", "CONFIDENTIAL"], "PUBLIC", token
+        end
+
+        # Set the creation time, see Icalendar::Property::Common#created
+        def created(time)
+          set_datetime 'CREATED', time
+        end
+
+        # Set the description, see Icalendar::Property::Common#description.
+        def description(text)
+          set_text 'DESCRIPTION', text
+        end
+
+        # Set the sequence number, see Icalendar::Property::Common#sequence.
+        # is no SEQUENCE; property.
+        def sequence(int)
+          set_integer 'SEQUENCE', int
+        end
+
+        # Set the timestamp, see Icalendar::Property::Common#timestamp.
+        def dtstamp(time)
+          set_datetime 'DTSTAMP', time
+          self
+        end
+
+        # The start time or date, see Icalendar::Property::Common#dtstart.
+        def dtstart(start)
+          set_date_or_datetime 'DTSTART', 'DATE-TIME', start
+          self
+        end
+
+        # Set the last modification time, see Icalendar::Property::Common#lastmod.
+        def lastmod(time)
+          set_datetime 'LAST-MODIFIED', time
+          self
+        end
+
+        # Set the event organizer, an Icalendar::Address, see Icalendar::Property::Common#organizer.
+        #
+        # Without an +adr+ it yields an Icalendar::Address that is a copy of
+        # the current organizer (if any), allowing it to be modified.
+        def organizer(adr=nil) #:yield: organizer
+          unless adr
+            adr = @comp.organizer
+            if adr
+              adr = adr.copy
+            else
+              adr = Icalendar::Address.create
+            end
+            yield adr
+          end
+          set_address('ORGANIZER', adr)
+          self
+        end
+
+=begin
+        # 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
+          case self
+          when Vpim::Icalendar::Vevent
+            proptoken 'STATUS', ['TENTATIVE', 'CONFIRMED', 'CANCELLED']
+
+          when Vpim::Icalendar::Vtodo
+            proptoken 'STATUS', ['NEEDS-ACTION', 'COMPLETED', 'IN-PROCESS', 'CANCELLED']
+
+          when Vpim::Icalendar::Vevent
+            proptoken 'STATUS', ['DRAFT', 'FINAL', 'CANCELLED']
+          end
+        end
+=end
+
+        # Set summary description of component, see Icalendar::Property::Common#summary.
+        def summary(text)
+          set_text 'SUMMARY', text
+        end
+
+        # Set the unique identifier of this calendar component, see Icalendar::Property::Common#uid.
+        def uid(uid)
+          set_text 'UID', uid
+        end
+
+        def url(url)
+          set_text 'URL', url
+        end
+
+        # Add an attendee Address, see Icalendar::Property::Common#attendees.
+        def add_attendee(adr)
+          add_address('ATTENDEE', adr)
+        end
+
+        # Set the categories, see Icalendar::Property::Common#attendees.
+        #
+        # If +cats+ is provided, the categories are set to cats, either a
+        # String or an Array of String. Otherwise, and array of the existing
+        # category strings is yielded, and it can be modified.
+        def categories(cats = nil) #:yield: categories
+          unless cats
+            cats = @comp.categories
+            yield cats
+          end
+          # TODO - strip the strings
+          set_text_list('CATEGORIES', cats)
+        end
+
+        # Set the comment, see Icalendar::Property::Common#comments.
+        def comment(value)
+          set_text 'COMMENT', value
+        end
+
+=begin
+        def contacts
+          proptextarray 'CONTACT'
+        end
+
+        # An Array of attachments, see Attachment for more information.
+        def attachments
+          @properties.enum_by_name('ATTACH').map do |f|
+            attachment = Attachment.decode(f, 'uri', 'FMTTYPE')
+          end
+        end
+=end
+
+      end
+
+    end
+  end
+end
+
+

data/lib/vpim/property/location.rb

@@ -0,0 +1,38 @@
+=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
+
+module Vpim
+  class Icalendar
+    module Property
+      module Location
+        # Physical location information relevant to the component, or nil if
+        # there is no LOCATION property.
+        def location
+          proptext 'LOCATION'
+        end
+
+        # Array of Float, +[ latitude, longitude]+.
+        #
+        # North of the equator is positive latitude, east of the meridian is
+        # positive longitude.
+        #
+        # See RFC2445 for more info... there are lots of special cases.
+        def geo
+          prop = @properties.detect { |f| f.name? 'GEO' }
+          if prop
+            prop = Vpim.decode_list(prop.value_raw, ';') do |item| item.to_f end
+          end
+          prop
+        end
+
+      end
+    end
+  end
+end
+
+

data/lib/vpim/property/priority.rb

@@ -0,0 +1,43 @@
+=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
+
+module Vpim
+  class Icalendar
+    module Property
+      module Priority
+
+        # +priority+ is a number from 1 to 9, with 1 being the highest
+        # priority, 9 being the lowest. 0 means "no priority", equivalent to
+        # not specifying the PRIORITY field.
+        #
+        # The other integer values are reserved by RFC2445.
+        #
+        # TODO
+        # - methods to compare priorities?
+        # - return as class Priority, with #to_i, and #to_s, and appropriate
+        #   comparison operators?
+        def priority
+          p = @properties.detect { |f| f.name? 'PRIORITY' }
+          
+          if !p
+            p = 0
+          else
+            p = p.value.to_i
+
+            if( p < 0 || p > 9 )
+              raise Vpim::InvalidEncodingError, 'Invalid priority #{@priority} - it must be 0-9!'
+            end
+          end
+          p
+        end
+      end
+    end
+  end
+end
+
+

data/lib/vpim/property/recurrence.rb

@@ -0,0 +1,69 @@
+=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 "enumerator"
+
+module Vpim
+  class Icalendar
+    module Property
+
+      # Occurrences are calculated from DTSTART and RRULE. If there is no
+      # RRULE, the component occurs only once, at the start time.
+      #
+      # Limitations:
+      #
+      # Only a single RRULE: is currently supported, this is the most common
+      # case.
+      module Recurrence
+        def rrule #:nodoc:
+          start = dtstart
+          unless start
+            raise ArgumentError, "Components without a DTSTART don't have occurrences!"
+          end
+          Vpim::Rrule.new(start, propvalue('RRULE'))
+        end
+
+        # The times this components occurs. If a block is not provided, returns
+        # an enumerator.
+        #
+        # Occurrences may be infinite, +dountil+ can be provided to limit the
+        # iterations, see Rrule#each.
+        def occurrences(dountil = nil, &block) #:yield: occurrence time
+          rr = rrule
+          unless block_given?
+            return Enumerable::Enumerator.new(self, :occurrences, dountil)
+          end
+
+          rr.each(dountil, &block)
+        end
+
+        alias occurences occurrences #:nodoc: backwards compatibility
+
+        # True if this components occurs in a time period later than +t0+, but
+        # earlier than +t1+.
+        def occurs_in?(t0, t1)
+          # TODO - deprecate this, its a hack
+          occurrences(t1).detect do |tend|
+            if respond_to? :duration
+              tend += duration || 0
+            end
+            tend >= t0
+          end
+        end
+
+        def rdates #:nodoc:
+          # TODO - this is a hack, remove it
+          Vpim.decode_date_time_list(propvalue('RDATE'))
+        end
+
+      end
+    end
+  end
+end
+
+

data/lib/vpim/property/resources.rb

@@ -0,0 +1,24 @@
+=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
+
+module Vpim
+  class Icalendar
+    module Property
+
+      module Resources
+
+        def resources
+          proptextlistarray 'RESOURCES'
+        end
+
+      end
+    end
+  end
+end
+
+

data/lib/vpim/repo.rb

@@ -0,0 +1,181 @@
+=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 'enumerator'
+
+require 'plist'
+
+require 'vpim/icalendar'
+require 'vpim/duration'
+
+module Vpim
+  # A Repo is a representation of a calendar repository.
+  #
+  # Currently supported repository types are:
+  # - Repo::Apple3, an Apple iCal3 repository.
+  # - Repo::Directory, a directory hierarchy containing .ics files
+  #
+  # All repository types support at least the methods of Repo, and all
+  # repositories return calendars that support at least the methods of
+  # Repo::Calendar.
+  class Repo
+    include Enumerable
+
+    # Open a repository at location +where+.
+    def initialize(where)
+    end
+
+    # Enumerate the calendars in the repository.
+    def each #:yield: calendar
+    end
+
+    # A calendar abstraction. It models a calendar in a calendar repository
+    # that may not be an iCalendar.
+    #
+    # It has methods that behave identically to Icalendar, but it also has
+    # methods like name and displayed that are not present in an iCalendar.
+    class Calendar
+      include Enumerable
+
+      # The calendar name.
+      def name
+      end
+
+      # Whether a calendar should be displayed.
+      #
+      # TODO - should be #displayed?
+      def displayed
+      end
+
+      # Encode into iCalendar format.
+      def encode
+      end
+
+      # Enumerate the components in the calendar, both todos and events, or
+      # the specified klass. Like Icalendar#each()
+      def each(klass=nil, &block) #:yield: component
+      end
+
+      # Enumerate the events in the calendar.
+      def events(&block) #:yield: Vevent
+        each(Vpim::Icalendar::Vevent, &block)
+      end
+
+      # Enumerate the todos in the calendar.
+      def todos(&block) #:yield: Vtodo
+        each(Vpim::Icalendar::Vtodo, &block)
+      end
+
+      # The method definitions are just to fool rdoc, not to be used.
+      %w{each name displayed encode}.each{|m| remove_method m}
+
+      def file_each(file, klass, &block) #:nodoc:
+        unless iterator?
+          return Enumerable::Enumerator.new(self, :each, klass)
+        end
+
+        cals = Vpim::Icalendar.decode(File.open(file))
+
+        cals.each do |cal|
+          cal.each(klass, &block)
+        end
+        self
+      end
+    end
+  end
+
+  class Repo
+    include Enumerable
+
+    # An Apple iCal version 3 repository.
+    class Apple3 < Repo
+      def initialize(where = "~/Library/Calendars")
+        @where = where.to_str
+      end
+
+      def each #:nodoc:
+        Dir[ File.expand_path(@where + "/**/*.calendar") ].each do |dir|
+          yield Calendar.new(dir)
+        end
+        self
+      end
+
+      class Calendar < Repo::Calendar
+        def initialize(dir) # :nodoc:
+          @dir = dir
+        end
+
+        def plist(key) #:nodoc:
+          Plist::parse_xml( @dir + "/Info.plist")[key]
+        end
+
+        def name #:nodoc:
+          plist "Title"
+        end
+
+        def displayed #:nodoc:
+          1 == plist("Checked")
+        end
+
+        def each(klass=nil, &block) #:nodoc:
+          unless iterator?
+            return Enumerable::Enumerator.new(self, :each, klass)
+          end
+          Dir[ @dir + "/Events/*.ics" ].map do |ics|
+            file_each(ics, klass, &block)
+          end
+          self
+        end
+
+        def encode #:nodoc:
+          Icalendar.create2 do |cal|
+            each{|c| cal << c}
+          end.encode
+        end
+      end
+
+    end
+
+    class Directory < Repo
+      class Calendar < Repo::Calendar
+        def initialize(file) #:nodoc:
+          @file = file
+        end
+
+        def name #:nodoc:
+          File.basename(@file)
+        end
+
+        def displayed #:nodoc:
+          true
+        end
+
+        def each(klass, &block) #:nodoc:
+          file_each(@file, klass, &block)
+        end
+
+        def encode #:nodoc:
+          open(@file, "r"){|f| f.read}
+        end
+
+      end
+
+      def initialize(where = ".")
+        @where = where.to_str
+      end
+
+      def each #:nodoc:
+        Dir[ File.expand_path(@where + "/**/*.ics") ].each do |file|
+          yield Calendar.new(file)
+        end
+        self
+      end
+    end
+  end
+end
+