vpim 0.619 → 0.658

data/lib/vpim/rfc2425.rb

@@ -14,9 +14,10 @@ module Vpim
 
     # 1*(ALPHA / DIGIT / "-")
     # Note: I think I can add A-Z here, and get rid of the "i" matches elsewhere.
-    # Note: added '_' to allowed because its produced by Notes - X-LOTUS-CHILD_UID
-    # Note: added '/' to allowed because its produced by KAddressBook - X-messaging/xmpp-All:
-    NAME    = '[-a-z0-9_/]+'
+    # Note: added '_' to allowed because its produced by Notes  (X-LOTUS-CHILD_UID:)
+    # Note: added '/' to allowed because its produced by KAddressBook (X-messaging/xmpp-All:)
+    # Note: added ' ' to allowed because its produced by highrisehq.com (X-GOOGLE TALK:)
+    NAME    = '[-a-z0-9_/][-a-z0-9_/ ]*'
 
     # <"> <Any character except CTLs, DQUOTE> <">
     QSTR    = '"([^"]*)"'
@@ -348,7 +349,7 @@ module Vpim
   # an array of all the inner arrays of fields. Return the array [outer,
   # inner].
   def Vpim.outer_inner(fields) #:nodoc:
-    # FIXME - use Enumerable#partition
+    # TODO - use Enumerable#partition
     # seperate into the outer-level fields, and the arrays of component
     # fields
     outer = []

data/lib/vpim/rrule.rb

@@ -57,11 +57,10 @@ module Vpim
     # from a start time, +dtstart+ (which must the first of the set of
     # recurring times). If +rrule+ is nil, the set contains only +dtstart+.
     def initialize(dtstart, rrule = nil)
-      # dtstart must be in local time, they say, but I think that really
-      # means must be in a particular timezone
-
-      # Note: DTSTART is always in the recurrence set
-       @dtstart = dtstart
+       @dtstart = dtstart.getlocal
+       # The getlocal is a hack so that UTC times get converted to local,
+       # because yielded times are always local, because we don't support
+       # timezones.
        @rrule = rrule
 
        # Freq is mandatory, but must occur only once.
@@ -511,7 +510,7 @@ module Vpim
       dates
     end
 
-    def byday_in_weekly(year, mon, day, wkst, byday)
+    def byday_in_weekly(year, mon, day, wkst, byday) #:nodoc:
       #    debug ["day", year,mon,day,wkst,byday]
       days = byday.map{ |_, byday| Date.str2wday(byday) }
       week = DateGen.weekofdate(year, mon, day, wkst)
@@ -522,7 +521,71 @@ module Vpim
       week
     end
 
-  end
+    # Help encode an RRULE value.
+    #
+    # TODO - the Maker is both incomplete, and its a bit cheesy, I'd like to do
+    # something that is a kind of programmatic version of the UI that iCal has.
+    class Maker
+      def initialize(&block) #:yield: self
+        @freq = nil
+        @until = nil
+        @count = nil
+        @interval = nil
+        @wkst = nil
+        @by = {}
+
+        if block
+          yield self
+        end
+      end
+
+      FREQ = %w{ YEARLY WEEKLY MONTHLY DAILY } #:nodoc: incomplete!
+
+      def frequency=(freq)
+        freq = freq.to_str.upcase
+        unless FREQ.include? freq
+          raise ArgumentError, "Frequency #{freq} is not valid"
+        end
+        @freq = freq
+      end
+
+      # +runtil+ is Time, Date, or DateTime
+      def until=(runtil)
+        if @count
+          raise ArgumentError, "Cannot specify UNTIL if COUNT was specified"
+        end
+        @until = runtil
+      end
 
+      # +count+ is integral
+      def count=(rcount)
+        if @until
+          raise ArgumentError, "Cannot specify COUNT if UNTIL was specified"
+        end
+        @count = rcount.to_int
+      end
+
+      # TODO - BY....
+
+      def encode
+        unless @freq
+          raise ArgumentError, "Must specify FREQUENCY"
+        end
+
+        rrule = "FREQ=#{@freq}"
+
+        [
+          ["COUNT", @count],
+          ["UNTIL", @until],
+          # TODO...
+        ].each do |k,v|
+          if v
+            rrule += ";#{k}=#{v}"
+          end
+        end
+        rrule
+      end
+    end
+  end
 end
 

data/lib/vpim/vcard.rb

@@ -868,7 +868,7 @@ module Vpim
     #
     # LOGO is a graphic image of a logo associated with the object the vCard
     # represents. Its not common, but would probably be equivalent to the logo
-    # on printed card.
+    # on a printed card.
     #
     # See Attachment for a description of the value.
     def logos(&proc) #:yield: Line.value
@@ -958,7 +958,12 @@ module Vpim
       values('TEL')
     end
 
-    ## TITLE
+    # The TITLE value, a text string specifying the job title, functional
+    # position, or function of the object the card represents. A wrapper around
+    # #value('TITLE').
+    def title
+      value('TITLE')
+    end
 
     ## UID
 
@@ -1334,6 +1339,25 @@ module Vpim
         self
       end
 
+      # Set the title field, TITLE.
+      #
+      # It can be set to a single String.
+      def title=(title)
+        delete_if { |l| l.name == 'TITLE' }
+
+        @card << Vpim::DirectoryInfo::Field.create( 'TITLE', title );
+      end
+
+      # Set the org field, ORG.
+      #
+      # It can be set to a single String or an Array of String.
+      def org=(org)
+        delete_if { |l| l.name == 'ORG' }
+
+        @card << Vpim::DirectoryInfo::Field.create( 'ORG', org );
+      end
+
+
       # Add a URL field, URL.
       def add_url(url)
         @card << Vpim::DirectoryInfo::Field.create( 'URL', url.to_str );

data/lib/vpim/version.rb

@@ -7,9 +7,9 @@
 =end
 
 module Vpim
-  PRODID = '-//Ensemble Independent//vPim 0.619//EN'
+  PRODID = '-//Ensemble Independent//vPim 0.658//EN'
 
-  VERSION = '0.619'
+  VERSION = '0.658'
 
   # Return the API version as a string.
   def Vpim.version

data/lib/vpim/vevent.rb

@@ -9,6 +9,7 @@
 require 'vpim/dirinfo'
 require 'vpim/field'
 require 'vpim/rfc2425'
+require 'vpim/rrule'
 require 'vpim/vpim'
 require 'vpim/property/base'
 require 'vpim/property/common'
@@ -38,7 +39,7 @@ module Vpim
         # See "TODO - fields" in dirinfo.rb
       end
 
-      # TODO - derive everything from Icalendar::Component to get this kind of stuff?
+      # TODO - derive everything from Icalendar::Component to get rid of this kind of stuff?
       def fields #:nodoc:
         f = @properties.to_a
         last = f.pop
@@ -50,10 +51,8 @@ module Vpim
         @properties
       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
@@ -62,10 +61,13 @@ module Vpim
       #
       #   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=[])
+        # 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.
+        # - I don't think its useful to have a default dtstart for events
+        # - also, I don't think dstart is mandatory
         dtstart = DirectoryInfo::Field.create('DTSTART', start)
         di = DirectoryInfo.create([ dtstart ], 'VEVENT')
 
@@ -114,50 +116,23 @@ module Vpim
         proptoken 'TRANSP', ["OPAQUE", "TRANSPARENT"], "OPAQUE"
       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.
+      # The duration in seconds of an Event, or nil if unspecified. If the
+      # DURATION field is not present, but the DTEND field is, the duration is
+      # calculated from DTSTART and DTEND.  Durations of zero seconds are
+      # possible.
       def duration
-        dur = @properties.field 'DURATION'
-        dte = @properties.field 'DTEND'
-        if !dur
-          return nil unless dte
-
-          b = dtstart
-          e = dtend
-
-          return (e - b).to_i
-        end
-
-        Icalendar.decode_duration(dur.value_raw)
+        propduration 'DTEND'
       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.
+      # The end time for this Event. If the DTEND field is not present, but the
+      # DURATION field is, the end will be calculated from DTSTART and
+      # DURATION.
       def dtend
-        dte = @properties.field 'DTEND'
-        if dte
-          dte.to_time.first
-        elsif duration
-            dtstart + duration
-        else
-          nil
-        end
+        propend 'DTEND'
       end
 
       # Make a new Vevent, or make changes to an existing Vevent.
       class Maker
-        # TODO - should I automatically set
-        #   #created
-        #   #dtstamp
-        #   #sequence
-        #   ...?
-        #
-        # Many have pretty specific meanings in iTIP, perhaps I should leave
-        # them alone.
         include Vpim::Icalendar::Set::Util #:nodoc:
         include Vpim::Icalendar::Set::Common
 
@@ -187,16 +162,23 @@ module Vpim
           set_date_or_datetime 'DTEND', 'DATE-TIME', dtend
         end
 
-        # Yields a selector that allows the duration to be set.
-        #
-        # TODO - syntax is:
-        #   dur-value =  (["+"] / "-") "P" (dur-date / dur-time / dur-week)
-        #   dur-date  = dur-day [ "T" (dur-hour / dur-minute / dur-second) ]
-        #   dur-time  = "T" (dur-hour / dur-minute / dur-second)
-        #   dur-week  = 1*DIGIT "W"
-        def duration(dur) #:yield:selector
-          raise Vpim::Unsupported
+        # Add a RRULE to this event. The rule can be provided as a pre-build
+        # RRULE value, or the RRULE maker can be used.
+        def add_rrule(rule = nil, &block) #:yield: Rrule::Maker
+          # TODO - should be in Property::Reccurrence::Set
+          unless rule
+            rule = Rrule::Maker.new(&block).encode
+          end
+          @comp.properties.push(Vpim::DirectoryInfo::Field.create("RRULE", rule))
+          self
+        end
+
+        # Set the RRULE for this event. See #add_rrule
+        def set_rrule(rule = nil, &block) #:yield: Rrule::Maker
+          rm_all("RRULE")
+          add_rrule(rule, &block)
         end
+
       end
 
     end

data/lib/vpim/view.rb

@@ -0,0 +1,90 @@
+=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
+  module View
+    
+    SECSPERDAY = 24 * 60 * 60
+
+    # View only events occuring in the next week.
+    module Week
+      def each(klass = nil) #:nodoc:
+        unless block_given?
+          return Enumerable::Enumerator.new(self, :each, klass)
+        end
+
+        t0 = Time.new.to_a
+        t0[0] = t0[1] = t0[2] = 0 # sec,min,hour = 0
+        t0 = Time.local(*t0)
+        t1 = t0 + 7 * SECSPERDAY
+
+        # Need to filter occurrences, too. Create modules for this on the fly.
+        occurrences = Module.new
+        # I'm passing state into the module's instance methods by doing string
+        # evaluation... which sucks, but I don't think I can get this closure in
+        # there.
+        occurrences.module_eval(<<"__", __FILE__, __LINE__+1)
+          def occurrences(dountil=nil)
+            unless block_given?
+              return Enumerable::Enumerator.new(self, :occurrences, dountil)
+            end
+            super(dountil) do |t|
+              t0 = Time.at(#{t0.to_i})
+              t1 = Time.at(#{t1.to_i})
+              break if t >= t1
+              tend = t
+              if respond_to? :duration
+                tend += duration || 0
+              end
+              if tend >= t0
+                yield t
+              end
+            end
+          end
+__
+=begin
+        block = lambda do |dountil| 
+            unless block_given?
+              return Enumerable::Enumerator.new(self, :occurrences, dountil)
+            end
+            super(dountil) do |t|
+              break if t >= t1
+              yield t
+            end
+        end
+        occurrences.send(:define_method, :occurrences, block)
+=end
+        super do |ve|
+          if ve.occurs_in?(t0, t1)
+            if ve.respond_to? :occurrences
+              ve.extend occurrences
+            end
+            yield ve
+          end
+        end
+      end
+    end
+
+    # Return a calendar view for the next week.
+    def self.week(cal)
+      cal.clone.extend Week.dup
+    end
+
+    module Todo
+    end
+
+    # Return a calendar view of only todos (optionally, include todos that
+    # are done).
+    def self.todos(cal, withdone=false)
+    end
+
+  end
+end
+

data/lib/vpim/vjournal.rb

@@ -30,6 +30,18 @@ module Vpim
         @elements = inner
       end
 
+      # TODO - derive everything from Icalendar::Component to get rid of this kind of stuff?
+      def fields #:nodoc:
+        f = properties.to_a
+        last = f.pop
+        f.push @elements
+        f.push last
+      end
+
+      def properties #:nodoc:
+        @properties
+      end
+
       # Create a Vjournal component.
       def self.create(fields=[])
         di = DirectoryInfo.create([], 'VJOURNAL')

data/lib/vpim/vpim.rb

@@ -9,7 +9,7 @@
 require 'vpim/version'
 
 #:main:README
-#:title:vpim - a library to manipulate vCards and iCalendars
+#:title:vPim - vCard and iCalendar support for Ruby
 module Vpim
   # Exception used to indicate that data being decoded is invalid, the message
   # should describe what is invalid.

data/lib/vpim/vtodo.rb

@@ -68,9 +68,18 @@ module Vpim
         new(di.to_a)
       end
 
-      # The date and time that a to-do is expected to be completed, a Time.
+      # The duration in seconds of a Todo, or nil if unspecified. If the
+      # DURATION field is not present, but the DUE field is, the duration is
+      # calculated from DTSTART and DUE. Durations of zero seconds are
+      # possible.
+      def duration
+        propduration 'DUE'
+      end
+
+      # The time at which this Todo is due to be completed. If the DUE field is not present,
+      # but the DURATION field is, due will be calculated from DTSTART and DURATION.
       def due
-        proptime 'DUE'
+        propend 'DUE'
       end
 
       # The date and time that a to-do was actually completed, a Time.