tilia-vobject 4.0.0.pre.alpha5 → 4.0.2

data/lib/tilia/v_object/recur/r_rule_iterator.rb

@@ -11,8 +11,8 @@ module Tilia
       class RRuleIterator
         # Creates the Iterator.
         #
-        # @param string|array rrule
-        # @param DateTimeInterface start
+        # @param [String|array] rrule
+        # @param [Time] start
         def initialize(rrule, start)
           @week_start = 'MO'
           @counter = 0
@@ -48,7 +48,7 @@ module Tilia
 
         # Returns the current item number.
         #
-        # @return int
+        # @return [Fixnum]
         def key
           @counter
         end
@@ -57,7 +57,7 @@ module Tilia
         # iterator. This will return false if we've gone beyond the UNTIL or COUNT
         # statements.
         #
-        # @return bool
+        # @return [Boolean]
         def valid
           return @counter < @count if @count
           @until.nil? || @current_date <= @until
@@ -65,7 +65,7 @@ module Tilia
 
         # Resets the iterator.
         #
-        # @return void
+        # @return [void]
         def rewind
           @current_date = @start_date.clone
           @counter = 0
@@ -73,7 +73,7 @@ module Tilia
 
         # Goes on to the next iteration.
         #
-        # @return void
+        # @return [void]
         def next
           # Otherwise, we find the next event in the normal RRULE
           # sequence.
@@ -95,7 +95,7 @@ module Tilia
 
         # Returns true if this recurring event never ends.
         #
-        # @return bool
+        # @return [Boolean]
         def infinite?
           !@count && !@until
         end
@@ -103,153 +103,25 @@ module Tilia
         # This method allows you to quickly go to the next occurrence after the
         # specified date.
         #
-        # @param DateTimeInterface dt
+        # @param [Time] dt
         #
-        # @return void
+        # @return [void]
         def fast_forward(dt)
           self.next while valid && @current_date < dt
         end
 
         protected
 
-        # The reference start date/time for the rrule.
-        #
-        # All calculations are based on this initial date.
-        #
-        # @var DateTimeInterface
-        # RUBY attr_accessor :start_date
-
-        # The date of the current iteration. You can get this by calling
-        # .current.
-        #
-        # @var DateTimeInterface
-        # RUBY attr_accessor :current_date
-
-        # Frequency is one of: secondly, minutely, hourly, daily, weekly, monthly,
-        # yearly.
-        #
-        # @var string
-        # RUBY attr_accessor :frequency
-
-        # The number of recurrences, or 'null' if infinitely recurring.
-        #
-        # @var int
-        # RUBY attr_accessor :count
-
-        # The interval.
-        #
-        # If for example frequency is set to daily, interval = 2 would mean every
-        # 2 days.
-        #
-        # @var int
-        # RUBY attr_accessor :interval
-
-        # The last instance of this recurrence, inclusively.
-        #
-        # @var DateTimeInterface|null
-        # RUBY attr_accessor :until
-
-        # Which seconds to recur.
-        #
-        # This is an array of integers (between 0 and 60)
-        #
-        # @var array
-        # RUBY attr_accessor :by_second
-
-        # Which minutes to recur.
-        #
-        # This is an array of integers (between 0 and 59)
-        #
-        # @var array
-        # RUBY attr_accessor :by_minute
-
-        # Which hours to recur.
-        #
-        # This is an array of integers (between 0 and 23)
-        #
-        # @var array
-        # RUBY attr_accessor :by_hour
-
-        # The current item in the list.
-        #
-        # You can get this number with the key method.
-        #
-        # @var int
-        # RUBY attr_accessor :counter
-
-        # Which weekdays to recur.
-        #
-        # This is an array of weekdays
-        #
-        # This may also be preceeded by a positive or negative integer. If present,
-        # this indicates the nth occurrence of a specific day within the monthly or
-        # yearly rrule. For instance, -2TU indicates the second-last tuesday of
-        # the month, or year.
-        #
-        # @var array
-        # RUBY attr_accessor :by_day
-
-        # Which days of the month to recur.
-        #
-        # This is an array of days of the months (1-31). The value can also be
-        # negative. -5 for instance means the 5th last day of the month.
-        #
-        # @var array
-        # RUBY attr_accessor :by_month_day
-
-        # Which days of the year to recur.
-        #
-        # This is an array with days of the year (1 to 366). The values can also
-        # be negative. For instance, -1 will always represent the last day of the
-        # year. (December 31st).
-        #
-        # @var array
-        # RUBY attr_accessor :by_year_day
-
-        # Which week numbers to recur.
-        #
-        # This is an array of integers from 1 to 53. The values can also be
-        # negative. -1 will always refer to the last week of the year.
-        #
-        # @var array
-        # RUBY attr_accessor :by_week_no
-
-        # Which months to recur.
-        #
-        # This is an array of integers from 1 to 12.
-        #
-        # @var array
-        # RUBY attr_accessor :by_month
-
-        # Which items in an existing st to recur.
-        #
-        # These numbers work together with an existing by* rule. It specifies
-        # exactly which items of the existing by-rule to filter.
-        #
-        # Valid values are 1 to 366 and -1 to -366. As an example, this can be
-        # used to recur the last workday of the month.
-        #
-        # This would be done by setting frequency to 'monthly', byDay to
-        # 'MO,TU,WE,TH,FR' and bySetPos to -1.
-        #
-        # @var array
-        # RUBY attr_accessor :by_set_pos
-
-        # When the week starts.
-        #
-        # @var string
-        # RUBY attr_accessor :week_start
-
         # Does the processing for advancing the iterator for hourly frequency.
         #
-        # @return void
+        # @return [void]
         def next_hourly
           @current_date += @interval.hours
         end
 
         # Does the processing for advancing the iterator for daily frequency.
         #
-        # @return void
+        # @return [void]
         def next_daily
           unless @by_hour || @by_day
             @current_date += @interval.days
@@ -290,7 +162,7 @@ module Tilia
 
         # Does the processing for advancing the iterator for weekly frequency.
         #
-        # @return void
+        # @return [void]
         def next_weekly
           if !@by_hour && !@by_day
             @current_date += @interval.weeks
@@ -334,7 +206,7 @@ module Tilia
 
         # Does the processing for advancing the iterator for monthly frequency.
         #
-        # @return void
+        # @return [void]
         def next_monthly
           current_day_of_month = @current_date.day
           unless @by_month_day || @by_day
@@ -376,7 +248,7 @@ module Tilia
             # If we made it all the way here, it means there were no
             # valid occurrences, and we need to advance to the next
             # month.
-            @current_date - (@current_date.day - 1).days
+            @current_date -= (@current_date.day - 1).days
             @current_date += @interval.months
 
             # This goes to 0 because we need to start counting at the
@@ -389,7 +261,7 @@ module Tilia
 
         # Does the processing for advancing the iterator for yearly frequency.
         #
-        # @return void
+        # @return [void]
         def next_yearly
           current_month = @current_date.month
           current_year = @current_date.year
@@ -502,9 +374,9 @@ module Tilia
         # This method receives a string from an RRULE property, and populates this
         # class with all the values.
         #
-        # @param string|array rrule
+        # @param [String|array] rrule
         #
-        # @return void
+        # @return [void]
         def parse_r_rule(rrule)
           if rrule.is_a?(String)
             rrule = Property::ICalendar::Recur.string_to_array(rrule)
@@ -516,7 +388,7 @@ module Tilia
             when 'FREQ'
               value = value.downcase
               unless ['secondly', 'minutely', 'hourly', 'daily', 'weekly', 'monthly', 'yearly'].include?(value)
-                fail ArgumentError, "Unknown value for FREQ=#{value.upcase}"
+                fail InvalidDataException, "Unknown value for FREQ=#{value.upcase}"
               end
               @frequency = value
             when 'UNTIL'
@@ -534,7 +406,7 @@ module Tilia
             when 'INTERVAL', 'COUNT'
               val = value.to_i
               if val < 1
-                fail ArgumentError, "#{key.upcase} in RRULE must be a positive integer!"
+                fail InvalidDataException, "#{key.upcase} in RRULE must be a positive integer!"
               end
               key = key.downcase
               key == 'interval' ? @interval = val : @count = val
@@ -548,7 +420,7 @@ module Tilia
               value = value.is_a?(Array) ? value : [value]
               value.each do |part|
                 unless part =~ /^  (-|\+)? ([1-5])? (MO|TU|WE|TH|FR|SA|SU) $/xi
-                  fail ArgumentError, "Invalid part in BYDAY clause: #{part}"
+                  fail InvalidDataException, "Invalid part in BYDAY clause: #{part}"
                 end
               end
               @by_day = value
@@ -565,22 +437,17 @@ module Tilia
             when 'WKST'
               @week_start = value.upcase
             else
-              fail ArgumentError, "Not supported: #{key.upcase}"
+              fail InvalidDataException, "Not supported: #{key.upcase}"
             end
           end
         end
 
-        # Mappings between the day number and english day name.
-        #
-        # @var array
-        # RUBY: attr_accessor :day_names
-
         # Returns all the occurrences for a monthly frequency with a 'byDay' or
         # 'byMonthDay' expansion for the current month.
         #
         # The returned list is an array of integers with the day of month (1-31).
         #
-        # @return array
+        # @return [array]
         def monthly_occurrences
           start_date = @current_date.clone
 
@@ -682,7 +549,7 @@ module Tilia
 
         # Simple mapping from iCalendar day names to day numbers.
         #
-        # @var array
+        # @return [array]
         # RUBY: attr_accessor :day_map
 
         def hours

data/lib/tilia/v_object/settings.rb

@@ -23,9 +23,25 @@ module Tilia
       # appointments made for many years to come.
       @max_date = '2100-01-01'
 
+      # The maximum number of recurrences that will be generated.
+      #
+      # This setting limits the maximum of recurring events that this library
+      # generates in its recurrence iterators.
+      #
+      # This is a security measure. Without this, it would be possible to craft
+      # specific events that recur many, many times, potentially DDOSing the
+      # server.
+      #
+      # The default (3500) allows creation of a dialy event that goes on for 10
+      # years, which is hopefully long enough for most.
+      #
+      # Set this value to -1 to disable this control altogether.
+      @max_recurrences = 3500
+
       class << self
         attr_accessor :min_date
         attr_accessor :max_date
+        attr_accessor :max_recurrences
       end
     end
   end

data/lib/tilia/v_object/splitter.rb

@@ -1,5 +1,6 @@
 module Tilia
   module VObject
+    # Splitts VObject files that contain several VObjects
     module Splitter
       require 'tilia/v_object/splitter/splitter_interface'
       require 'tilia/v_object/splitter/i_calendar'

data/lib/tilia/v_object/splitter/i_calendar.rb

@@ -14,20 +14,20 @@ module Tilia
 
         # Timezones.
         #
-        # @var array
+        # @return [array]
         # RUBY: attr_accessor :vtimezones
 
         # iCalendar objects.
         #
-        # @var array
+        # @return [array]
         # RUBY: attr_accessor :objects
 
         # Constructor.
         #
         # The splitter should receive an readable file stream as it's input.
         #
-        # @param resource input
-        # @param int options Parser options, see the OPTIONS constants.
+        # @param [resource] input
+        # @param [Fixnum] options Parser options, see the OPTIONS constants.
         def initialize(input, options = 0)
           @vtimezones = {}
           @objects = {}
@@ -65,7 +65,7 @@ module Tilia
         #
         # When the end is reached, null will be returned.
         #
-        # @return Sabre\VObject\Component|null
+        # @return [Sabre\VObject\Component, nil]
         def next
           key = @objects.keys.first
 

data/lib/tilia/v_object/splitter/splitter_interface.rb

@@ -13,7 +13,7 @@ module Tilia
         #
         # The splitter should receive an readable file stream as it's input.
         #
-        # @param resource input
+        # @param [resource] input
         def initialize(_input)
         end
 
@@ -22,7 +22,7 @@ module Tilia
         #
         # When the end is reached, null will be returned.
         #
-        # @return Sabre\VObject\Component|null
+        # @return [Sabre\VObject\Component, nil]
         def next
         end
       end

data/lib/tilia/v_object/splitter/v_card.rb

@@ -12,20 +12,20 @@ module Tilia
         include SplitterInterface
         # File handle.
         #
-        # @var resource
+        # @return [resource]
         # RUBY: attr_accessor :input
 
         # Persistent parser.
         #
-        # @var MimeDir
+        # @return [MimeDir]
         # RUBY: attr_accessor :parser
 
         # Constructor.
         #
         # The splitter should receive an readable file stream as it's input.
         #
-        # @param resource input
-        # @param int options Parser options, see the OPTIONS constants.
+        # @param [resource] input
+        # @param [Fixnum] options Parser options, see the OPTIONS constants.
         def initialize(input, options = 0)
           @input = input
           @parser = Parser::MimeDir.new(input, options)
@@ -36,7 +36,7 @@ module Tilia
         #
         # When the end is reached, null will be returned.
         #
-        # @return Sabre\VObject\Component|null
+        # @return [Sabre\VObject\Component, nil]
         def next
           begin
             object = @parser.parse

data/lib/tilia/v_object/string_util.rb

@@ -4,9 +4,9 @@ module Tilia
     class StringUtil
       # Returns true or false depending on if a string is valid UTF-8.
       #
-      # @param string str
+      # @param [String] str
       #
-      # @return bool
+      # @return [Boolean]
       def self.utf8?(str)
         fail ArgumentError, 'str needs to be a String' unless str.is_a?(String)
         # Control characters
@@ -20,22 +20,38 @@ module Tilia
       # Currently only ISO-5991-1 input and UTF-8 input is supported, but this
       # may be expanded upon if we receive other examples.
       #
-      # @param string str
+      # @param [String] str
       #
-      # @return string
+      # @return [String]
       def self.convert_to_utf8(str)
+        str = str.encode('UTF-8', guess_encoding(str))
+
+        # Removing any control characters
+        str.gsub(/(?:[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F])/, '')
+      end
+
+      # Detects the encoding of a string
+      #
+      # Currently only supports 'UTF-8', 'ISO-5991-1' and 'Windows-1252'.
+      #
+      # @param [String] str
+      # @return [String] encoding
+      def self.guess_encoding(str)
         cd = CharDet.detect(str)
 
         # Best solution I could find ...
         if cd['confidence'] > 0.4 && cd['encoding'] =~ /(?:windows|iso)/i
-          str = str.encode('UTF-8', cd['encoding'])
+          cd['encoding']
+        else
+          'UTF-8'
         end
-
-        # Removing any control characters
-        str.gsub(/(?:[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F])/, '')
       end
 
-      # TODO: document
+      # Cuts the string after a certain bytelength
+      #
+      # @param [String] string
+      # @param [Fixnum] length
+      # @return [String] cut string
       def self.mb_strcut(string, length)
         return '' if string == ''