vpim 0.619 → 0.658

data/lib/vpim/date.rb

@@ -16,7 +16,7 @@ class Date
 
   # 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 to_time
+  def vpim_to_time
     raise ArgumentError, 'date is before the start of system time' if self < TIME_START
     days = self - TIME_START
 

data/lib/vpim/enumerator.rb

@@ -6,11 +6,16 @@
   details.
 =end
 
+require "enumerator"
+
 module Vpim
   # This is a way for an object to have multiple ways of being enumerated via
   # argument to it's #each() method. An Enumerator mixes in Enumerable, so the
-  # standard APIS such as Enumerable#map(), Enumerable#to_a(), and
+  # standard APIs such as Enumerable#map(), Enumerable#to_a(), and
   # Enumerable#find_all() can be used on it.
+  #
+  # TODO since 1.8, this is part of the standard library, I should rewrite vPim
+  # so this can be removed.
   class Enumerator
     include Enumerable
 

data/lib/vpim/field.rb

@@ -98,6 +98,7 @@ module Vpim
             line << value
 
           else
+            # FIXME - somewhere along here, values with special chars need escaping...
             line << value.to_str
         end
         line

data/lib/vpim/icalendar.rb

@@ -6,6 +6,8 @@
   details.
 =end
 
+require "enumerator"
+
 require 'vpim/rfc2425'
 require 'vpim/dirinfo'
 require 'vpim/rrule'
@@ -43,6 +45,7 @@ module Vpim
   # iCalendars are usually transmitted in files with <code>.ics</code>
   # extensions.
   class Icalendar
+    # FIXME do NOT do this!
     include Vpim
 
     # Regular expression strings for the EBNF of RFC 2445
@@ -70,19 +73,16 @@ module Vpim
 
       @components = []
 
+      # could use #constants instead of this
       factory = {
         'VEVENT' => Vevent,
         'VTODO' => Vtodo,
         'VJOURNAL' => Vjournal,
+        # TODO - VTIMEZONE
       }
 
       inner.each do |component|
-        name = component.first
-        unless name.name? 'BEGIN'
-          raise InvalidEncodingError, "calendar component begins with #{name.name}, instead of BEGIN!"
-        end
-
-        name = name.value
+        name = component.first.value
 
         if klass = factory[name]
           @components << klass.new(component)
@@ -90,25 +90,43 @@ module Vpim
       end
     end
 
-    # Add and event to this calendar.
+    # Add an event to this calendar.
     #
     # Yields an event maker, Icalendar::Vevent::Maker.
     def add_event(&block) #:yield:event
       push Vevent::Maker.make( &block )
     end
 
-    # FIXME - could take mandatory fields as an arguments
-    # FIXME - args: support PRODID
-    # FIXME - yield an Icalendar::Maker if block provided
-    # FIXME - maker#prodid=
-    def Icalendar.create2(args = nil)
+    # TODO add_todo, add_journal
+
+=begin
+TODO
+    # Allows customization of calendar creation.
+    class Maker
+      def initialize #:nodoc:
+        @prodid = Vpim::PRODID
+      end
+
+      attr :prodid
+    end
+=end
+
+    # The producer ID defaults to Vpim::PRODID but you can set it to something
+    # specific to your application.
+    def Icalendar.create2(producer = Vpim::PRODID) #:yield: self
       # FIXME - make the primary API
       di = DirectoryInfo.create( [ DirectoryInfo::Field.create('VERSION', '2.0') ], 'VCALENDAR' )
 
-      di.push_unique DirectoryInfo::Field.create('PRODID',   Vpim::PRODID)
+      di.push_unique DirectoryInfo::Field.create('PRODID', producer.to_str)
       di.push_unique DirectoryInfo::Field.create('CALSCALE', "Gregorian")
 
-      new(di.to_a)
+      cal = new(di.to_a)
+
+      if block_given?
+        yield cal
+      end
+
+      cal
     end
 
     # Create a new Icalendar object with the minimal set of fields for a valid
@@ -149,7 +167,10 @@ module Vpim
     def fields # :nodoc:
       f = @properties.to_a
       last = f.pop
-      @components.each { |c| f << c.fields }
+      # Use of #each means we won't encode components in our View, but also
+      # that we won't encode timezones... but we don't decode/support timezones
+      # anyhow, so fix later.
+      each { |c| f << c.fields }
       f.push last
     end
 
@@ -175,6 +196,8 @@ module Vpim
       self
     end
 
+    alias :<< :push
+
     # Check if the protocol method is +method+
     def protocol?(method)
       Vpim::Methods.casecmp?(protocol, method)
@@ -246,9 +269,8 @@ module Vpim
       calendars
     end
 
-    # The iCalendar version multiplied by 10 as an Integer.  If no VERSION field
-    # is present (which is non-conformant), nil is returned. iCalendar must
-    # have a version of 20, and vCalendar would have a version of 10.
+    # The iCalendar version multiplied by 10 as an Integer. iCalendar must have
+    # a version of 20, and vCalendar must have a version of 10.
     def version
       v = @properties['VERSION']
 
@@ -284,11 +306,11 @@ module Vpim
     # The value of the CALSCALE: property, or "GREGORIAN" if CALSCALE: is not
     # present.
     #
-    # This is of academic interest, really because there aren't any other
-    # calendar scales defined, and given that its hard enough just dealing with
-    # Gregorian calendars, there probably won't be.
+    # This is of academic interest only. There aren't any other calendar scales
+    # defined, and given that its hard enough just dealing with Gregorian
+    # calendars, there probably won't be.
     def calscale
-      proptext('CALSCALE') || 'GREGORIAN'
+      (@properties['CALSCALE'] || 'GREGORIAN').upcase
     end
 
     # The array of all supported calendar components. If a class is provided,
@@ -305,8 +327,12 @@ module Vpim
     #
     #   calendar.components {|c| c... }
     #   => yield all components
+    #
+    # Note - use of this is mildly deprecated in favour of #each, #events,
+    # #todos, #journals because those won't return timezones, and will return
+    # Enumerators if called without a block.
     def components(klass=Object) #:yields:component
-      # TODO - should this take an interval: t0,t1?
+      klass ||= Object
 
       unless block_given?
         return @components.select{|c| klass === c}.freeze
@@ -320,14 +346,33 @@ module Vpim
       self
     end
 
-    # For backwards compatibility. Use #components.
-    def events #:nodoc:
-      components Icalendar::Vevent
+    include Enumerable
+
+    # Enumerate the top-level calendar components. Yields them if a block
+    # is provided, otherwise returns an Enumerator.
+    #
+    # This skips components that are only internally meaningful to iCalendar,
+    # such as timezone definitions.
+    def each(klass=nil, &block) # :yield: component
+      unless block
+        return Enumerable::Enumerator.new(self, :each, klass)
+      end
+      components(klass, &block)
+    end
+
+    # Short-hand for #each(Icalendar::Vevent).
+    def events(&block) #:yield: Vevent
+      each(Icalendar::Vevent, &block)
+    end
+
+    # Short-hand for #each(Icalendar::Vtodo).
+    def todos(&block) #:yield: Vtodo
+      each(Icalendar::Vtodo, &block)
     end
 
-    # For backwards compatibility. Use #components.
-    def todos #:nodoc:
-      components Icalendar::Vtodo
+    # Short-hand for #each(Icalendar::Vjournal).
+    def journals(&block) #:yield: Vjournal
+      each(Icalendar::Vjournal, &block)
     end
 
   end

data/lib/vpim/property/base.rb

@@ -10,6 +10,7 @@ module Vpim
   class Icalendar
     module Set #:nodoc:
       module Util #:nodoc:
+        # TODO - rename module to Private?
 
         def rm_all(name)
           rm = @comp.properties.select { |f| f.name? name }
@@ -114,7 +115,7 @@ module Vpim
         end
 
         def proptoken(name, allowed, default_token = nil) #:nodoc:
-          prop = propvalue name
+          prop = propvalue(name)
 
           if prop
             prop = prop.to_str.upcase
@@ -156,6 +157,35 @@ module Vpim
           @properties.select{ |f| f.name? name }.map{ |p| Vpim.decode_text_list(p.value_raw) }.flatten
         end
 
+        # Duration has "almost" the same definition for Event and Todo
+        def propduration(endfield)
+          dur = @properties.field 'DURATION'
+          dte = @properties.field endfield
+
+          if !dur
+            return nil unless dte
+
+            b = dtstart
+            e = send(endfield.downcase.to_sym)
+
+            return (e - b).to_i
+          end
+
+          Icalendar.decode_duration(dur.value_raw)
+        end
+
+        def propend(endfield)
+          dte = @properties.field endfield.to_s.upcase
+          if dte
+            dte.to_time.first
+          elsif duration
+            dtstart + duration
+          else
+            nil
+          end
+        end
+
+
       end
     end
   end

data/lib/vpim/property/common.rb

@@ -180,46 +180,46 @@ seq
       # Properties common to Vevent, Vtodo, and Vjournal.
       module Common
 
-        # Set the access class of the component, see Icalendar::Get::Common#access_class.
+        # 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::Get::Common#created
+        # Set the creation time, see Icalendar::Property::Common#created
         def created(time)
           set_datetime 'CREATED', time
         end
 
-        # Set the description, see Icalendar::Get::Common#description.
+        # Set the description, see Icalendar::Property::Common#description.
         def description(text)
           set_text 'DESCRIPTION', text
         end
 
-        # Set the sequence number, see Icalendar::Get::Common#sequence.
+        # 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::Get::Common#timestamp.
+        # Set the timestamp, see Icalendar::Property::Common#timestamp.
         def dtstamp(time)
           set_datetime 'DTSTAMP', time
           self
         end
 
-        # The start time or date, see Icalendar::Get::Common#dtstart.
+        # 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::Get::Common#lastmod.
+        # 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::Get::Common#organizer.
+        # 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.
@@ -255,12 +255,12 @@ seq
         end
 =end
 
-        # Set summary description of component, see Icalendar::Get::Common#summary.
+        # 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::Get::Common#uid.
+        # Set the unique identifier of this calendar component, see Icalendar::Property::Common#uid.
         def uid(uid)
           set_text 'UID', uid
         end
@@ -269,12 +269,12 @@ seq
           set_text 'URL', url
         end
 
-        # Add an attendee Address, see Icalendar::Get::Common#attendees.
+        # Add an attendee Address, see Icalendar::Property::Common#attendees.
         def add_attendee(adr)
           add_address('ATTENDEE', adr)
         end
 
-        # Set the categories, see Icalendar::Get::Common#attendees.
+        # 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
@@ -288,7 +288,7 @@ seq
           set_text_list('CATEGORIES', cats)
         end
 
-        # Set the comment, see Icalendar::Get::Common#comments.
+        # Set the comment, see Icalendar::Property::Common#comments.
         def comment(value)
           set_text 'COMMENT', value
         end

data/lib/vpim/property/recurrence.rb

@@ -6,42 +6,58 @@
   details.
 =end
 
+require "enumerator"
+
 module Vpim
   class Icalendar
     module Property
 
-      # Occurrences are calculated from DTSTART: and RRULE:. If there is not
-      # RRULE:, the component recurs only once, at the start time.
+      # 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.
-      #
-      # Implementation of multiple RRULE:s, and RDATE:, EXRULE:, and EXDATE: is
-      # on the todo list.  Its not a very high priority, because I haven't seen
-      # calendars using the full range of recurrence features, and haven't
-      # received feedback from any users requesting these features. So, if you
-      # need it, contact me and implementation will get on the schedule.
       module Recurrence
-        # The times this event occurs, as a Vpim::Rrule.
-        def occurrences
+        def rrule #:nodoc:
           start = dtstart
           unless start
-            raise ArgumentError, "Components with no DTSTART: don't have occurrences!"
+            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
 
-        # Check if this event overlaps with the time period later than or equal to +t0+, but
+        # True if this components occurs in a time period later than +t0+, but
         # earlier than +t1+.
         def occurs_in?(t0, t1)
-          occurrences.each_until(t1).detect { |t| tend = t + (duration || 0); tend > t0 }
+          # 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
+        def rdates #:nodoc:
+          # TODO - this is a hack, remove it
           Vpim.decode_date_time_list(propvalue('RDATE'))
         end
 

data/lib/vpim/repo.rb

@@ -6,109 +6,174 @@
   details.
 =end
 
+require 'enumerator'
+
+require 'plist'
+
 require 'vpim/icalendar'
 require 'vpim/duration'
 
 module Vpim
-  # A Repo is a representation of an event repository. Currently iCalv3
-  # repositories and directories containing .ics files are supported.
+  # A Repo is a representation of a calendar repository.
   #
-  # TODO - should yield them if a block is given, or return
-  # an enumerable otherwise. Later.
-  module Repo
-    def self.somethings_from_file(something, file) #:nodoc:
-      somethings = []
-      begin
+  # 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.send(something).each do |x|
-            somethings << x
-          end
+          cal.each(klass, &block)
         end
+        self
       end
-      somethings
-    end
-
-    def self.events_from_file(file) #:nodoc:
-      self.somethings_from_file("events", file)
     end
+  end
 
-    def self.todos_from_file(file) #:nodoc:
-      self.somethings_from_file("todos", file)
-    end
+  class Repo
+    include Enumerable
 
     # An Apple iCal version 3 repository.
-    module Ical3
-      class Calendar
+    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]
+          Plist::parse_xml( @dir + "/Info.plist")[key]
         end
 
-        # The calendar name.
-        def name
+        def name #:nodoc:
           plist "Title"
         end
 
-        # Whether a calendar should be displayed.
-        def displayed
+        def displayed #:nodoc:
           1 == plist("Checked")
         end
 
-        # Array of all events defined in the calendar.
-        def events #:yield: Vevent
+        def each(klass=nil, &block) #:nodoc:
+          unless iterator?
+            return Enumerable::Enumerator.new(self, :each, klass)
+          end
           Dir[ @dir + "/Events/*.ics" ].map do |ics|
-            Repo.events_from_file(ics)
-          end.flatten
+            file_each(ics, klass, &block)
+          end
+          self
         end
 
-        # Array of all todos defined in the calendar.
-        def todos #:yield: Vevent
-          Dir[ @dir + "/Events/*.ics" ].map do |ics|
-            Repo.todos_from_file(ics)
-          end.flatten
+        def encode #:nodoc:
+          Icalendar.create2 do |cal|
+            each{|c| cal << c}
+          end.encode
         end
-
       end
 
-      def self.each(where = "~/Library/Calendars") # :yield: Apple::Calendar
-        Dir[ File.expand_path(where + "/**/*.calendar") ].each do |dir|
-          yield Calendar.new(dir)
-        end
-        self
-      end
     end
-    module Directory
-      class Calendar
+
+    class Directory < Repo
+      class Calendar < Repo::Calendar
         def initialize(file) #:nodoc:
           @file = file
         end
 
-        def name
+        def name #:nodoc:
           File.basename(@file)
         end
 
-        def displayed
+        def displayed #:nodoc:
           true
         end
 
-        def events
-          Repo.events_from_file(@file)
+        def each(klass, &block) #:nodoc:
+          file_each(@file, klass, &block)
         end
 
-        def todos
-          Repo.todos_from_file(@file)
+        def encode #:nodoc:
+          open(@file, "r"){|f| f.read}
         end
+
+      end
+
+      def initialize(where = ".")
+        @where = where.to_str
       end
 
-      def self.each(where)
-         Dir[ File.expand_path(where + "/**/*.ics") ].each do |file|
-           yield Calendar.new(file)
-         end
-         self
+      def each #:nodoc:
+        Dir[ File.expand_path(@where + "/**/*.ics") ].each do |file|
+          yield Calendar.new(file)
+        end
+        self
       end
     end
   end