fat_period 1.1.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05402b5173907362901a6890276937450921c418596ebe53e7d3576bcebd3d7b
-  data.tar.gz: 4d78c11cb533cb6f45f8e6cd941887c8cc2f1645c4db5052ad543627228c3e73
+  metadata.gz: cb2c6b600f446fa2bff8080b8056a32ceb3fda88be68c03db076591753c4992e
+  data.tar.gz: f4d65daa079f338c2a1a7ab5a0d326ae9af884d819a72077f1f24e8128ed70de
 SHA512:
-  metadata.gz: 5fcb751568bcf4c7f33ee03f4a60c55bbbf04def94475069383ed31400fc62dc8c46d70affa60374b0cace8016b1f60655275127a6cbbed36479f7cc86972879
-  data.tar.gz: 8b5120f531483283c834531b7b3a8ddfbc0e7f816087cbcaa50338c74a06990aa6bce5d619ac0331976e05608b645406d6ca6723a3cfec8bc936f2584a4ccc40
+  metadata.gz: 3059659aed2c2000401a6fceca177b9b7ea633adaaa1012bcb20db1069845bdc7dff35b97a53289a498399d1bc2217ceffd06c4dae94377ce7a47710c71ab2af
+  data.tar.gz: ab0e1a8aebca6fc8acf0e952e9a48956767b03e7cd9071d6487b52e0a544519e6801b927ae3b2f5021e1fc3ac8aeb95114488192fcd343b265b235efc38a6784

data/.travis.yml

@@ -3,4 +3,4 @@ rvm:
   - 2.5
   - 2.6
   - 2.7
-  - ruby-head
+  - 3.0

data/fat_period.gemspec

@@ -23,9 +23,9 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'debug', '>= 1.0.0'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-doc'
-  spec.add_development_dependency 'pry-byebug'
 
   spec.add_runtime_dependency 'fat_core', '>= 4.8.3'
 end

data/lib/fat_period/period.rb

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-
 require 'fat_core/date'
 require 'fat_core/range'
 require 'fat_core/string'
@@ -29,8 +27,9 @@ class Period
   # @raise [ArgumentError] if first date is later than last date
   # @return [Period]
   def initialize(first, last)
-    @first = Date.ensure_date(first)
-    @last = Date.ensure_date(last)
+    @first = Date.ensure_date(first).freeze
+    @last = Date.ensure_date(last).freeze
+    freeze
 
     return unless @first > @last
 
@@ -71,36 +70,59 @@ 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.
+  PHRASE_RE = %r{\A
+      # One or both of from and to parts
+      ((from\s+(?<from_part>[-_a-z0-9]+)\s*)?
+      (to\s+(?<to_part>[-_a-z0-9]+))?)
+      # Wholly optional chunk part
+      (\s+per\s+(?<chunk_part>\w+))?\z}xi
+
+  # Return an array of periods, either a single period as in `Period.parse`
+  # from a String phrase in which a `from spec` is introduced with 'from' and,
+  # optionally, a `to spec` is introduced with 'to', or a number of periods if
+  # there is a 'per <chunk>' modifier.  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.
   #
   # @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')
-  #
-  # @param phrase [String] with 'from <spec> to <spec>'
-  # @return [Period] translated from phrase
-  def self.parse_phrase(phrase)
-    phrase = phrase.clean
-    if phrase =~ /\Afrom (.*) to (.*)\z/
-      from_phrase = $1
-      to_phrase = $2
-    elsif phrase =~ /\Afrom (.*)\z/
-      from_phrase = $1
-      to_phrase = nil
-    elsif phrase =~ /\Ato (.*)\z/
-      from_phrase = $1
+  #   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('from 2015-3Q')            #=> [Period('2015-09-01..2015-12-31')]
+  #   Period.parse_phrase('from 2015 per month')     #=> [
+  #                                                        Period('2015-01-01..2015-01-31'),
+  #                                                        Period('2015-02-01..2015-02-28'),
+  #                                                         ...
+  #                                                        Period('2015-12-01..2015-12-31')
+  #                                                       ]
+  #
+  # @param phrase [String] with 'from <spec> to <spec> [per <chunk>]'
+  # @return [Array<Period>] translated from phrase
+  def self.parse_phrase(phrase,
+                        partial_first: false, partial_last: false, round_up_last: false)
+    phrase = phrase.downcase.clean
+    mm = phrase.match(PHRASE_RE)
+    raise ArgumentError, "invalid period phrase: `#{phrase}`" unless mm
+
+    if mm[:from_part] && mm[:to_part].nil?
+      from_part = mm[:from_part]
+      to_part = nil
+    elsif mm[:from_part].nil? && mm[:to_part]
+      from_part = mm[:to_part]
+      to_part = nil
     else
-      from_phrase = phrase
-      to_phrase = nil
+      from_part = mm[:from_part]
+      to_part = mm[:to_part]
+    end
+
+    whole_period = parse(from_part, to_part)
+    if mm[:chunk_part].nil?
+      [whole_period]
+    else
+      whole_period.chunks(size: mm[:chunk_part], partial_first: partial_first,
+                         partial_last: partial_last, round_up_last: round_up_last)
     end
-    parse(from_phrase, to_phrase)
   end
 
   # @group Conversion
@@ -180,6 +202,20 @@ class Period
     !(self == other)
   end
 
+  # Return the hash value for this Period.  Make Period's with identical
+  # values test eql? so that they may be used as hash keys.
+  #
+  # @return [Integer]
+  def hash
+    (first.hash | last.hash)
+  end
+
+  def eql?(other)
+    return nil unless other.is_a?(Period)
+
+    hash == other.hash
+  end
+
   # Return whether this Period contains the given date.
   #
   # @param date [Date] date to test
@@ -327,9 +363,7 @@ class Period
     raise ArgumentError, 'chunk is nil' unless chunk
 
     chunk = chunk.to_sym
-    unless CHUNKS.include?(chunk)
-      raise ArgumentError, "unknown chunk name: #{chunk}"
-    end
+    raise ArgumentError, "unknown chunk name: #{chunk}" unless CHUNKS.include?(chunk)
 
     date = Date.ensure_date(date)
     method = "#{chunk}_containing".to_sym
@@ -456,20 +490,20 @@ class Period
     end
   end
 
-  # Return the chunk symbol represented by the number of days given, but allow a
-  # deviation from the minimum and maximum number of days for periods larger
-  # than bimonths. The default tolerance is +/-10%, but that can be adjusted. The
-  # reason for allowing a bit of tolerance for the larger periods is that
-  # financial statements meant to cover a given calendar period are often short
-  # or long by a few days due to such things as weekends, holidays, or
-  # accounting convenience. For example, a bank might issuer "monthly"
-  # statements approximately every 30 days, but issue them earlier or later to
-  # avoid having the closing date fall on a weekend or holiday. We still want to
-  # be able to recognize them as "monthly", even though the period covered might
-  # be a few days shorter or longer than any possible calendar month.  You can
-  # eliminate this "fudge factor" by setting the `tolerance_pct` to zero.  If
-  # the number of days corresponds to none of the defined calendar periods,
-  # return the symbol `:irregular`.
+  # Return the chunk symbol represented by the number of days given, but allow
+  # a deviation from the minimum and maximum number of days for periods larger
+  # than bimonths. The default tolerance is +/-10%, but that can be
+  # adjusted. The reason for allowing a bit of tolerance for the larger
+  # periods is that financial statements meant to cover a given calendar
+  # period are often short or long by a few days due to such things as
+  # weekends, holidays, or accounting convenience. For example, a bank might
+  # issuer "monthly" statements approximately every 30 days, but issue them
+  # earlier or later to avoid having the closing date fall on a weekend or
+  # holiday. We still want to be able to recognize them as "monthly", even
+  # though the period covered might be a few days shorter or longer than any
+  # possible calendar month.  You can eliminate this "fudge factor" by setting
+  # the `tolerance_pct` to zero.  If the number of days corresponds to none of
+  # the defined calendar periods, return the symbol `:irregular`.
   #
   # @example
   #   Period.days_to_chunk(360)    #=> :year
@@ -478,12 +512,12 @@ class Period
   #   Period.days_to_chunk(88, 0)  #=> :irregular
   #
   # @param days [Integer] the number of days in the period under test
-  # @param tolerance_pct [Numberic] the percent deviation allowed, e.g. 10 => 10%
+  # @param tolerance_pct [Numeric] the percent deviation allowed, e.g. 10 => 10%
   # @return [Symbol] symbol for the period corresponding to days number of days
   def self.days_to_chunk(days, tolerance_pct = 10)
     result = :irregular
     CHUNK_RANGE.each_pair do |chunk, rng|
-      if [:semimonth, :biweek, :week, :day].include?(chunk)
+      if %i[semimonth biweek week day].include?(chunk)
         # Be strict for shorter periods.
         if rng.cover?(days)
           result = chunk
@@ -574,9 +608,7 @@ class Period
   def chunks(size: :month, partial_first: false, partial_last: false,
              round_up_last: false)
     chunk_size = size.to_sym
-    unless CHUNKS.include?(chunk_size)
-      raise ArgumentError, "unknown chunk size '#{chunk_size}'"
-    end
+    raise ArgumentError, "unknown chunk size '#{chunk_size}'" unless CHUNKS.include?(chunk_size)
 
     containing_period = Period.chunk_containing(first, chunk_size)
     return [dup] if self == containing_period
@@ -598,26 +630,25 @@ class Period
       return result
     end
 
+    # The first chunk
     chunk_start = first.dup
     chunk_end = chunk_start.end_of_chunk(chunk_size)
     if chunk_start.beginning_of_chunk?(chunk_size) || partial_first
       # Keep the first chunk if it's whole or partials allowed
       result << Period.new(chunk_start, chunk_end)
-      chunk_start = chunk_end + 1.day
-      chunk_end = chunk_start.end_of_chunk(chunk_size)
-    else
-      # Discard the partial first or move to next whole chunk
-      chunk_start = chunk_end + 1.day
-      chunk_end = chunk_start.end_of_chunk(chunk_size)
     end
+    chunk_start = chunk_end + 1.day
+    chunk_end = chunk_start.end_of_chunk(chunk_size)
+
     # Add Whole chunks
     while chunk_end <= last
       result << Period.new(chunk_start, chunk_end)
       chunk_start = chunk_end + 1.day
       chunk_end = chunk_start.end_of_chunk(chunk_size)
     end
+
     # Possibly append the final chunk to result
-    if chunk_start < last
+    if chunk_start <= last
       if round_up_last
         result << Period.new(chunk_start, chunk_end)
       elsif partial_last
@@ -625,15 +656,15 @@ class Period
       else
         result
       end
-    elsif partial_last
+    end
+    if partial_last && !partial_first && result.empty?
       # Catch the case where the period is too small to make a whole chunk and
       # partial_first is false, so it did not get included as the initial
       # partial chunk, yet a partial_last is allowed, so include the whole
       # period as a partial chunk.
       result << Period.new(first, last)
-    else
-      result
     end
+    result
   end
 
   # @group Set operations
@@ -677,7 +708,7 @@ class Period
     to_range.superset_of?(other.to_range)
   end
 
-  # Does this period wholly contain but not coincident with `other`?
+  # Does this period wholly contain but is not coincident with `other`?
   #
   # @example
   #   Period.parse('2015').proper_superset_of?(Period.parse('2015-2Q'))    #=> true

data/lib/fat_period/version.rb

@@ -1,3 +1,3 @@
 module FatPeriod
-  VERSION = '1.1.1'.freeze
+  VERSION = '1.3.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fat_period
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Daniel E. Doherty
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-07 00:00:00.000000000 Z
+date: 2022-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,21 +53,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: debug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
 - !ruby/object:Gem::Dependency
-  name: pry-doc
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: pry-doc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -108,7 +108,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 4.8.3
-description: 
+description:
 email:
 - ded-law@ddoherty.net
 executables: []
@@ -132,7 +132,7 @@ files:
 homepage: https://github.com/ddoherty03/fat_period
 licenses: []
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -147,8 +147,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.3.3
+signing_key:
 specification_version: 4
 summary: Implements a Period class as a Range of Dates.
 test_files: []