gcal4ruby 0.1.0

data/lib/gcal4ruby/event.rb

@@ -0,0 +1,403 @@
+require 'gcal4ruby/recurrence'
+
+module GCal4Ruby
+  #The Event Class represents a remote event in calendar. 
+  #
+  #=Usage
+  #All usages assume a successfully authenticated Service and valid Calendar.
+  #1. Create a new Event
+  #    event = Event.new(calendar)
+  #    event.title = "Soccer Game"
+  #    event.start = Time.parse("12-06-2009 at 12:30 PM")
+  #    event.end = Time.parse("12-06-2009 at 1:30 PM")
+  #    event.where = "Merry Playfields"
+  #    event.save
+  #
+  #2. Find an existing Event
+  #    event = Event.find(cal, "Soccer Game", :first)
+  #
+  #3. Find all events containing the search term
+  #    event = Event.find(cal, "Soccer Game")
+  #
+  #4. Create a recurring event for every saturday
+  #    event = Event.new(calendar)
+  #    event.title = "Baseball Game"
+  #    event.where = "Municipal Stadium"
+  #    event.recurrence = Recurrence.new
+  #    event.recurrence.start = Time.parse("13-06-2009 at 4:30 PM")
+  #    event.recurrence.end = Time.parse("13-06-2009 at 6:30 PM")
+  #    event.recurrence.frequency = {"weekly" => ["SA"]}
+  #    event.save 
+  #
+  #5. Create an event with a 15 minute email reminder
+  #    event = Event.new(calendar)
+  #    event.title = "Dinner with Kate"
+  #    event.start = Time.parse("20-06-2009 at 5 pm")
+  #    event.end = Time.parse("20-06-209 at 8 pm")
+  #    event.where = "Luigi's"
+  #    event.reminder = {:minutes => 15, :method => 'email'}
+  #    event.save
+  #
+  #6. Create an event with attendees
+  #    event = Event.new(calendar)
+  #    event.title = "Dinner with Kate"
+  #    event.start = Time.parse("20-06-2009 at 5 pm")
+  #    event.end = Time.parse("20-06-209 at 8 pm")
+  #    event.attendees => {:name => "Kate", :email => "kate@gmail.com"}
+  #    event.save
+  #
+  #After an event object has been created or loaded, you can change any of the 
+  #attributes like you would any other object.  Be sure to save the event to write changes
+  #to the Google Calendar service.
+  class Event
+    #The event title
+    attr_accessor :title
+    #The content for the event
+    attr_accessor :content
+    #The location of the event
+    attr_accessor :where
+    #A flag for whether the event show as :free or :busy
+    attr_accessor :transparency
+    #A flag indicating the status of the event.  Values can be :confirmed, :tentative or :cancelled
+    attr_accessor :status
+    #The unique event ID
+    attr_accessor :id
+    
+    @attendees
+    
+    #The event start time
+    attr_reader :start
+    #The event end time
+    attr_reader :end
+    #The reminder settings for the event, returned as a hash
+    attr_reader :reminder
+    
+    #Sets the reminder options for the event.  Parameter must be a hash containing one of 
+    #:hours, :minutes and :days, which are simply the number of each before the event start date you'd like to 
+    #receive the reminder.  
+    #
+    #:method can be one of the following:
+    #- <b>'alert'</b>: causes an alert to appear when a user is viewing the calendar in a browser
+    #- <b>'email'</b>: sends the user an email message
+    def reminder=(r)
+      @reminder = r
+    end
+    
+    #Returns the current event's Recurrence information
+    def recurrence
+      @recurrence
+    end
+    
+    #Returns an array of the current attendees
+    def attendees
+      @attendees
+    end
+    
+    #Accepts an array of email address/name pairs for attendees.  
+    #  [{:name => 'Mike Reich', :email => 'mike@seabourneconsulting.com'}]
+    #The email address is requried, but the name is optional
+    def attendees=(a)
+      if a.is_a?(Array)
+        @attendees = a
+      else
+        raise "Attendees must be an Array of email/name hash pairs"
+      end
+    end
+    
+    #Sets the event's recurrence information to a Recurrence object.  Returns the recurrence if successful,
+    #false otherwise
+    def recurrence=(r)
+      if r.is_a?(Recurrence)
+        r.event = self
+        @recurrence = r
+      else
+        return false
+      end
+    end
+    
+    #Returns a duplicate of the current event as a new Event object
+    def copy()
+      e = Event.new()
+      e.load(to_xml)
+      e.calendar = @calendar
+      return e
+    end
+    
+    #Sets the start time of the Event.  Must be a Time object or a parsable string representation
+    #of a time.
+    def start=(str)
+      if str.class == String
+        @start = Time.parse(str)      
+      elsif str.class == Time
+        @start = str
+      else
+        raise "Start Time must be either Time or String"
+      end
+    end
+    
+    #Sets the end time of the Event.  Must be a Time object or a parsable string representation
+    #of a time.
+    def end=(str)
+      if str.class == String
+        @end = Time.parse(str)      
+      elsif str.class == Time
+        @end = str
+      else
+        raise "End Time must be either Time or String"
+      end
+    end
+    
+    #Deletes the event from the Google Calendar Service.  All values are cleared.
+    def delete
+        if @exists    
+          if @calendar.service.send_delete(@edit_feed, {"If-Match" => @etag})
+            @exists = false
+            @deleted = true
+            @title = nil
+            @content = nil
+            @id = nil
+            @start = nil
+            @end = nil
+            @transparency = nil
+            @status = nil
+            @where = nil
+            return true
+          else
+            return false
+          end
+        else
+          return false
+        end
+    end
+    
+    #Creates a new Event.  Accepts a valid Calendar object.
+    def initialize(calendar)
+      super()
+      @xml = EVENT_XML
+      @calendar = calendar
+      @title = nil
+      @content = nil
+      @start = nil
+      @end = nil
+      @where = nil
+      @transparency = "http://schemas.google.com/g/2005#event.opaque"
+      @status = "http://schemas.google.com/g/2005#event.confirmed"
+      @attendees = []
+      @reminder = nil
+    end
+    
+    #If the event does not exist on the Google Calendar service, save creates it.  Otherwise
+    #updates the existing event data.  Returns true on success, false otherwise.
+    def save
+      if @deleted
+        return false
+      end
+      if @exists 
+        ret = @calendar.service.send_put(@edit_feed, to_xml, {'Content-Type' => 'application/atom+xml', "If-Match" => @etag})
+      else
+        ret = @calendar.service.send_post(@calendar.event_feed, to_xml, {'Content-Type' => 'application/atom+xml'})
+      end
+      if !@exists
+        if load(ret.read_body)
+          return true
+        else
+          raise EventSaveFailed
+        end
+      end
+      return true
+    end
+    
+    #Returns an XML representation of the event.
+    def to_xml()
+      xml = REXML::Document.new(@xml)
+      xml.root.elements.each(){}.map do |ele|
+        case ele.name
+        when 'id'
+          ele.text = @id
+        when "title"
+          ele.text = @title
+        when "content"
+          ele.text = @content
+        when "when"
+          if not @recurrence
+            ele.attributes["startTime"] = @start.xmlschema
+            ele.attributes["endTime"] = @end.xmlschema
+            set_reminder(ele)
+          else
+            if not @reminder
+              xml.root.delete_element("/entry/gd:when")
+              xml.root.add_element("gd:recurrence").text = @recurrence.to_s
+            else
+              ele.delete_attribute('startTime')
+              ele.delete_attribute('startTime')
+              set_reminder(ele)  
+            end
+          end
+        when "eventStatus"
+          ele.attributes["value"] = case @status
+            when :confirmed
+              "http://schemas.google.com/g/2005#event.confirmed"
+            when :tentative
+              "http://schemas.google.com/g/2005#event.tentative"
+            when :cancelled
+              "http://schemas.google.com/g/2005#event.canceled"
+            else
+              "http://schemas.google.com/g/2005#event.confirmed"
+          end
+        when "transparency"
+          ele.attributes["value"] = case @transparency
+              when :free
+                "http://schemas.google.com/g/2005#event.transparent"
+              when :busy
+                "http://schemas.google.com/g/2005#event.opaque"
+              else
+                "http://schemas.google.com/g/2005#event.opaque"
+            end
+        when "where"
+          ele.attributes["valueString"] = @where
+        end
+      end        
+      if not @attendees.empty?
+        @attendees.each do |a|
+          xml.root.add_element("gd:who", {"email" => a[:email], "valueString" => a[:name], "rel" => "http://schemas.google.com/g/2005#event.attendee"})
+        end
+      end
+      xml.to_s
+    end
+    
+    #Loads the event info from an XML string.
+    def load(string)
+      @xml = string
+      @exists = true
+      xml = REXML::Document.new(string)
+      @etag = xml.root.attributes['etag']
+      xml.root.elements.each(){}.map do |ele|
+          case ele.name
+             when 'id'
+                @id, @edit_feed = ele.text
+             when 'title'
+                @title = ele.text
+              when 'content'
+                @content = ele.text
+              when "when"
+                @start = Time.parse(ele.attributes['startTime'])
+                @end = Time.parse(ele.attributes['endTime'])
+                ele.elements.each("gd:reminder") do |r|
+                  @reminder = {:minutes => r.attributes['minutes'] ? r.attributes['minutes'] : 0, :hours => r.attributes['hours'] ? r.attributes['hours'] : 0, :days => r.attributes['days'] ? r.attributes['days'] : 0, :method => r.attributes['method'] ? r.attributes['method'] : ''}
+                end
+              when "where"
+                @where = ele.attributes['valueString']
+              when "link"
+                if ele.attributes['rel'] == 'edit'
+                  @edit_feed = ele.attributes['href']
+                end
+              when "who"
+                if ele.attributes['rel'] == "http://schemas.google.com/g/2005#event.attendee"
+                n = {}
+                ele.attributes.each do |name, value|
+                    case name
+                      when "email"
+                        n[:email] = value
+                      when "valueString"
+                        n[:name] = value
+                    end
+                  end                
+               @attendees << n
+               end
+              when "eventStatus"
+              case ele.attributes["value"] 
+                when "http://schemas.google.com/g/2005#event.confirmed"
+                 @status =  :confirmed
+                when "http://schemas.google.com/g/2005#event.tentative"
+                  @status = :tentative
+                when "http://schemas.google.com/g/2005#event.confirmed"
+                  @status = :cancelled
+              end
+            when "transparency"
+               case ele.attributes["value"]
+                  when "http://schemas.google.com/g/2005#event.transparent" 
+                    @transparency = :free
+                  when "http://schemas.google.com/g/2005#event.opaque"
+                    @transparency = :busy
+                end
+            end      
+        end
+    end
+    
+    #Reloads the event data from the Google Calendar Service.  Returns true if successful,
+    #false otherwise.
+    def reload
+      t = Event.find(@calendar, @id, :first)
+      if t
+        if load(t.xml)
+         return true
+        else
+         return false
+        end
+      else
+        return false
+      end
+    end
+    
+    #Finds the event that matches search_term in title or description full text search.  The scope parameter can
+    #be either :all to return an array of all matches, or :first to return the first match as an Event. 
+    def self.find(calendar, search_term, scope = :all)
+        events = calendar.service.send_get("http://www.google.com/calendar/feeds/#{calendar.id}/private/full?q="+CGI.escape(search_term))
+        ret = []
+        REXML::Document.new(events.read_body).root.elements.each("entry"){}.map do |entry|
+          entry.attributes["xmlns:gCal"] = "http://schemas.google.com/gCal/2005"
+          entry.attributes["xmlns:gd"] = "http://schemas.google.com/g/2005"
+          entry.attributes["xmlns"] = "http://www.w3.org/2005/Atom"
+          event = Event.new(calendar)
+          event.load("<?xml version='1.0' encoding='UTF-8'?>#{entry.to_s}")
+          ret << event
+      end
+      if scope == :all
+        return ret
+      elsif scope == :first
+        return ret[0]
+      end
+      return false
+    end
+    
+    #Returns true if the event exists on the Google Calendar Service.
+    def exists?
+      return @exists
+    end
+  
+    private 
+    @exists = false
+    @calendar = nil
+    @xml = nil
+    @etag = nil
+    @recurrence = nil
+    @deleted = false
+    @edit_feed = ''
+    
+    def set_reminder(ele)
+      ele.delete_element("gd:reminder")
+      if @reminder
+        e = ele.add_element("gd:reminder")
+        used = false
+        if @reminder[:minutes] 
+          e.attributes['minutes'] = @reminder[:minutes] 
+          used = true
+        elsif @reminder[:hours] and not used
+          e.attributes['hours'] = @reminder[:hours]
+          used = true
+        elsif @reminder[:days] and not used
+          e.attributes['days'] = @reminder[:days]
+        end
+        if @reminder[:method] 
+          e.attributes['method'] = @reminder[:method]
+        else
+          e.attributes['method'] = 'email'
+        end
+      else
+        ele.delete_element("gd:reminder")
+      end
+    end
+end
+
+end
+

data/lib/gcal4ruby/recurrence.rb

@@ -0,0 +1,164 @@
+class Time
+  #Returns a ISO 8601 complete formatted string of the time
+  def complete
+    self.utc.strftime("%Y%m%dT%H%M%S")
+  end
+end
+
+module GCal4Ruby
+  #The Recurrence class stores information on an Event's recurrence.  The class implements
+  #the RFC 2445 iCalendar recurrence description.
+  class Recurrence
+    #The event start date/time
+    attr_reader :start
+    #The event end date/time
+    attr_reader :end
+    #the event reference
+    attr_reader :event
+    #The date until which the event will be repeated
+    attr_reader :repeat_until
+    #The event frequency
+    attr_reader :frequency
+    #True if the event is all day (i.e. no start/end time)
+    attr_accessor :all_day
+    
+    #Returns a new Recurrence object
+    def initialize
+      @start = nil
+      @end = nil
+      @event = nil
+      @day_of_week = nil
+      @repeat_until = nil
+      @frequency = nil
+      @all_day = false
+    end
+    
+    #Returns a string with the correctly formatted ISO 8601 recurrence rule
+    def to_s
+      
+      output = ''
+      if @all_day
+        output += "DTSTART;VALUE=DATE:#{@start.utc.strftime("%Y%m%d")}\n"
+      else
+        output += "DTSTART;VALUE=DATE-TIME:#{@start.complete}\n"
+      end
+      if @all_day
+        output += "DTEND;VALUE=DATE:#{@end.utc.strftime("%Y%m%d")}\n"
+      else
+        output += "DTEND;VALUE=DATE-TIME:#{@end.complete}\n"
+      end
+      output += "RRULE:"
+      if @frequency
+        f = 'FREQ='
+        i = ''
+        by = ''
+        @frequency.each do |key, v|
+          if v.is_a?(Array) 
+            if v.size > 0
+              value = v.join(",") 
+            else
+              value = nil
+            end
+          else
+            value = v
+          end
+          f += "#{key.upcase};" if key != 'interval'
+          case key.downcase
+            when "secondly"
+              by += "BYSECOND=#{value};"
+            when "minutely"
+              by += "BYMINUTE=#{value};"
+            when "hourly"
+              by += "BYHOUR=#{value};"
+            when "weekly"
+              by += "BYDAY=#{value};" if value
+            when "monthly"
+              by += "BYDAY=#{value};"
+            when "yearly"
+              by += "BYYEARDAY=#{value}"
+            when 'interval'
+              i += "INTERVAL=#{value};"
+          end
+        end
+        output += f+i+by
+      end      
+      if @repeat_until
+        output += ";UNTIL=#{@repeat_until.strftime("%Y%m%d")}"
+      end
+      
+      output += "\n"
+    end
+    
+    #Sets the start date/time.  Must be a Time object.
+    def start=(s)
+      if not s.is_a?(Time)
+        raise RecurrenceValueError, "Start must be a date or a time"
+      else
+        @start = s
+      end
+    end
+    
+    #Sets the end Date/Time. Must be a Time object.
+    def end=(e)
+      if not e.is_a?(Time)
+        raise RecurrenceValueError, "End must be a date or a time"
+      else
+        @end = e
+      end
+    end
+    
+    #Sets the parent event reference
+    def event=(e)
+      if not e.is_a?(Event)
+        raise RecurrenceValueError, "Event must be an event"
+      else
+        @event = e
+      end
+    end
+    
+    #Sets the end date for the recurrence
+    def repeat_until=(r)
+      if not  r.is_a?(Date)
+        raise RecurrenceValueError, "Repeat_until must be a date"
+      else
+        @repeat_until = r
+      end
+    end
+    
+    #Sets the frequency of the recurrence.  Should be a hash with one of 
+    #"SECONDLY", "MINUTELY", "HOURLY", "DAILY", "WEEKLY", "MONTHLY", "YEARLY" as the key,
+    #and as the value, an array containing zero to n of the following:
+    #- *Secondly*: A value between 0 and 59.  Causes the event to repeat on that second of each minut.
+    #- *Minutely*: A value between 0 and 59.  Causes the event to repeat on that minute of every hour.
+    #- *Hourly*: A value between 0 and 23.  Causes the even to repeat on that hour of every day.
+    #- *Daily*: No value needed - will cause the event to repeat every day until the repeat_until date.
+    #- *Weekly*: A value of the first two letters of a day of the week.  Causes the event to repeat on that day.
+    #- *Monthly*: A value of a positive or negative integer (i.e. +1) prepended to a day-of-week string ('TU') to indicate the position of the day within the month.  E.g. +1TU would be the first tuesday of the month.
+    #- *Yearly*: A value of 1 to 366 indicating the day of the year.  May be negative to indicate counting down from the last day of the year.
+    #
+    #Optionally, you may specific a second hash pair to set the internal the even repeats:
+    #   "interval" => '2'
+    #If the interval is missing, it is assumed to be 1.
+    #
+    #===Examples
+    #Repeat event every Tuesday:
+    #   frequency = {"Weekly" => ["TU"]}
+    #
+    #Repeat every first and third Monday of the month
+    #   frequency = {"Monthly" => ["+1MO", "+3MO"]}
+    #
+    #Repeat on the last day of every year
+    #   frequency = {"Yearly" => [366]}
+    #
+    #Repeat every other week on Friday
+    #   frequency = {"Weekly" => ["FR"], "interval" => "2"}
+    
+    def frequency=(f)
+      if f.is_a?(Hash)
+        @frequency = f
+      else
+        raise RecurrenceValueError, "Frequency must be a hash (see documentation)"
+      end
+    end
+  end
+end

data/lib/gcal4ruby/service.rb

@@ -0,0 +1,61 @@
+require 'gcal4ruby/base' 
+require 'gcal4ruby/calendar'
+
+module GCal4Ruby
+
+#The service class is the main handler for all direct interactions with the 
+#Google Calendar API.  A service represents a single user account.  Each user
+#account can have multiple calendars, so you'll need to find the calendar you
+#want from the service, using the Calendar#find class method.
+#=Usage
+#
+#1. Authenticate
+#    service = Service.new
+#    service.authenticate("user@gmail.com", "password")
+#
+#2. Get Calendar List
+#    calendars = service.calendars
+#
+
+class Service < Base
+  #Convenience attribute contains the currently authenticated account name
+  attr_reader :account
+      
+  # The token returned by the Google servers, used to authorize all subsequent messages
+  attr_reader :auth_token
+
+  # The authenticate method passes the username and password to google servers.  
+  # If authentication succeeds, returns true, otherwise raises the AuthenticationFailed error.
+  def authenticate(username, password)
+    ret = nil
+    ret = send_post(AUTH_URL, "Email=#{username}&Passwd=#{password}&source=GCal4Ruby&service=cl")
+    if ret.class == Net::HTTPOK
+      @auth_token = ret.read_body.to_a[2].gsub("Auth=", "").strip
+      @account = username
+      return true
+    else
+      raise AuthenticationFailed
+    end
+  end
+
+  #Returns an array of Calendar objects for each calendar associated with 
+  #the authenticated account.
+  def calendars
+    if not @auth_token
+       raise NotAuthenticated
+    end
+    ret = send_get(CALENDAR_LIST_FEED)
+    cals = []
+    REXML::Document.new(ret.body).root.elements.each("entry"){}.map do |entry|
+      entry.attributes["xmlns:gCal"] = "http://schemas.google.com/gCal/2005"
+      entry.attributes["xmlns:gd"] = "http://schemas.google.com/g/2005"
+      entry.attributes["xmlns"] = "http://www.w3.org/2005/Atom"
+      cal = Calendar.new(self)
+      cal.load("<?xml version='1.0' encoding='UTF-8'?>#{entry.to_s}")
+      cals << cal
+    end
+    return cals
+  end
+end
+
+end

data/lib/gcal4ruby.rb

@@ -0,0 +1 @@
+require "gcal4ruby/service"