tilia-vobject 4.0.0.pre.alpha5 → 4.0.2

data/lib/tilia/v_object/date_time_parser.rb

@@ -12,16 +12,16 @@ module Tilia
       # 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
+      # @param [String] dt
+      # @param [ActiveSupport::TimeZone] tz
       #
-      # @return DateTimeImmutable
+      # @return [Time]
       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}"
+          fail InvalidDataException, "The supplied iCalendar datetime value is incorrect: #{dt}"
         end
 
         tz = ActiveSupport::TimeZone.new('UTC') if matches[7] == 'Z' || tz.nil?
@@ -32,16 +32,16 @@ module Tilia
 
       # Parses an iCalendar (rfc5545) formatted date and returns a DateTimeImmutable object.
       #
-      # @param string date
-      # @param DateTimeZone tz
+      # @param [String] date
+      # @param [ActiveSupport::TimeZone] tz
       #
-      # @return DateTimeImmutable
+      # @return [Time]
       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}"
+          fail InvalidDataException, "The supplied iCalendar date value is incorrect: #{date}"
         end
 
         tz = ActiveSupport::TimeZone.new('UTC') if tz.nil?
@@ -56,15 +56,15 @@ module Tilia
       # This method will either return a DateTimeInterval object, or a string
       # suitable for strtotime or DateTime::modify.
       #
-      # @param string duration
-      # @param bool as_string
+      # @param [String] duration
+      # @param [Boolean] as_string
       #
-      # @return DateInterval|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}"
+          fail InvalidDataException, "The supplied iCalendar duration value is incorrect: #{duration}"
         end
 
         unless as_string
@@ -122,10 +122,10 @@ module Tilia
 
       # Parses either a Date or DateTime, or Duration value.
       #
-      # @param string date
-      # @param DateTimeZone|string reference_tz
+      # @param [String] date
+      # @param [ActiveSupport::TimeZone|string] reference_tz
       #
-      # @return DateTimeImmutable|DateInterval
+      # @return [DateTimeImmutable|DateInterval]
       def self.parse(date, reference_tz = nil)
         if date[0] == 'P' || (date[0] == '-' && date[1] == 'P')
           parse_duration(date)
@@ -187,9 +187,9 @@ module Tilia
       # 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
+      # @param [String] date
       #
-      # @return array
+      # @return [array]
       def self.parse_v_card_date_time(date)
         regex = /^
             (?:  # date part
@@ -241,7 +241,7 @@ module Tilia
 
           matches = regex.match(date)
           unless matches
-            fail ArgumentError, "Invalid vCard date-time string: #{date}"
+            fail InvalidDataException, "Invalid vCard date-time string: #{date}"
           end
         end
 
@@ -310,9 +310,9 @@ module Tilia
       # 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
+      # @param [String] date
       #
-      # @return array
+      # @return [array]
       def self.parse_v_card_time(date)
         regex = /^
             (?<hour> [0-9]{2} | -)
@@ -345,7 +345,7 @@ module Tilia
 
           matches = regex.match(date)
           unless matches
-            fail ArgumentError, "Invalid vCard time string: #{date}"
+            fail InvalidDataException, "Invalid vCard time string: #{date}"
           end
         end
 
@@ -416,9 +416,9 @@ module Tilia
       # 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
+      # @param [String] date
       #
-      # @return array
+      # @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     = /^(?:
@@ -452,7 +452,7 @@ module Tilia
         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}"
+          fail InvalidDataException, "Invalid vCard date-time string: #{date}"
         end
 
         map = {

data/lib/tilia/v_object/document.rb

@@ -31,22 +31,22 @@ module Tilia
       #
       # This should be 'VCALENDAR' or 'VCARD'.
       #
-      # @var string
-      @default_name
+      # @return [String]
+      @default_name = nil
 
       # List of properties, and which classes they map to.
       #
-      # @var array
+      # @return [array]
       @property_map = {}
 
       # List of components, along with which classes they map to.
       #
-      # @var array
+      # @return [array]
       @component_map = {}
 
       # List of value-types, and which classes they map to.
       #
-      # @var array
+      # @return [array]
       @value_map = {}
 
       class << self
@@ -69,9 +69,9 @@ module Tilia
       # new Document(array children = [], defaults = true)
       # new Document(string name, array children = [], defaults = true)
       #
-      # @return void
+      # @return [void]
       def initialize(*args)
-        if args.size == 0 || args[0].is_a?(Hash)
+        if args.size == 0 || args[0].is_a?(Hash) || args[0].is_a?(Array)
           args.unshift(self.class.default_name)
           args.unshift(self)
 
@@ -84,9 +84,9 @@ module Tilia
 
       # Returns the current document type.
       #
-      # @return int
+      # @return [Fixnum]
       def document_type
-        self.class::UNKNOWN
+        UNKNOWN
       end
 
       # Creates a new component or property.
@@ -94,10 +94,10 @@ module Tilia
       # 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
+      # @param [String] name
+      # @param [String] arg1,... Unlimited number of args
       #
-      # @return mixed
+      # @return [mixed]
       def create(name, *args)
         if self.class.component_map.key?(name.upcase)
           create_component(name, *args)
@@ -119,11 +119,11 @@ module Tilia
       # 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
+      # @param [String] name
+      # @param [array] children
+      # @param [Boolean] defaults
       #
-      # @return Component
+      # @return [Component]
       def create_component(name, children = nil, defaults = true)
         name = name.upcase
 
@@ -144,12 +144,12 @@ module Tilia
       # 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
+      # @param [String] name
+      # @param value
+      # @param [array] parameters
+      # @param [String] value_type Force a specific valuetype, such as URI or TEXT
       #
-      # @return Property
+      # @return [Property]
       def create_property(name, value = nil, parameters = nil, value_type = nil)
         parameters = {} unless parameters
 
@@ -190,9 +190,9 @@ module Tilia
       #
       # This method returns null if we don't have a specialized class.
       #
-      # @param string value_param
+      # @param [String] value_param
       #
-      # @return void
+      # @return [void]
       def class_name_for_property_value(value_param)
         value_param = value_param.upcase
 
@@ -203,9 +203,9 @@ module Tilia
 
       # Returns the default class for a property name.
       #
-      # @param string property_name
+      # @param [String] property_name
       #
-      # @return string
+      # @return [String]
       def class_name_for_property_name(property_name)
         if self.class.property_map.key?(property_name)
           self.class.property_map[property_name]

data/lib/tilia/v_object/free_busy_data.rb

@@ -4,17 +4,17 @@ module Tilia
     class FreeBusyData
       # Start timestamp
       #
-      # @var int
+      # @return [Fixnum]
       # RUBY: attr_accessor :start
 
       # End timestamp
       #
-      # @var int
+      # @return [Fixnum]
       # RUBY: attr_accessor :end
 
       # A list of free-busy times.
       #
-      # @var array
+      # @return [array]
       # RUBY: attr_accessor :data
 
       def initialize(start, ending)
@@ -31,10 +31,10 @@ module Tilia
 
       # Adds free or busytime to the data.
       #
-      # @param int start
-      # @param int end
-      # @param string type FREE, BUSY, BUSY-UNAVAILABLE or BUSY-TENTATIVE
-      # @return void
+      # @param [Fixnum] start
+      # @param [Fixnum] end
+      # @param [String] type FREE, BUSY, BUSY-UNAVAILABLE or BUSY-TENTATIVE
+      # @return [void]
       def add(start, ending, type)
         if start > @end || ending < @start
           # This new data is outside our timerange.

data/lib/tilia/v_object/free_busy_generator.rb

@@ -11,22 +11,22 @@ module Tilia
     class FreeBusyGenerator
       # Input objects.
       #
-      # @var array
+      # @return [array]
       # RUBY: attr_accessor :objects
 
       # Start of range.
       #
-      # @var DateTimeInterface|null
+      # @return [DateTimeInterface, nil]
       # RUBY: attr_accessor :start
 
       # End of range.
       #
-      # @var DateTimeInterface|null
+      # @return [DateTimeInterface, nil]
       # RUBY: attr_accessor :end
 
       # VCALENDAR object.
       #
-      # @var Document
+      # @return [Document]
       # RUBY: attr_accessor :base_object
 
       # Reference timezone.
@@ -39,7 +39,7 @@ module Tilia
       #
       # This defaults to UTC.
       #
-      # @var DateTimeZone
+      # @return [ActiveSupport::TimeZone]
       # RUBY: attr_accessor :time_zone
 
       # A VAVAILABILITY document.
@@ -47,7 +47,7 @@ module Tilia
       # If this is set, it's information will be included when calculating
       # freebusy time.
       #
-      # @var Document
+      # @return [Document]
       # RUBY: attr_accessor :vavailability
 
       # Creates the generator.
@@ -55,10 +55,10 @@ module Tilia
       # Check the setTimeRange and setObjects methods for details about the
       # arguments.
       #
-      # @param DateTimeInterface start
-      # @param DateTimeInterface end
-      # @param mixed objects
-      # @param DateTimeZone time_zone
+      # @param [Time] start
+      # @param [Time] end
+      # @param objects
+      # @param [ActiveSupport::TimeZone] time_zone
       def initialize(start = nil, ending = nil, objects = nil, time_zone = nil)
         start = Time.zone.parse(Settings.min_date) unless start
         ending = Time.zone.parse(Settings.max_date) unless ending
@@ -78,14 +78,14 @@ module Tilia
       #
       # The VFREEBUSY object will be automatically added though.
       #
-      # @param Document vcalendar
-      # @return void
+      # @param [Document] vcalendar
+      # @return [void]
       attr_writer :base_object
 
       # Sets a VAVAILABILITY document.
       #
-      # @param Document vcalendar
-      # @return void
+      # @param [Document] vcalendar
+      # @return [void]
       def v_availability=(vcalendar)
         @vavailability = vcalendar
       end
@@ -96,9 +96,9 @@ module Tilia
       # Component.
       # It's also possible to specify multiple objects as an array.
       #
-      # @param mixed objects
+      # @param objects
       #
-      # @return void
+      # @return [void]
       def objects=(objects)
         objects = [objects] unless objects.is_a?(Array)
 
@@ -118,10 +118,10 @@ module Tilia
       #
       # Any freebusy object falling outside of this time range will be ignored.
       #
-      # @param DateTimeInterface start
-      # @param DateTimeInterface end
+      # @param [Time] start
+      # @param [Time] end
       #
-      # @return void
+      # @return [void]
       def time_range=(range)
         @start = range.begin
         @end = range.end
@@ -129,17 +129,15 @@ module Tilia
 
       # Sets the reference timezone for floating times.
       #
-      # @param DateTimeZone time_zone
+      # @param [ActiveSupport::TimeZone] time_zone
       #
-      # @return void
-      def time_zone=(time_zone)
-        @time_zone = time_zone
-      end
+      # @return [void]
+      attr_writer :time_zone
 
       # Parses the input data and returns a correct VFREEBUSY object, wrapped in
       # a VCALENDAR.
       #
-      # @return Component
+      # @return [Component]
       def result
         fb_data = FreeBusyData.new(@start.to_i, @end.to_i)
 
@@ -154,9 +152,9 @@ module Tilia
       # This method takes a VAVAILABILITY component and figures out all the
       # available times.
       #
-      # @param FreeBusyData fb_data
-      # @param VCalendar vavailability
-      # @return void
+      # @param [FreeBusyData] fb_data
+      # @param [VCalendar] vavailability
+      # @return [void]
       def calculate_availability(fb_data, vavailability)
         vavail_comps = vavailability['VAVAILABILITY'].to_a
         vavail_comps.sort! do |a, b|
@@ -201,13 +199,13 @@ module Tilia
           skip = false
           new.each do |higher_vavail|
             (higher_start, higher_end) = higher_vavail.effective_start_end
-            if (higher_start.nil? || higher_start < comp_start) &&
-               (higher_end.nil? || higher_end > comp_end)
-              # Component is fully covered by a higher priority
-              # component. We can skip this component.
-              skip = true
-              break
-            end
+
+            next unless (higher_start.nil? || higher_start < comp_start) && (higher_end.nil? || higher_end > comp_end)
+
+            # Component is fully covered by a higher priority
+            # component. We can skip this component.
+            skip = true
+            break
           end
           next if skip
 
@@ -238,50 +236,50 @@ module Tilia
           )
 
           # Looping over the AVAILABLE components.
-          if vavail.key?('AVAILABLE')
-            vavail['AVAILABLE'].each do |available|
-              (avail_start, avail_end) = available.effective_start_end
-              fb_data.add(
-                avail_start.to_i,
-                avail_end.to_i,
-                'FREE'
-              )
+          next unless vavail.key?('AVAILABLE')
 
-              if available['RRULE']
-                # Our favourite thing: recurrence!!
-                rrule_iterator = Recur::RRuleIterator.new(
-                  available['RRULE'].value,
-                  avail_start
-                )
+          vavail['AVAILABLE'].each do |available|
+            (avail_start, avail_end) = available.effective_start_end
+            fb_data.add(
+              avail_start.to_i,
+              avail_end.to_i,
+              'FREE'
+            )
 
-                rrule_iterator.fast_forward(vavail_start)
+            next unless available['RRULE']
 
-                start_end_diff = avail_end - avail_start
+            # Our favourite thing: recurrence!!
+            rrule_iterator = Recur::RRuleIterator.new(
+              available['RRULE'].value,
+              avail_start
+            )
 
-                while rrule_iterator.valid
-                  recur_start = rrule_iterator.current
-                  recur_end = recur_start + start_end_diff
+            rrule_iterator.fast_forward(vavail_start)
 
-                  if recur_start > vavail_end
-                    # We're beyond the legal timerange.
-                    break
-                  end
+            start_end_diff = avail_end - avail_start
 
-                  if recur_end > vavail_end
-                    # Truncating the end if it exceeds the
-                    # VAVAILABILITY end.
-                    recur_end = vavail_end
-                  end
+            while rrule_iterator.valid
+              recur_start = rrule_iterator.current
+              recur_end = recur_start + start_end_diff
 
-                  fb_data.add(
-                    recur_start.to_i,
-                    recur_end.to_i,
-                    'FREE'
-                  )
+              if recur_start > vavail_end
+                # We're beyond the legal timerange.
+                break
+              end
 
-                  rrule_iterator.next
-                end
+              if recur_end > vavail_end
+                # Truncating the end if it exceeds the
+                # VAVAILABILITY end.
+                recur_end = vavail_end
               end
+
+              fb_data.add(
+                recur_start.to_i,
+                recur_end.to_i,
+                'FREE'
+              )
+
+              rrule_iterator.next
             end
           end
         end
@@ -290,8 +288,8 @@ module Tilia
       # This method takes an array of iCalendar objects and applies its busy
       # times on fbData.
       #
-      # @param FreeBusyData fb_data
-      # @param VCalendar[] objects
+      # @param [FreeBusyData] fb_data
+      # @param [VCalendar[]] objects
       def calculate_busy(fb_data, objects)
         objects.each_with_index do |object, key|
           object.base_components.each do |component|
@@ -317,7 +315,7 @@ module Tilia
                 if component.key?('RRULE')
                   begin
                     iterator = Recur::EventIterator.new(object, component['UID'].to_s, @time_zone)
-                  rescue Recur::NoInstancesException => e
+                  rescue Recur::NoInstancesException
                     # This event is recurring, but it doesn't have a single
                     # instance. We are skipping this event from the output
                     # entirely.
@@ -327,7 +325,7 @@ module Tilia
 
                   iterator.fast_forward(@start) if @start
 
-                  max_recurrences = 200
+                  max_recurrences = Settings.max_recurrences
 
                   while iterator.valid && max_recurrences > 0
                     max_recurrences -= 1
@@ -409,7 +407,7 @@ module Tilia
       # This method takes a FreeBusyData object and generates the VCALENDAR
       # object associated with it.
       #
-      # @return VCalendar
+      # @return [VCalendar]
       def generate_free_busy_calendar(fb_data)
         if @base_object
           calendar = @base_object