fat_period 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5742b6c1b70e7477cb2b8e077c3b1e5d96fc417858f618a12ad64a457df692e4
-  data.tar.gz: 7965192d8da3ea88002089c52dc9344cae1f75e7fab28739185b5f290c3f1bc9
+  metadata.gz: 875ad1917477c27f17278fb0d5aad18423f4dcf52f32c9957651c829a1164f4b
+  data.tar.gz: 1495e04adb60e49dfc26f1b94c9699a129f30b7a15c36e9fa82d0e68d87ed183
 SHA512:
-  metadata.gz: 78bf26849daf793f3b2115e136599178817fd43a1a03bc2882eea408bd7995c44feb94998f22bb220afeb3c2b8270770aa7dc586736849af5f5506f6f7e1123b
-  data.tar.gz: dc0b08cb99a577a8fe11827e96ef1c9473a4536fe4ae0e7dd483fc7a1d1d0493a333eecbbcc8a2cd9f710d03489bc32aa4c8695b9787007dc51efddb9805e14b
+  metadata.gz: f7e5ece151032b3ce11aad94225ef649c9e217a2d9239406f3ef030b335169cc33a130ff860b11b65a2e9d90ab4d9f900eb6df713f904beb9d841a7068ebcb96
+  data.tar.gz: 91a94d16666150d0eba4cd4bd5cb24813150d714f2e534a15746bd70119e87996d39940d8da40c5ab7589707975fe53f60a53cd4ae7d9bd58254b710d7d3c4ee

data/lib/fat_period/period.rb

@@ -30,9 +30,7 @@ class Period
     @last = Date.ensure_date(last).freeze
     freeze
 
-    return unless @first > @last
-
-    raise ArgumentError, "Period's first date is later than its last date"
+    raise ArgumentError, "Period's first date is later than its last date" if @first > @last
   end
 
   # These need to come after initialize is defined
@@ -66,35 +64,73 @@ class Period
     Period.new(first, second) if first && second
   end
 
-  # Return a period as in `Period.parse` from a String phrase in which the from
-  # spec is introduced with 'from' and, optionally, the to spec is introduced
-  # with 'to'.  A phrase with only a to spec is treated the same as one with
-  # only a from spec.  If neither 'from' nor 'to' appear in phrase, treat the
-  # whole string as a from spec.
+  # Return a Period either from a given String or other type that can
+  # reasonably converted to a Period.
   #
   # @example
-  #   Period.parse_phrase('from 2014-11 to 2015-3Q') #=> Period('2014-11-01..2015-09-30')
-  #   Period.parse_phrase('from 2014-11')            #=> Period('2014-11-01..2014-11-30')
-  #   Period.parse_phrase('from 2015-3Q')            #=> Period('2015-09-01..2015-12-31')
-  #   Period.parse_phrase('to 2015-3Q')              #=> Period('2015-09-01..2015-12-31')
-  #   Period.parse_phrase('2015-3Q')                 #=> Period('2015-09-01..2015-12-31')
+  #   Period.ensure('2014-11').inspect    #=> Period('2014-11-01..2014-11-30')
+  #   pd = Period.parse('2011')
+  #   Period.ensure(pd).inspect           #=> Period('2011-01-01..2011-12-31')
+  #
+  # @param prd [String|Period] or any candidate for conversion to Period
+  # @return Period correspondign to prd parameter
+  def self.ensure(prd)
+    prd.to_period if prd.respond_to?(:to_period)
+    case prd
+    when String
+      if prd.match(/from|to/i)
+        Period.parse_phrase(prd).first
+      else
+        Period.parse(prd)
+      end
+    when Period
+      prd
+    end
+  end
+
+  # Return an Array of Periods from a String phrase in which the from spec is
+  # introduced with 'from' and, optionally, the to spec is introduced with
+  # 'to' and optionally a 'per' clause is introduced by 'per'.  A phrase with
+  # only a to spec is treated the same as one with only a from spec.  If
+  # neither 'from' nor 'to' appear in phrase, treat the string before any
+  # per-clause as a from spec.
   #
-  # @param phrase [String] with 'from <spec> to <spec>'
+  # @example
+  #   Period.parse_phrase('from 2014-11 to 2015-3Q') #=> [Period('2014-11-01..2015-09-30')]
+  #   Period.parse_phrase('from 2014-11')            #=> [Period('2014-11-01..2014-11-30')]
+  #   Period.parse_phrase('from 2015-3Q')            #=> [Period('2015-09-01..2015-12-31')]
+  #   Period.parse_phrase('to 2015-3Q')              #=> [Period('2015-09-01..2015-12-31')]
+  #   Period.parse_phrase('2015-3Q')                 #=> [Period('2015-09-01..2015-12-31')]
+  #   Period.parse_phrase('to 2015-3Q per week')     #=> [Period('2015-09-01..2015-09-04')...]
+  #   Period.parse_phrase('2015-3Q per month')       #=> [Period('2015-09-01..2015-09-30')...]
+  #
+  # @param phrase [String] with 'from <spec> [to <spec>] [per chunk]'
   # @return [Period] translated from phrase
-  def self.parse_phrase(phrase)
+  def self.parse_phrase(phrase, partial_first: true, partial_last: true, round_up_last: false)
     phrase = phrase.clean
     case phrase
-    when /\Afrom (.*) to (.*)\z/
+    when /\Afrom\s+([^\s]+)\s+to\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
       from_phrase = $1
       to_phrase = $2
-    when /\Afrom (.*)\z/, /\Ato (.*)\z/
+    when /\Afrom\s+([^\s]+)(\s+per\s+[^\s]+)?\z/, /\Ato\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
       from_phrase = $1
       to_phrase = nil
-    else
-      from_phrase = phrase
+    when /\A([^\s]+)(\s+per\s+[^\s]+)?\z/
+      from_phrase = $1
       to_phrase = nil
+    else
+      raise ArgumentError, "unintelligible period phrase: '#{phrase}''"
+    end
+    # Return an Array of periods divided by chunks if any.
+    whole_period = parse(from_phrase, to_phrase)
+    if phrase =~ /per\s+(?<chunk>[a-z_]+)/i
+      chunk_size = Regexp.last_match[:chunk].downcase.to_sym
+      raise ArgumentError, "invalid chunk size #{chunk_size}" unless CHUNKS.include?(chunk_size)
+
+      whole_period.chunks(size: chunk_size, partial_first:, partial_last:, round_up_last:)
+    else
+      [whole_period]
     end
-    parse(from_phrase, to_phrase)
   end
 
   # @group Conversion
@@ -183,7 +219,7 @@ class Period
   end
 
   def eql?(other)
-    return unless other.is_a?(Period)
+    return false unless other.is_a?(Period)
 
     hash == other.hash
   end
@@ -284,7 +320,6 @@ class Period
     quarter
     half
     year
-    irregular
   ].freeze
 
   CHUNK_ORDER = {}

data/lib/fat_period/version.rb

@@ -1,3 +1,3 @@
 module FatPeriod
-  VERSION = '2.0.0'.freeze
+  VERSION = '2.1.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fat_period
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Daniel E. Doherty
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-12 00:00:00.000000000 Z
+date: 2024-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fat_core