kali 0.0.1

data/README.md

@@ -0,0 +1,42 @@
+# Kali: iCalendar for the rest of us
+
+Kali attempts to provide a simple and extensible implementation of [RFC
+5545][rfc5545] and friends, which describe the iCalendar format, used for
+representing and exchanging calendaring and scheduling information.
+
+[Kālī][wikipedia] is also the Hindu Goddess of Time.
+
+![Kali: Goddess of Time and Change, by Raja Ravi Varma](
+  http://upload.wikimedia.org/wikipedia/commons/8/89/Kali_by_Raja_Ravi_Varma.jpg
+)
+
+## Generating Calendars
+
+The simplest example possible:
+
+``` ruby
+require "uri"
+require "kali"
+
+calendar = Kali::Calendar.new do |cal|
+  cal.event do |event|
+    event.summary = "Lunch" # Or: event.summary = Kali::Property::Summary.new("Lunch")
+    event.description = "Let's get some food"
+    event.dtstart = DateTime.civil(2013, 7, 31, 12, 30)
+    event.dtend = DateTime.civil(2013, 7, 31, 14, 30)
+
+    event.attendees.add URI("mailto:hi@nicolassanguinetti.info") do |attendee|
+      attendee.partstat = "ACCEPTED"
+      attendee.cn = "Nicolás Sanguinetti"
+      attendee["X-GUEST-COUNT"] = 2
+    end
+
+    event.attendees.add URI("mailto:someone@example.com") # Simplified attendee
+  end
+end
+
+File.open("cal.ics", "w") { |f| f.puts(calendar.to_ics) }
+```
+
+[rfc5545]: http://tools.ietf.org/html/rfc5545
+[wikipedia]: http://en.wikipedia.org/wiki/Kali

data/examples/calendar.rb

@@ -0,0 +1,48 @@
+require "kali"
+require "uri"
+
+cal = Kali::Calendar.new do |calendar|
+  calendar.events.add do |event|
+    event.uid = 1
+    event.summary = "Conference Talk"
+
+    event.description = "A description of the talk"
+    event.description.language = "en" # setting parameters on properties.
+
+    event.location = "The Venue"
+    event.geo = [-54.458594, -34.123310]
+    event.categories = ["CATEGORY A", "CATEGORY B"]
+
+    event.dtstart = DateTime.civil(2013, 7, 31, 15, 00, 00, "-07:00")
+    event.dtstart.tzid = "America/Los_Angeles"
+    event.dtend = DateTime.civil(2013, 7, 31, 16, 00, 00, "-07:00")
+    event.dtend.tzid = "America/Los_Angeles"
+
+    event.comments.add "I'm sure the talk will be a disaster --The Speaker"
+    event.comments.add "Estoy convencido de que va a ser buena" do |comment|
+      comment.language = "es"
+    end
+
+    event.attendees.add URI.parse("mailto:john@example.org") do |attendee|
+      attendee.partstat = "ACCEPTED"
+      attendee.role = "CHAIR"
+    end
+
+    event.attendees.add URI.parse("mailto:jane@example.org") do |attendee|
+      # the property parameters can be specified as if the property was a Hash.
+      attendee["PARTSTAT"] = "DECLINED"
+    end
+  end
+
+  calendar.events.add do |event|
+    event.uid = 2
+    event.summary = "Another Thing"
+    event.location = "The Venue"
+
+    event.dtstart = DateTime.new(2013, 7, 31, 18, 00, 00, "+02:00")
+    event.dtstart["TZID"] = "Europe/Berlin"
+    event.duration = { minute: 45 }
+  end
+end
+
+puts cal.to_ics

data/lib/kali.rb

@@ -0,0 +1,16 @@
+require "kali/version"
+require "kali/type"
+require "kali/utils"
+require "kali/key_value_pair"
+require "kali/typed_list"
+require "kali/property"
+require "kali/parameter"
+require "kali/component"
+require "kali/parameters"
+require "kali/properties"
+
+require "kali/component/calendar"
+require "kali/component/event"
+
+module Kali
+end

data/lib/kali/component.rb

@@ -0,0 +1,128 @@
+module Kali
+  class Component
+    extend Utils::Named
+
+    # Public: Add a property to this component. This property will appear 0 or 1
+    # times in this component. If you want to add a property that can appear
+    # multiple times in the component, look at `Component.property_list`.
+    #
+    # Example
+    #
+    #   class Event < Kali::Component
+    #     property Kali::Property::Summary
+    #     property Kali::Property::Description, :desc
+    #   end
+    #
+    #   Event.new do |event|
+    #     event.summary = "Summary"
+    #     event.desc = "Description"
+    #   end
+    #
+    # type   - The class that defines the property. Must be a Kali::Property
+    #          subclass.
+    # method - The name of the method under which to mount this property.
+    #
+    # Returns nothing.
+    def self.property(type, method = type.method_name)
+      define_method method do
+        properties[type.name] ||= type.new
+      end
+
+      define_method "#{method}=" do |value|
+        property = type === value ? value : type.new(value)
+        properties[type.name] = property
+      end
+    end
+
+    # Public: Add a family of properties to this component. This adds a property
+    # that can appear multiple times in this component. If you need a property
+    # that appears at most once in the component, look at `Component.property`.
+    #
+    # Example
+    #
+    #   class Event < Kali::Component
+    #     property_list Kali::Property::Attendee, :attendees
+    #   end
+    #
+    #   Event.new do |event|
+    #     event.attendees.add do |attendee|
+    #       ...
+    #     end
+    #   end
+    #
+    # type   - The class that defines the property. Must be a Kali::Property
+    #          subclass.
+    # method - The name of the method under which to mount this property.
+    #
+    # Returns nothing.
+    def self.property_list(type, method = type.method_name)
+      define_method method do
+        properties[type.name] ||= TypedList.new(type)
+      end
+    end
+
+    # Public: Add a family of components to this component. This exposes a list
+    # to which you can add sub-components.
+    #
+    # Example
+    #
+    #   class Calendar < Kali::Component
+    #     component Kali::Event, :events
+    #   end
+    #
+    #   Calendar.new do |cal|
+    #     cal.events.add do |event|
+    #       ...
+    #     end
+    #   end
+    #
+    # type   - The class that defines the component. Must be a Kali::Component
+    #          subclass.
+    # method - The name of the method under which to mount this property.
+    #
+    # Returns nothing.
+    def self.component(type, method = type.method_name)
+      define_method method do
+        components[type.name] ||= TypedList.new(type)
+      end
+    end
+
+    # Public: Initialize the component.
+    #
+    # Yields itself if a block is passed.
+    def initialize
+      yield self if block_given?
+    end
+
+    # Public: Generate an iCalendar representation of the component.
+    #
+    # Returns a String.
+    def to_ics
+      properties = self.properties.map { |_, value| value.to_ics }
+      components = self.components.map { |_, value| value.to_ics }
+
+      lines = [
+        "BEGIN:#{self.class.name}",
+        *properties.compact,
+        *components.compact,
+        "END:#{self.class.name}"
+      ]
+
+      lines.reject { |s| s.empty? }.join("\n")
+    end
+
+    # Internal: List of properties stored in this component.
+    #
+    # Returns a Hash.
+    def properties
+      @properties ||= {}
+    end
+
+    # Internal: List of sub-components that form this component.
+    #
+    # Returns a Hash.
+    def components
+      @components ||= {}
+    end
+  end
+end

data/lib/kali/component/calendar.rb

@@ -0,0 +1,23 @@
+require "kali/component"
+require "kali/properties"
+require "kali/component/event"
+
+module Kali
+  class Calendar < Component
+    name "VCALENDAR"
+
+    component Event, :events
+
+    property Property::ProductIdentifier
+    property Property::Version
+    property Property::CalendarScale
+    property Property::Method
+
+    def initialize
+      self.prodid   = Property::ProductIdentifier.new
+      self.version  = Property::Version.new
+      self.calscale = Property::CalendarScale.new
+      super
+    end
+  end
+end

data/lib/kali/component/event.rb

@@ -0,0 +1,33 @@
+require "kali/component"
+require "kali/properties"
+
+module Kali
+  class Event < Component
+    name "VEVENT"
+
+    property Property::UniqueIdentifier
+    property Property::SequenceNumber
+    property Property::Summary
+    property Property::Description
+    property Property::GeographicPosition
+    property Property::Location
+    property Property::Priority
+    property Property::Resources
+    property Property::Categories
+    property Property::EventStatus
+    property Property::StartDateTime
+    property Property::EndDateTime
+    property Property::Duration
+    property Property::TimeTransparency
+    property Property::Organizer
+    property Property::Contact
+
+    property_list Property::Comment, :comments
+    property_list Property::Attendee, :attendees
+
+    def initialize
+      self.sequence = Property::SequenceNumber.new
+      super
+    end
+  end
+end

data/lib/kali/key_value_pair.rb

@@ -0,0 +1,62 @@
+module Kali
+  class KeyValuePair
+    extend Utils::Named
+
+    # Internal: Given a value for this KV-pair, if it's already of the pair's
+    # type, return it as is, or otherwise instantiate a new pair with this as a
+    # value.
+    #
+    # Returns an instance of this KV-pair's type.
+    def self.wrap(value)
+      self === value ? value : new(value)
+    end
+
+    # Public: Get/Set the Type of the KV-pair implemented by this class.
+    def self.type(type = nil)
+      @type = type if type
+      @type
+    end
+
+    # Public: Get/Set a default value for this KV-pair.
+    def self.default(default = nil)
+      @default = default if default
+      @default
+    end
+
+    # Public: Get/Set the value of this specific instance of the KV-pair.
+    attr_accessor :value
+
+    # Internal: Initialize the KV-pair.
+    #
+    # value - Any value that can be set for this KV-pair.
+    def initialize(value = self.class.default)
+      @value = value
+    end
+
+    # Public: Generate an iCalendar representation of this KV-pair.
+    #
+    # Returns a String.
+    def to_ics
+      encoded_value = self.class.type.encode(value)
+      "#{name}#{separator}#{encoded_value}"
+    end
+
+    # Public: Get the String representation of this KV-pair.
+    def to_s
+      value.to_s
+    end
+
+    # Internal: Get the name of the KV-pair.
+    def name
+      @name ||= self.class.name
+    end
+
+    # Internal: Separator of the key and value in iCalendar representations of
+    # this KV-pair.
+    #
+    # Returns a String.
+    def separator
+      ":"
+    end
+  end
+end

data/lib/kali/parameter.rb

@@ -0,0 +1,14 @@
+module Kali
+  # Public: Parameters are meta-information about a certain property.
+  class Parameter < KeyValuePair
+    # Public: See KeyValuePair#to_ics
+    def to_ics
+      ";#{super}"
+    end
+
+    # Internal: See KeyValuePair#separator
+    def separator
+      "="
+    end
+  end
+end

data/lib/kali/parameters.rb

@@ -0,0 +1,146 @@
+module Kali
+  # Public: Meta-property that represents any user-defined property not
+  # currently implemented in the system.
+  class Parameter::Default < Parameter
+    type Type::Text.new
+
+    def initialize(name, value)
+      @name = name
+      super(value)
+    end
+  end
+
+  # URI pointing to an alternate representation of the value of the property to
+  # which this parameter applies to.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.1
+  class Parameter::AlternateRepresentation < Parameter
+    name "ALTREP"
+    type Type::Quoted.new(Type::URI.new)
+  end
+
+  # Common name of a calendar user. Specified in properties with the type
+  # CalAddress.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.2
+  class Parameter::CommonName < Parameter
+    name "CN"
+    type Type::Quoted.new(Type::Text.new)
+  end
+
+  # Identifies the type of user to which this property refers to.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.3
+  class Parameter::CalendarUserType < Parameter
+    name "CUTYPE"
+    type Type::Text.new(Enum["INDIVIDUAL", "GROUP", "RESOURCE", "ROOM",
+                             "UNKNOWN"])
+    default "INDIVIDUAL"
+  end
+
+  # List of users that have delegated their participation to the calendar user
+  # specified by the property to which this parameter applies.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.4
+  class Parameter::Delegators < Parameter
+    name "DELEGATED-FROM"
+    type Type::List.new(Type::Quoted.new(Type::CalAddress.new))
+  end
+
+  # List of users to which the calendar user has delegated his/her participation
+  # to.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.5
+  class Parameter::Delegatees < Parameter
+    name "DELEGATED-TO"
+    type Type::List.new(Type::Quoted.new(Type::CalAddress.new))
+  end
+
+  # URI pointing to a directory entry associated with the calendar user to which
+  # this parameter applies.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.6
+  class Parameter::DirectoryEntry < Parameter
+    name "DIR"
+    type Type::Quoted.new(Type::URI.new)
+  end
+
+  # Alternate encoding for the value of this property.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.7
+  class Parameter::Encoding < Parameter
+    name "ENCODING"
+    type Type::Text.new(Enum["8BIT", "BASE64"])
+    default "8BIT"
+  end
+
+  # Specifies the content type of the referenced object.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.8
+  class Parameter::ContentType < Parameter
+    name "FMTTYPE"
+    type Type::Text.new(/[a-z0-9\!\#\$\&\.\+\-\^\_]{1,127}\/[a-z0-9\!\#\$\&\.\+\-\^\_]{1,127}/i)
+  end
+
+  # Specifies the language of the associated property (using an identifier as
+  # conceived by [RFC 5646](http://tools.ietf.org/html/rfc5646)).
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.10
+  class Parameter::Language < Parameter
+    name "LANGUAGE"
+    type Type::Text.new
+  end
+
+  # Mailing lists/groups of which the calendar user is a member of.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.11
+  class Parameter::GroupMemberships < Parameter
+    name "MEMBER"
+    type Type::List.new(Type::Quoted.new(Type::CalAddress.new))
+  end
+
+  # Current status of participation in an event of the calendar user.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.12
+  class Parameter::EventParticipationStatus < Parameter
+    name "PARTSTAT"
+    type Type::Text.new(Enum["NEEDS-ACTION", "ACCEPTED", "DECLINED",
+                             "TENTATIVE", "DELEGATED"])
+  end
+
+  # Role within the event of the calendar user described by this property.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.16
+  class Parameter::ParticipationRole < Parameter
+    name "ROLE"
+    type Type::Text.new(Enum["CHAIR", "REQ-PARTICIPANT", "OPT-PARTICIPANT",
+                             "NON-PARTICIPANT"])
+    default "REQ-PARTICIPANT"
+  end
+
+  # Specified whether a reply is expected from the calendar user.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.17
+  class Parameter::RSVPExpectation < Parameter
+    name "RSVP"
+    type Type::Boolean.new
+    default false
+  end
+
+  # Specify that the described calendar user is acting on behalf of the calendar
+  # user addressed by this parameter.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.18
+  class Parameter::SentBy < Parameter
+    name "SENT-BY"
+    type Type::Quoted.new(Type::CalAddress.new)
+  end
+
+  # Specify the timezone in which this Time or DateTime is occurring.
+  #
+  # See http://tools.ietf.org/html/rfc5545#section-3.2.19
+  class Parameter::TimeZoneIdentifier < Parameter
+    name "TZID"
+    type Type::Text.new
+  end
+end