tilia-vobject 4.0.0.pre.alpha5 → 4.0.2

data/lib/tilia/v_object/component.rb

@@ -21,12 +21,12 @@ module Tilia
       #
       # This will contain a string such as VEVENT, VTODO, VCALENDAR, VCARD.
       #
-      # @var string
+      # @return [String]
       attr_accessor :name
 
       # A list of properties and/or sub-components.
       #
-      # @var array
+      # @return [array]
       # RUBY: attr_accessor :children
 
       # Creates a new component.
@@ -39,12 +39,12 @@ module Tilia
       # an iCalendar object, this may be something like CALSCALE:GREGORIAN. To
       # ensure that this does not happen, set defaults to false.
       #
-      # @param Document root
-      # @param string name such as VCALENDAR, VEVENT.
-      # @param array children
-      # @param bool defaults
+      # @param [Document] root
+      # @param [String] name such as VCALENDAR, VEVENT.
+      # @param [array] children
+      # @param [Boolean] defaults
       #
-      # @return void
+      # @return [void]
       def initialize(root, name, children = {}, defaults = true)
         @children = {}
         @name = name.to_s.upcase
@@ -104,17 +104,16 @@ module Tilia
       # add(name, array children = []) // Adds a new component
       # by name.
       #
-      # @return Node
-      def add(a1, a2 = nil, a3 = nil)
-        if a1.is_a?(Node)
-          unless a2.nil?
+      # @return [Node]
+      def add(*arguments)
+        if arguments[0].is_a?(Node)
+          if arguments[1]
             fail ArgumentError, 'The second argument must not be specified, when passing a VObject Node'
           end
-          a1.parent = self
-          new_node = a1
-        elsif a1.is_a?(String)
-          new_node = @root.create(a1, a2, a3)
-          new_node.parent = self
+          arguments[0].parent = self
+          new_node = arguments[0]
+        elsif arguments[0].is_a?(String)
+          new_node = @root.create(*arguments)
         else
           fail ArgumentError, 'The first argument must either be a Node or a string'
         end
@@ -136,8 +135,8 @@ module Tilia
       # pass an instance of a property or component, in which case only that
       # exact item will be removed.
       #
-      # @param string|Property|Component item
-      # @return void
+      # @param [String|Property|Component] item
+      # @return [void]
       def remove(item)
         if item.is_a?(String)
           # If there's no dot in the name, it's an exact property name and
@@ -168,7 +167,7 @@ module Tilia
       # Returns a flat list of all the properties and components in this
       # component.
       #
-      # @return array
+      # @return [array]
       def children
         result = []
         @children.each do |_, child_group|
@@ -181,7 +180,7 @@ module Tilia
       # This method only returns a list of sub-components. Properties are
       # ignored.
       #
-      # @return array
+      # @return [array]
       def components
         result = []
 
@@ -203,8 +202,8 @@ module Tilia
       # string ("HOME.EMAIL"). If you want to search on a specific property that
       # has not been assigned a group, specify ".EMAIL".
       #
-      # @param string name
-      # @return array
+      # @param [String] name
+      # @return [array]
       def select(name)
         group = nil
         name = name.upcase
@@ -243,7 +242,7 @@ module Tilia
 
       # Turns the object back into a serialized blob.
       #
-      # @return string
+      # @return [String]
       def serialize
         str = "BEGIN:#{@name}\r\n"
 
@@ -256,10 +255,10 @@ module Tilia
         # space to accomodate elements. The key is added to the score to
         # preserve the original relative order of elements.
         #
-        # @param int key
-        # @param array array
+        # @param [Fixnum] key
+        # @param [array] array
         #
-        # @return int
+        # @return [Fixnum]
         sort_score = lambda do |key, array|
           key = array.index(key)
           if array[key].is_a?(Component)
@@ -305,7 +304,7 @@ module Tilia
       # 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
+      # @return [array]
       def json_serialize
         components = []
         properties = []
@@ -330,9 +329,9 @@ module Tilia
       # This method serializes the data into XML. This is used to create xCard or
       # xCal documents.
       #
-      # @param Xml\Writer writer  XML writer.
+      # @param [Xml\Writer] writer  XML writer.
       #
-      # @return void
+      # @return [void]
       def xml_serialize(writer)
         components = []
         properties = []
@@ -372,7 +371,7 @@ module Tilia
 
       # This method should return a list of default property values.
       #
-      # @return array
+      # @return [array]
       def defaults
         []
       end
@@ -388,9 +387,9 @@ module Tilia
       #
       # event = calendar->VEVENT
       #
-      # @param string name
+      # @param [String] name
       #
-      # @return Property
+      # @return [Property]
       def [](name)
         return super(name) if name.is_a?(Fixnum)
 
@@ -404,7 +403,7 @@ module Tilia
           return nil
         else
           first_match = matches.first
-          # @var first_match Property
+          # @return [first_match] Property
           first_match.iterator = ElementList.new(matches.to_a)
           return first_match
         end
@@ -412,9 +411,9 @@ module Tilia
 
       # This method checks if a sub-element with the specified name exists.
       #
-      # @param string name
+      # @param [String] name
       #
-      # @return bool
+      # @return [Boolean]
       def key?(name)
         matches = select(name)
         matches.any?
@@ -428,10 +427,10 @@ module Tilia
       # If the item already exists, it will be removed. If you want to add
       # a new item with the same name, always use the add method.
       #
-      # @param string name
-      # @param mixed value
+      # @param [String] name
+      # @param value
       #
-      # @return void
+      # @return [void]
       def []=(name, value)
         return super(name, value) if name.is_a?(Fixnum)
         name = name.upcase
@@ -448,9 +447,9 @@ module Tilia
       # Removes all properties and components within this component with the
       # specified name.
       #
-      # @param string name
+      # @param [String] name
       #
-      # @return void
+      # @return [void]
       def delete(name)
         return super(name) if name.is_a?(Fixnum)
         remove(name)
@@ -459,7 +458,7 @@ module Tilia
       # This method is automatically called when the object is cloned.
       # Specifically, this will ensure all child elements are also cloned.
       #
-      # @return void
+      # @return [void]
       def initialize_copy(_original)
         new_children = {}
         @children.each do |child_name, child_group|
@@ -492,7 +491,7 @@ module Tilia
       # See the VEVENT implementation for getValidationRules for a more complex
       # example.
       #
-      # @var array
+      # @return [array]
       def validation_rules
         []
       end
@@ -516,9 +515,9 @@ module Tilia
       #   2 - A warning.
       #   3 - An error.
       #
-      # @param int options
+      # @param [Fixnum] options
       #
-      # @return array
+      # @return [array]
       def validate(options = 0)
         rules = validation_rules
         defaults = self.defaults
@@ -551,7 +550,7 @@ module Tilia
           when '1'
             if !property_counters.key?(prop_name) || property_counters[prop_name] != 1
               repaired = false
-              add(prop_name, defaults[prop_name]) if options & self.class::REPAIR > 0 && defaults.key?(prop_name)
+              add(prop_name, defaults[prop_name]) if options & REPAIR > 0 && defaults.key?(prop_name)
 
               messages << {
                 'level'   => repaired ? 1 : 3,
@@ -587,14 +586,12 @@ module Tilia
       # It's intended to remove all circular references, so PHP can easily clean
       # it up.
       #
-      # @return void
+      # @return [void]
       def destroy
         super
 
-        @children.each do |child_name, child_group|
-          child_group.each do |child|
-            child.destroy
-          end
+        @children.each do |_child_name, child_group|
+          child_group.each(&:destroy)
         end
 
         @children = {}

data/lib/tilia/v_object/component/available.rb

@@ -15,10 +15,10 @@ module Tilia
         # If either the start or end is 'unbounded' its value will be null
         # instead.
         #
-        # @return array
+        # @return [Array<Time, nil>]
         def effective_start_end
           effective_start = self['DTSTART'].date_time
-          if key? 'DTEND'
+          if key?('DTEND')
             effective_end = self['DTEND'].date_time
           else
             effective_end = effective_start + DateTimeParser.parse_duration(self['DURATION'])
@@ -27,19 +27,7 @@ module Tilia
           [effective_start, effective_end]
         end
 
-        # A simple list of validation rules.
-        #
-        # This is simply a list of properties, and how many times they either
-        # must or must not appear.
-        #
-        # Possible values per property:
-        #   * 0 - Must not appear.
-        #   * 1 - Must appear exactly once.
-        #   * + - Must appear at least once.
-        #   * * - Can appear any number of times.
-        #   * ? - May appear, but not more than once.
-        #
-        # @var array
+        # (see Component#validation_rules)
         def validation_rules
           {
             'UID'     => 1,
@@ -66,28 +54,7 @@ module Tilia
           }
         end
 
-        # Validates the node for correctness.
-        #
-        # The following options are supported:
-        #   Node::REPAIR - May attempt to automatically repair the problem.
-        #   Node::PROFILE_CARDDAV - Validate the vCard for CardDAV purposes.
-        #   Node::PROFILE_CALDAV - Validate the iCalendar for CalDAV purposes.
-        #
-        # 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 - A warning.
-        #   3 - An error.
-        #
-        # @param int options
-        #
-        # @return array
+        # (see Component#validate)
         def validate(options = 0)
           result = super(options)
 

data/lib/tilia/v_object/component/v_alarm.rb

@@ -9,7 +9,7 @@ module Tilia
         #
         # This ignores repeated alarm, only the first trigger is returned.
         #
-        # @return DateTimeImmutable
+        # @return [Time]
         def effective_trigger_time
           trigger = self['TRIGGER']
           if !trigger.key?('VALUE') || trigger['VALUE'].to_s.upcase == 'DURATION'
@@ -32,7 +32,7 @@ module Tilia
               elsif parent_component.name == 'VEVENT'
                 end_prop = 'DTEND'
               else
-                fail 'time-range filters on VALARM components are only supported when they are a child of VTODO or VEVENT'
+                fail InvalidDataException, 'time-range filters on VALARM components are only supported when they are a child of VTODO or VEVENT'
               end
 
               if parent_component.key?(end_prop)
@@ -61,10 +61,10 @@ module Tilia
         # The rules used to determine if an event falls within the specified
         # time-range is based on the CalDAV specification.
         #
-        # @param DateTime start
-        # @param DateTime ending
+        # @param [Time] start
+        # @param [Time] ending
         #
-        # @return bool
+        # @return [Boolean]
         def in_time_range?(start, ending)
           effective_trigger = effective_trigger_time
 
@@ -86,19 +86,7 @@ module Tilia
           end
         end
 
-        # A simple list of validation rules.
-        #
-        # This is simply a list of properties, and how many times they either
-        # must or must not appear.
-        #
-        # Possible values per property:
-        #   * 0 - Must not appear.
-        #   * 1 - Must appear exactly once.
-        #   * + - Must appear at least once.
-        #   * * - Can appear any number of times.
-        #   * ? - May appear, but not more than once.
-        #
-        # @var array
+        # (see Component#validation_rules)
         def validation_rules
           {
             'ACTION'  => 1,

data/lib/tilia/v_object/component/v_availability.rb

@@ -14,10 +14,10 @@ module Tilia
         #
         # https://tools.ietf.org/html/draft-daboo-calendar-availability-05#section-3.1
         #
-        # @param DateTimeInterface start
-        # @param DateTimeInterface ending
+        # @param [Time] start
+        # @param [Time] ending
         #
-        # @return bool
+        # @return [Boolean]
         def in_time_range?(start, ending)
           (effective_start, effective_end) = effective_start_end
           (effective_start.nil? || start < effective_end) &&
@@ -33,7 +33,7 @@ module Tilia
         # If either the start or end is 'unbounded' its value will be null
         # instead.
         #
-        # @return array
+        # @return [Array<Time, nil>]
         def effective_start_end
           effective_start = nil
           effective_end = nil
@@ -49,19 +49,7 @@ module Tilia
           [effective_start, effective_end]
         end
 
-        # A simple list of validation rules.
-        #
-        # This is simply a list of properties, and how many times they either
-        # must or must not appear.
-        #
-        # Possible values per property:
-        #   * 0 - Must not appear.
-        #   * 1 - Must appear exactly once.
-        #   * + - Must appear at least once.
-        #   * * - Can appear any number of times.
-        #   * ? - May appear, but not more than once.
-        #
-        # @var array
+        # (see Component#validation_rules)
         def validation_rules
           {
             'UID'     => 1,
@@ -87,28 +75,7 @@ module Tilia
           }
         end
 
-        # Validates the node for correctness.
-        #
-        # The following options are supported:
-        #   Node::REPAIR - May attempt to automatically repair the problem.
-        #   Node::PROFILE_CARDDAV - Validate the vCard for CardDAV purposes.
-        #   Node::PROFILE_CALDAV - Validate the iCalendar for CalDAV purposes.
-        #
-        # 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 - A warning.
-        #   3 - An error.
-        #
-        # @param int options
-        #
-        # @return array
+        # (see Component#validate)
         def validate(options = 0)
           result = super(options)
 

data/lib/tilia/v_object/component/v_calendar.rb

@@ -9,13 +9,14 @@ module Tilia
         #
         # This should be 'VCALENDAR' or 'VCARD'.
         #
-        # @var string
+        # @return [String]
         @default_name = 'VCALENDAR'
 
         # This is a list of components, and which classes they should map to.
         #
-        # @var array
+        # @return [Hash]
         @component_map = {
+          'VCALENDAR'     => Component::VCalendar,
           'VALARM'        => Component::VAlarm,
           'VEVENT'        => Component::VEvent,
           'VFREEBUSY'     => Component::VFreeBusy,
@@ -28,7 +29,7 @@ module Tilia
 
         # List of value-types, and which classes they map to.
         #
-        # @var array
+        # @return [Hash]
         @value_map = {
           'BINARY'           => Property::Binary,
           'BOOLEAN'          => Property::Boolean,
@@ -49,7 +50,7 @@ module Tilia
 
         # List of properties, and which classes they map to.
         #
-        # @var array
+        # @return [Hash]
         @property_map = {
           # Calendar properties
           'CALSCALE'      => Property::FlatText,
@@ -128,9 +129,9 @@ module Tilia
 
         # Returns the current document type.
         #
-        # @return int
+        # @return [Fixnum]
         def document_type
-          self.class::ICALENDAR20
+          ICALENDAR20
         end
 
         # Returns a list of all 'base components'. For instance, if an Event has
@@ -139,9 +140,9 @@ module Tilia
         #
         # VTIMEZONE components will always be excluded.
         #
-        # @param string component_name filter by component name
+        # @param [String] component_name filter by component name
         #
-        # @return VObject\Component[]
+        # @return [Array<Component>]
         def base_components(component_name = nil)
           is_base_component = lambda do |component|
             return false unless component.is_a?(Component)
@@ -178,9 +179,9 @@ module Tilia
         #
         # If there is no such component, null will be returned.
         #
-        # @param string component_name filter by component name
+        # @param [String] component_name filter by component name
         #
-        # @return VObject\Component|null
+        # @return [Component, nil]
         def base_component(component_name = nil)
           is_base_component = lambda do |component|
             return false unless component.is_a?(Component)
@@ -205,6 +206,9 @@ module Tilia
           nil
         end
 
+        # Expand all events in this VCalendar object and return a new VCalendar
+        # with the expanded events.
+        #
         # If this calendar object, has events with recurrence rules, this method
         # can be used to expand the event into multiple sub-events.
         #
@@ -215,43 +219,59 @@ module Tilia
         # In addition, this method will cause timezone information to be stripped,
         # and normalized to UTC.
         #
-        # This method will alter the VCalendar. This cannot be reversed.
-        #
-        # This functionality is specifically used by the CalDAV standard. It is
-        # possible for clients to request expand events, if they are rather simple
-        # clients and do not have the possibility to calculate recurrences.
+        # @param [Time] start
+        # @param [Time] end
+        # @param [ActiveSupport::TimeZone, nil] time_zone reference timezone for floating dates and
+        #                                       times.
         #
-        # @param DateTimeInterface start
-        # @param DateTimeInterface end
-        # @param DateTimeZone time_zone reference timezone for floating dates and
-        #                     times.
-        #
-        # @return void
+        # @return [VCalendar]
         def expand(start, ending, time_zone = nil)
-          new_events = []
-
-          time_zone = ActiveSupport::TimeZone.new('UTC') unless time_zone
-
-          # An array of events. Events are indexed by UID. Each item in this
-          # array is a list of one or more events that match the UID.
+          new_children = []
           recurring_events = {}
 
-          select('VEVENT').each do |vevent|
-            uid = vevent['UID'].to_s
-            fail 'Event did not have a UID!' if uid.blank?
+          time_zone = ActiveSupport::TimeZone.new('UTC') unless time_zone
 
-            if vevent.key?('RECURRENCE-ID') || vevent.key?('RRULE')
-              if recurring_events.key?(uid)
-                recurring_events[uid] << vevent
-              else
-                recurring_events[uid] = [vevent]
+          strip_timezones = lambda do |component|
+            component.children.each do |component_child|
+              if component_child.is_a?(Property::ICalendar::DateTime) && component_child.time?
+                dt = component_child.date_times(time_zone)
+
+                # We only need to update the first timezone, because
+                # setDateTimes will match all other timezones to the
+                # first.
+                dt[0] = dt[0].in_time_zone(ActiveSupport::TimeZone.new('UTC'))
+                component_child.date_times = dt
+              elsif component_child.is_a?(Component)
+                strip_timezones.call(component_child)
               end
-              next
             end
 
-            unless vevent.key?('RRULE')
-              new_events << vevent if vevent.in_time_range?(start, ending)
-              next
+            component
+          end
+
+          children.each do |child|
+            if child.is_a?(Property) && child.name != 'PRODID'
+              # We explictly want to ignore PRODID, because we want to
+              # overwrite it with our own.
+              new_children << child.clone
+            elsif child.is_a?(Component) && child.name != 'VTIMEZONE'
+              # We're also stripping all VTIMEZONE objects because we're
+              # converting everything to UTC.
+
+              if child.name == 'VEVENT' && (child.key?('RECURRENCE-ID') || child.key?('RRULE') || child.key?('RDATE'))
+                # Handle these a bit later.
+                uid = child['UID'].to_s
+
+                fail InvalidDataException, 'Every VEVENT object must have a UID property' if uid.blank?
+
+                if recurring_events.key?(uid)
+                  recurring_events[uid] << child.clone
+                else
+                  recurring_events[uid] = [child.clone]
+                end
+              elsif child.name == 'VEVENT' && child.in_time_range?(start, ending)
+                new_children << strip_timezones.call(child.clone)
+              end
             end
           end
 
@@ -268,38 +288,19 @@ module Tilia
             it.fast_forward(start)
 
             while it.valid && it.dt_start < ending
-              new_events << it.event_object if it.dt_end > start
+              new_children << strip_timezones.call(it.event_object) if it.dt_end > start
               it.next
             end
           end
 
-          # Wiping out all old VEVENT objects
-          delete('VEVENT')
-
-          # Setting all properties to UTC time.
-          new_events.each do |new_event|
-            new_event.children.each do |child|
-              next unless child.is_a?(Property::ICalendar::DateTime) && child.time?
-              dt = child.date_times(time_zone)
-              # We only need to update the first timezone, because
-              # setDateTimes will match all other timezones to the
-              # first.
-              dt[0] = dt[0].in_time_zone(ActiveSupport::TimeZone.new('UTC'))
-              child.date_times = dt
-            end
-
-            add(new_event)
-          end
-
-          # Removing all VTIMEZONE components
-          delete('VTIMEZONE')
+          self.class.new(new_children)
         end
 
         protected
 
         # This method should return a list of default property values.
         #
-        # @return array
+        # @return [Hash]
         def defaults
           {
             'VERSION'  => '2.0',
@@ -310,19 +311,7 @@ module Tilia
 
         public
 
-        # A simple list of validation rules.
-        #
-        # This is simply a list of properties, and how many times they either
-        # must or must not appear.
-        #
-        # Possible values per property:
-        #   * 0 - Must not appear.
-        #   * 1 - Must appear exactly once.
-        #   * + - Must appear at least once.
-        #   * * - Can appear any number of times.
-        #   * ? - May appear, but not more than once.
-        #
-        # @var array
+        # (see Component#validation_rules)
         def validation_rules
           {
             'PRODID'  => 1,
@@ -333,28 +322,7 @@ module Tilia
           }
         end
 
-        # Validates the node for correctness.
-        #
-        # The following options are supported:
-        #   Node::REPAIR - May attempt to automatically repair the problem.
-        #   Node::PROFILE_CARDDAV - Validate the vCard for CardDAV purposes.
-        #   Node::PROFILE_CALDAV - Validate the iCalendar for CalDAV purposes.
-        #
-        # 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 - A warning.
-        #   3 - An error.
-        #
-        # @param int options
-        #
-        # @return array
+        # (see Component#validate)
         def validate(options = 0)
           warnings = super(options)
 
@@ -410,7 +378,7 @@ module Tilia
             }
           end
 
-          if options & self.class::PROFILE_CALDAV > 0
+          if options & PROFILE_CALDAV > 0
             if uid_list.size > 1
               warnings << {
                 'level'   => 3,
@@ -450,7 +418,7 @@ module Tilia
 
         # Returns all components with a specific UID value.
         #
-        # @return array
+        # @return [array]
         def by_uid(uid)
           components.select do |item|
             item_uid = item.select('UID')