enumdate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7941bd64bd2ffee84449e892558f43592866010fcd92d8809be7df94ec80f3a
+  data.tar.gz: f9ae67f04f0e5134700c4ad535d69f94f7e685607bb3fa8d9e69946c6610104b
+SHA512:
+  metadata.gz: 0a2c4d506c93db39dd5e56ab5a562294d747e47977133191fe9682879dd1cfafb146214812a698da2837443e0a0aa32805e25c1991ebb0881b825eb596fc5929
+  data.tar.gz: eb6686a639cd867b90a938425abdb90f2465b2dc1fdefe79fb3d20a9ca1e66f477056a3a0b85d469e1e12794d94eec4771e63fcd781cb6e312d6169fd8cb8648

data/.github/workflows/main.yml

@@ -0,0 +1,16 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.0.2
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,65 @@
+################################################################
+# Added from https://raw.github.com/github/gitignore/master/Ruby.gitignore
+#
+
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+.rubocop-https?--*
+
+################################################################
+# Site-locals
+
+attic/

data/.rubocop.yml

@@ -0,0 +1,32 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+
+Layout/LineLength:
+  Max: 120
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
+
+Layout/SpaceInsideBlockBraces:
+  SpaceBeforeBlockParameters: false
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Style/Alias:
+  Enabled: true
+  EnforcedStyle: prefer_alias_method
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes

data/.solargraph.yml

@@ -0,0 +1,21 @@
+---
+include:
+- "**/*.rb"
+exclude:
+- spec/**/*
+- test/**/*
+- vendor/**/*
+- ".bundle/**/*"
+require: []
+domains: []
+reporters:
+- rubocop
+formatter:
+  rubocop:
+    cops: safe
+    except: []
+    only: []
+    extra_args: []
+require_paths: []
+plugins: []
+max_files: 5000

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in enumdate.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "rubocop", "~> 1.7"
+
+gem "solargraph"
+
+gem "org-ruby"
+gem "yard"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Yoshinari Nomura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.org

@@ -0,0 +1,147 @@
+#+TITLE: enumdate -- a small enumerator library to expand recurring dates
+#+AUTHOR: Yoshinari Nomura
+#+EMAIL:
+#+DATE: 2021-08-21
+#+OPTIONS: H:3 num:2 toc:nil
+#+OPTIONS: ^:nil @:t \n:nil ::t |:t f:t TeX:t
+#+OPTIONS: skip:nil
+#+OPTIONS: author:t
+#+OPTIONS: email:nil
+#+OPTIONS: creator:nil
+#+OPTIONS: timestamp:nil
+#+OPTIONS: timestamps:nil
+#+OPTIONS: d:nil
+#+OPTIONS: tags:t
+#+LANGUAGE: ja
+
+[[https://badge.fury.io/rb/enumdate.svg]]
+[[https://github.com/yoshinari-nomura/enumdate/actions/workflows/main.yml/badge.svg]]
+
+** Description
+   Enumdate is a small enumerator library to expand recurring dates.
+
+   You can get the latest version from:
+   + https://github.com/yoshinari-nomura/enumdate
+
+** How to use
+*** Create enumerables
+    Thease a simple example to create enumerables:
+    #+begin_src ruby
+      #      June 2021
+      # Su Mo Tu We Th Fr Sa
+      #        1  2  3  4  5
+      #  6  7  8  9 10 11 12
+      # 13 14 15 16 17 18 19
+      # 20 21 22 23 24 25 26
+      # 27 28 29 30
+      #
+      start = Date.new(2021, 6, 1) # first Tuesday June
+
+      # June 1st every year:
+      Enumdate.yearly_by_monthday(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2022-06-01", "2023-06-01"]
+
+      # First Tuesday June every year:
+      Enumdate.yearly_by_day(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2022-06-07", "2023-06-06"]
+
+      # 1st monthday every month:
+      Enumdate.monthly_by_monthday(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2021-07-01", "2021-08-01"]
+
+      # First Tuesday every month:
+      Enumdate.monthly_by_day(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2021-07-06", "2021-08-03"]
+
+      # every Tuesday:
+      Enumdate.weekly(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2021-06-08", "2021-06-15"]
+
+      # Everyday:
+      Enumdate.daily(start).lazy.map(&:to_s).take(3).force
+      # => ["2021-06-01", "2021-06-02", "2021-06-03"]
+    #+end_src
+
+    These constructor methods can take more complex parameters
+    such as ~month:~, ~mday:~, ~wday:~, ~nth:~, ~wkst:~, ~interval:~.
+    See the gem document for details.
+
+*** Make finit durations
+    This code makes infinit loop (every two years forever):
+    #+begin_src ruby
+      start = Date.new(2021, 6, 1)
+      Enumdate.yearly_by_monthday(start, interval: 2).each do |date|
+        puts date
+      end
+    #+end_src
+    Results:
+    : 2021-06-01
+    : 2023-06-01
+    : 2025-06-01
+    : :
+
+    To clip the duration, you can use ~forward_to~ and ~until~:
+    #+begin_src ruby
+      start = Date.new(2021, 6, 1)
+      Enumdate.yearly_by_monthday(start, interval: 2)
+        .forward_to(Date.new(2022, 1, 1))
+        .until(Date.new(2025, 12, 31))
+        .each do |date|
+        puts date
+      end
+    #+end_src
+    Rssults:
+    : 2023-06-01
+    : 2025-06-01
+
+    Note that the meaning of ~forward_to~ is different from that of
+    changing the ~start~ parameter.
+    #+begin_src ruby
+      start = Date.new(2022, 1, 1) # changed as if set forward_to
+      Enumdate.yearly_by_monthday(start, interval: 2)
+        .until(Date.new(2025, 12, 31))
+        .each do |date|
+        puts date
+      end
+    #+end_src
+    Rssults:
+    : 2022-01-01
+    : 2024-01-01
+
+    ~forward_to~ and ~until~ clip concrete occurrences without changing
+    the recurring pattern.
+
+*** Merge multiple enumerables
+    Sometimes, you may need to compose more complex recurring patterns.
+    In this case, you can merge multiple enumerables:
+    #+begin_src ruby
+      mon = Date.new(2021, 8, 2) # = 1st Monday
+      wed = Date.new(2021, 8, 4) # = 1st Wednesday
+
+      # Every Monday and Wednesday:
+      (Enumdate::EnumMerger.new << Enumdate.weekly(mon) << Enumdate.weekly(wed))
+        .lazy.map(&:to_s).take(4).force
+      # => ["2021-08-02", "2021-08-04", "2021-08-09", "2021-08-11"]
+    #+end_src
+
+** Installation
+   Add this line to your application's Gemfile:
+   #+begin_src ruby
+     gem "enumdate"
+   #+end_src
+
+   And then execute:
+   #+begin_src shell-script
+     $ bundle install
+   #+end_src
+
+   Or install it yourself as:
+   #+begin_src shell-script
+     $ gem install enumdate
+   #+end_src
+
+** Contributing
+   Bug reports and pull requests are welcome on GitHub at https://github.com/yoshinari-nomura/enumdate.
+
+** License
+   The gem is available as open source under the terms of the [[https://opensource.org/licenses/MIT][MIT License]].

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rubocop/rake_task"
+require "yard"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+RuboCop::RakeTask.new
+
+YARD::Rake::YardocTask.new do |t|
+  t.options = ["-m", "org"]
+end
+
+task doc: %i[yard]
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "enumdate"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/enumdate.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "lib/enumdate/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "enumdate"
+  spec.version       = Enumdate::VERSION
+  spec.authors       = ["Yoshinari Nomura"]
+  spec.email         = ["nom@quickhack.net"]
+
+  spec.summary       = "Enumerator for recurring dates."
+  spec.homepage      = "https://github.com/yoshinari-nomura/enumdate"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.5.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yoshinari-nomura/enumdate"
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject {|f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) {|f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

data/lib/enumdate.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Enumerator for recurring dates
+module Enumdate
+  class Error < StandardError; end
+
+  require "date"
+
+  dir = File.expand_path("enumdate", File.dirname(__FILE__))
+
+  autoload :EnumMerger,     "#{dir}/enum_merger.rb"
+  autoload :DateEnumerator, "#{dir}/date_enumerator.rb"
+  autoload :DateFrame,      "#{dir}/date_frame.rb"
+  autoload :DateHelper,     "#{dir}/date_helper.rb"
+  autoload :VERSION,        "#{dir}/version.rb"
+
+  class << self
+    # @return [DateEnumerator::YearlyByMonthday]
+    def yearly_by_monthday(first_date, month: nil, mday: nil, interval: 1)
+      month ||= first_date.month
+      mday  ||= first_date.mday
+      DateEnumerator::YearlyByMonthday.new(
+        first_date: first_date,
+        month: month,
+        mday: mday,
+        interval: interval
+      )
+    end
+
+    # @return [DateEnumerator::YearlyByDay]
+    def yearly_by_day(first_date, month: nil, nth: nil, wday: nil, interval: 1)
+      month ||= first_date.month
+      nth   ||= (first_date.mday + 6) / 7
+      wday  ||= first_date.wday
+      DateEnumerator::YearlyByDay.new(
+        first_date: first_date,
+        month: month,
+        nth: nth,
+        wday: wday,
+        interval: interval
+      )
+    end
+
+    # @return [DateEnumerator::MonthlyByMonthday]
+    def monthly_by_monthday(first_date, mday: nil, interval: 1)
+      mday ||= first_date.mday
+      DateEnumerator::MonthlyByMonthday.new(
+        first_date: first_date,
+        mday: mday,
+        interval: interval
+      )
+    end
+
+    # @return [DateEnumerator::MonthlyByDay]
+    def monthly_by_day(first_date, nth: nil, wday: nil, interval: 1)
+      nth  ||= (first_date.mday + 6) / 7
+      wday ||= first_date.wday
+      DateEnumerator::MonthlyByDay.new(
+        first_date: first_date,
+        nth: nth,
+        wday: wday,
+        interval: interval
+      )
+    end
+
+    # @return [DateEnumerator::Weekly]
+    def weekly(first_date, wday: nil, wkst: 1, interval: 1)
+      wday ||= first_date.wday
+      DateEnumerator::Weekly.new(
+        first_date: first_date,
+        wday: wday,
+        wkst: wkst,
+        interval: interval
+      )
+    end
+
+    # @return [DateEnumerator::Daily]
+    def daily(first_date, interval: 1)
+      DateEnumerator::Daily.new(
+        first_date: first_date,
+        interval: interval
+      )
+    end
+  end
+end

data/lib/enumdate/date_enumerator.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Enumdate
+  module DateEnumerator
+    # Base class for DateEnumerator
+    class Base
+      include DateHelper
+      include Enumerable
+
+      def initialize(first_date:, interval: 1, wkst: 1)
+        @first_date, @interval, @wkst = first_date, interval, wkst
+        @frame_manager = frame_manager.new(first_date, interval, wkst)
+        @duration_begin = first_date
+        @duration_until = nil
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def each
+        return enum_for(:each) unless block_given?
+
+        # ~first_date~ value always counts as the first occurrence
+        # even if it does not match the specified rule.
+        # cf. DTSTART vs RRULE in RFC5445.
+        yield @first_date if between_duration?(@first_date)
+
+        @frame_manager.each do |frame|
+          # Avoid inifinit loops even if the rule emits no occurrences
+          # such as "31st April in every year".
+          # (Every ~occurrence_in_frame(frame)~ returns nil)
+          break if @duration_until && @duration_until < frame
+
+          # In some cases, ~occurrence_in_frame~ returns nil.
+          # For example, a recurrence that returns 31st of each month
+          # will return nil for short months such as April and June.
+          next unless (date = occurrence_in_frame(frame))
+
+          break if @duration_until && @duration_until < date
+
+          # ~occurrence_in_frame~ may return a date earlier than
+          # ~first_date~ in the first iteration.  This is because
+          # ~first_date~ does not necessarily follow the repetetion
+          # rule.  For example, if the rule is "every August 1st" and
+          # ~first_date~ is August 15th, The first occurrence calculated
+          # by the rule returns "August 1st", which is earlier than
+          # August 15th. In this context, ~@duration_begin~ is the matter.
+          next if date < @duration_begin
+
+          # Ignore ~first_date~ not to yield twice.
+          next if date == @first_date
+
+          yield date
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      # Set the new beginning of duration for the recurrence rule.
+      #
+      # It also controls the underlying frame manager.  Since the
+      # frame manager is enough smart to avoid unnecessary repetition,
+      # there is no problem in setting the date hundred years later.
+      #
+      # Note that the meaning of calling ~forward_to~ is different
+      # from that of setting the ~first_date~ parameter on creation.
+      # For example, if a yearly event has *two-years* ~interval~:
+      #
+      # 1) if first_date is 2021-08-01 and forward_to 2022-08-01,
+      #      it will create [2021-08-01 2023-08-01 ...]
+      #
+      # 2) if first_date is 2022-08-01,
+      #      it will create [2022-08-01 2024-08-01 ...]
+      #
+      def forward_to(date)
+        @frame_manager.forward_to(date)
+        @duration_begin = date
+        self
+      end
+
+      # Imprement rewind for Enumrator class
+      def rewind
+        @frame_manager.rewind
+        self
+      end
+
+      # Set the new end of duration for the recurrence rule.
+      def until(date)
+        @duration_until = date
+        self
+      end
+
+      private
+
+      def between_duration?(date)
+        (!@duration_begin || @duration_begin <= date) &&
+          (!@duration_until || date <= @duration_until)
+      end
+
+      def frame_manager
+        raise NotImplementedError
+      end
+
+      def occurrence_in_frame(date)
+        raise NotImplementedError
+      end
+    end
+
+    ################################################################
+    # Enumerate yealy dates by day like: Apr 4th Tue
+    class YearlyByDay < Base
+      def initialize(first_date:, month:, nth:, wday:, interval: 1)
+        super(first_date: first_date, interval: interval)
+        @month, @nth, @wday = month, nth, wday
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Yearly
+      end
+
+      def occurrence_in_frame(date)
+        make_date_by_day(year: date.year, month: @month, nth: @nth, wday: @wday)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    ################################################################
+    # Enumerate yealy dates by month-day like: Apr 22
+    # s, e = Date.new(2021, 1, 1), Date.new(20100, 12, 31)
+    # Enumdate::YearlyByMonthday(start_date: s, end_date: e, month: 4, mday: 22, interval: 2).map(&:to_s)
+    # : => [2021-04-22, 2023-04-22, ..., 2099-04-22]
+    class YearlyByMonthday < Base
+      def initialize(first_date:, month:, mday:, interval: 1)
+        super(first_date: first_date, interval: interval)
+        @month, @mday = month, mday
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Yearly
+      end
+
+      def occurrence_in_frame(date)
+        Date.new(date.year, @month, @mday)
+      rescue Date::Error
+        nil
+      end
+    end
+
+    ################################################################
+    # Enumerate monthly dates by day like: 4th Tue
+    class MonthlyByDay < Base
+      def initialize(first_date:, nth:, wday:, interval: 1)
+        super(first_date: first_date, interval: interval)
+        @nth, @wday = nth, wday
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Monthly
+      end
+
+      def occurrence_in_frame(date)
+        make_date_by_day(year: date.year, month: date.month, nth: @nth, wday: @wday)
+      rescue Date::Error
+        nil
+      end
+    end
+
+    ################################################################
+    # Enumerate monthly dates by month-day like: 22
+    class MonthlyByMonthday < Base
+      def initialize(first_date:, mday:, interval: 1)
+        super(first_date: first_date, interval: interval)
+        @mday = mday
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Monthly
+      end
+
+      def occurrence_in_frame(date)
+        Date.new(date.year, date.month, @mday)
+      rescue Date::Error
+        nil
+      end
+    end
+
+    ################################################################
+    # Enumerate weekly dates like: Tue
+    class Weekly < Base
+      def initialize(first_date:, wday:, interval: 1, wkst: 1)
+        super(first_date: first_date, interval: interval, wkst: wkst)
+        @wday = wday
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Weekly
+      end
+
+      # Sun Mon Tue Wed Thu Fri Sat Sun Mon Tue ...
+      #  0   1   2   3   4   5   6   0   1   2  ...
+      def occurrence_in_frame(date)
+        bof = date - ((date.wday - @wkst) % 7)
+        candidate = bof + (@wday - bof.wday) % 7
+        return candidate if date <= candidate
+
+        nil
+      end
+    end
+
+    ################################################################
+    # Enumerate every n days
+    class Daily < Base
+      def initialize(first_date:, interval: 1)
+        super(first_date: first_date, interval: interval)
+      end
+
+      private
+
+      def frame_manager
+        DateFrame::Daily
+      end
+
+      def occurrence_in_frame(date)
+        date
+      end
+    end
+
+    ################################################################
+    # Enumerate dates from list.
+    class ByDateList
+      include Enumerable
+
+      def initialize(date_list: [])
+        @date_list = date_list
+        @duration_until = nil
+      end
+
+      def <<(date)
+        @date_list << date
+      end
+
+      def rewind; end
+
+      def until(date)
+        @duration_until = date
+      end
+
+      def forward_to(date)
+        @first_date = date
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        @date_list.sort.each do |date|
+          next if @fist_date && date < @first_date
+          break if @duration_until && date > @duration_until
+
+          yield date
+        end
+      end
+    end
+  end
+end

data/lib/enumdate/date_frame.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Enumdate
+  # SYNOPSIS:
+  # + Enumdate::DateFrame::Yearly.new(first_date, interval)
+  # + Enumdate::DateFrame::Monthly.new(first_date, interval)
+  # + Enumdate::DateFrame::Weekly.new(first_date, interval, wkst)
+  # + Enumdate::DateFrame::Daily.new(first_date, interval)
+  #
+  # Iterate the date in frames of year, month, week, or day,
+  # and enumerate the first date of each frame.
+  #
+  # ~FIRST_DATE~ is an arbitrary date of the first frame.
+  #
+  # #+begin_src ruby
+  # Enumdate::DateFrame::Yearly.new(Date.new(2021, 1, 1), 2).lazy.map(&:to_s).take(3).force
+  # # => ["2021-01-01", "2023-01-01", "2025-01-01"]
+  #
+  # Enumdate::DateFrame::Yearly.new(Date.new(2021, 6, 1), 2).lazy.map(&:to_s).take(3).force
+  # # => ["2021-01-01", "2023-01-01", "2025-01-01"]
+  #
+  # Enumdate::DateFrame::Monthly.new(Date.new(2021, 6, 10), 2).lazy.map(&:to_s).take(3).force
+  # # => ["2021-06-01", "2021-08-01", "2021-10-01"]
+  # #+end_src
+  #
+  # ~Enumdate::DateFrame::Weekly~ is sensitive to ~WKST~ param:
+  #
+  # 2021-06-08 is Tuesday:
+  # #+begin_example
+  #      June 2021
+  # Su Mo Tu We Th Fr Sa
+  # 30 31  1  2  3  4  5
+  #  6  7  8  9 10 11 12
+  # 13 14 15 16 17 18 19
+  # 20 21 22 23 24 25 26
+  # 27 28 29 30  1  2  3
+  # #+end_example
+  #
+  # #+begin_src ruby
+  # sun, mon, tue, wed = 0, 1, 2, 3
+  #
+  # # If week start is Sunday:
+  # Enumdate::DateFrame::Weekly.new(Date.new(2021, 6, 8), 2, sun).lazy.map(&:to_s).take(3).force
+  # # => ["2021-06-06", "2021-06-20", "2021-07-04"]
+  #
+  # # Monday (default):
+  # Enumdate::DateFrame::Weekly.new(Date.new(2021, 6, 8), 2, mon).lazy.map(&:to_s).take(3).force
+  # #  => ["2021-06-07", "2021-06-21", "2021-07-05"]
+  #
+  # # Tuesday:
+  # Enumdate::DateFrame::Weekly.new(Date.new(2021, 6, 8), 2, tue).lazy.map(&:to_s).take(3).force
+  # # => ["2021-06-08", "2021-06-22", "2021-07-06"]
+  #
+  # # Wednesday:
+  # Enumdate::DateFrame::Weekly.new(Date.new(2021, 6, 8), 2, wed).lazy.map(&:to_s).take(3).force
+  # # => ["2021-06-02", "2021-06-16", "2021-06-30"]
+  #
+  # Enumdate::DateFrame::Daily.new(Date.new(2021, 5, 15), 10).lazy.map(&:to_s).take(3).force
+  # # => ["2021-05-15", "2021-05-25", "2021-06-04"]
+  #
+  # # `forward_to` method is helpful to jump to some specific date before the iteration.
+  # Enumdate::DateFrame::Yearly.new(Date.new(2021, 1, 1), 2).forward_to(Date.new(2100, 1, 1))
+  #   .lazy.map(&:to_s).take(3).force
+  # # => ["2101-01-01", "2103-01-01", "2105-01-01"]
+  #
+  # # Let's see how it differs from simply changing FIRST_DATE:
+  # Enumdate::DateFrame::Yearly.new(Date.new(2100, 1, 1), 2).lazy.map(&:to_s).take(3).force
+  # #  => ["2100-01-01", "2102-01-01", "2104-01-01"]
+  # #+end_src
+  #
+  module DateFrame
+    # DateFrame: yearly, monthly, weekly, and daily
+    class Base
+      include DateHelper
+      include Enumerable
+
+      def initialize(first_date, interval = 1, wkst = 1)
+        @first_date, @interval, @wkst = first_date, interval, wkst
+        rewind
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        loop do
+          yield @current_frame_date
+          @current_frame_date = next_frame_start(@current_frame_date)
+        end
+      end
+
+      # Imprement rewind for Enumrator class
+      def rewind
+        @current_frame_date = beginning_of_frame(@first_date)
+        self
+      end
+
+      # Go forward to the frame in which DATE is involved
+      def forward_to(date)
+        rewind # reset @current_frame_date
+        frames = frames_between(@current_frame_date, date)
+        cycles = (frames + (@interval - 1)) / @interval
+        @current_frame_date = next_frame_start(@current_frame_date, cycles) if cycles.positive?
+        self
+      end
+
+      private
+
+      def next_frame_start(current_frame_date, cycles = 1)
+        raise NotImplementedError
+      end
+
+      def beginning_of_frame(date)
+        raise NotImplementedError
+      end
+
+      def frames_between(date1, date2)
+        raise NotImplementedError
+      end
+    end
+
+    # Dummy date frame
+    class Dummy < Base
+    end
+
+    # Yearly date frame
+    class Yearly < Base
+      private
+
+      def next_frame_start(current_frame_date, cycles = 1)
+        current_frame_date >> (@interval * 12 * cycles)
+      end
+
+      def beginning_of_frame(date)
+        beginning_of_year(date)
+      end
+
+      def frames_between(date1, date2)
+        years_between(date1, date2)
+      end
+    end
+
+    # Monthly date frame
+    class Monthly < Base
+      private
+
+      def next_frame_start(current_frame_date, cycles = 1)
+        current_frame_date >> (@interval * cycles)
+      end
+
+      def beginning_of_frame(date)
+        beginning_of_month(date)
+      end
+
+      def frames_between(date1, date2)
+        months_between(date1, date2)
+      end
+    end
+
+    # Weekly date frame
+    class Weekly < Base
+      private
+
+      def next_frame_start(current_frame_date, cycles = 1)
+        current_frame_date + (@interval * 7 * cycles)
+      end
+
+      def beginning_of_frame(date)
+        beginning_of_week(date, @wkst)
+      end
+
+      def frames_between(date1, date2)
+        (beginning_of_frame(date2) - beginning_of_frame(date1)) / 7
+      end
+    end
+
+    # Daily date frame
+    class Daily < Base
+      private
+
+      def next_frame_start(current_frame_date, cycles = 1)
+        current_frame_date + (@interval * cycles)
+      end
+
+      def beginning_of_frame(date)
+        date
+      end
+
+      def frames_between(date1, date2)
+        date2 - date1
+      end
+    end
+  end
+end

data/lib/enumdate/date_helper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Enumdate
+  # Helper for date-calculation.
+  module DateHelper
+    private
+
+    # Make a date by DAY like ``1st Wed of Nov, 1999''.
+    # caller must make sure:
+    #   YEAR and MONTH must be valid
+    #   NTH must be < 0 or > 0
+    #   WDAY must be 0:Sun .. 6:Sat
+    #
+    # raise ArgumentError if no date matches. for example:
+    #   no 5th Saturday exists on April 2010.
+    #
+    def make_date_by_day(year:, month:, nth:, wday:)
+      direction = nth.positive? ? 1 : -1
+
+      edge  = Date.new(year, month, direction)
+      ydiff = nth - direction
+      xdiff = direction * ((direction * (wday - edge.wday)) % 7)
+      mday  = edge.mday + ydiff * 7 + xdiff
+
+      raise ArgumentError if mday < 1
+
+      Date.new(year, month, mday)
+    end
+
+    def beginning_of_year(date)
+      date.class.new(date.year, 1, 1)
+    end
+
+    def beginning_of_month(date)
+      date.class.new(date.year, date.month, 1)
+    end
+
+    def beginning_of_week(date, wkst = 1)
+      date - ((date.wday - wkst) % 7)
+    end
+
+    def years_between(date1, date2)
+      date2.year - date1.year
+    end
+
+    def months_between(date1, date2)
+      (date2.year * 12 + date2.month) - (date1.year * 12 + date1.month)
+    end
+  end
+end

data/lib/enumdate/enum_merger.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Enumdate
+  # Create new Enumerator merging multiple enumerators.
+  #
+  # All enumerators should yield objects that respond to `<=>` method.
+  # enums = (EnumMerger.new << enum1 << enum2).to_enum
+  #
+  class EnumMerger
+    include Enumerable
+
+    def initialize
+      @enumerators = []
+    end
+
+    # Imprement each for Enumrator class
+    def each
+      return enum_for(:each) unless block_given?
+
+      loop do
+        yield next_minimum(@enumerators)
+      end
+    end
+
+    # Imprement rewind for Enumrator class
+    def rewind
+      @enumerators.map(&:rewind)
+    end
+
+    # Add enumerator
+    def <<(enumerator)
+      @enumerators << enumerator.to_enum
+      self
+    end
+
+    private
+
+    # Yield next minimum value
+    def next_minimum(enumerators)
+      raise StopIteration if enumerators.empty?
+
+      # Could raise StopIteration
+      minimum_enumrator(enumerators).next
+    end
+
+    def minimum_enumrator(enumerators)
+      min_e, min_v = enumerators.first, nil
+      enumerators.each do |e|
+        v = e.peek
+        min_e, min_v = e, v if min_v.nil? || v < min_v
+      rescue StopIteration
+        # do nothing
+      end
+      min_e
+    end
+  end
+end

data/lib/enumdate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Enumdate
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: enumdate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yoshinari Nomura
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-08-22 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- nom@quickhack.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- ".solargraph.yml"
+- Gemfile
+- LICENSE.txt
+- README.org
+- Rakefile
+- bin/console
+- bin/setup
+- enumdate.gemspec
+- lib/enumdate.rb
+- lib/enumdate/date_enumerator.rb
+- lib/enumdate/date_frame.rb
+- lib/enumdate/date_helper.rb
+- lib/enumdate/enum_merger.rb
+- lib/enumdate/version.rb
+homepage: https://github.com/yoshinari-nomura/enumdate
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yoshinari-nomura/enumdate
+  source_code_uri: https://github.com/yoshinari-nomura/enumdate
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.22
+signing_key:
+specification_version: 4
+summary: Enumerator for recurring dates.
+test_files: []