kali 0.0.1

data/lib/kali/properties.rb

@@ -0,0 +1,207 @@
+module Kali
+  # Identifier for the product that created this iCalendar object.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.7.3
+  class Property::ProductIdentifier < Property
+    name "PRODID"
+    type Type::Text.new
+    default "Kali/#{Kali::VERSION}"
+  end
+
+  # Version of the iCalendar protocol implemented in this iCalendar object.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.7.4
+  class Property::Version < Property
+    name "VERSION"
+    type Type::Text.new("2.0")
+    default "2.0"
+  end
+
+  # Calendar scale used in this iCalendar object.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.7.1
+  class Property::CalendarScale < Property
+    name "CALSCALE"
+    type Type::Text.new("GREGORIAN")
+    default "GREGORIAN"
+  end
+
+  # The iCalendar object method associated with this iCalendar object.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.7.2
+  class Property::Method < Property
+    name "METHOD"
+    type Type::Text.new(
+      Enum["PUBLISH", "REQUEST", "REPLY", "ADD", "CANCEL", "REFRESH", "COUNTER",
+           "DECLINECOUNTER"]
+    )
+  end
+
+  # Globally unique identifier for this component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.4.7
+  class Property::UniqueIdentifier < Property
+    name "UID"
+    type Type::Text.new
+  end
+
+  # The "current version" of the component, according to the organizer's
+  # judgement.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.7.4
+  class Property::SequenceNumber < Property
+    name "SEQUENCE"
+    type Type::Integer.new(->(i) { i >= 0 })
+    default 0
+  end
+
+  # Short summary of the current component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.12
+  class Property::Summary < Property
+    name "SUMMARY"
+    type Type::Text.new
+  end
+
+  # Longer description of the current component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.5
+  class Property::Description < Property
+    name "DESCRIPTION"
+    type Type::Text.new
+  end
+
+  # Lat/Lng pair indicating where this component takes place.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.6
+  class Property::GeographicPosition < Property
+    name "GEO"
+    type Type::Geo.new
+  end
+
+  # Name/description of the venue where this component takes place.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.7
+  class Property::Location < Property
+    name "LOCATION"
+    type Type::Text.new
+  end
+
+  # How important is this component compared to others. Can be 0 (no special
+  # priority), or range from 1 (high) to 9 (low).
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.9
+  class Property::Priority < Property
+    name "PRIORITY"
+    type Type::Integer.new(0..9)
+    default 0
+  end
+
+  # List of categories describing this component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.2
+  class Property::Categories < Property
+    name "CATEGORIES"
+    type Type::List.new(Type::Text.new)
+  end
+
+  # List of resources needed to be able to fulfill this component. For example
+  # ["PROJECTOR", "EASEL", "WHITEBOARD"].
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.10
+  class Property::Resources < Property
+    name "RESOURCES"
+    type Type::List.new(Type::Text.new)
+  end
+
+  # User provided comments about the current component. Can be specified
+  # multiple times for a single component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.4
+  class Property::Comment < Property
+    name "COMMENT"
+    type Type::Text.new
+  end
+
+  # Status representing whether the event is taking place or not.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.1.11
+  class Property::EventStatus < Property
+    name "STATUS"
+    type Type::Text.new(Enum["TENTATIVE", "CONFIRMED", "CANCELLED"])
+  end
+
+  # End date of a component. This is required, unless there's a Duration, in
+  # which case this can't appear.
+  #
+  # TODO: This can be a DateTime or a Date. We should take that into
+  # consideration.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.2.2
+  class Property::EndDateTime < Property
+    name "DTEND"
+    type Type::DateTime.new
+  end
+
+  # Start date of a component.
+  #
+  # TODO: This can be a DateTime or a Date. We should take that into
+  # consideration.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.2.4
+  class Property::StartDateTime < Property
+    name "DTSTART"
+    type Type::DateTime.new
+  end
+
+  # Duration of the component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.2.5
+  class Property::Duration < Property
+    name "DURATION"
+    type Type::Duration.new
+  end
+
+  # Does this event affect your free/busy schedule? Transparent events are the
+  # ones that don't, while opaque events do.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.2.7
+  class Property::TimeTransparency < Property
+    name "TRANSP"
+    type Type::Text.new(Enum["OPAQUE", "TRANSPARENT"])
+    default "OPAQUE"
+  end
+
+  # Represent a person involved with this event.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.4.1
+  class Property::Attendee < Property
+    name "ATTENDEE"
+    type Type::CalAddress.new
+  end
+
+  # Represent the party organizing the event.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.4.3
+  class Property::Organizer < Property
+    name "ORGANIZER"
+    type Type::CalAddress.new
+  end
+
+  # This component is used to represent contact information for someone
+  # associated with the Event's venue.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.4.3
+  class Property::Contact < Property
+    name "CONTACT"
+    type Type::Text.new
+  end
+
+  # External URL associated with this calendar component.
+  #
+  # As per http://tools.ietf.org/html/rfc5545#section-3.8.4.6
+  class Property::URL < Property
+    name "URL"
+    type Type::URI.new
+  end
+end

data/lib/kali/property.rb

@@ -0,0 +1,93 @@
+module Kali
+  # Public: Properties are the definition of an attribute describing a
+  # component.
+  class Property < KeyValuePair
+    # Public: Add a new parameter to this Property.
+    #
+    # type - A subclass of Kali::Parameter.
+    #
+    # Returns nothing.
+    def self.parameter(type, method = type.method_name)
+      default_parameter_types[type.name] = type
+
+      define_method method do
+        parameters[type.name] ||= type.new
+      end
+
+      define_method "#{method}=" do |value|
+        parameters[type.name] = type.wrap(value)
+      end
+    end
+
+    # Public: Register the type of this property, and all the parameters
+    # associated with that type, or get the current type of the object.
+    #
+    # See `KeyValuePair.type`.
+    def self.type(type = nil)
+      if type
+        type.parameters.each do |param, method|
+          parameter(param, method)
+        end
+      end
+      super
+    end
+
+    # Internal: List of parameter types added to the class explicitly. Any
+    # parameter added that is not in this store will be assumed to be a simple
+    # Type::Text parameter. See `Property#[]=`.
+    def self.default_parameter_types
+      @parameter_types ||= {}
+    end
+
+    def initialize(*) # :nodoc:
+      super
+    end
+
+    # Internal: Storage of parameters associated with this instance of the
+    # property.
+    #
+    # Returns a Hash.
+    def parameters
+      @parameters ||= {}
+    end
+
+    # Public: Get a parameter by iCalendar name.
+    #
+    # name - The name of the parameter.
+    #
+    # Returns the passed in value.
+    def [](name)
+      parameters[name]
+    end
+
+    # Public: Set a parameter manually by explicitly passing the iCalendar name
+    # (so, for example, "DELEGATED-TO" instead of calling `#delegated_to=`).
+    #
+    # name  - A String with the name of the parameter. If there's a typed
+    #         parameter for this name already, this will be equivalent to
+    #         setting that parameter via the setter. Otherwise it will assume
+    #         this is a Text parameter and set it. Useful for setting
+    #         experimental ("X-*") params, such as "X-GUEST-COUNT".
+    # value - The value of the param.
+    #
+    # Returns the passed in value.
+    def []=(name, value)
+      param = if type = self.class.default_parameter_types.fetch(name, false)
+        type.wrap(value)
+      else
+        Parameter::Default.new(name, value)
+      end
+
+      parameters[name] = param
+    end
+
+    # Public: Generate an iCalendar representation of this property.
+    #
+    # Returns a String.
+    def to_ics
+      params = parameters.map { |_, value| value.to_ics }.join("")
+      encoded_value = self.class.type.encode(value)
+      Utils::Text.fold_line "#{self.class.name}#{params}:#{encoded_value}"
+    end
+  end
+end

data/lib/kali/type.rb

@@ -0,0 +1,118 @@
+require "set"
+
+module Kali
+  # Public: Type classes are used to convert ruby objects from and to their
+  # iCalendar representations.
+  #
+  # Examples:
+  #   type = Kali::Type::Date.new
+  #   type.encode(Date.today) #=> "20130712"
+  #   type.decode("20130712") #=> Date.new(2013, 7, 12)
+  #
+  #   type = Kali::Type::Integer.new(0..9)
+  #   type.encode(3) #=> "3"
+  #   type.encode(15) #=> ArgumentError
+  #   type.decode("7") #=> 7
+  #
+  #   type = Kali::Type::Text.new(->(s) { s.size > 3 })
+  #   type.encode("x") #=> ArgumentError
+  #   type.encode("long") #=> "long"
+  #
+  #   type = Kali::Type::Text.new(Enum["ACTIVE", "INACTIVE"])
+  #   type.encode("ACTIVE") #=> "ACTIVE"
+  #   type.encode("nope") #=> ArgumentError
+  class Type
+    # Public: Initialize the Type.
+    #
+    # restriction - An object that implenents the #=== operator. When we
+    #               validate that a certain value is valid for this type, we
+    #               will check the value against `restriction.===`. If it's
+    #               `nil` then we don't restrict the value.
+    def initialize(restriction = nil)
+      @restriction = restriction
+    end
+
+    # Public: Parameters added by deafult to properties that are of this type.
+    #
+    # Returns an Array where each entry is a Hash keyed by a subclass of
+    # Kali::Parameter, and the value is a Symbol with the name of the method for
+    # that property.
+    def parameters
+      []
+    end
+
+    # Public: Encode an object into an iCalendar-compatible String using the
+    # format specific to this Type.
+    #
+    # Requires a subclass to implement #encode!
+    #
+    # obj - An Object that matches this Type.
+    #
+    # Returns a String that matches the iCalendar representation of this Type.
+    def encode(obj)
+      encode!(validate(obj))
+    end
+
+    # Public: Decode an iCalendar-compatible String into an Object that matches
+    # this Type.
+    #
+    # Requires a subclass to implement #decode!
+    #
+    # obj - A String that matches the iCalendar representation for this Type..
+    #
+    # Returns an Object that matches this Type.
+    def decode(obj)
+      validate(decode!(obj))
+    end
+
+    private
+
+    # Internal: Check that an Object meets the restrictions of this particular
+    # Type.
+    #
+    # value - An Object.
+    #
+    # Returns the value if it satisfies the restriction.
+    # Raises ArgumentError if the restriction is not satisfied.
+    def validate(value)
+      if @restriction.nil? || @restriction === value
+        value
+      else
+        raise ArgumentError, "#{value.inspect} does not satisfy the type restriction for #{self.class} (#{@restriction.inspect})"
+      end
+    end
+
+    autoload :Text,       "kali/type/text"
+    autoload :Integer,    "kali/type/integer"
+    autoload :Float,      "kali/type/float"
+    autoload :Geo,        "kali/type/geo"
+    autoload :List,       "kali/type/list"
+    autoload :DateTime,   "kali/type/date_time"
+    autoload :Date,       "kali/type/date"
+    autoload :Time,       "kali/type/time"
+    autoload :Duration,   "kali/type/duration"
+    autoload :URI,        "kali/type/uri"
+    autoload :CalAddress, "kali/type/cal_address"
+    autoload :Quoted,     "kali/type/quoted"
+    autoload :Boolean,    "kali/type/boolean"
+  end
+
+  # Public: Helper class that allows us to easily restrict a value from a set of
+  # predetermined values. It's just a Set that implements the case equality
+  # operator to check for Set inclusion.
+  #
+  # This is meant to be used as a Type restriction. See Type for examples.
+  #
+  # Examples:
+  #   Enum[1, 2, 3] === 1 #=> true
+  #   Enum[1, 2, 3] === 5 #=> false
+  class Enum < Set
+    def self.[](*values)
+      new(values).freeze
+    end
+
+    def ===(element)
+      include?(element)
+    end
+  end
+end

data/lib/kali/type/boolean.rb

@@ -0,0 +1,18 @@
+module Kali
+  class Type::Boolean < Type
+    def initialize(requirement = nil)
+      super(->(o) { (o == true || o == false) && (requirement.nil? || requirement === o) })
+    end
+
+    def encode!(flag)
+      flag ? "TRUE" : "FALSE"
+    end
+
+    def decode!(string)
+      case string
+      when "TRUE";  true
+      when "FALSE"; false
+      end
+    end
+  end
+end

data/lib/kali/type/cal_address.rb

@@ -0,0 +1,28 @@
+require "uri"
+
+module Kali
+  # The CAL-ADDRESS type represents a person involved with an event. It must be
+  # an email URI.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.3.3
+  class Type::CalAddress < Type::URI
+    def initialize
+      super(::URI::MailTo)
+    end
+
+    def parameters
+      {
+        Parameter::CommonName               => :cn,
+        Parameter::CalendarUserType         => :cutype,
+        Parameter::Delegators               => :delegators,
+        Parameter::Delegatees               => :delegatees,
+        Parameter::DirectoryEntry           => :dir,
+        Parameter::GroupMemberships         => :members,
+        Parameter::EventParticipationStatus => :partstat,
+        Parameter::ParticipationRole        => :role,
+        Parameter::RSVPExpectation          => :rsvp,
+        Parameter::SentBy                   => :sent_by
+      }
+    end
+  end
+end