icalendar2 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+0.1.0
+* Initial commit

data/README.md

@@ -0,0 +1,89 @@
+# icalendar2 - generate, consume and validate iCalendar feeds
+
+## Warning
+
+This is NOT production ready yet. It has not been extensively tested, and you
+use it at your own risk.
+
+## Installation
+
+If you want to jump right in and try it out, here's how you install it:
+
+``` bash
+gem install icalendar2
+```
+
+Website: https://github.com/ericcf/icalendar2
+
+## Introduction
+
+icalendar2 is a Ruby library for parsing, manipulating and generating iCalendar
+objects as described in RFC 5545. Its API is intended to be mostly compatible
+with that of the icalendar gem (https://github.com/sdague/icalendar), at least
+initially.
+
+For example:
+
+``` ruby
+require 'rubygems'
+require 'icalendar2'
+include Icalendar2
+
+calendar = Calendar.new
+calendar.event do
+  dtstart     Date.new(2012, 12, 25)
+  dtend       Date.new(2012, 1, 5)
+  summary     "12 days of Christmas."
+  description "Eat lots of cookies."
+end
+calendar.valid? # true
+puts calendar.to_ical
+# BEGIN:VCALENDAR
+# BEGIN:VEVENT
+# UID:2012-12-12T10:12:45-06:00_253060006@example.com
+# DTSTAMP:20121212T101245
+# DTSTART:20121225
+# DTEND:20120105
+# SUMMARY:12 days of Christmas.
+# DESCRIPTION:Eat lots of cookies.
+# END:VEVENT
+# END:VCALENDAR
+
+calendars = Parser.new(calendar.to_ical).parse
+calendars.size # 1
+calendars.first.valid? # true
+```
+
+## Improvements over/differences with icalendar gem
+
+While this gem is based on (and borrows some code from) the icalendar gem, it
+also improves on it in several key areas:
+* No monkey patching of core Ruby classes such as String for conversions
+* Better separation of concerns makes it easier to test and extend
+* Validates calendars and pinpoints errors
+* Uses RSpec for tests
+
+## Testing
+
+To run the icalendar2 tests ensure that the rspec gem is installed, and run:
+
+``` bash
+rake test
+```
+
+## Building the gem
+
+``` bash
+gem build icalendar2.gemspec
+```
+
+## Contributions
+
+I need your help to make this library better. Please use the GitHub issue
+tracker for feature requests and bug reports. The more detail you can provide
+the better.
+
+## License
+
+As this is based on the icalendar gem, which employs the Ruby licence, this too
+falls under that license: http://www.ruby-lang.org/en/about/license.txt

data/lib/icalendar2/calendar.rb

@@ -0,0 +1,85 @@
+module Icalendar2
+  # See http://tools.ietf.org/html/rfc5545#section-3.4
+  class Calendar
+    VALUE = "VCALENDAR"
+
+    def initialize
+      @components = {
+        Event::VALUE => []
+      }
+      @properties = {
+        :calscale => Property::Nil.new,
+        :method =>   Property::Nil.new,
+        :prodid =>   Property::Nil.new,
+        :version =>  Property::Nil.new
+      }
+    end
+
+    def calscale(value = nil)
+      set_property(:calscale, value)
+    end
+
+    def method_property(value = nil)
+      set_property(:method, value)
+    end
+
+    def prodid(value = nil)
+      set_property(:prodid, value)
+    end
+
+    def version(value = nil)
+      set_property(:version, value)
+    end
+
+    def set_property(property_name, value, parameters = {})
+      property = property_name.downcase.to_sym
+      if value.nil?
+        @properties[property].value.to_s
+      elsif (factory = CalendarProperty.get_factory(property_name))
+        if value.is_a? factory
+          @properties[property] = value
+        else
+          @properties[property] = factory.new(value)
+        end
+      end
+    end
+
+    def events
+      @components[Event::VALUE]
+    end
+
+    def event(&block)
+      e = Event.new
+      e.instance_eval(&block)
+      events << e
+
+      e
+    end
+
+    def add_event(event)
+      events << event
+    end
+
+    def to_ical
+      str = "#{Tokens::COMPONENT_BEGIN}:#{VALUE}#{Tokens::CRLF}"
+      str << body_to_ical
+      str << "#{Tokens::COMPONENT_END}:#{VALUE}#{Tokens::CRLF}"
+      str.encode("UTF-8")
+    end
+
+    def add_component(component)
+      @components[component.class::VALUE] << component
+    end
+
+    def valid?
+      events.all?(&:valid?)
+    end
+
+    private
+
+    def body_to_ical
+      str = @properties.values.map(&:to_ical).join
+      str << events.map(&:to_ical).join
+    end
+  end
+end

data/lib/icalendar2/calendar_property/calscale.rb

@@ -0,0 +1,9 @@
+module Icalendar2
+  module CalendarProperty
+    # See http://tools.ietf.org/html/rfc5545#section-3.7.1
+    class Calscale < Property::Base
+      name "CALSCALE"
+      value :types => [:text]
+    end
+  end
+end

data/lib/icalendar2/calendar_property/method.rb

@@ -0,0 +1,9 @@
+module Icalendar2
+  module CalendarProperty
+    # See http://tools.ietf.org/html/rfc5545#section-3.7.2
+    class Method < Property::Base
+      name "METHOD"
+      value :types => [:text]
+    end
+  end
+end

data/lib/icalendar2/calendar_property/prodid.rb

@@ -0,0 +1,9 @@
+module Icalendar2
+  module CalendarProperty
+    # See http://tools.ietf.org/html/rfc5545#section-3.7.3
+    class Prodid < Property::Base
+      name "PRODID"
+      value :types => [:text]
+    end
+  end
+end

data/lib/icalendar2/calendar_property/version.rb

@@ -0,0 +1,9 @@
+module Icalendar2
+  module CalendarProperty
+    # See http://tools.ietf.org/html/rfc5545#section-3.7.4
+    class Version < Property::Base
+      name "VERSION"
+      value :types => [:text]
+    end
+  end
+end

data/lib/icalendar2/calendar_property.rb

@@ -0,0 +1,12 @@
+module Icalendar2
+  module CalendarProperty
+    def self.get_factory(calendar_property_name)
+      # "VERSION" => CalendarProperty::Version, etc.
+      begin
+        const_get(calendar_property_name.capitalize, false)
+      rescue NameError
+        nil
+      end
+    end
+  end
+end

data/lib/icalendar2/component/base.rb

@@ -0,0 +1,90 @@
+module Icalendar2
+  module Component
+    require 'socket'
+
+    class Base
+
+      class << self; attr_reader :property_names end
+      class << self; attr_reader :required_property_names end
+
+      def self.requires(properties = {})
+        add_properties(properties)
+        @required_property_names = properties.values.flatten
+      end
+
+      def self.accepts(properties = {})
+        add_properties(properties)
+      end
+
+      def initialize
+        @properties = {}
+      end
+
+      def new_uid
+        "#{DateTime.now}_#{rand(999999999)}@#{Socket.gethostname}"
+      end
+
+      def new_timestamp
+        DateTime.now
+      end
+
+      def valid?
+        present_property_names = @properties.keys
+        @properties.values.flatten.all?(&:valid?) &&
+          self.class.required_property_names.all? { |p| present_property_names.include?(p) }
+      end
+
+      def set_property(property_name, value, parameters = {})
+        name = (property_name == "class" ? "klass" : property_name)
+        unless self.class.property_names.include? name.to_sym
+          raise "#{self.class} component property #{name} not defined"
+        end
+        self.send(name, value, parameters)
+      end
+
+      private
+
+      def self.add_properties(properties)
+        single_properties = properties[:exactly_one] || []
+        single_properties.each do |property_sym|
+          define_accessor(property_sym)
+        end
+        multiple_properties = properties[:one_or_more] || []
+        multiple_properties.each do |property_sym|
+          define_multiple_accessor(property_sym)
+        end
+        @property_names ||= []
+        @property_names += single_properties + multiple_properties
+      end
+
+      def self.define_accessor(property_sym)
+        define_method(property_sym) do |*args|
+          value, parameters = *args
+          if value.nil?
+            @properties[property_sym]
+          else
+            @properties[property_sym] = Property.get_factory(property_sym).new(value, parameters)
+          end
+        end
+        alias_method "#{property_sym}=", property_sym
+      end
+
+      def self.define_multiple_accessor(property_sym)
+        property_factory = Property.get_factory(property_sym)
+        define_method(property_factory::PLURAL) do
+          @properties[property_sym]
+        end
+        define_method(property_sym) do |*args|
+          value, parameters = *args
+          @properties[property_sym] ||= []
+          @properties[property_sym] << property_factory.new(value, parameters)
+        end
+        alias_method "#{property_sym}=", property_sym
+      end
+
+      def properties_to_ical
+        @properties.values.flatten.map(&:to_ical).join
+      end
+    end
+  end
+end

data/lib/icalendar2/component/event.rb

@@ -0,0 +1,32 @@
+module Icalendar2
+  # See http://tools.ietf.org/html/rfc5545#section-3.6.1
+  class Event < Component::Base
+    VALUE = "VEVENT"
+
+    requires :exactly_one => [:dtstamp, :uid]
+    accepts :exactly_one => [:dtstart, :klass, :created, :description, :geo,
+      :last_mod, :location, :organizer, :priority, :sequence, :status, :summary,
+      :transp, :url, :recurid, :dtend, :duration],
+      :one_or_more => [:rrule, :attach, :attendee, :categories, :comment,
+      :contact, :exdate, :rstatus, :related_to, :resources, :rdate]
+
+    def initialize
+      super
+      self.uid = new_uid
+      self.dtstamp = new_timestamp
+    end
+
+    def to_ical
+      str = "#{Tokens::COMPONENT_BEGIN}:#{VALUE}#{Tokens::CRLF}"
+      str << properties_to_ical
+      #str << alarm_to_ical
+      str << "#{Tokens::COMPONENT_END}:#{VALUE}#{Tokens::CRLF}"
+    end
+
+    private
+
+    def alarm_to_ical
+      #alarm.print if alarm
+    end
+  end
+end

data/lib/icalendar2/component.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Component
+    def self.get_factory(component_name)
+      # "VFOO" => "Foo", etc.
+      Icalendar2.const_get(component_name.gsub(/^V/, "").capitalize, false)
+    end
+  end
+end

data/lib/icalendar2/parameter/altrep.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.1
+    class Altrep < Base
+      format /^ALTREP="#{Tokens::URI}"$/
+    end
+  end
+end

data/lib/icalendar2/parameter/base.rb

@@ -0,0 +1,34 @@
+module Icalendar2
+  module Parameter
+    class Base
+
+      class << self; attr_reader :format_matcher end
+
+      def self.format(matcher)
+        @format_matcher = matcher
+      end
+
+      def initialize(value)
+        @valid = true
+        @value = value
+        validate
+      end
+
+      def valid?
+        @valid
+      end
+
+      private
+
+      def validate
+        unless self.class.format_matcher.nil?
+          if @value.respond_to?(:to_s) && (val = @value.to_s).respond_to?(:match)
+            @valid = !!val.match(self.class.format_matcher)
+          else
+            @valid = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/icalendar2/parameter/cn.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.2
+    class Cn < Base
+      format /^CN=#{Tokens::PARAM_VALUE}$/
+    end
+  end
+end

data/lib/icalendar2/parameter/cutype.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.3
+    class Cutype < Base
+      format /^CUTYPE=(?:INDIVIDUAL|GROUP|RESOURCE|ROOM|UNKNOWN|(?:#{Tokens::X_NAME})|(?:#{Tokens::IANA_TOKEN}))$/
+    end
+  end
+end

data/lib/icalendar2/parameter/delegated_from.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.4
+    class DelegatedFrom < Base
+      format /^DELEGATED-FROM="#{Tokens::URI}"(?:,"#{Tokens::URI}")*$/
+    end
+  end
+end

data/lib/icalendar2/parameter/delegated_to.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.5
+    class DelegatedTo < Base
+      format /^DELEGATED-TO="#{Tokens::URI}"(?:,"#{Tokens::URI}")*$/
+    end
+  end
+end

data/lib/icalendar2/parameter/dir.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.6
+    class Dir < Base
+      format /^DIR="#{Tokens::URI}"$/
+    end
+  end
+end

data/lib/icalendar2/parameter/encoding.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.7
+    class Encoding < Base
+      format /^ENCODING=(?:8BIT|BASE64)$/
+    end
+  end
+end

data/lib/icalendar2/parameter/fmttype.rb

@@ -0,0 +1,10 @@
+module Icalendar2
+  module Parameter
+    # See http://tools.ietf.org/html/rfc5545#section-3.2.8
+    class Fmttype < Base
+      TYPE_NAME = "(?:#{Tokens::ALPHA}|#{Tokens::DIGIT}|[-!#$&.+^_])+"
+      SUBTYPE_NAME = TYPE_NAME
+      format /^FMTTYPE=#{TYPE_NAME}\/#{SUBTYPE_NAME}$/
+    end
+  end
+end

data/lib/icalendar2/parameter.rb

@@ -0,0 +1,4 @@
+module Icalendar2
+  module Parameter
+  end
+end

data/lib/icalendar2/parser.rb

@@ -0,0 +1,136 @@
+module Icalendar2
+  require 'stringio'
+
+  class Parser
+
+    def initialize(source)
+      if source.respond_to?(:gets)
+        @file = source
+      elsif !source.nil? && source.respond_to?(:to_s)
+        @file = StringIO.new(source.to_s, 'r')
+      else
+        raise ArgumentError, "#{self.class}.new must be called with an IO-like object or a path"
+      end
+
+      @previous_line = next_line_of_file
+    end
+
+    # Returns an iCalendar stream (collection of iCalendar objects).
+    def parse
+      calendars = []
+
+      while (line = next_multiline)
+        fields = parse_line(line)
+        if fields[:name] == Tokens::COMPONENT_BEGIN && fields[:value] == Calendar::VALUE
+          calendar = parse_calendar
+          calendars << calendar
+        end
+      end
+
+      calendars
+    end
+
+    private
+
+    def parse_calendar
+      calendar = Calendar.new
+
+      while (line = next_multiline)
+        fields = parse_line(line)
+
+        name, value = fields[:name].upcase, fields[:value]
+        if name == Tokens::COMPONENT_BEGIN
+          component_factory = Component.get_factory(value)
+          if component_factory.nil?
+            raise "Unable to find component: #{value}"
+          end
+          calendar.add_component parse_component(component_factory.new)
+        else
+          calendar.set_property(name, value, fields[:params])
+        end
+      end
+
+      calendar
+    end
+
+    def parse_component(component)
+      while (line = next_multiline)
+        fields = parse_line(line)
+        name = fields[:name].downcase
+        break if name.upcase == Tokens::COMPONENT_END
+        params, value = fields[:params], fields[:value]
+        component.set_property(name, value, params)
+      end
+
+      component
+    end
+
+    CONTINUED_LINE = /^[ \t]/
+    NAME =           "(?:#{Tokens::IANA_TOKEN}|#{Tokens::X_NAME})"
+    PARAM_NAME =     "(?:#{Tokens::IANA_TOKEN}|#{Tokens::X_NAME})"
+    PARAM =          "(?:#{PARAM_NAME}=#{Tokens::PARAM_VALUE}(?:,#{Tokens::PARAM_VALUE})*)"
+    PARAM_CAPTURE =  "(#{PARAM_NAME})=(#{Tokens::PARAM_VALUE}(?:,#{Tokens::PARAM_VALUE})*)"
+    CONTENT_LINE =   /^(#{NAME})(;#{PARAM})*:(#{Tokens::VALUE_CHAR}*)/
+
+    def next_line_of_file
+      line = @file.gets
+      line.chomp! unless line.nil?
+    end
+
+    def next_multiline
+      line = @previous_line
+
+      if line.nil?
+        return nil
+      end
+
+      loop do
+        next_line = next_line_of_file
+
+        if next_line =~ CONTINUED_LINE
+          line << next_line[1, next_line.size]
+        elsif next_line.nil? || next_line.size > 0
+          @previous_line = next_line
+          break
+        end
+      end
+
+      line
+    end
+
+    def parse_line(line)
+      unless line =~ %r{#{CONTENT_LINE}}i
+        raise "Invalid line in calendar string: #{line}"
+      end
+
+      name = $1.upcase
+      value = unescape($3)
+      params = parse_params_str($2)
+
+      { :name => name, :value => value, :params => params }
+    end
+
+    def unescape(str)
+      str.gsub("\\;", ";").gsub("\\,", ",").gsub("\\n", "\n").gsub("\\\\", "\\")
+    end
+
+    def parse_params_str(params_str)
+      params = {}
+      if !params_str.nil? && params_str.size > 1
+        params_str.scan(/#{PARAM_CAPTURE}/) do
+          name = $1
+          values = $2
+
+          params[name] ||= []
+          values.scan(/(#{Tokens::PARAM_VALUE})/) do
+            if $1.size > 0
+              params[name] << $1
+            end
+          end
+        end
+      end
+
+      params
+    end
+  end
+end

data/lib/icalendar2/property/attach.rb

@@ -0,0 +1,10 @@
+module Icalendar2
+  module Property
+    # See http://tools.ietf.org/html/rfc5545#section-3.8.1.1
+    class Attach < Base
+      PLURAL = "attachments"
+      name "ATTACH"
+      value :types => [:uri, :binary]
+    end
+  end
+end

data/lib/icalendar2/property/attendee.rb

@@ -0,0 +1,8 @@
+module Icalendar2
+  module Property
+    # See http://tools.ietf.org/html/rfc5545#section-3.8.4.1
+    class Attendee < Base
+      PLURAL = "attendees"
+    end
+  end
+end