tilia-vobject 4.0.0.pre.alpha2

data/lib/tilia/v_object/i_tip/i_tip_exception.rb

@@ -0,0 +1,9 @@
+module Tilia
+  module VObject
+    module ITip
+      # This message is emitted in case of serious problems with iTip messages.
+      class ITipException < Exception
+      end
+    end
+  end
+end

data/lib/tilia/v_object/i_tip/message.rb

@@ -0,0 +1,109 @@
+module Tilia
+  module VObject
+    module ITip
+      # This class represents an iTip message.
+      #
+      # A message holds all the information relevant to the message, including the
+      # object itself.
+      #
+      # It should for the most part be treated as immutable.
+      class Message
+        # The object's UID.
+        #
+        # @var string
+        attr_accessor :uid
+
+        # The component type, such as VEVENT.
+        #
+        # @var string
+        attr_accessor :component
+
+        # Contains the ITip method, which is something like REQUEST, REPLY or
+        # CANCEL.
+        #
+        # @var string
+        attr_accessor :method
+
+        # The current sequence number for the event.
+        #
+        # @var int
+        attr_accessor :sequence
+
+        # The senders' email address.
+        #
+        # Note that this does not imply that this has to be used in a From: field
+        # if the message is sent by email. It may also be populated in Reply-To:
+        # or not at all.
+        #
+        # @var string
+        attr_accessor :sender
+
+        # The name of the sender. This is often populated from a CN parameter from
+        # either the ORGANIZER or ATTENDEE, depending on the message.
+        #
+        # @var string|null
+        attr_accessor :sender_name
+
+        # The recipient's email address.
+        #
+        # @var string
+        attr_accessor :recipient
+
+        # The name of the recipient. This is usually populated with the CN
+        # parameter from the ATTENDEE or ORGANIZER property, if it's available.
+        #
+        # @var string|null
+        attr_accessor :recipient_name
+
+        # After the message has been delivered, this should contain a string such
+        # as : 1.1;Sent or 1.2;Delivered.
+        #
+        # In case of a failure, this will hold the error status code.
+        #
+        # See:
+        # http://tools.ietf.org/html/rfc6638#section-7.3
+        #
+        # @var string
+        attr_accessor :schedule_status
+
+        # The iCalendar / iTip body.
+        #
+        # @var \Sabre\VObject\Component\VCalendar
+        attr_accessor :message
+
+        # This will be set to true, if the iTip broker considers the change
+        # 'significant'.
+        #
+        # In practice, this means that we'll only mark it true, if for instance
+        # DTSTART changed. This allows systems to only send iTip messages when
+        # significant changes happened. This is especially useful for iMip, as
+        # normally a ton of messages may be generated for normal calendar use.
+        #
+        # To see the list of properties that are considered 'significant', check
+        # out Sabre\VObject\ITip\Broker::significant_change_properties.
+        #
+        # @var bool
+        attr_accessor :significant_change
+
+        # Returns the schedule status as a string.
+        #
+        # For example:
+        # 1.2
+        #
+        # @return mixed bool|string
+        def schedule_status
+          if !@schedule_status
+            false
+          else
+            @schedule_status.split(';').first
+          end
+        end
+
+        # TODO: document
+        def initialize
+          @significant_change = true
+        end
+      end
+    end
+  end
+end

data/lib/tilia/v_object/i_tip/same_organizer_for_all_components_exception.rb

@@ -0,0 +1,13 @@
+module Tilia
+  module VObject
+    module ITip
+      # SameOrganizerForAllComponentsException.
+      #
+      # This exception is emitted when an event is encountered with more than one
+      # component (e.g.: exceptions), but the organizer is not identical in every
+      # component.
+      class SameOrganizerForAllComponentsException < ITipException
+      end
+    end
+  end
+end

data/lib/tilia/v_object/i_tip.rb

@@ -0,0 +1,10 @@
+module Tilia
+  module VObject
+    module ITip
+      require 'tilia/v_object/i_tip/i_tip_exception'
+      require 'tilia/v_object/i_tip/same_organizer_for_all_components_exception'
+      require 'tilia/v_object/i_tip/message'
+      require 'tilia/v_object/i_tip/broker'
+    end
+  end
+end

data/lib/tilia/v_object/node.rb

@@ -0,0 +1,192 @@
+module Tilia
+  module VObject
+    # A node is the root class for every element in an iCalendar of vCard object.
+    class Node
+      include Tilia::Xml::XmlSerializable
+      include Enumerable
+
+      # The following constants are used by the validate method.
+      #
+      # If REPAIR is set, the validator will attempt to repair any broken data
+      # (if possible).
+      REPAIR ||= 1
+
+      # If this option is set, the validator will operate on the vcards on the
+      # assumption that the vcards need to be valid for CardDAV.
+      #
+      # This means for example that the UID is required, whereas it is not for
+      # regular vcards.
+      PROFILE_CARDDAV ||= 2
+
+      # If this option is set, the validator will operate on iCalendar objects
+      # on the assumption that the vcards need to be valid for CalDAV.
+      #
+      # This means for example that calendars can only contain objects with
+      # identical component types and UIDs.
+      PROFILE_CALDAV ||= 4
+
+      # Reference to the parent object, if this is not the top object.
+      #
+      # @var Node
+      attr_accessor :parent
+
+      # The root document.
+      #
+      # @var Component
+      # RUBY: attr_accessor :root
+
+      # Serializes the node into a mimedir format.
+      #
+      # @return string
+      def serialize
+      end
+
+      # This method returns an array, with the representation as it should be
+      # encoded in JSON. This is used to create jCard or jCal documents.
+      #
+      # @return array
+      def json_serialize
+      end
+
+      # This method serializes the data into XML. This is used to create xCard or
+      # xCal documents.
+      #
+      # @param Xml\Writer writer  XML writer.
+      #
+      # @return void
+      def xml_serialize(_writer)
+      end
+
+      # Validates the node for correctness.
+      #
+      # The following options are supported:
+      #   Node::REPAIR - May attempt to automatically repair the problem.
+      #
+      # This method returns an array with detected problems.
+      # Every element has the following properties:
+      #
+      #  * level - problem level.
+      #  * message - A human-readable string describing the issue.
+      #  * node - A reference to the problematic node.
+      #
+      # The level means:
+      #   1 - The issue was repaired (only happens if REPAIR was turned on)
+      #   2 - An inconsequential issue
+      #   3 - A severe issue.
+      #
+      # @param int options
+      #
+      # @return array
+      def validate(_options = 0)
+        []
+      end
+
+      # Returns the iterator for this object.
+      #
+      # @return ElementList
+      def iterator
+        return @iterator if @iterator
+
+        ElementList.new([self])
+      end
+
+      # Sets the overridden iterator.
+      #
+      # Note that this is not actually part of the iterator interface
+      #
+      # @param ElementList $iterator
+      #
+      # @return void
+      attr_writer :iterator
+
+      # Returns the number of elements.
+      #
+      # @return int
+      def size
+        it = iterator
+        it.size
+      end
+      alias_method :length, :size
+      alias_method :count, :size
+
+      # Checks if an item exists through ArrayAccess.
+      #
+      # This method just forwards the request to the inner iterator
+      #
+      # @param int $offset
+      #
+      # @return bool
+      def key?(offset)
+        iterator = self.iterator
+        iterator.key?(offset)
+      end
+
+      # Gets an item through ArrayAccess.
+      #
+      # This method just forwards the request to the inner iterator
+      #
+      # @param int $offset
+      #
+      # @return mixed
+      def [](offset)
+        iterator = self.iterator
+        iterator[offset]
+      end
+
+      # Sets an item through ArrayAccess.
+      #
+      # This method just forwards the request to the inner iterator
+      #
+      # @param int $offset
+      # @param mixed $value
+      #
+      # @return void
+      def []=(offset, value)
+        iterator = self.iterator
+        iterator[offset] = value
+      end
+
+      # Sets an item through ArrayAccess.
+      #
+      # This method just forwards the request to the inner iterator
+      #
+      # @param int $offset
+      #
+      # @return void
+      def delete(offset)
+        iterator = self.iterator
+        iterator.delete(offset)
+      end
+
+      def initialize
+        @root = nil
+      end
+
+      def each
+        iterator = self.iterator
+        iterator.each { |i| yield(i) }
+      end
+
+      def ==(other)
+        return true if other.__id__ == __id__
+
+        # check class
+        return false unless self.class == other.class
+
+        # Instance variables should be the same
+        return false unless instance_variables.sort == other.instance_variables.sort
+
+        # compare all instance variables
+        instance_variables.each do |var|
+          if var == :@root && instance_variable_get(var) == self
+            # We are our own root
+            return false unless other.instance_variable_get(var) == other
+          else
+            return false unless instance_variable_get(var) == other.instance_variable_get(var)
+          end
+        end
+        true
+      end
+    end
+  end
+end

data/lib/tilia/v_object/parameter.rb

@@ -0,0 +1,327 @@
+module Tilia
+  module VObject
+    # VObject Parameter.
+    #
+    # This class represents a parameter. A parameter is always tied to a property.
+    # In the case of:
+    #   DTSTART;VALUE=DATE:20101108
+    # VALUE=DATE would be the parameter name and value.
+    class Parameter < Node
+      # Parameter name.
+      #
+      # @var string
+      attr_accessor :name
+
+      # vCard 2.1 allows parameters to be encoded without a name.
+      #
+      # We can deduce the parameter name based on it's value.
+      #
+      # @var bool
+      attr_accessor :no_name
+
+      # Parameter value.
+      #
+      # @var string
+      # RUBY: attr_accessor :value
+
+      # Sets up the object.
+      #
+      # It's recommended to use the create:: factory method instead.
+      #
+      # @param string name
+      # @param string value
+      def initialize(root, name, value = nil)
+        @no_name = false
+        @name = (name || '').upcase
+        @root = root
+
+        if name.nil?
+          @no_name = true
+          @name = self.class.guess_parameter_name_by_value(value)
+        else
+          @name = name.upcase
+        end
+
+        # If guess_parameter_name_by_value returns an empty string
+        # above, we're actually dealing with a parameter that has no value.
+        # In that case we have to move the value to the name.
+        if @name == ''
+          @no_name = false
+          @name = value.upcase
+        else
+          self.value = value
+        end
+      end
+
+      # Try to guess property name by value, can be used for vCard 2.1 nameless parameters.
+      #
+      # Figuring out what the name should have been. Note that a ton of
+      # these are rather silly in 2014 and would probably rarely be
+      # used, but we like to be complete.
+      #
+      # @param string value
+      #
+      # @return string
+      def self.guess_parameter_name_by_value(value)
+        value ||= ''
+        case value.upcase
+        # Encodings
+        when '7-BIT',
+            'QUOTED-PRINTABLE',
+            'BASE64'
+          'ENCODING'
+        # Common types
+        when 'WORK',
+            'HOME',
+            'PREF',
+
+            # Delivery Label Type
+            'DOM',
+            'INTL',
+            'POSTAL',
+            'PARCEL',
+
+            # Telephone types
+            'VOICE',
+            'FAX',
+            'MSG',
+            'CELL',
+            'PAGER',
+            'BBS',
+            'MODEM',
+            'CAR',
+            'ISDN',
+            'VIDEO',
+
+            # EMAIL types (lol)
+            'AOL',
+            'APPLELINK',
+            'ATTMAIL',
+            'CIS',
+            'EWORLD',
+            'INTERNET',
+            'IBMMAIL',
+            'MCIMAIL',
+            'POWERSHARE',
+            'PRODIGY',
+            'TLX',
+            'X400',
+
+            # Photo / Logo format types
+            'GIF',
+            'CGM',
+            'WMF',
+            'BMP',
+            'DIB',
+            'PICT',
+            'TIFF',
+            'PDF',
+            'PS',
+            'JPEG',
+            'MPEG',
+            'MPEG2',
+            'AVI',
+            'QTIME',
+
+            # Sound Digital Audio Type
+            'WAVE',
+            'PCM',
+            'AIFF',
+
+            # Key types
+            'X509',
+            'PGP'
+          'TYPE'
+
+        # Value types
+        when 'INLINE',
+            'URL',
+            'CONTENT-ID',
+            'CID'
+          'VALUE'
+        else
+          ''
+        end
+      end
+
+      # Updates the current value.
+      #
+      # This may be either a single, or multiple strings in an array.
+      #
+      # @param string|array value
+      #
+      # @return void
+      attr_writer :value
+
+      # Returns the current value.
+      #
+      # This method will always return a string, or null. If there were multiple
+      # values, it will automatically concatenate them (separated by comma).
+      #
+      # @return string|null
+      def value
+        if @value.is_a?(Array)
+          @value.join(',')
+        else
+          @value
+        end
+      end
+
+      # Sets multiple values for this parameter.
+      #
+      # @param array value
+      #
+      # @return void
+      def parts=(value)
+        @value = value
+      end
+
+      # Returns all values for this parameter.
+      #
+      # If there were no values, an empty array will be returned.
+      #
+      # @return array
+      def parts
+        if @value.is_a?(Array)
+          @value
+        elsif @value.nil?
+          []
+        else
+          [@value]
+        end
+      end
+
+      # Adds a value to this parameter.
+      #
+      # If the argument is specified as an array, all items will be added to the
+      # parameter value list.
+      #
+      # @param string|array part
+      #
+      # @return void
+      def add_value(part)
+        if @value.nil?
+          @value = part
+        else
+          @value = [@value] unless @value.is_a?(Array)
+          part = [part] unless part.is_a?(Array)
+          @value.concat(part)
+        end
+      end
+
+      # Checks if this parameter contains the specified value.
+      #
+      # This is a case-insensitive match. It makes sense to call this for for
+      # instance the TYPE parameter, to see if it contains a keyword such as
+      # 'WORK' or 'FAX'.
+      #
+      # @param string value
+      #
+      # @return bool
+      def has(value)
+        value = value.downcase
+        results = (@value.is_a?(Array) ? @value : [@value]).select do |entry|
+          entry.downcase == value
+        end
+        results.any?
+      end
+
+      # Turns the object back into a serialized blob.
+      #
+      # @return string
+      def serialize
+        value = parts
+
+        return "#{@name}=" if value.size == 0
+
+        if @root.document_type == Document::VCARD21 && @no_name
+          return value.join(';')
+        end
+
+        result = value.inject('') do |keep, item|
+          keep += ',' unless keep == ''
+
+          # If there's no special characters in the string, we'll use the simple
+          # format.
+          #
+          # The list of special characters is defined as:
+          #
+          # Any character except CONTROL, DQUOTE, ";", ":", ","
+          #
+          # by the iCalendar spec:
+          # https://tools.ietf.org/html/rfc5545#section-3.1
+          #
+          # And we add ^ to that because of:
+          # https://tools.ietf.org/html/rfc6868
+          #
+          # But we've found that iCal (7.0, shipped with OSX 10.9)
+          # severaly trips on + characters not being quoted, so we
+          # added + as well.
+          if !(item.to_s =~ /(?: [\n":;\^,\+] )/x)
+            keep + item.to_s
+          else
+            # Enclosing in double-quotes, and using RFC6868 for encoding any
+            # special characters
+            keep += '"' + item.to_s.gsub(
+              /[\^\n"]/,
+              '^'  => '^^',
+              "\n" => '^n',
+              '"'  => '^\''
+            )
+            keep + '"'
+          end
+        end
+
+        "#{@name}=#{result}"
+      end
+
+      # This method returns an array, with the representation as it should be
+      # encoded in JSON. This is used to create jCard or jCal documents.
+      #
+      # @return array
+      def json_serialize
+        @value
+      end
+
+      # This method serializes the data into XML. This is used to create xCard or
+      # xCal documents.
+      #
+      # @param Xml\Writer writer  XML writer.
+      #
+      # @return void
+      def xml_serialize(writer)
+        @value.split(',').each do |value|
+          writer.write_element('text', value)
+        end
+      end
+
+      # Called when this object is being cast to a string.
+      #
+      # @return string
+      def to_s
+        value.to_s
+      end
+
+      def each
+        @value.each do |value|
+          yield(value)
+        end
+      end
+
+      def iterator
+        return @iterator if @iterator
+
+        @iterator = @value || []
+      end
+
+      # TODO: document
+      def ==(other)
+        if other.is_a?(String)
+          to_s == other
+        else
+          super(other)
+        end
+      end
+    end
+  end
+end

data/lib/tilia/v_object/parse_exception.rb

@@ -0,0 +1,7 @@
+module Tilia
+  module VObject
+    # Exception thrown by Reader if an invalid object was attempted to be parsed.
+    class ParseException < Exception
+    end
+  end
+end