sof-cycle 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 416c2fd3c9e369ece57bafe7cbf5a58f07b9e30177c04b7253059cb87d6e32dc
-  data.tar.gz: 00fd30f51d4efb2eeabbe7eef1b8fdd58a6290a08579ae661984b2de359585e4
+  metadata.gz: ea1c2c9a48bba72114b7681278cd467c57ee147f6f8b1ff176b4508de355920b
+  data.tar.gz: 93a7560799df4730a5eaf2d14708b9a24199c0a95d2b01f1487ddc587b0846da
 SHA512:
-  metadata.gz: 582f1597715e073ea8d517b8236ad3daf81fcdf9ce023c860a77ed2ddb4847e4df027b606764915d816d7d5ddd06ec383bcae58fb0174e8e1e6f02d97265ed71
-  data.tar.gz: 8d9e747a1ac2d0a649f911f6c7de8e81dc7a8139294c41c37eb20b8d9cc67e52e5242f61df1315b74aab24127f5c0c7ea7738a9d9fc7e1130ddc94dec9de6445
+  metadata.gz: baf569f5fb7e0500b8a28915c8f19b86dc97ebee380301787182216d162fd02e659645345d369440959ebde737b59bb8ddd4372dae0bf014a9e3b448e8455e03
+  data.tar.gz: 84756e0428c56a7f6dd72e5dc7aa545a587bbffd49479a436e4f8bee2d60ec3496e128f713a36b0169799ff908e0690e4518b147e750eaa0fb662681f0e036a0

data/CHANGELOG.md

@@ -5,8 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2024-07-09
+## [0.1.2] - 2024-08-09
 
 ### Added
 
-- Initial extraction
+- `Cycle#recurring?` to reveal if a given Cycle is one-and-done or must be repeated.
+
+## [0.1.1] - 2024-08-09
+
+### Added
+
+- Basic example in README.md
+- Add `Cycles::EndOf` to handle cycles that cover through the end of the nth
+  subsequent period
+- Add predicate methods for each `Cycle` subclass. E.g. `#dormant?`, `#within?`, etc
+- Refactor into namespaces

data/README.md

@@ -14,7 +14,12 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-TODO: Write usage instructions here
+```ruby
+cycle = SOF::Cycle.load({ volume: 3, kind: :lookback, period: :day, period_count: 3 })
+cycle.to_h # => { volume: 3, kind: :lookback, period: :day, period_count: 3 }
+cycle.notation # => "V3L3D"
+cycle.to_s # => "3x in the prior 3 days"
+```
 
 ## Development
 

data/Rakefile

@@ -14,4 +14,4 @@ require "reissue/gem"
 
 Reissue::Task.create do |task|
   task.version_file = "lib/sof/cycle/version.rb"
-end
+end

data/checksums/sof-cycle-0.1.0.gem.sha512

@@ -0,0 +1 @@
+9a87a33268363c7f7afbb084677ff7e37c9b1102992b8082cac7529cfb3871fc92e8218d14de218a04b26afb415505286a76f948094b3cd5032b52dcf81645c6

data/checksums/sof-cycle-0.1.1.gem.sha512

@@ -0,0 +1 @@
+53766201b732ae80e67079d1efeda25c86f144cc59c1aed2a210a8d068a689409bfd1fc0e6be7b769ae15500c3224d2c5c7854385ac84b60e44a54f94bb22c65

data/checksums/sof-cycle-0.1.2.gem.sha512

@@ -0,0 +1 @@
+78a488a4cea134800aeca3e3e06461a413c564b111d96b25a74c4ae44b5afa66a04d4c59be33cc455bab0c9b1d80cfdd3af1b980859ae3955cb1fd7350fe1459

data/lib/sof/cycle/version.rb

@@ -2,6 +2,6 @@
 
 module SOF
   class Cycle
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/sof/cycle.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "cycle/version"
-require "forwardable"
-require_relative "cycle/parser"
-require_relative "cycle/time_span"
-require "active_support/core_ext/date/conversions"
-require "active_support/core_ext/string/filters"
+require_relative "parser"
 
 module SOF
   class Cycle
@@ -30,8 +25,10 @@ module SOF
 
     delegate [:activated_notation, :volume, :from, :from_date, :time_span, :period,
       :humanized_period, :period_key, :active?] => :@parser
-    delegate [:kind, :volume_only?, :valid_periods] => "self.class"
+    delegate [:kind, :recurring?, :volume_only?, :valid_periods] => "self.class"
     delegate [:period_count, :duration] => :time_span
+    delegate [:calendar?, :dormant?, :end_of?, :lookback?, :volume_only?,
+      :within?] => :kind_inquiry
 
     # Turn a cycle or notation string into a hash
     def self.dump(cycle_or_string)
@@ -83,7 +80,7 @@ module SOF
     # @return [Cycle] a Cycle object representing the provide string notation
     def self.for(notation)
       return notation if notation.is_a? Cycle
-      return notation if notation.is_a? Cycle::Dormant
+      return notation if notation.is_a? Cycles::Dormant
       parser = Parser.new(notation)
       unless parser.valid?
         raise InvalidInput, "'#{notation}' is not a valid input"
@@ -94,7 +91,7 @@ module SOF
       end.new(notation, parser:)
       return cycle if parser.active?
 
-      Cycle::Dormant.new(cycle, parser:)
+      Cycles::Dormant.new(cycle, parser:)
     end
 
     # Return the appropriate class for the give notation id
@@ -133,10 +130,11 @@ module SOF
     @kind = nil
     @valid_periods = []
 
-    def self.volume_only? = @volume_only
-
     class << self
       attr_reader :notation_id, :kind, :valid_periods
+      def volume_only? = @volume_only
+
+      def recurring? = raise "#{name} must implement #{__method__}"
     end
 
     # Raises an error if the given period isn't in the list of valid periods.
@@ -150,6 +148,8 @@ module SOF
       ERR
     end
 
+    def kind_inquiry = ActiveSupport::StringInquirer.new(kind.to_s)
+
     def validate_period
       return if valid_periods.empty?
 
@@ -208,146 +208,5 @@ module SOF
     end
 
     def as_json(...) = notation
-
-    class Dormant
-      def initialize(cycle, parser:)
-        @cycle = cycle
-        @parser = parser
-      end
-
-      attr_reader :cycle, :parser
-
-      def to_s
-        cycle.to_s + " (dormant)"
-      end
-
-      def covered_dates(...) = []
-
-      def expiration_of(...) = nil
-
-      def satisfied_by?(...) = false
-
-      def cover?(...) = false
-
-      def method_missing(method, ...) = cycle.send(method, ...)
-
-      def respond_to_missing?(method, include_private = false)
-        cycle.respond_to?(method, include_private)
-      end
-    end
-
-    class Within < self
-      @volume_only = false
-      @notation_id = "W"
-      @kind = :within
-      @valid_periods = %w[D W M Y]
-
-      def to_s = "#{volume}x within #{date_range}"
-
-      def date_range
-        return humanized_span unless active?
-
-        [start_date, final_date].map { _1.to_fs(:american) }.join(" - ")
-      end
-
-      def final_date(_ = nil) = time_span.end_date(start_date)
-
-      def start_date(_ = nil) = from_date.to_date
-    end
-
-    class VolumeOnly < self
-      @volume_only = true
-      @notation_id = nil
-      @kind = :volume_only
-      @valid_periods = []
-
-      class << self
-        def handles?(sym) = sym.nil? || super
-
-        def validate_period(period)
-          raise InvalidPeriod, <<~ERR.squish unless period.nil?
-            Invalid period value of '#{period}' provided. Valid periods are:
-            #{valid_periods.join(", ")}
-          ERR
-        end
-      end
-
-      def to_s = "#{volume}x total"
-
-      def covered_dates(dates, ...) = dates
-
-      def cover?(...) = true
-    end
-
-    class Lookback < self
-      @volume_only = false
-      @notation_id = "L"
-      @kind = :lookback
-      @valid_periods = %w[D W M Y]
-
-      def to_s = "#{volume}x in the prior #{period_count} #{humanized_period}"
-
-      def volume_to_delay_expiration(completion_dates, anchor:)
-        oldest_relevant_completion = completion_dates.min
-        [completion_dates.count(oldest_relevant_completion), volume].min
-      end
-
-      # "Absent further completions, you go red on this date"
-      # @return [Date, nil] the date on which the cycle will expire given the
-      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
-      def expiration_of(completion_dates)
-        anchor = completion_dates.max_by(volume) { _1 }.min
-        return unless satisfied_by?(completion_dates, anchor:)
-
-        window_end anchor
-      end
-
-      def final_date(anchor)
-        return if anchor.nil?
-
-        time_span.end_date(anchor.to_date)
-      end
-      alias_method :window_end, :final_date
-
-      def start_date(anchor)
-        time_span.begin_date(anchor.to_date)
-      end
-      alias_method :window_start, :start_date
-    end
-
-    class Calendar < self
-      @volume_only = false
-      @notation_id = "C"
-      @kind = :calendar
-      @valid_periods = %w[M Q Y]
-
-      class << self
-        def frame_of_reference = "total"
-      end
-
-      def to_s
-        "#{volume}x every #{period_count} calendar #{humanized_period}"
-      end
-
-      # "Absent further completions, you go red on this date"
-      # @return [Date, nil] the date on which the cycle will expire given the
-      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
-      def expiration_of(completion_dates)
-        anchor = completion_dates.max_by(volume) { _1 }.min
-        return unless satisfied_by?(completion_dates, anchor:)
-
-        window_end(anchor) + duration
-      end
-
-      def final_date(anchor)
-        return if anchor.nil?
-        time_span.end_date_of_period(anchor.to_date)
-      end
-      alias_method :window_end, :final_date
-
-      def start_date(anchor)
-        time_span.begin_date_of_period(anchor.to_date)
-      end
-    end
   end
 end

data/lib/sof/cycles/calendar.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class Calendar < Cycle
+      @volume_only = false
+      @notation_id = "C"
+      @kind = :calendar
+      @valid_periods = %w[M Q Y]
+
+      class << self
+        def frame_of_reference = "total"
+      end
+
+      def self.recurring? = true
+
+      def to_s
+        "#{volume}x every #{period_count} calendar #{humanized_period}"
+      end
+
+      # "Absent further completions, you go red on this date"
+      # @return [Date, nil] the date on which the cycle will expire given the
+      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
+      def expiration_of(completion_dates)
+        anchor = completion_dates.max_by(volume) { _1 }.min
+        return unless satisfied_by?(completion_dates, anchor:)
+
+        window_end(anchor) + duration
+      end
+
+      def final_date(anchor)
+        return if anchor.nil?
+        time_span.end_date_of_period(anchor.to_date)
+      end
+      alias_method :window_end, :final_date
+
+      def start_date(anchor)
+        time_span.begin_date_of_period(anchor.to_date)
+      end
+    end
+  end
+end

data/lib/sof/cycles/dormant.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class Dormant
+      def initialize(cycle, parser:)
+        @cycle = cycle
+        @parser = parser
+      end
+
+      attr_reader :cycle, :parser
+
+      def self.recurring? = false
+
+      def kind = :dormant
+
+      def dormant? = true
+
+      def to_s
+        cycle.to_s + " (dormant)"
+      end
+
+      def covered_dates(...) = []
+
+      def expiration_of(...) = nil
+
+      def satisfied_by?(...) = false
+
+      def cover?(...) = false
+
+      def method_missing(method, ...) = cycle.send(method, ...)
+
+      def respond_to_missing?(method, include_private = false)
+        cycle.respond_to?(method, include_private)
+      end
+    end
+  end
+end

data/lib/sof/cycles/end_of.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class EndOf < Cycle
+      @volume_only = false
+      @notation_id = "E"
+      @kind = :end_of
+      @valid_periods = %w[W M Q Y]
+
+      def self.recurring? = true
+
+      def to_s
+        return dormant_to_s if dormant?
+
+        "#{volume}x by #{final_date.to_fs(:american)}"
+      end
+
+      def final_date(_ = nil) = time_span
+        .end_date(start_date)
+        .end_of_month
+
+      def start_date(_ = nil) = from_date.to_date
+
+      private
+
+      def dormant_to_s
+        <<~DESC.squish
+          #{volume}x by the last day of the #{subsequent_ordinal}
+          subsequent #{period}
+        DESC
+      end
+
+      def subsequent_ordinal
+        ActiveSupport::Inflector.ordinalize(period_count - 1)
+      end
+    end
+  end
+end

data/lib/sof/cycles/lookback.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class Lookback < Cycle
+      @volume_only = false
+      @notation_id = "L"
+      @kind = :lookback
+      @valid_periods = %w[D W M Y]
+
+      def self.recurring? = true
+
+      def to_s = "#{volume}x in the prior #{period_count} #{humanized_period}"
+
+      def volume_to_delay_expiration(completion_dates, anchor:)
+        oldest_relevant_completion = completion_dates.min
+        [completion_dates.count(oldest_relevant_completion), volume].min
+      end
+
+      # "Absent further completions, you go red on this date"
+      # @return [Date, nil] the date on which the cycle will expire given the
+      #   provided completion dates. Returns nil if the cycle is already unsatisfied.
+      def expiration_of(completion_dates)
+        anchor = completion_dates.max_by(volume) { _1 }.min
+        return unless satisfied_by?(completion_dates, anchor:)
+
+        window_end anchor
+      end
+
+      def final_date(anchor)
+        return if anchor.nil?
+
+        time_span.end_date(anchor.to_date)
+      end
+      alias_method :window_end, :final_date
+
+      def start_date(anchor)
+        time_span.begin_date(anchor.to_date)
+      end
+      alias_method :window_start, :start_date
+    end
+  end
+end

data/lib/sof/cycles/volume_only.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class VolumeOnly < Cycle
+      @volume_only = true
+      @notation_id = nil
+      @kind = :volume_only
+      @valid_periods = []
+
+      class << self
+        def handles?(sym) = sym.nil? || super
+
+        def validate_period(period)
+          raise InvalidPeriod, <<~ERR.squish unless period.nil?
+            Invalid period value of '#{period}' provided. Valid periods are:
+            #{valid_periods.join(", ")}
+          ERR
+        end
+      end
+
+      def self.recurring? = false
+
+      def to_s = "#{volume}x total"
+
+      def covered_dates(dates, ...) = dates
+
+      def cover?(...) = true
+    end
+  end
+end

data/lib/sof/cycles/within.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SOF
+  module Cycles
+    class Within < Cycle
+      @volume_only = false
+      @notation_id = "W"
+      @kind = :within
+      @valid_periods = %w[D W M Y]
+
+      def self.recurring? = false
+
+      def to_s = "#{volume}x within #{date_range}"
+
+      def date_range
+        return humanized_span unless active?
+
+        [start_date, final_date].map { _1.to_fs(:american) }.join(" - ")
+      end
+
+      def final_date(_ = nil) = time_span.end_date(start_date)
+
+      def start_date(_ = nil) = from_date.to_date
+    end
+  end
+end

data/lib/sof/{cycle/parser.rb → parser.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../cycle"
+require_relative "cycle"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/object/blank"
 require "active_support/core_ext/object/inclusion"
@@ -10,22 +10,22 @@ require "active_support/isolated_execution_state"
 module SOF
   # This class is not intended to be referenced directly.
   # This is an internal implementation of Cycle behavior.
-  class Cycle::Parser
+  class Parser
     extend Forwardable
     PARTS_REGEX = /
       ^(?<vol>V(?<volume>\d*))? # optional volume
-      (?<set>(?<kind>L|C|W) # kind
+      (?<set>(?<kind>L|C|W|E) # kind
       (?<period_count>\d+) # period count
       (?<period_key>D|W|M|Q|Y)?)? # period_key
       (?<from>F(?<from_date>\d{4}-\d{2}-\d{2}))?$ # optional from
     /ix
 
-    def self.dormant_capable_kinds = %w[W]
+    def self.dormant_capable_kinds = %w[E W]
 
-    def self.for(str_or_notation)
-      return str_or_notation if str_or_notation.is_a? self
+    def self.for(notation_or_parser)
+      return notation_or_parser if notation_or_parser.is_a? self
 
-      new(str_or_notation)
+      new(notation_or_parser)
     end
 
     def self.load(hash)
@@ -50,7 +50,7 @@ module SOF
 
     # Return a TimeSpan object for the period and period_count
     def time_span
-      @time_span ||= Cycle::TimeSpan.for(period_count, period_key)
+      @time_span ||= TimeSpan.for(period_count, period_key)
     end
 
     def valid? = match.present?

data/lib/sof/{cycle/time_span.rb → time_span.rb}

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "../cycle"
-require "active_support/deprecator"
-require "active_support/deprecation"
-require "active_support/core_ext/numeric/time"
-require "active_support/core_ext/integer/time"
-require "active_support/core_ext/string/conversions"
 module SOF
   # This class is not intended to be referenced directly.
   # This is an internal implementation of Cycle behavior.
-  class Cycle::TimeSpan
+  class TimeSpan
     extend Forwardable
     # TimeSpan objects map Cycle notations to behaviors for their periods
     #

data/lib/sof-cycle.rb

@@ -1 +1,17 @@
+require "forwardable"
+require "active_support/deprecator"
+require "active_support/deprecation"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/integer/time"
+require "active_support/core_ext/string/conversions"
+require "active_support/core_ext/date/conversions"
+require "active_support/core_ext/string/filters"
+require "active_support/inflector"
+require "active_support/string_inquirer"
+
+require_relative "sof/cycle/version"
 require_relative "sof/cycle"
+
+Dir[File.join(__dir__, "sof", "cycles", "*.rb")].each { |file| require file }
+
+require_relative "sof/time_span"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jim Gay
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-09 00:00:00.000000000 Z
+date: 2024-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwardable
@@ -50,11 +50,20 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
+- checksums/sof-cycle-0.1.0.gem.sha512
+- checksums/sof-cycle-0.1.1.gem.sha512
+- checksums/sof-cycle-0.1.2.gem.sha512
 - lib/sof-cycle.rb
 - lib/sof/cycle.rb
-- lib/sof/cycle/parser.rb
-- lib/sof/cycle/time_span.rb
 - lib/sof/cycle/version.rb
+- lib/sof/cycles/calendar.rb
+- lib/sof/cycles/dormant.rb
+- lib/sof/cycles/end_of.rb
+- lib/sof/cycles/lookback.rb
+- lib/sof/cycles/volume_only.rb
+- lib/sof/cycles/within.rb
+- lib/sof/parser.rb
+- lib/sof/time_span.rb
 homepage: https://github.com/SOFware/sof-cycle
 licenses: []
 metadata:
@@ -75,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.4.13
 signing_key:
 specification_version: 4
 summary: Parse and interact with SOF cycle notation.