fat_period 2.0.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5742b6c1b70e7477cb2b8e077c3b1e5d96fc417858f618a12ad64a457df692e4
-  data.tar.gz: 7965192d8da3ea88002089c52dc9344cae1f75e7fab28739185b5f290c3f1bc9
+  metadata.gz: dadf65165f7640c1ed71d1b39446a330f810779a23acc6975986249b71918a8e
+  data.tar.gz: c118e93977b2133c99fbb53bcc64eea6dd7a98f30f05bfe64742f501d7d60753
 SHA512:
-  metadata.gz: 78bf26849daf793f3b2115e136599178817fd43a1a03bc2882eea408bd7995c44feb94998f22bb220afeb3c2b8270770aa7dc586736849af5f5506f6f7e1123b
-  data.tar.gz: dc0b08cb99a577a8fe11827e96ef1c9473a4536fe4ae0e7dd483fc7a1d1d0493a333eecbbcc8a2cd9f710d03489bc32aa4c8695b9787007dc51efddb9805e14b
+  metadata.gz: 8cb63a7e83eb0035be2d3757a7969ff5c9ef244be16495e4aa0a1dcb2276e229d287a695ce8ec8cfdff21c891c076a2d29b6ccbffdb585f821fcfe578e8f3dde
+  data.tar.gz: 4d121f6f04a7780ded6ed2d6f7bb8de6c32e89ea2e96d97f14029f1800ce6ca4516dd6769887210ca5557816c978c39b270b289dee1f84d61737d6216e4ae4d5

data/.envrc

@@ -1,5 +1,4 @@
 PATH_add .bundle/bin
-PATH_add ./scripts
 # Ensure that we use the development DB when in the src dir.
 export DB=development
 export COMPOSE_FILE=.devcontainer/docker-compose.yml

data/.github/workflows/ruby.yml

@@ -0,0 +1,54 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby CI (setup-ruby)
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        ruby: [3.2.2, 3.3.0, 3.4.0]
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Install build dependencies (needed if Ruby must be compiled)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            build-essential autoconf bison libssl-dev libreadline-dev \
+            zlib1g-dev libyaml-dev libffi-dev libgdbm-dev libncurses5-dev \
+            libgmp-dev pkg-config
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Verify Ruby
+        run: |
+          ruby -v
+          gem -v
+        shell: bash
+
+      - name: Install gems
+        run: |
+          gem install bundler --conservative
+          # optional: use vendor/bundle to keep gems within repo workspace
+          bundle config set --local path 'vendor/bundle' || true
+          bundle install --jobs 4 --retry 3
+        shell: bash
+
+      - name: Run tests
+        run: bundle exec rake
+        shell: bash

data/.rubocop.yml

@@ -0,0 +1,3 @@
+# Inherit the shared config from the rubocop-ddoherty gem (git-hosted on GitHub)
+inherit_gem:
+  rubocop-ddoherty: 'config/default.yml'

data/CHANGELOG.org

@@ -0,0 +1,29 @@
+* Version 3.0.0
+- Use the newly-spun-out fat_date library in place of fat_core/date, which no
+  longer exists starting with fat_core version 6.0.0.
+- The fat_date library uses ~Date.spec~ instead of ~Date.parse_spec~, which is
+  just cleaner to type.
+- The new ~fat_date~ libraries come with some notable enhancements to date
+  specs, including:
+  1. Skip modifiers, which allow the spec to "skip" from its usual target date
+     to the nearest day-of-week, either before or after the target date, and
+     either including or not including the target date as a candidate.
+  2. Changes the semimonth specifier from uppercase roman to A or B, so
+     2025-10-A (rather than 2025-I) is now the first semimonth for October,
+     2025, and 2025-10-B (rather than 2025-II) is now the second semimonth.
+     This allows week-of-month specs to be case insensitive, so 2025-10-i,
+     2025-10-ii, 2025-10-iii, 2025-10-iv, and 2025-10-v, can represent the
+     first through fifth week of October, 2025, as well as 2025-10-I,
+     2025-10-II, 2025-10-III, 2025-10-IV, and 2025-10-V.
+  3. In general, all the spec involving letters should now be case insensitive.
+- Some other code cleanup with no impact on the API.
+
+* Version 2.1.0
+- When the first date is later than the second in ~Period.new~, raise
+  ~ArgumentError~ exception instead of returning nil.
+- Allow ~Period.parse_phrase~ to parse a 'per' clause and return an Array of
+  Periods that are sub-periods of the period given by the from- and
+  to-clauses.
+- Add ~Period.ensure(arg)~ to try to return a ~Period~ from a string that can
+  be parsed as a ~Period~, an object that has a ~to_period~ method, or return
+  the ~arg~ if its already a ~Period~.

data/Gemfile

@@ -1,16 +1,17 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in fat_period.gemspec
 gemspec
 
-gem 'bundler'
-gem 'debug'
-gem 'pry'
-gem 'pry-doc'
-gem 'rake'
-gem 'rspec'
-gem 'rubocop'
-gem 'rubocop-rspec'
-gem 'rubocop-performance'
-gem 'rubocop-rake'
-gem 'rubocop-shopify'
+group :development do
+  gem 'bundler'
+  gem 'debug'
+  gem 'pry'
+  gem 'pry-doc'
+  gem 'rake'
+  gem 'rspec'
+  gem 'rubocop', require: false
+  gem 'rubocop-ddoherty', git: 'https://github.com/ddoherty03/rubocop-ddoherty.git', branch: 'master', require: false
+end

data/README.org

@@ -1,22 +1,103 @@
-#+OPTIONS: :toc
+#+TITLE: FatPeriod User Guide
+#+OPTIONS: toc:5
+#+PROPERTY: header-args:ruby :colnames no :session fat_period :hlines yes :exports both :wrap example :ruby "bundle exec irb --prompt=simple"
+#+PROPERTY: header-args:sh :exports code
 #+LATEX_HEADER: \usepackage[margin=0.75in]{geometry}
 
-#+BEGIN_COMMENT
-This is for markdown output:
+[[https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml][https://github.com/ddoherty03/fat_period/actions/workflows/ruby.yml/badge.svg?branch=master]]
 
-The following is for org.
-#+END_COMMENT
+* Setup for Code Blocks                            :noexport:
+Run this block before all others to ensure that we are reading the libraries
+from the source directory.
 
-[[https://travis-ci.org/ddoherty03/fat_table.svg?branch=master]]
+#+begin_src ruby :results output :export no
+  Dir.chdir("/home/ded/src/fat_period")
+  puts "Current directory: #{Dir.pwd}"
+  puts "Ruby LOADPATH:"
+  $LOAD_PATH.unshift(File.expand_path("lib", Dir.pwd)) unless $:[0].match?(%r{src/fat_period/lib})
+  $:[0..10].each { |d| puts d }
+  puts "..."
+  require 'fat_period'
+#+end_src
+
+#+RESULTS:
+#+begin_example
+Current directory: /home/ded/src/fat_period
+Ruby LOADPATH:
+/home/ded/src/fat_period/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/bundler-2.6.7/lib
+/home/ded/.rbenv/rbenv.d/exec/gem-rehash
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/bundler/gems/rubocop-ddoherty-6b28e9614f18/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-shopify-2.17.1/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-rspec-3.7.0/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-rake-0.7.1/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-performance-1.26.1/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/rubocop-1.81.6/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/unicode-display_width-3.2.0/lib
+/home/ded/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/unicode-emoji-4.1.0/lib
+...
+#+end_example
+
+* Version
+#+begin_src ruby :wrap EXAMPLE
+  "Current version is: #{FatPeriod::VERSION}"
+#+end_src
+
+#+begin_EXAMPLE
+Current version is: 3.0.0
+#+end_EXAMPLE
 
 * Introduction
 
-~FatPeriod~ provides a Ruby ~Period~ class for dealing with time periods, that
-is ranges whose endpoints are ~Date~ s.  Set operations, for example, are
-provided for Period, as well as methods for parsing strings into Periods and
-methods for breaking a larger periods into an array of smaller periods of
-various 'chunk' sizes that correspond to calendar-related periods such as
-days, weeks, months, and so forth.'
+~FatPeriod~ provides a Ruby ~Period~ class for dealing with time periods of
+days, that is ranges whose endpoints are of class ~Date~.  It's target is
+financial applications, but it serves well for any application where periods
+of time are useful.  It builds on the [[https://github.com/ddoherty03/fat_date][fat_date]] gem, which provides
+enhancements to the ~Date~ class, especially its class method ~Date.spec~ for
+interpreting a rich set of "specs" as the beginning or end of a variety of
+calendar-related periods.
+
+In addition, set operations are provided for Period, as well as methods for
+breaking a larger periods into an array of smaller periods of various 'chunk'
+sizes that correspond to calendar-related periods such as days, weeks, months,
+and so forth.
+
+* Table of Contents                                            :toc:noexport:
+- [[#version][Version]]
+- [[#introduction][Introduction]]
+- [[#installation][Installation]]
+  - [[#installing-the-gem][Installing the gem]]
+- [[#usage][Usage]]
+  - [[#constant-periodforever][Constant Period::FOREVER]]
+  - [[#construction-of-periods][Construction of Periods]]
+    - [[#periodnew][Period.new]]
+    - [[#periodparse][Period.parse]]
+      - [[#with-only-a-from-spec][With Only a From-Spec]]
+      - [[#with-both-a-from-spec-and-to-spec][With Both a From-Spec and To-Spec]]
+      - [[#using-skip-modifiers][Using Skip Modifiers]]
+    - [[#periodparse_phrase][Period.parse_phrase]]
+    - [[#periodensure][Period.ensure]]
+  - [[#conversion][Conversion]]
+    - [[#to-range][To Range]]
+    - [[#to-string][To String]]
+    - [[#tex-form][TeX Form]]
+  - [[#comparison][Comparison]]
+  - [[#enumeration][Enumeration]]
+  - [[#size][Size]]
+  - [[#chunking][Chunking]]
+  - [[#set-operations][Set Operations]]
+    - [[#subset-determination][Subset Determination]]
+    - [[#superset-determination][Superset Determination]]
+    - [[#intersection][Intersection]]
+    - [[#difference][Difference]]
+    - [[#union][Union]]
+  - [[#coverage][Coverage]]
+    - [[#contains][Contains?]]
+    - [[#overlapping][Overlapping]]
+    - [[#spanning][Spanning]]
+    - [[#gaps][Gaps]]
+- [[#development][Development]]
+- [[#contributing][Contributing]]
 
 * Installation
 
@@ -41,9 +122,17 @@ Or install it yourself as:
 #+END_SRC
 
 * Usage
+** Constant Period::FOREVER
 
-** Construction of Periods
+The ~Period~ class depends on the extensions to ~Date~ made by the ~fat_core~
+gem, which you can read about [[https://github.com/ddoherty03/fat_core][here]].  It defines a constant, ~Period::FOREVER~,
+which is defined as extending from ~Date::BOT~ to ~Date::EOT~, which are
+defined in ~fat_date~ as 1900-01-01 and 3000-12-31, respectively and define
+the beginning of time and end of time for practical commercial purposes.  The
+constant is not frozen, so you can re-define it to your liking.
 
+** Construction of Periods
+*** Period.new
 A Period is constructed with two arguments for the begin and end date.  The
 begin date must be on or before the end date.  Each argument can be (1) a
 Date, (2) a string parseable as a Date by the Date.parse method, or (3) an
@@ -53,15 +142,295 @@ object that responds to ~#to_s~ and can be parsed as a Date by Date.parse:
   p1 = Period.new(Date.today, Date.today + 30)
   p2 = Period.new('Nov 22, 1963', Date.today)
   p3 = Period.new('1961-01-21', '1963-11-22')
-  puts "Camelot lasted #{p3.length} days"
+  [[p1.to_s], [p2.to_s], [p3.to_s]]
 #+end_SRC
 
-** Period Constants
+#+RESULTS:
+| 2025-03-20 to 2025-04-19 |
+| 1963-11-22 to 2025-03-20 |
+| 1961-01-21 to 1963-11-22 |
 
-The ~Period~ class depends on the extensions to ~Date~ made by the ~fat_core~
-gem, which you can read about [[https://github.com/ddoherty03/fat_core][here]].  It defines two constants, ~Date::BOT~ and
-~Date::EOT~, which define beginning of time and end of time for practical
-commercial purposes.
+#+begin_src ruby
+  ["Camelot lasted #{p3.length} days"]
+#+end_src
+
+#+RESULTS:
+| Camelot lasted 1036 days |
+
+*** Period.parse
+A more convenient way to construct a period is provided by ~Period.parse~.  It
+takes two strings as its arguments, a mandatory "from-spec" and an optional
+"to-spec":
+
+A "spec" is a string designating some period of time.  There are many ways of
+specifying a period, which are detailed below.
+
+**** With Only a From-Spec
+
+If only a from-spec is given, it defines both the beginning and end of the
+overall period:
+
+#+begin_src ruby
+  tab = []
+  tab << ['From Spec', 'Result']
+  tab << nil
+  froms = ['2020', '2020-2Q', '2020-W15', '2020-09', '2020-09-A', '2020-09-iii']
+  froms.each do |f|
+    tab << [f, Period.parse(f).inspect]
+  end
+  tab
+#+end_src
+
+#+begin_example
+| From Spec   | Result                         |
+|-------------+--------------------------------|
+| 2020        | Period(2020-01-01..2020-12-31) |
+| 2020-2Q     | Period(2020-04-01..2020-06-30) |
+| 2020-W15    | Period(2020-04-06..2020-04-12) |
+| 2020-09     | Period(2020-09-01..2020-09-30) |
+| 2020-09-A   | Period(2020-09-01..2020-09-15) |
+| 2020-09-iii | Period(2020-09-14..2020-09-20) |
+#+end_example
+
+**** With Both a From-Spec and To-Spec
+But, if a to-spec is also given, the from-spec defines the beginning of the
+period and the to-spec defines the end of the period. In particular, the
+beginning of the period is the first day of the from-spec and the end of the
+period is the last day of the to-spec:
+
+#+begin_src ruby
+  tab = []
+  tab << ['From Spec', 'To Spec', 'Result']
+  tab << nil
+  from_tos = [['2020', '2020-2Q'], ['2020-2Q', '2020-W15'], ['2020-W15', '2020-09'], ['2020-09', '2020-09-A'], ['2020-09-A', '2020-09-iii']]
+  from_tos.each do |f, t|
+    tab << [f, t, Period.parse(f, t).inspect]
+  end
+  tab
+#+end_src
+
+#+begin_example
+| From Spec | To Spec     | Result                         |
+|-----------+-------------+--------------------------------|
+| 2020      | 2020-2Q     | Period(2020-01-01..2020-06-30) |
+| 2020-2Q   | 2020-W15    | Period(2020-04-01..2020-04-12) |
+| 2020-W15  | 2020-09     | Period(2020-04-06..2020-09-30) |
+| 2020-09   | 2020-09-A   | Period(2020-09-01..2020-09-15) |
+| 2020-09-A | 2020-09-iii | Period(2020-09-01..2020-09-20) |
+#+end_example
+
+**** Using Skip Modifiers
+One new feature of FatDate is the ability to add a "skip modifier" to the end
+of a date spec to skip forward or backward to the first day-of-week either on
+or before/after the date given by the spec.  For example, the following
+demonstrates that one can set the 'to' spec to the /last/ Wednesday of 2025 or
+the last Wednesday /before/ the end of 2025.  Using '>' or '>=' specified
+skipping forward instead.
+
+#+begin_src ruby
+  tab = []
+  tab << ['From Spec', 'To Spec', 'Result', 'Description']
+  tab << nil
+  from_to_descs = [['2025-2Q', '2025<=Wed', 'From 2q to last Wednesday of 2025'],
+                   ['2025-2Q', '2025<Wed', 'From 2q to last Wednesday /before/ the end of 2025'],
+                   ['2012-11', '2012-11<=Thur', 'November 2012 through last Thursday'],
+                   ['2012-11', '2012-11-4Thur', 'And through Thanksgiving (not always the /last/ Thursday!)']
+                  ]
+  from_to_descs.each do |f, t, d|
+    tab << [f, t, Period.parse(f, t).inspect, d]
+  end
+  tab
+#+end_src
+
+#+begin_example
+| From Spec | To Spec       | Result                         | Description                                                |
+|-----------+---------------+--------------------------------+------------------------------------------------------------|
+| 2025-2Q   | 2025<=Wed     | Period(2025-04-01..2025-12-31) | From 2q to last Wednesday of 2025                          |
+| 2025-2Q   | 2025<Wed      | Period(2025-04-01..2025-12-31) | From 2q to last Wednesday /before/ the end of 2025         |
+| 2012-11   | 2012-11<=Thur | Period(2012-11-01..2012-11-29) | November 2012 through last Thursday                        |
+| 2012-11   | 2012-11-4Thur | Period(2012-11-01..2012-11-22) | And through Thanksgiving (not always the /last/ Thursday!) |
+#+end_example
+
+*** Period.parse_phrase
+For example:
+
+The ~Period.parse_phrase~ method will take a string having a 'from', 'to', and
+'per' clause and return an Array of Periods encompassing the same period as
+~Period.parse~, but optionally broken into sub-periods each having the length
+specified by the 'per' clause.  ~Period.parse_phrase~ always returns an Array
+of Periods even if there is no 'per' clause and the Array has only one
+member. If there is no 'to' clause, the returned period is from the start of
+the 'from' period to its end.  If there is neither a 'from' or a 'to' clause,
+it tries to interpret the beginning of the phrase as a valid spec and uses it
+as a 'from' clause.
+
+#+begin_src ruby
+  tab = []
+  tab << ['k', 'Sub Period']
+  tab << nil
+  pds = Period.parse_phrase('from 2025 to 2025-3Q per month')
+  pds.each_with_index do |pd, k|
+    tab << [k, pd.inspect]
+  end
+  tab
+#+end_src
+
+#+begin_example
+| k | Sub Period                     |
+|---+--------------------------------|
+| 0 | Period(2025-01-01..2025-01-31) |
+| 1 | Period(2025-02-01..2025-02-28) |
+| 2 | Period(2025-03-01..2025-03-31) |
+| 3 | Period(2025-04-01..2025-04-30) |
+| 4 | Period(2025-05-01..2025-05-31) |
+| 5 | Period(2025-06-01..2025-06-30) |
+| 6 | Period(2025-07-01..2025-07-31) |
+| 7 | Period(2025-08-01..2025-08-31) |
+| 8 | Period(2025-09-01..2025-09-30) |
+#+end_example
+
+The period named in the 'per' clause is called a 'chunk' and there are several
+valid chunk names in ~FatPeriod~:
+
+| Chunk Name |
+|------------|
+| year       |
+| half       |
+| quarter    |
+| bimonth    |
+| month      |
+| semimonth  |
+| biweek     |
+| week       |
+| day        |
+
+Here is the same period broken into weeks.  Notice that the first and last
+"weeks" are not whole weeks because parts of them fall outside the boundaries
+of the overall period.
+
+#+begin_src ruby
+  tab = []
+  tab << ['k', 'Sub Period']
+  tab << nil
+  pds = Period.parse_phrase('from 2025 to 2025-3Q per week')
+  pds.each_with_index do |pd, k|
+    tab << [k, pd.inspect]
+  end
+  tab
+#+end_src
+
+#+begin_example
+|  k | Sub Period                     |
+|----+--------------------------------|
+|  0 | Period(2025-01-01..2025-01-05) |
+|  1 | Period(2025-01-06..2025-01-12) |
+|  2 | Period(2025-01-13..2025-01-19) |
+|  3 | Period(2025-01-20..2025-01-26) |
+|  4 | Period(2025-01-27..2025-02-02) |
+|  5 | Period(2025-02-03..2025-02-09) |
+|  6 | Period(2025-02-10..2025-02-16) |
+|  7 | Period(2025-02-17..2025-02-23) |
+|  8 | Period(2025-02-24..2025-03-02) |
+|  9 | Period(2025-03-03..2025-03-09) |
+| 10 | Period(2025-03-10..2025-03-16) |
+| 11 | Period(2025-03-17..2025-03-23) |
+| 12 | Period(2025-03-24..2025-03-30) |
+| 13 | Period(2025-03-31..2025-04-06) |
+| 14 | Period(2025-04-07..2025-04-13) |
+| 15 | Period(2025-04-14..2025-04-20) |
+| 16 | Period(2025-04-21..2025-04-27) |
+| 17 | Period(2025-04-28..2025-05-04) |
+| 18 | Period(2025-05-05..2025-05-11) |
+| 19 | Period(2025-05-12..2025-05-18) |
+| 20 | Period(2025-05-19..2025-05-25) |
+| 21 | Period(2025-05-26..2025-06-01) |
+| 22 | Period(2025-06-02..2025-06-08) |
+| 23 | Period(2025-06-09..2025-06-15) |
+| 24 | Period(2025-06-16..2025-06-22) |
+| 25 | Period(2025-06-23..2025-06-29) |
+| 26 | Period(2025-06-30..2025-07-06) |
+| 27 | Period(2025-07-07..2025-07-13) |
+| 28 | Period(2025-07-14..2025-07-20) |
+| 29 | Period(2025-07-21..2025-07-27) |
+| 30 | Period(2025-07-28..2025-08-03) |
+| 31 | Period(2025-08-04..2025-08-10) |
+| 32 | Period(2025-08-11..2025-08-17) |
+| 33 | Period(2025-08-18..2025-08-24) |
+| 34 | Period(2025-08-25..2025-08-31) |
+| 35 | Period(2025-09-01..2025-09-07) |
+| 36 | Period(2025-09-08..2025-09-14) |
+| 37 | Period(2025-09-15..2025-09-21) |
+| 38 | Period(2025-09-22..2025-09-28) |
+| 39 | Period(2025-09-29..2025-09-30) |
+#+end_example
+
+
+*** Period.ensure
+~Period.ensure~ tries to interpret its argument as a ~Period~ and returns it;
+otherwise it throws an ~ArgumentError~ exception:
+
+- if the argument responds to the ~to_period~ method, it invokes that on the
+  argument and returns it;
+- if the argument is a ~String~, it uses ~Period.parse_phrase~ to try to
+  interepret it as a ~Period~;
+- if it is already a ~Period~, it just returns the argument;
+- otherwise, it throws an ~ArgumentError~ exception.
+
+
+ #+begin_src ruby
+   class ContainingMonth
+     def initialize(dat)
+       @dat = Date.ensure(dat)
+     end
+
+     def to_period
+       Period.month_containing(@dat)
+     end
+   end
+
+   cm = ContainingMonth.new('2025-09-22')
+   Period.ensure(cm)
+  #+end_src
+
+#+begin_example
+Period(2025-09-01..2025-09-30)
+  #+end_example
+
+#+begin_src ruby
+  Period.ensure('from 2016 to 2018-3Q')
+#+end_src
+
+#+begin_example
+Period(2016-01-01..2018-09-30)
+#+end_example
+
+#+begin_src ruby
+  Period.ensure(Period.new('2016-01-02', '2017-09-29'))
+#+end_src
+
+#+begin_example
+Period(2016-01-02..2017-09-29)
+#+end_example
+
+** Conversion
+*** To Range
+*** To String
+*** TeX Form
+** Comparison
+** Enumeration
+** Size
+** Chunking
+** Set Operations
+*** Subset Determination
+*** Superset Determination
+*** Intersection
+*** Difference
+*** Union
+** Coverage
+*** Contains?
+*** Overlapping
+*** Spanning
+*** Gaps
 
 * Development
 

data/Rakefile

@@ -1,9 +1,26 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
 
-require 'rubocop/rake_task'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
-RuboCop::RakeTask.new
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => [:spec, :rubocop]
+########################################################################
+# Rubocop tasks
+########################################################################
+# Option A (recommended): Keep using Bundler and run rubocop via `bundle exec`.
+# This wrapper task ensures the rubocop run uses the gems from your Gemfile,
+# even when you invoke `rake rubocop` (no need to remember `bundle exec rake`).
+#
+# You can pass extra RuboCop CLI flags with the RUBOCOP_OPTS environment variable:
+#   RUBOCOP_OPTS="--format simple" rake rubocop
+
+desc 'Run rubocop under `bundle exec`'
+task :rubocop do
+  opts = (ENV['RUBOCOP_OPTS'] || '').split
+  Bundler.with_unbundled_env do
+    sh 'bundle', 'exec', 'rubocop', *opts
+  end
+end
+
+task default: %i[spec rubocop]

data/bin/console

@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
 require 'bundler/setup'
 require 'fat_period'

data/fat_period.gemspec

@@ -1,6 +1,6 @@
-# coding: utf-8
+# frozen_string_literal: true
 
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'fat_period/version'
 
@@ -21,5 +21,6 @@ Gem::Specification.new do |spec|
   # spec.executables = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'fat_core', '>= 5.4'
+  spec.add_dependency 'fat_core', '>= 6.0'
+  spec.add_dependency 'fat_date'
 end

data/lib/fat_period/date.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatPeriod
   # An extension of Date for methods useful with respect to FatPeriod::Periods.
   module Date

data/lib/fat_period/period.rb

@@ -1,5 +1,6 @@
-require 'active_support'
-require 'fat_core/date'
+# frozen_string_literal: true
+
+require 'fat_date'
 
 # The Period class represents a range of Dates and supports a variety of
 # operations on those ranges.
@@ -30,9 +31,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
@@ -43,7 +42,7 @@ class Period
   # @group Parsing
   #
   # Return a period based on two date specs passed as strings (see
-  # `FatCore::Date.parse_spec`), a 'from' and a 'to' spec. The returned period
+  # `FatCore::Date.spec`), a 'from' and a 'to' spec. The returned period
   # begins on the first day of the period given as the `from` spec and ends on
   # the last day given as the `to` spec. If the to spec is not given or is nil,
   # the from spec is used for both the from- and to-spec.
@@ -54,47 +53,86 @@ class Period
   #   # Assuming this executes in December, 2014
   #   Period.parse('last_month', 'this_month').inspect #=> Period('2014-11-01..2014-12-31')
   #
-  # @param from [String] spec ala FatCore::Date.parse_spec
-  # @param to [String] spec ala FatCore::Date.parse_spec
+  # @param from [String] spec ala FatCore::Date.spec
+  # @param to [String] spec ala FatCore::Date.spec
   # @return [Period] from beginning of `from` to end of `to`
   def self.parse(from, to = nil)
     raise ArgumentError, 'Period.parse missing argument' unless from
 
     to ||= from
-    first = Date.parse_spec(from, :from)
-    second = Date.parse_spec(to, :to)
+    first = Date.spec(from, :from)
+    second = Date.spec(to, :to)
     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)
+    return 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/
-      from_phrase = $1
-      to_phrase = $2
-    when /\Afrom (.*)\z/, /\Ato (.*)\z/
-      from_phrase = $1
+    when /\Afrom\s+([^\s]+)\s+to\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
+      from_phrase = ::Regexp.last_match(1)
+      to_phrase = ::Regexp.last_match(2)
+    when /\Afrom\s+([^\s]+)(\s+per\s+[^\s]+)?\z/, /\Ato\s+([^\s]+)(\s+per\s+[^\s]+)?\z/i
+      from_phrase = ::Regexp.last_match(1)
       to_phrase = nil
-    else
-      from_phrase = phrase
+    when /\A([^\s]+)(\s+per\s+[^\s]+)?\z/
+      from_phrase = ::Regexp.last_match(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,23 +221,11 @@ class Period
   end
 
   def eql?(other)
-    return unless other.is_a?(Period)
+    return false unless other.is_a?(Period)
 
     hash == other.hash
   end
 
-  # Return whether this Period contains the given date.
-  #
-  # @param date [Date] date to test
-  # @return [Boolean] is the given date within this Period?
-  def contains?(date)
-    date = date.to_date if date.respond_to?(:to_date)
-    raise ArgumentError, 'argument must be a Date' unless date.is_a?(Date)
-
-    to_range.cover?(date)
-  end
-  alias_method :===, :contains?
-
   include Enumerable
 
   # @group Enumeration
@@ -284,7 +310,6 @@ class Period
     quarter
     half
     year
-    irregular
   ].freeze
 
   CHUNK_ORDER = {}
@@ -784,6 +809,18 @@ class Period
     to_range.overlaps?(other.to_range)
   end
 
+  # Return whether this Period contains the given date.
+  #
+  # @param date [Date] date to test
+  # @return [Boolean] is the given date within this Period?
+  def contains?(date)
+    date = date.to_date if date.respond_to?(:to_date)
+    raise ArgumentError, 'argument must be a Date' unless date.is_a?(Date)
+
+    to_range.cover?(date)
+  end
+  alias_method :===, :contains?
+
   # Return whether any of the given periods overlap any other.
   #
   # @example

data/lib/fat_period/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module FatPeriod
-  VERSION = '2.0.0'.freeze
+  VERSION = '3.0.0'
 end

data/lib/fat_period.rb

@@ -1,9 +1,14 @@
+# frozen_string_literal: true
+
 require 'date'
 
+require 'active_support'
+
 require 'fat_period/version'
 require 'fat_period/date'
 require 'fat_period/period'
 
-require 'fat_core/date'
 require 'fat_core/range'
 require 'fat_core/string'
+
+require 'fat_date'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fat_period
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Daniel E. Doherty
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-12 00:00:00.000000000 Z
+date: 2025-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fat_core
@@ -16,15 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.4'
-description:
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: fat_date
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 email:
 - ded@ddoherty.net
 executables: []
@@ -32,10 +44,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".envrc"
-- ".github/workflows/gem-push.yml"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
-- ".travis.yml"
+- ".rubocop.yml"
+- CHANGELOG.org
 - Gemfile
 - LICENSE.txt
 - README.org
@@ -50,7 +63,6 @@ files:
 homepage: https://github.com/ddoherty03/fat_period
 licenses: []
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -65,8 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Implements a Period class as a Range of Dates.
 test_files: []

data/.github/workflows/gem-push.yml

@@ -1,48 +0,0 @@
-name: Ruby Gem
-
-on:
-  push:
-    branches: [ "master" ]
-  pull_request:
-    branches: [ "master" ]
-
-jobs:
-  build:
-    name: Build + Publish
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Set up Ruby 2.6
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-    # uses: ruby/setup-ruby@v1
-      uses: ruby/setup-ruby@55283cc23133118229fd3f97f9336ee23a179fcf # v1.146.0
-      with:
-        ruby-version: 2.6.x
-
-    - name: Publish to GPR
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
-      env:
-        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
-        OWNER: ${{ github.repository_owner }}
-
-    - name: Publish to RubyGems
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push *.gem
-      env:
-        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.travis.yml

@@ -1,6 +0,0 @@
-language: ruby
-rvm:
-  - 2.5
-  - 2.6
-  - 2.7
-  - 3.0