tilia-vobject 4.0.0.pre.alpha2

data/lib/tilia/v_object/date_time_parser.rb

@@ -0,0 +1,486 @@
+module Tilia
+  module VObject
+    # DateTimeParser.
+    #
+    # This class is responsible for parsing the several different date and time
+    # formats iCalendar and vCards have.
+    class DateTimeParser
+      # Parses an iCalendar (rfc5545) formatted datetime and returns a
+      # DateTimeImmutable object.
+      #
+      # Specifying a reference timezone is optional. It will only be used
+      # if the non-UTC format is used. The argument is used as a reference, the
+      # returned DateTimeImmutable object will still be in the UTC timezone.
+      #
+      # @param string dt
+      # @param DateTimeZone tz
+      #
+      # @return DateTimeImmutable
+      def self.parse_date_time(dt, tz = nil)
+        # Format is YYYYMMDD + "T" + hhmmss
+        matches = /^([0-9]{4})([0-1][0-9])([0-3][0-9])T([0-2][0-9])([0-5][0-9])([0-5][0-9])([Z]?)$/.match(dt)
+
+        unless matches
+          fail "The supplied iCalendar datetime value is incorrect: #{dt}"
+        end
+
+        tz = ActiveSupport::TimeZone.new('UTC') if matches[7] == 'Z' || tz.nil?
+        date = tz.parse("#{matches[1]}-#{matches[2]}-#{matches[3]} #{matches[4]}:#{matches[5]}:#{matches[6]}")
+
+        date
+      end
+
+      # Parses an iCalendar (rfc5545) formatted date and returns a DateTimeImmutable object.
+      #
+      # @param string date
+      # @param DateTimeZone tz
+      #
+      # @return DateTimeImmutable
+      def self.parse_date(date, tz = nil)
+        # Format is YYYYMMDD
+        matches = /^([0-9]{4})([0-1][0-9])([0-3][0-9])$/.match(date)
+
+        unless matches
+          fail "The supplied iCalendar date value is incorrect: #{date}"
+        end
+
+        tz = ActiveSupport::TimeZone.new('UTC') if tz.nil?
+
+        date = tz.parse("#{matches[1]}-#{matches[2]}-#{matches[3]}")
+
+        date
+      end
+
+      # Parses an iCalendar (RFC5545) formatted duration value.
+      #
+      # This method will either return a DateTimeInterval object, or a string
+      # suitable for strtotime or DateTime::modify.
+      #
+      # @param string duration
+      # @param bool as_string
+      #
+      # @return DateInterval|string
+      def self.parse_duration(duration, as_string = false)
+        matches = /^(?<plusminus>\+|-)?P((?<week>\d+)W)?((?<day>\d+)D)?(T((?<hour>\d+)H)?((?<minute>\d+)M)?((?<second>\d+)S)?)?$/.match(duration.to_s)
+
+        unless matches
+          fail "The supplied iCalendar duration value is incorrect: #{duration}"
+        end
+
+        unless as_string
+          invert = false
+
+          invert = true if matches['plusminus'] == '-'
+
+          parts = [
+            'week',
+            'day',
+            'hour',
+            'minute',
+            'second'
+          ]
+
+          new_matches = {}
+          parts.each do |part|
+            new_matches[part] = matches[part].to_i
+          end
+          matches = new_matches
+
+          # We need to re-construct the duration string, because weeks and
+          # days are not supported by DateInterval in the same string.
+          duration = matches['week'].weeks +
+                     matches['day'].days +
+                     matches['hour'].hours +
+                     matches['minute'].minutes +
+                     matches['second'].seconds
+
+          duration = -duration if invert
+
+          return duration
+        end
+
+        parts = [
+          'week',
+          'day',
+          'hour',
+          'minute',
+          'second'
+        ]
+
+        new_dur = ''
+
+        parts.each do |part|
+          new_dur += " #{matches[part]} #{part}s" if matches[part].to_i > 0
+        end
+
+        new_dur = (matches['plusminus'] == '-' ? '-' : '+') + new_dur.strip
+
+        new_dur = '+0 seconds' if new_dur == '+'
+
+        new_dur
+      end
+
+      # Parses either a Date or DateTime, or Duration value.
+      #
+      # @param string date
+      # @param DateTimeZone|string reference_tz
+      #
+      # @return DateTimeImmutable|DateInterval
+      def self.parse(date, reference_tz = nil)
+        if date[0] == 'P' || (date[0] == '-' && date[1] == 'P')
+          parse_duration(date)
+        elsif date.length == 8
+          parse_date(date, reference_tz)
+        else
+          parse_date_time(date, reference_tz)
+        end
+      end
+
+      # This method parses a vCard date and or time value.
+      #
+      # This can be used for the DATE, DATE-TIME, TIMESTAMP and
+      # DATE-AND-OR-TIME value.
+      #
+      # This method returns an array, not a DateTime value.
+      #
+      # The elements in the array are in the following order:
+      # year, month, date, hour, minute, second, timezone
+      #
+      # Almost any part of the string may be omitted. It's for example legal to
+      # just specify seconds, leave out the year, etc.
+      #
+      # Timezone is either returned as 'Z' or as '+0800'
+      #
+      # For any non-specified values null is returned.
+      #
+      # List of date formats that are supported:
+      # YYYY
+      # YYYY-MM
+      # YYYYMMDD
+      # --MMDD
+      # ---DD
+      #
+      # YYYY-MM-DD
+      # --MM-DD
+      # ---DD
+      #
+      # List of supported time formats:
+      #
+      # HH
+      # HHMM
+      # HHMMSS
+      # -MMSS
+      # --SS
+      #
+      # HH
+      # HH:MM
+      # HH:MM:SS
+      # -MM:SS
+      # --SS
+      #
+      # A full basic-format date-time string looks like :
+      # 20130603T133901
+      #
+      # A full extended-format date-time string looks like :
+      # 2013-06-03T13:39:01
+      #
+      # Times may be postfixed by a timezone offset. This can be either 'Z' for
+      # UTC, or a string like -0500 or +1100.
+      #
+      # @param string date
+      #
+      # @return array
+      def self.parse_v_card_date_time(date)
+        regex = /^
+            (?:  # date part
+                (?:
+                    (?: (?<year> [0-9]{4}) (?: -)?| --)
+                    (?<month> [0-9]{2})?
+                |---)
+                (?<date> [0-9]{2})?
+            )?
+            (?:T  # time part
+                (?<hour> [0-9]{2} | -)
+                (?<minute> [0-9]{2} | -)?
+                (?<second> [0-9]{2})?
+
+                (?: \.[0-9]{3})? # milliseconds
+                (?<timezone> # timezone offset
+
+                    Z | (?: \+|-)(?: [0-9]{4})
+
+                )?
+
+            )?
+            $/x
+
+        matches = regex.match(date)
+        unless matches
+          # Attempting to parse the extended format.
+          regex = /^
+              (?: # date part
+                  (?: (?<year> [0-9]{4}) - | -- )
+                  (?<month> [0-9]{2}) -
+                  (?<date> [0-9]{2})
+              )?
+              (?:T # time part
+
+                  (?: (?<hour> [0-9]{2}) : | -)
+                  (?: (?<minute> [0-9]{2}) : | -)?
+                  (?<second> [0-9]{2})?
+
+                  (?: \.[0-9]{3})? # milliseconds
+                  (?<timezone> # timezone offset
+
+                      Z | (?: \+|-)(?: [0-9]{2}:[0-9]{2})
+
+                  )?
+
+              )?
+              $/x
+
+          matches = regex.match(date)
+          unless matches
+            fail ArgumentError, "Invalid vCard date-time string: #{date}"
+          end
+        end
+
+        parts = [
+          'year',
+          'month',
+          'date',
+          'hour',
+          'minute',
+          'second',
+          'timezone'
+        ]
+
+        result = {}
+        parts.each do |part|
+          if matches[part].blank?
+            result[part] = nil
+          elsif matches[part] == '-' || matches[part] == '--'
+            result[part] = nil
+          else
+            if part == 'timezone'
+              result[part] = matches[part]
+            else
+              result[part] = matches[part].to_i
+            end
+          end
+        end
+
+        result
+      end
+
+      # This method parses a vCard TIME value.
+      #
+      # This method returns an array, not a DateTime value.
+      #
+      # The elements in the array are in the following order:
+      # hour, minute, second, timezone
+      #
+      # Almost any part of the string may be omitted. It's for example legal to
+      # just specify seconds, leave out the hour etc.
+      #
+      # Timezone is either returned as 'Z' or as '+08:00'
+      #
+      # For any non-specified values null is returned.
+      #
+      # List of supported time formats:
+      #
+      # HH
+      # HHMM
+      # HHMMSS
+      # -MMSS
+      # --SS
+      #
+      # HH
+      # HH:MM
+      # HH:MM:SS
+      # -MM:SS
+      # --SS
+      #
+      # A full basic-format time string looks like :
+      # 133901
+      #
+      # A full extended-format time string looks like :
+      # 13:39:01
+      #
+      # Times may be postfixed by a timezone offset. This can be either 'Z' for
+      # UTC, or a string like -0500 or +11:00.
+      #
+      # @param string date
+      #
+      # @return array
+      def self.parse_v_card_time(date)
+        regex = /^
+            (?<hour> [0-9]{2} | -)
+            (?<minute> [0-9]{2} | -)?
+            (?<second> [0-9]{2})?
+
+            (?: \.[0-9]{3})? # milliseconds
+            (?<timezone> # timezone offset
+
+                Z | (?: \+|-)(?: [0-9]{4})
+
+            )?
+            $/x
+
+        matches = regex.match(date)
+        unless matches
+          # Attempting to parse the extended format.
+          regex = /^
+              (?: (?<hour> [0-9]{2}) : | -)
+              (?: (?<minute> [0-9]{2}) : | -)?
+              (?<second> [0-9]{2})?
+
+              (?: \.[0-9]{3})? # milliseconds
+              (?<timezone> # timezone offset
+
+                  Z | (?: \+|-)(?: [0-9]{2}:[0-9]{2})
+
+              )?
+              $/x
+
+          matches = regex.match(date)
+          unless matches
+            fail ArgumentError, "Invalid vCard time string: #{date}"
+          end
+        end
+
+        parts = [
+          'hour',
+          'minute',
+          'second',
+          'timezone'
+        ]
+
+        result = {}
+        parts.each do |part|
+          if matches[part].blank?
+            result[part] = nil
+          elsif matches[part] == '-' || matches[part] == '--'
+            result[part] = nil
+          else
+            result[part] = matches[part]
+          end
+        end
+
+        result
+      end
+
+      # This method parses a vCard date and or time value.
+      #
+      # This can be used for the DATE, DATE-TIME and
+      # DATE-AND-OR-TIME value.
+      #
+      # This method returns an array, not a DateTime value.
+      # The elements in the array are in the following order:
+      #     year, month, date, hour, minute, second, timezone
+      # Almost any part of the string may be omitted. It's for example legal to
+      # just specify seconds, leave out the year, etc.
+      #
+      # Timezone is either returned as 'Z' or as '+0800'
+      #
+      # For any non-specified values null is returned.
+      #
+      # List of date formats that are supported:
+      #     20150128
+      #     2015-01
+      #     --01
+      #     --0128
+      #     ---28
+      #
+      # List of supported time formats:
+      #     13
+      #     1353
+      #     135301
+      #     -53
+      #     -5301
+      #     --01 (unreachable, see the tests)
+      #     --01Z
+      #     --01+1234
+      #
+      # List of supported date-time formats:
+      #     20150128T13
+      #     --0128T13
+      #     ---28T13
+      #     ---28T1353
+      #     ---28T135301
+      #     ---28T13Z
+      #     ---28T13+1234
+      #
+      # See the regular expressions for all the possible patterns.
+      #
+      # Times may be postfixed by a timezone offset. This can be either 'Z' for
+      # UTC, or a string like -0500 or +1100.
+      #
+      # @param string date
+      #
+      # @return array
+      def self.parse_v_card_date_and_or_time(date)
+        # \d{8}|\d{4}-\d\d|--\d\d(\d\d)?|---\d\d
+        value_date     = /^(?:
+                          (?<year>\d{4})(?<month>\d\d)(?<date>\d\d)
+                          |(?<year0>\d{4})-(?<month0>\d\d)
+                          |--(?<month1>\d\d)(?<date0>\d\d)?
+                          |---(?<date1>\d\d)
+                          )$/x
+
+        # (\d\d(\d\d(\d\d)?)?|-\d\d(\d\d)?|--\d\d)(Z|[+\-]\d\d(\d\d)?)?
+        value_time     = /^(?:
+                          ((?<hour>\d\d)((?<minute>\d\d)(?<second>\d\d)?)?
+                          |-(?<minute0>\d\d)(?<second0>\d\d)?
+                          |--(?<second1>\d\d))
+                          (?<timezone>(Z|[+\-]\d\d(\d\d)?))?
+                          )$/x
+
+        # (\d{8}|--\d{4}|---\d\d)T\d\d(\d\d(\d\d)?)?(Z|[+\-]\d\d(\d\d?)?
+        value_date_time = /^(?:
+                          ((?<year>\d{4})(?<month>\d\d)(?<date>\d\d)
+                          |--(?<month0>\d\d)(?<date0>\d\d)
+                          |---(?<date1>\d\d))
+                          T
+                          (?<hour>\d\d)((?<minute>\d\d)(?<second>\d\d)?)?
+                          (?<timezone>(Z|[+\-]\d\d(\d\d?)))?
+                          )$/x
+
+        # date-and-or-time is date | date-time | time
+        # in this strict order.
+        matches = value_date.match(date)
+        matches = value_date_time.match(date) unless matches
+        matches = value_time.match(date) unless matches
+        unless matches
+          fail ArgumentError, "Invalid vCard date-time string: #{date}"
+        end
+
+        map = {
+          'year'     => 'year',
+          'year0'    => 'year',
+          'month'    => 'month',
+          'month0'   => 'month',
+          'month1'   => 'month',
+          'date'     => 'date',
+          'date0'    => 'date',
+          'date1'    => 'date',
+          'hour'     => 'hour',
+          'minute'   => 'minute',
+          'minute0'  => 'minute',
+          'second'   => 'second',
+          'second0'  => 'second',
+          'second1'  => 'second',
+          'timezone' => 'timezone'
+        }
+
+        parts = {}
+        map.each do |key, real_key|
+          parts[real_key] ||= nil
+          parts[real_key] = matches[key] if matches.names.include?(key) && matches[key]
+        end
+
+        parts
+      end
+    end
+  end
+end

data/lib/tilia/v_object/document.rb

@@ -0,0 +1,218 @@
+module Tilia
+  module VObject
+    # Document.
+    #
+    # A document is just like a component, except that it's also the top level
+    # element.
+    #
+    # Both a VCALENDAR and a VCARD are considered documents.
+    #
+    # This class also provides a registry for document types.
+    class Document < Component
+      # Unknown document type.
+      UNKNOWN ||= 1
+
+      # vCalendar 1.0.
+      VCALENDAR10 ||= 2
+
+      # iCalendar 2.0.
+      ICALENDAR20 ||= 3
+
+      # vCard 2.1.
+      VCARD21 ||= 4
+
+      # vCard 3.0.
+      VCARD30 ||= 5
+
+      # vCard 4.0.
+      VCARD40 ||= 6
+
+      # The default name for this component.
+      #
+      # This should be 'VCALENDAR' or 'VCARD'.
+      #
+      # @var string
+      @default_name
+
+      # List of properties, and which classes they map to.
+      #
+      # @var array
+      @property_map = {}
+
+      # List of components, along with which classes they map to.
+      #
+      # @var array
+      @component_map = {}
+
+      # List of value-types, and which classes they map to.
+      #
+      # @var array
+      @value_map = {}
+
+      class << self
+        attr_accessor :default_name
+        attr_accessor :property_map
+        attr_accessor :component_map
+        attr_accessor :value_map
+      end
+
+      # Creates a new document.
+      #
+      # We're changing the default behavior slightly here. First, we don't want
+      # to have to specify a name (we already know it), and we want to allow
+      # children to be specified in the first argument.
+      #
+      # But, the default behavior also works.
+      #
+      # So the two sigs:
+      #
+      # new Document(array children = [], defaults = true)
+      # new Document(string name, array children = [], defaults = true)
+      #
+      # @return void
+      def initialize(*args)
+        if args.size == 0 || args[0].is_a?(Hash)
+          args.unshift(self.class.default_name)
+          args.unshift(self)
+
+          super(*args)
+        else
+          args.unshift(self)
+          super(*args)
+        end
+      end
+
+      # Returns the current document type.
+      #
+      # @return int
+      def document_type
+        self.class::UNKNOWN
+      end
+
+      # Creates a new component or property.
+      #
+      # If it's a known component, we will automatically call createComponent.
+      # otherwise, we'll assume it's a property and call createProperty instead.
+      #
+      # @param string name
+      # @param string arg1,... Unlimited number of args
+      #
+      # @return mixed
+      def create(name, *args)
+        if self.class.component_map.key?(name.upcase)
+          create_component(name, *args)
+        else
+          create_property(name, *args)
+        end
+      end
+
+      # Creates a new component.
+      #
+      # This method automatically searches for the correct component class, based
+      # on its name.
+      #
+      # You can specify the children either in key=>value syntax, in which case
+      # properties will automatically be created, or you can just pass a list of
+      # Component and Property object.
+      #
+      # By default, a set of sensible values will be added to the component. For
+      # an iCalendar object, this may be something like CALSCALE:GREGORIAN. To
+      # ensure that this does not happen, set defaults to false.
+      #
+      # @param string name
+      # @param array children
+      # @param bool defaults
+      #
+      # @return Component
+      def create_component(name, children = nil, defaults = true)
+        name = name.upcase
+
+        klass = Component
+
+        klass = self.class.component_map[name] if self.class.component_map.key?(name)
+
+        children = [] unless children
+        klass.new(self, name, children, defaults)
+      end
+
+      # Factory method for creating new properties.
+      #
+      # This method automatically searches for the correct property class, based
+      # on its name.
+      #
+      # You can specify the parameters either in key=>value syntax, in which case
+      # parameters will automatically be created, or you can just pass a list of
+      # Parameter objects.
+      #
+      # @param string name
+      # @param mixed value
+      # @param array parameters
+      # @param string value_type Force a specific valuetype, such as URI or TEXT
+      #
+      # @return Property
+      def create_property(name, value = nil, parameters = nil, value_type = nil)
+        parameters = {} unless parameters
+
+        # If there's a . in the name, it means it's prefixed by a groupname.
+        i = name.index('.')
+        if i
+          group = name[0...i]
+          name = name[i + 1..-1].upcase
+        else
+          name = name.upcase
+          group = nil
+        end
+
+        klass = nil
+
+        if value_type
+          # The valueType argument comes first to figure out the correct
+          # class.
+          klass = class_name_for_property_value(value_type)
+        end
+
+        unless klass
+          # If a VALUE parameter is supplied, we should use that.
+          if parameters.key?('VALUE')
+            klass = class_name_for_property_value(parameters['VALUE'])
+          else
+            klass = class_name_for_property_name(name)
+          end
+        end
+
+        klass.new(self, name, value, parameters, group)
+      end
+
+      # This method returns a full class-name for a value parameter.
+      #
+      # For instance, DTSTART may have VALUE=DATE. In that case we will look in
+      # our valueMap table and return the appropriate class name.
+      #
+      # This method returns null if we don't have a specialized class.
+      #
+      # @param string value_param
+      #
+      # @return void
+      def class_name_for_property_value(value_param)
+        value_param = value_param.upcase
+
+        return self.class.value_map[value_param] if self.class.value_map.key?(value_param)
+
+        nil
+      end
+
+      # Returns the default class for a property name.
+      #
+      # @param string property_name
+      #
+      # @return string
+      def class_name_for_property_name(property_name)
+        if self.class.property_map.key?(property_name)
+          self.class.property_map[property_name]
+        else
+          Property::Unknown
+        end
+      end
+    end
+  end
+end

data/lib/tilia/v_object/element_list.rb

@@ -0,0 +1,18 @@
+module Tilia
+  module VObject
+    # VObject ElementList.
+    #
+    # This class represents a list of elements. Lists are the result of queries,
+    # such as doing vcalendar.vevent where there's multiple VEVENT objects.
+    class ElementList < Array
+      def initialize(*args)
+        super(*args)
+        freeze
+      end
+
+      def delete(_offset)
+        fail 'RuntimeError: can\'t modify frozen Array'
+      end
+    end
+  end
+end