sof-cycle 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea1c2c9a48bba72114b7681278cd467c57ee147f6f8b1ff176b4508de355920b
-  data.tar.gz: 93a7560799df4730a5eaf2d14708b9a24199c0a95d2b01f1487ddc587b0846da
+  metadata.gz: f9b1ae30ef2bd0d0fb9dbc08efb701b9813d997c216a22bf1df67fcbed7efe29
+  data.tar.gz: ac73534e2d48354722e929e41fccf0bae4a913466b181802daa8afe3daa9beae
 SHA512:
-  metadata.gz: baf569f5fb7e0500b8a28915c8f19b86dc97ebee380301787182216d162fd02e659645345d369440959ebde737b59bb8ddd4372dae0bf014a9e3b448e8455e03
-  data.tar.gz: 84756e0428c56a7f6dd72e5dc7aa545a587bbffd49479a436e4f8bee2d60ec3496e128f713a36b0169799ff908e0690e4518b147e750eaa0fb662681f0e036a0
+  metadata.gz: 6b4a0d60e48feed105e71c6410e4ba22152e88ed8502b43b32974e585cc1abce432867b0c635ada9376258df79d799d2f3f383e4499742f5023db623a4ac8ebe
+  data.tar.gz: e506926aed85332f02e8f5790ec752416679fe9a0c1542bd750f6097d204c4ed4237a866cc4552e67f612218ae58dbb819f68260de67e84fcf32b3d78351e0ba

data/CHANGELOG.md

@@ -5,18 +5,14 @@ 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.2] - 2024-08-09
+## [0.1.4] - 2024-09-02
 
 ### Added
 
-- `Cycle#recurring?` to reveal if a given Cycle is one-and-done or must be repeated.
+- `Cycle#last_completed` to return the last completion given the cycle and an array of dates
 
-## [0.1.1] - 2024-08-09
+## [0.1.3] - 2024-09-01
 
-### Added
+### Fixed
 
-- 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
+- `Cycles::EndOf` to have the correct behavior

data/lib/sof/cycle/version.rb

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

data/lib/sof/cycle.rb

@@ -11,142 +11,142 @@ module SOF
 
     class InvalidKind < InvalidInput; end
 
-    def initialize(notation, parser: Parser.new(notation))
-      @notation = notation
-      @parser = parser
-      validate_period
+    class << self
+      # Turn a cycle or notation string into a hash
+      def dump(cycle_or_string)
+        if cycle_or_string.is_a? Cycle
+          cycle_or_string
+        else
+          Cycle.for(cycle_or_string)
+        end.to_h
+      end
 
-      return if @parser.valid?
+      # Return a Cycle object from a hash
+      def load(hash)
+        symbolized_hash = hash.symbolize_keys
+        cycle_class = class_for_kind(symbolized_hash[:kind])
 
-      raise InvalidInput, "'#{notation}' is not a valid input"
-    end
+        unless cycle_class.valid_periods.empty?
+          cycle_class.validate_period(
+            TimeSpan.notation_id_from_name(symbolized_hash[:period])
+          )
+        end
 
-    attr_reader :parser
+        Cycle.for notation(symbolized_hash)
+      rescue TimeSpan::InvalidPeriod => exc
+        raise InvalidPeriod, exc.message
+      end
 
-    delegate [:activated_notation, :volume, :from, :from_date, :time_span, :period,
-      :humanized_period, :period_key, :active?] => :@parser
-    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
+      # Retun a notation string from a hash
+      #
+      # @param hash [Hash] hash of data for a valid Cycle
+      # @return [String] string representation of a Cycle
+      def notation(hash)
+        volume_notation = "V#{hash.fetch(:volume) { 1 }}"
+        return volume_notation if hash[:kind].nil? || hash[:kind].to_sym == :volume_only
+
+        cycle_class = class_for_kind(hash[:kind].to_sym)
+        [
+          volume_notation,
+          cycle_class.notation_id,
+          TimeSpan.notation(hash.slice(:period, :period_count)),
+          hash.fetch(:from, nil)
+        ].compact.join
+      end
 
-    # Turn a cycle or notation string into a hash
-    def self.dump(cycle_or_string)
-      if cycle_or_string.is_a? Cycle
-        cycle_or_string
-      else
-        Cycle.for(cycle_or_string)
-      end.to_h
-    end
+      # Return a Cycle object from a notation string
+      #
+      # @param notation [String] a string notation representing a Cycle
+      # @example
+      #   Cycle.for('V2C1Y)
+      # @return [Cycle] a Cycle object representing the provide string notation
+      def for(notation)
+        return notation if notation.is_a? Cycle
+        return notation if notation.is_a? Cycles::Dormant
+        parser = Parser.new(notation)
+        unless parser.valid?
+          raise InvalidInput, "'#{notation}' is not a valid input"
+        end
+
+        cycle = cycle_handlers.find do |klass|
+          parser.parses?(klass.notation_id)
+        end.new(notation, parser:)
+        return cycle if parser.active?
+
+        Cycles::Dormant.new(cycle, parser:)
+      end
 
-    # Return a Cycle object from a hash
-    def self.load(hash)
-      symbolized_hash = hash.symbolize_keys
-      cycle_class = class_for_kind(symbolized_hash[:kind])
+      # Return the appropriate class for the give notation id
+      #
+      # @param notation [String] notation id matching the kind of Cycle class
+      # @example
+      #   class_for_notation_id('L')
+      #
+      def class_for_notation_id(notation_id)
+        cycle_handlers.find do |klass|
+          klass.notation_id == notation_id
+        end || raise(InvalidKind, "'#{notation_id}' is not a valid kind of #{name}")
+      end
 
-      unless cycle_class.valid_periods.empty?
-        cycle_class.validate_period(
-          TimeSpan.notation_id_from_name(symbolized_hash[:period])
-        )
+      # Return the class handling the kind
+      #
+      # @param sym [Symbol] symbol matching the kind of Cycle class
+      # @example
+      #   class_for_kind(:lookback)
+      def class_for_kind(sym)
+        Cycle.cycle_handlers.find do |klass|
+          klass.handles?(sym)
+        end || raise(InvalidKind, "':#{sym}' is not a valid kind of Cycle")
       end
 
-      Cycle.for notation(symbolized_hash)
-    rescue TimeSpan::InvalidPeriod => exc
-      raise InvalidPeriod, exc.message
-    end
+      def cycle_handlers = @cycle_handlers ||= Set.new
 
-    # Retun a notation string from a hash
-    #
-    # @param hash [Hash] hash of data for a valid Cycle
-    # @return [String] string representation of a Cycle
-    def self.notation(hash)
-      volume_notation = "V#{hash.fetch(:volume) { 1 }}"
-      return volume_notation if hash[:kind].nil? || hash[:kind].to_sym == :volume_only
-
-      cycle_class = class_for_kind(hash[:kind].to_sym)
-      [
-        volume_notation,
-        cycle_class.notation_id,
-        TimeSpan.notation(hash.slice(:period, :period_count)),
-        hash.fetch(:from, nil)
-      ].compact.join
-    end
+      def inherited(klass) = cycle_handlers << klass
 
-    # Return a Cycle object from a notation string
-    #
-    # @param notation [String] a string notation representing a Cycle
-    # @example
-    #   Cycle.for('V2C1Y)
-    # @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? Cycles::Dormant
-      parser = Parser.new(notation)
-      unless parser.valid?
-        raise InvalidInput, "'#{notation}' is not a valid input"
+      def handles?(sym)
+        sym && kind == sym.to_sym
       end
 
-      cycle = cycle_handlers.find do |klass|
-        parser.parses?(klass.notation_id)
-      end.new(notation, parser:)
-      return cycle if parser.active?
+      @volume_only = false
+      @notation_id = nil
+      @kind = nil
+      @valid_periods = []
 
-      Cycles::Dormant.new(cycle, parser:)
-    end
+      attr_reader :notation_id, :kind, :valid_periods
+      def volume_only? = @volume_only
 
-    # Return the appropriate class for the give notation id
-    #
-    # @param notation [String] notation id matching the kind of Cycle class
-    # @example
-    #   class_for_notation_id('L')
-    #
-    def self.class_for_notation_id(notation_id)
-      cycle_handlers.find do |klass|
-        klass.notation_id == notation_id
-      end || raise(InvalidKind, "'#{notation_id}' is not a valid kind of #{name}")
-    end
+      def recurring? = raise "#{name} must implement #{__method__}"
 
-    # Return the class handling the kind
-    #
-    # @param sym [Symbol] symbol matching the kind of Cycle class
-    # @example
-    #   class_for_kind(:lookback)
-    def self.class_for_kind(sym)
-      Cycle.cycle_handlers.find do |klass|
-        klass.handles?(sym)
-      end || raise(InvalidKind, "':#{sym}' is not a valid kind of Cycle")
+      # Raises an error if the given period isn't in the list of valid periods.
+      #
+      # @param period [String] period matching the class valid periods
+      # @raise [InvalidPeriod]
+      def validate_period(period)
+        raise InvalidPeriod, <<~ERR.squish unless valid_periods.include?(period)
+          Invalid period value of '#{period}' provided. Valid periods are:
+          #{valid_periods.join(", ")}
+        ERR
+      end
     end
 
-    def self.cycle_handlers = @cycle_handlers ||= Set.new
+    def initialize(notation, parser: Parser.new(notation))
+      @notation = notation
+      @parser = parser
+      validate_period
 
-    def self.inherited(klass) = cycle_handlers << klass
+      return if @parser.valid?
 
-    def self.handles?(sym)
-      sym && kind == sym.to_sym
+      raise InvalidInput, "'#{notation}' is not a valid input"
     end
 
-    @volume_only = false
-    @notation_id = nil
-    @kind = nil
-    @valid_periods = []
-
-    class << self
-      attr_reader :notation_id, :kind, :valid_periods
-      def volume_only? = @volume_only
-
-      def recurring? = raise "#{name} must implement #{__method__}"
-    end
+    attr_reader :parser
 
-    # Raises an error if the given period isn't in the list of valid periods.
-    #
-    # @param period [String] period matching the class valid periods
-    # @raise [InvalidPeriod]
-    def self.validate_period(period)
-      raise InvalidPeriod, <<~ERR.squish unless valid_periods.include?(period)
-        Invalid period value of '#{period}' provided. Valid periods are:
-        #{valid_periods.join(", ")}
-      ERR
-    end
+    delegate [:activated_notation, :volume, :from, :from_date, :time_span, :period,
+      :humanized_period, :period_key, :active?] => :@parser
+    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
 
     def kind_inquiry = ActiveSupport::StringInquirer.new(kind.to_s)
 
@@ -162,6 +162,9 @@ module SOF
     # Cycles are considered equal if their hash representations are equal
     def ==(other) = to_h == other.to_h
 
+    # Return the most recent completion date from the supplied array of dates
+    def last_completed(dates) = dates.compact.map(&:to_date).max
+
     # From the supplied anchor date, are there enough in-window completions to
     # satisfy the cycle?
     #

data/lib/sof/cycles/end_of.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# Captures the logic for enforcing the EndOf cycle variant
+#   E.g. "V1E18MF2020-01-05" means:
+#     You're good until the end of the 17th subsequent month from 2020-01-05.
+#     Complete 1 by that date to reset the cycle.
+#
+# Some of the calculations are quite different from other cycles.
+# Whereas other cycles look at completion dates to determine if the cycle is
+# satisfied, this cycle checks whether the anchor date is prior to the final date.
 module SOF
   module Cycles
     class EndOf < Cycle
@@ -16,8 +24,37 @@ module SOF
         "#{volume}x by #{final_date.to_fs(:american)}"
       end
 
+      # Always returns the from_date
+      def last_completed(_) = from_date.to_date
+
+      # Returns the expiration date for the cycle
+      #
+      # @param [nil] _ Unused parameter, maintained for compatibility
+      # @param anchor [nil] _ Unused parameter, maintained for compatibility
+      # @return [Date] The final date of the cycle
+      #
+      # @example
+      #   Cycle.for("V1E18MF2020-01-09")
+      #     .expiration_of(anchor: "2020-06-04".to_date)
+      #   # => #<Date: 2021-06-30>
+      def expiration_of(_ = nil, anchor: nil) = final_date
+
+      # Is the supplied anchor date prior to the final date?
+      #
+      # @return [Boolean] true if the cycle is satisfied, false otherwise
+      def satisfied_by?(_ = nil, anchor: Date.current) = anchor <= final_date
+
+      # Calculates the final date of the cycle
+      #
+      # @param [nil] _ Unused parameter, maintained for compatibility
+      # @return [Date] The final date of the cycle calculated as the end of the
+      #   nth subsequent period after the FROM date, where n = (period count - 1)
+      #
+      # @example
+      #   Cycle.for("V1E18MF2020-01-09").final_date
+      #   # => #<Date: 2021-06-30>
       def final_date(_ = nil) = time_span
-        .end_date(start_date)
+        .end_date(start_date - 1.send(period))
         .end_of_month
 
       def start_date(_ = nil) = from_date.to_date

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sof-cycle
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Jim Gay
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-09 00:00:00.000000000 Z
+date: 2024-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: forwardable
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Parse and interact with SOF cycle notation.