Update to BYSETPOS support (#449)

* Support BYSETPOS for MONTHLY AND YEARLY freq

* Modernize BYSETPOS commit

A few small updates to Nicolas Marlier's BYSETPOS support added in
PR #349

* address the spec DST sensitivity in .to_yaml round trips

* update PR from feedback

rebased against master -- its been 4 years

* excluding until, not util

* remove no longer needed TimeUtil active_support require

This was a holdover from the original PR back in 2016.  TimeUtil
has since been refactored to not need this, but the require was
inadvertently left.

* fix interval use with bysetpos

* remove unneeded use of activesupport for date arithmetic

* support for bysetpos with freq=weekly

* support for parsing rrules from ical that are very long and wrap

* dont require the wrapped line to be the last the ical string

* nitpick fixes - use map and double quotes for consistency

* do not rely on ActiveSupport-only helper methods

* fix BYSETPOS serialization

* fix SETBYPOS with non BYDAY expansions

* expand BYSETPOS spec coverage

- weekly: positive/multi/mixed positions, BYHOUR expansion
- monthly: negative positions, BYMONTHDAY, BYMINUTE
- yearly: multiple positive/negative positions

* adding BYSETPOS validations for daily/hourly/minutely

* add verification that bysetpos runs after other byXXX filters

* BYSETPOS interval boundaries specs

* dd BYSETPOS ordering specs

* add BYSETPOS anchor and interval specs

* refactor and create BYSETPOS helper for interval bounds

* adding more comprehensive BYSETPOS specs

This covers repeated values, out-of-range, and UNTIL cases

* updating readme with bysetpos support

* adding BYSETPOS to_ical spec coverage

* adding SECONDLY BYSETPOS support and specs

* adding BYYEARDAY BYSETPOS specs

* Gemfile adjustments for Ruby stdlib changes

* adding support for more versions of ActiveSupport

* Fix BYSETPOS to count positions from interval start per RFC 5545

BYSETPOS was anchoring candidate enumeration to DTSTART instead of the
interval boundary, causing positions to be miscounted. This skipped the
first occurrence when DTSTART itself matched a BYSETPOS position (e.g.,
starting on the 2nd Tuesday when selecting BYSETPOS=2).

The fix anchors the temporary schedule to the interval start based on
which BYxxx components expand the candidate set (day, month, hour, etc.).

* Fix flaky YAML round-trip test that failed across DST boundaries

Use UTC instead of Time.now to avoid DST offset mismatches when YAML
serialization loses timezone info and preserves only the numeric offset.

* linting fixes

* CHANGELOG entry

* Fix lint errors

* Add missing round-trip YAML tests for BYSETPOS

* Create time objects correctly

* Add edge cases for BYSETPOS

---------

Co-authored-by: Nicolas Marlier <[email protected]>
Co-authored-by: Jon Pascoe <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -5,10 +5,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [UNRELEASED]
+### Added
+- Support for BYSETPOS with all rule frequencies (yearly, monthly, weekly, daily, hourly, minutely, secondly). ([#449](https://github.com/ice-cube-ruby/ice_cube/pull/449)) by [@nehresma](https://github.com/nehresma) and [@NicolasMarlier](https://github.com/NicolasMarlier)
+
 ### Changed
 - Updated CI test matrix to support Rails 7.2, 8.0, 8.1 and Ruby 3.2, 3.3, 3.4, 4.0 by [@nehresma](https://github.com/nehresma) and [@pacso](https://github.com/pacso)
 
-
 ## [0.17.0] - 2024-07-18
 ### Added
 - Indonesian translations. ([#505](https://github.com/seejohnrun/ice_cube/pull/505)) by [@achmiral](https://github.com/achmiral)

Gemfile

@@ -9,3 +9,10 @@ compatible_rails_versions = [
 gem "activesupport", (ENV["RAILS_VERSION"] || compatible_rails_versions), require: false
 gem "i18n", require: false
 gem "tzinfo", require: false # only needed explicitly for RAILS_VERSION=3
+
+gem "base64", require: false     # remove base64 deprecation warnings for Ruby 3.3+
+gem "bigdecimal", require: false # remove bigdecimal deprecation warnings for Ruby 3.3+
+gem "mutex_m", require: false    # ActiveSupport dependency on Ruby 3.4+
+gem "ostruct", require: false    # remove ostruct deprecation warnings for Ruby 3.4+
+gem "logger", require: false     # remove logger deprecation warnings for Ruby 3.4+
+gem "benchmark", require: false  # remove benchmark deprecation warnings for Ruby 3.4+

README.md

@@ -253,6 +253,31 @@ schedule.add_recurrence_rule IceCube::Rule.yearly(3).month_of_year(:march)
 schedule.add_recurrence_rule IceCube::Rule.yearly(3).month_of_year(3)
 ```
 
+### BYSETPOS (select the nth occurrence)
+
+BYSETPOS selects the nth occurrence within each interval after all other BYxxx
+filters/expansions are applied. Use positive values (from the start) or
+negative values (from the end). Repeated values do not duplicate occurrences,
+and positions beyond the set size yield no occurrence for that interval.
+RFC 5545 requires BYSETPOS to be used with another BYxxx rule part; IceCube
+allows BYSETPOS without another BYxxx and applies it to the single occurrence
+in each interval.
+
+```ruby
+# last weekday of the month
+schedule.add_recurrence_rule(
+  IceCube::Rule.monthly.day(:monday, :tuesday, :wednesday, :thursday, :friday).by_set_pos(-1)
+)
+
+# second occurrence in each day's expanded set
+schedule.add_recurrence_rule(
+  IceCube::Rule.daily.hour_of_day(9, 17).by_set_pos(2)
+)
+```
+
+Note: If you expand with BYHOUR/BYMINUTE/BYSECOND, any unspecified smaller
+time components are inherited from the schedule's start_time.
+
 ### Hourly (by hour of day)
 
 ```ruby

lib/ice_cube.rb

@@ -50,6 +50,15 @@ module Validations
     autoload :YearlyInterval, "ice_cube/validations/yearly_interval"
     autoload :HourlyInterval, "ice_cube/validations/hourly_interval"
 
+    autoload :BySetPosHelper, "ice_cube/validations/by_set_pos_helper"
+    autoload :SecondlyBySetPos, "ice_cube/validations/secondly_by_set_pos"
+    autoload :MinutelyBySetPos, "ice_cube/validations/minutely_by_set_pos"
+    autoload :HourlyBySetPos, "ice_cube/validations/hourly_by_set_pos"
+    autoload :DailyBySetPos, "ice_cube/validations/daily_by_set_pos"
+    autoload :WeeklyBySetPos, "ice_cube/validations/weekly_by_set_pos"
+    autoload :MonthlyBySetPos, "ice_cube/validations/monthly_by_set_pos"
+    autoload :YearlyBySetPos, "ice_cube/validations/yearly_by_set_pos"
+
     autoload :HourOfDay, "ice_cube/validations/hour_of_day"
     autoload :MonthOfYear, "ice_cube/validations/month_of_year"
     autoload :MinuteOfHour, "ice_cube/validations/minute_of_hour"

lib/ice_cube/occurrence.rb

@@ -85,11 +85,8 @@ def to_time
     # time formats and is only used when ActiveSupport is available.
     #
     def to_s(format = nil)
-      if format && to_time.public_method(:to_s).arity != 0
-        t0, t1 = start_time.to_s(format), end_time.to_s(format)
-      else
-        t0, t1 = start_time.to_s, end_time.to_s
-      end
+      t0 = format_time(start_time, format)
+      t1 = format_time(end_time, format)
       (duration > 0) ? "#{t0} - #{t1}" : t0
     end
 
@@ -98,5 +95,18 @@ def overnight?
       midnight = Time.new(offset.year, offset.month, offset.day)
       midnight < end_time
     end
+
+    private
+
+    # Normalize formatted output across ActiveSupport versions:
+    # Rails 7.1+ prefers to_fs, older versions use to_formatted_s or to_s(:format).
+    def format_time(time, format)
+      return time.to_s unless format
+      return time.to_fs(format) if time.respond_to?(:to_fs)
+      return time.to_formatted_s(format) if time.respond_to?(:to_formatted_s)
+      return time.to_s(format) if time.public_method(:to_s).arity != 0
+
+      time.to_s
+    end
   end
 end

lib/ice_cube/parsers/ical_parser.rb

@@ -2,7 +2,18 @@ module IceCube
   class IcalParser
     def self.schedule_from_ical(ical_string, options = {})
       data = {}
+
+      # First join lines that are wrapped
+      lines = []
       ical_string.each_line do |line|
+        if lines[-1] && line =~ /\A[ \t].+/
+          lines[-1] = lines[-1].strip + line.sub(/\A[ \t]+/, "")
+        else
+          lines << line
+        end
+      end
+
+      lines.each do |line|
         (property, value) = line.split(":")
         (property, _tzid) = property.split(";")
         case property
@@ -75,7 +86,7 @@ def self.rule_from_ical(ical)
         when "BYYEARDAY"
           validations[:day_of_year] = value.split(",").map(&:to_i)
         when "BYSETPOS"
-          # noop
+          validations[:by_set_pos] = value.split(",").map(&:to_i)
         else
           validations[name] = nil # invalid type
         end

lib/ice_cube/rule.rb

@@ -49,11 +49,11 @@ def to_hash
       raise MethodNotImplemented, "Expected to be overridden by subclasses"
     end
 
-    def next_time(time, schedule, closing_time)
+    def next_time(time, schedule, closing_time, increment: true)
     end
 
     def on?(time, schedule)
-      next_time(time, schedule, time).to_i == time.to_i
+      next_time(time, schedule, time, increment: false).to_i == time.to_i
     end
 
     class << self

lib/ice_cube/rules/daily_rule.rb

@@ -10,6 +10,7 @@ class DailyRule < ValidatedRule
     # include Validations::DayOfYear    # n/a
 
     include Validations::DailyInterval
+    include Validations::DailyBySetPos
 
     def initialize(interval = 1)
       super

lib/ice_cube/rules/hourly_rule.rb

@@ -10,6 +10,7 @@ class HourlyRule < ValidatedRule
     include Validations::DayOfYear
 
     include Validations::HourlyInterval
+    include Validations::HourlyBySetPos
 
     def initialize(interval = 1)
       super

lib/ice_cube/rules/minutely_rule.rb

@@ -10,6 +10,7 @@ class MinutelyRule < ValidatedRule
     include Validations::DayOfYear
 
     include Validations::MinutelyInterval
+    include Validations::MinutelyBySetPos
 
     def initialize(interval = 1)
       super