ri_cal 0.5.0

data/docs/incrementers.txt

@@ -0,0 +1,7 @@
+Seconds - Freq="SECONDLY", BYSECOND
+Minutes - Freq="MINUTELY", BYMINUTE
+Hours -   Freq="HOURLY",   BYHOUR
+Days -    Freq="DAILY",    BYDAY, BYMONTHDAY, BYYEARDAY
+Weeks -   Freq="WEEKLY",   BYWEEKNO
+Months -  Freq="MONTHLY",  BYMONTH
+Years -   Freq="YEARLY"

data/lib/ri_cal.rb

@@ -0,0 +1,144 @@
+#- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+#
+# The RiCal module provides the outermost namespace, along with several convenience methods for parsing
+# and building calendars and calendar components.
+module RiCal
+  
+  my_dir =  File.dirname(__FILE__)
+  
+  autoload :Component, "#{my_dir}/ri_cal/component.rb"
+  autoload :TimezonePeriod, "#{my_dir}/ri_cal/properties/timezone_period.rb"
+  autoload :OccurrenceEnumerator, "#{my_dir}/ri_cal/occurrence_enumerator.rb"
+  
+  # :stopdoc:
+  VERSION = '0.5.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(::File.join(::File.dirname(fname), dir, '**', '*.rb'))
+    Dir.glob(search_me).sort.each {|rb|
+      require rb}
+  end
+  
+  # :startdoc:
+  
+  # Parse an io stream and return an array of iCalendar entities.
+  # Normally this will be an array of RiCal::Component::Calendar instances
+  def self.parse(io)
+    Parser.new(io).parse
+  end
+  
+  # Parse a string and return an array of iCalendar entities.
+  # see RiCal.parse
+  def self.parse_string(string)
+    parse(StringIO.new(string))
+  end
+  
+  def self.debug # :nodoc:
+    @debug
+  end
+  
+  def self.debug=(val) # :nodoc:
+    @debug = val
+  end
+ 
+  # return a new Alarm event or todo component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties of the 
+  # new Alarm.  
+  def self.Alarm(&init_block)
+    Component::Alarm.new(&init_block)
+  end
+  
+  # return a new Calendar.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and components of the 
+  # new calendar.  
+  def self.Calendar(&init_block)
+    Component::Calendar.new(&init_block)
+  end
+
+  # return a new Event calendar component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and alarms of the 
+  # new Event.  
+  def self.Event(&init_block)
+    Component::Event.new(&init_block)
+  end
+
+  # return a new Freebusy calendar component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and components of the 
+  # new Freebusy.  
+  def self.Freebusy(&init_block)
+    Component::Freebusy.new(&init_block)
+  end
+
+  # return a new Journal calendar component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and components of the 
+  # new Event.  
+  def self.Journal(&init_block)
+    Component::Journal.new(&init_block)
+  end
+
+  # return a new Timezone calendar component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and timezone periods of the 
+  # new Timezone.  
+  def self.Timezone(&init_block)
+    Component::Timezone.new(&init_block)
+  end
+
+  # return a new TimezonePeriod timezone component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties of the 
+  # new TimezonePeriod.  
+  def self.TimezonePeriod(&init_block)
+    Component::TimezonePeriod.new(&init_block)
+  end
+
+  if Object.const_defined?(:ActiveSupport)
+    as = Object.const_get(:ActiveSupport)
+    if as.const_defined?(:TimeWithZone)
+      time_with_zone = as.const_get(:TimeWithZone)
+    end
+  end
+  
+  # TimeWithZone will be set to ActiveSupport::TimeWithZone if the activesupport gem is loaded
+  # otherwise it will be nil
+  TimeWithZone = time_with_zone
+
+  # return a new Todo calendar component.  If a block is provided it will will be executed in
+  # the context of a builder object which can be used to initialize the properties and alarms of the 
+  # new Todo.  
+  def self.Todo(&init_block)
+    Component::Todo.new(&init_block)
+  end
+end  # module RiCal
+
+RiCal.require_all_libs_relative_to(__FILE__)
+
+# EOF

data/lib/ri_cal/component.rb

@@ -0,0 +1,247 @@
+module RiCal
+  #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+  #
+  class Component #:nodoc:
+    class ComponentBuilder #:nodoc:
+      def initialize(component)
+        @component = component
+      end
+
+      def method_missing(selector, *args, &init_block) #:nodoc:
+        if(sub_comp_class = @component.subcomponent_class[selector])
+          if init_block
+            sub_comp = sub_comp_class.new(@component)
+            if init_block.arity == 1
+              yield ComponentBuilder.new(sub_comp)
+            else
+              ComponentBuilder.new(sub_comp).instance_eval(&init_block)
+            end
+            self.add_subcomponent(sub_comp)
+          end
+        else
+          sel = selector.to_s
+          sel = "#{sel}=" unless /(^(add_)|(remove_))|(=$)/ =~ sel
+          if @component.respond_to?(sel)
+            @component.send(sel, *args)
+          else
+            super
+          end
+        end
+      end
+    end
+
+    autoload :Timezone, "#{File.dirname(__FILE__)}/component/timezone.rb"
+
+    attr_accessor :imported #:nodoc:
+
+    def initialize(parent=nil, &init_block) #:nodoc:
+      @parent = parent
+      if block_given?
+        if init_block.arity == 1
+          init_block.call(ComponentBuilder.new(self))
+        else
+          ComponentBuilder.new(self).instance_eval(&init_block)
+        end
+      end
+    end
+
+    def default_tzid #:nodoc:
+      if @parent
+        @parent.default_tzid
+      else
+        PropertyValue::DateTime.default_tzid
+      end
+    end
+
+    def find_timezone(identifier) #:nodoc:
+      if @parent
+        @parent.find_timezone(identifier)
+      else
+        begin
+          Calendar::TZInfoWrapper.new(TZInfo::Timezone.get(identifier), self)
+        rescue ::TZInfo::InvalidTimezoneIdentifier => ex
+          raise RiCal::InvalidTimezoneIdentifier.invalid_tzinfo_identifier(identifier)
+        end
+      end
+    end
+
+    def tz_info_source?
+      if @parent
+        @parent.tz_info_source?
+      else
+        true
+      end
+    end
+
+    def time_zone_for(ruby_object) #:nodoc:
+      @parent.time_zone_for(ruby_object) #:nodoc:
+    end
+
+    def subcomponent_class #:nodoc:
+      {}
+    end
+
+    def self.from_parser(parser, parent) #:nodoc:
+      entity = self.new(parent)
+      entity.imported = true
+      line = parser.next_separated_line
+      while parser.still_in(entity_name, line)
+        entity.process_line(parser, line)
+        line = parser.next_separated_line
+      end
+      entity
+    end
+
+    def self.parse(io) #:nodoc:
+      Parser.new(io).parse
+    end
+
+    def imported? #:nodoc:
+      imported
+    end
+
+    def self.parse_string(string) #:nodoc:
+      parse(StringIO.new(string))
+    end
+
+    def subcomponents #:nodoc:
+      @subcomponents ||= Hash.new {|h, k| h[k] = []}
+    end
+
+    def entity_name #:nodoc:
+      self.class.entity_name
+    end
+
+    # return an array of Alarm components within this component :nodoc:
+    # Alarms may be contained within Events, and Todos
+    def alarms
+      subcomponents["VALARM"]
+    end
+
+    def add_subcomponent(component) #:nodoc:
+      subcomponents[component.entity_name] << component
+    end
+
+    def parse_subcomponent(parser, line) #:nodoc:
+      subcomponents[line[:value]] << parser.parse_one(line, self)
+    end
+
+    def process_line(parser, line) #:nodoc:
+      if line[:name] == "BEGIN"
+        parse_subcomponent(parser, line)
+      else
+        setter = self.class.property_parser[line[:name]]
+        if setter
+          send(setter, line)
+        else
+          self.add_x_property(line[:name], PropertyValue::Text.new(self, line))
+        end
+      end
+    end
+
+    # return a hash of any extended properties, (i.e. those with a property name starting with "X-"
+    # representing an extension to the RFC 2445 specification)
+    def x_properties
+      @x_properties ||= {}
+    end
+
+    # Add a n extended property
+    def add_x_property(name, prop)
+      x_properties[name] = prop
+    end
+
+    def method_missing(selector, *args, &b) #:nodoc:
+      xprop_candidate = selector.to_s
+      if (match = /^x_(.+)(=?)$/.match(xprop_candidate))
+        if match[2] == "="
+          add_x_property("x_#{match[1]}", *args)
+        else
+          x_properties[xprop_candidate]
+        end
+      else
+        super
+      end
+    end
+
+    # Predicate to determine if the component is valid according to RFC 2445
+    def valid?
+      !mutual_exclusion_violation
+    end
+
+    def initialize_copy(original) #:nodoc:
+    end
+
+    def prop_string(prop_name, *properties) #:nodoc:
+      properties = properties.flatten.compact
+      if properties && !properties.empty?
+        properties.map {|prop| "#{prop_name}#{prop.to_s}"}.join("\n")
+      else
+        nil
+      end
+    end
+
+    def add_property_date_times_to(required_timezones, property) #:nodoc:
+      if property
+        if Array === property
+          property.each do |prop|
+            prop.add_date_times_to(required_timezones)
+          end
+        else
+          property.add_date_times_to(required_timezones)
+        end
+      end
+    end
+
+    def export_prop_to(export_stream, name, prop) #:nodoc:
+      if prop
+        string = prop_string(name, prop)
+        export_stream.puts(string) if string
+      end
+    end
+
+    def export_x_properties_to(export_stream) #:nodoc:
+      x_properties.each do |name, prop|
+        export_stream.puts("#{name}:#{prop}")
+      end
+    end
+
+    def export_subcomponent_to(export_stream, subcomponent) #:nodoc:
+      subcomponent.each do |component|
+        component.export_to(export_stream)
+      end
+    end
+
+    # return a string containing the rfc2445 format of the component
+    def to_s
+      io = StringIO.new
+      export_to(io)
+      io.string
+    end
+
+    # Export this component to an export stream
+    def export_to(export_stream)
+      export_stream.puts("BEGIN:#{entity_name}")
+      export_properties_to(export_stream)
+      export_x_properties_to(export_stream)
+      subcomponents.values do |sub|
+        export_subcomponent_to(export_subcomponent_to, sub)
+      end
+      export_stream.puts("END:#{entity_name}")
+    end
+
+    # Export this single component as an iCalendar component containing only this component and
+    # any required additional components (i.e. VTIMEZONES referenced from this component)
+    # if stream is nil (the default) then this method will return a string,
+    # otherwise stream should be an IO to which the iCalendar file contents will be written
+    def export(stream=nil)
+      wrapper_calendar = Calendar.new
+      wrapper_calendar.add_subcomponent(self)
+      wrapper_calendar.export(stream)
+    end
+  end
+end
+
+Dir[File.dirname(__FILE__) + "/component/*.rb"].sort.each do |path|
+  filename = File.basename(path)
+  require path
+end

data/lib/ri_cal/component/alarm.rb

@@ -0,0 +1,21 @@
+require File.join(File.dirname(__FILE__), %w[.. properties alarm.rb])
+
+module RiCal
+
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # An Alarm component groups properties defining a reminder or alarm associated with an event or to-do
+    # TODO: The Alarm component has complex cardinality restrictions depending on the value of the action property
+    # i.e. audio, display, email, and proc alarms, this is currently not checked or enforced
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Alarm module
+    class Alarm < Component
+      include RiCal::Properties::Alarm
+
+      def self.entity_name #:nodoc:
+        "VALARM"
+      end
+    end
+  end
+end

data/lib/ri_cal/component/calendar.rb

@@ -0,0 +1,219 @@
+require File.join(File.dirname(__FILE__), %w[.. properties calendar.rb])
+
+module RiCal
+  class Component
+    #- ©2009 Rick DeNatale, All rights reserved. Refer to the file README.txt for the license
+    #
+    # to see the property accessing methods for this class see the RiCal::Properties::Calendar module
+    class Calendar < Component
+      include RiCal::Properties::Calendar
+      attr_reader :tz_source #:nodoc:
+
+      def initialize(parent=nil, &init_block) #:nodoc:
+        @tz_source = 'TZINFO' # Until otherwise told
+        super
+      end
+
+      def self.entity_name #:nodoc:
+        "VCALENDAR"
+      end
+
+      def tz_info_source? #:nodoc:
+        @tz_source == 'TZINFO'
+      end
+
+      def required_timezones # :nodoc:
+        @required_timezones ||=  RequiredTimezones.new
+      end
+
+      def subcomponent_class # :nodoc:
+        {
+          :event => Event,
+          :todo  => Todo,
+          :journal => Journal,
+          :freebusy => Freebusy,
+          :timezone => Timezone,
+        }
+      end
+
+      def export_properties_to(export_stream) # :nodoc:
+        prodid_property.params["X-RICAL-TZSOURCE"] = @tz_source
+        export_prop_to(export_stream, "PRODID", prodid_property)
+        export_prop_to(export_stream, "CALSCALE", calscale_property)
+        export_prop_to(export_stream, "VERSION", version_property)
+        export_prop_to(export_stream, "METHOD", method_property)
+      end
+
+      def prodid_property_from_string(line) # :nodoc:
+        result = super
+        @tz_source = prodid_property.params["X-RICAL-TZSOURCE"]
+        result
+      end
+
+      # Return the default time zone identifier for this calendar
+      def default_tzid
+        @default_tzid || PropertyValue::DateTime.default_tzid
+      end
+
+      # Set the default time zone identifier for this calendar
+      # To set the default to floating times use a value of :floating
+      def default_tzid=(value)
+        @default_tzid=value
+      end
+
+      # return an array of event components contained within this Calendar
+      def events
+        subcomponents["VEVENT"]
+      end
+
+      # add an event to the calendar
+      def add_subcomponent(component)
+        super(component)
+        component.add_date_times_to(required_timezones) if tz_info_source?
+      end
+
+      # return an array of todo components contained within this Calendar
+      def todos
+        subcomponents["VTODO"]
+      end
+
+      # return an array of journal components contained within this Calendar
+      def journals
+        subcomponents["VJOURNAL"]
+      end
+
+      # return an array of freebusy components contained within this Calendar
+      def freebusys
+        subcomponents["VFREEBUSY"]
+      end
+
+      class TimezoneID #:nodoc:
+        attr_reader :identifier, :calendar
+        def initialize(identifier, calendar)
+          self.identifier, self.calendar = identifier, calendar
+        end
+
+        def tzinfo_timezone
+          nil
+        end
+
+        def resolved
+          calendar.find_timezone(identifier)
+        end
+
+        def local_to_utc(local)
+          resolved.local_to_utc(date_time_prop)
+        end
+      end
+
+      # return an array of timezone components contained within this calendar
+      def timezones
+        subcomponents["VTIMEZONE"]
+      end
+
+      class TZInfoWrapper #:nodoc:
+        attr_reader :tzinfo, :calendar #:nodoc:
+        def initialize(tzinfo, calendar) #:nodoc:
+          @tzinfo = tzinfo
+          @calendar = calendar
+        end
+
+        def identifier #:nodoc:
+          tzinfo.identifier
+        end
+
+        def local_date_time(ruby_time, tzid) #:nodoc:
+          RiCal::PropertyValue::DateTime.new(calendar, :value => ruby_time.strftime("%Y%m%dT%H%M%S"), :params => {'TZID' => tzid})
+        end
+
+        def utc_date_time(ruby_time) #:nodoc
+            RiCal::PropertyValue::DateTime.new(calendar, :value => ruby_time.strftime("%Y%m%dT%H%M%SZ"))
+        end
+
+        def local_to_utc(utc) #:nodoc:
+          utc_date_time(tzinfo.local_to_utc(utc.to_ri_cal_ruby_value))
+        end
+
+        def utc_to_local(local) #:nodoc:
+          local_date_time(tzinfo.utc_to_local(local.to_ri_cal_ruby_value), tzinfo.identifier)
+        end
+
+
+        def rational_utc_offset(local)
+          Rational(tzinfo.period_for_local(local, true).utc_total_offset, 3600) / 24
+        end
+
+      end
+
+      def find_timezone(identifier)  #:nodoc:
+        if tz_info_source?
+          begin
+            TZInfoWrapper.new(TZInfo::Timezone.get(identifier), self)
+          rescue ::TZInfo::InvalidTimezoneIdentifier => ex
+            raise RiCal::InvalidTimezoneIdentifier.invalid_tzinfo_identifier(identifier)
+          end
+        else
+          result = timezones.find {|tz| tz.tzid == identifier}
+          raise RiCal::InvalidTimezoneIdentifier.not_found_in_calendar(identifier) unless result
+          result
+        end
+      end
+
+      def export_required_timezones(export_stream) # :nodoc:
+        required_timezones.export_to(export_stream)
+      end
+
+      class FoldingStream #:nodoc:
+        attr_reader :stream #:nodoc:
+        def initialize(stream) #:nodoc:
+          @stream = stream || StringIO.new
+        end
+
+        def string #:nodoc:
+          stream.string
+        end
+
+        def fold(string) #:nodoc:
+          stream.puts(string[0,73])
+          string = string[73..-1]
+          while string
+            stream.puts " #{string[0, 72]}"
+            string = string[72..-1]
+          end
+        end
+
+        def puts(*strings) #:nodoc:
+          strings.each do |string|
+            string.split("\n").each do |line|
+              fold(line)
+            end
+          end
+        end
+      end
+
+      # Export this calendar as an iCalendar file.
+      # if to is nil (the default) then this method will return a string,
+      # otherwise to should be an IO to which the iCalendar file contents will be written
+      def export(to=nil)
+        export_stream = FoldingStream.new(to)
+        export_stream.puts("BEGIN:VCALENDAR")
+        #TODO: right now I'm assuming that all timezones are internal what happens when we export
+        #      an imported calendar.
+        export_properties_to(export_stream)
+        export_x_properties_to(export_stream)
+        export_required_timezones(export_stream)
+        export_subcomponent_to(export_stream, events)
+        export_subcomponent_to(export_stream, todos)
+        export_subcomponent_to(export_stream, journals)
+        export_subcomponent_to(export_stream, freebusys)
+        export_stream.puts("END:VCALENDAR")
+        if to
+          nil
+        else
+          export_stream.string
+        end
+      end
+
+    end
+  end
+end