fat_core 5.1.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d377f4ea28c3310ce28733b4da66dad3e39dc13be3f5406ab1cce4b4e784924
-  data.tar.gz: d1e6f6fb84c9211104a87c2e4d596a3637eaacfa5bc82349b3d5baaa2b9657df
+  metadata.gz: c2376c4bac5a7a1702ae4361cca280a07b1bfde4304f42fad41e0f37754d41c8
+  data.tar.gz: e87c81524e1901bf80443b421d62ad8ebffe7212916f0bd18817625e79795985
 SHA512:
-  metadata.gz: 0f81e05b5728f6dc3a7fe556bcd48ff011a006375938afd269ced9d3b6266715118dd5281d7e5c2dd39665257ed8f49a86fc73ddb3d5c3a1f9b1bc728efecb15
-  data.tar.gz: 8c6fd80723f159aaaf92cf52b249cb194f4394bb8f655963a4287c37523e8212e93ed27c7a9b40be8620bb45773cd47e38a701b0ceead250e1f69fd20fab162a
+  metadata.gz: c0b95bc966b857fae1bcfbf2b38dcb8e4275dee5b269091944f2dcd08830162ebf22b98072a49b9b40e1599b7c0f940beeffa4e08f9f6b9f05dc003ba81a3e8c
+  data.tar.gz: 6cf190c0656ba641ccfe10a27e832d9bbe2bb71dde2491c97179ae4acc677af884679a4c635aefe40379e5a022dda71549c705cc6c05e71a5e4d7037639c193b

data/.rubocop.yml

@@ -1,25 +1,9 @@
 inherit_from:
   - ~/.rubocop.yml
 
-# inherit_gem:
-#     rubocop-shopify: rubocop.yml
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
 
-# require:
-#   - rubocop-rspec
-
-# AllCops:
-#   TargetRubyVersion: 2.7
-#   Exclude:
-#     - 'test/tmp/**/*'
-#     - 'vendor/bundle/**/*'
-
-# Style/MethodCallWithArgsParentheses:
-#   Exclude:
-#     - '**/Gemfile'
-
-# Style/ClassAndModuleChildren:
-#   Exclude:
-#     - 'test/**/*'
-
-# Style/StringLiterals:
-#   Enabled: false
+Style/BitwisePredicate:
+   Enabled: false

data/Gemfile

@@ -1,13 +1,19 @@
 source 'https://rubygems.org'
 
-gem 'damerau-levenshtein', git: 'https://github.com/ddoherty03/damerau-levenshtein'
-gem 'rubocop-shopify', require: false
-
 # Specify your gem's dependencies in fat_core.gemspec
 gemspec
 
-# group :debug do
-#   gem "byebug"
-#   gem "pry"
-#   gem "pry-doc"
-# end
+group :development do
+  gem 'rubocop-shopify', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rake', require: false
+  gem 'bundler'
+  gem 'debug', '>= 1.0.0'
+  gem 'pry'
+  gem 'redcarpet'
+  gem 'pry-doc'
+  gem 'rake'
+  gem 'rspec'
+  gem 'simplecov'
+end

data/README.org

@@ -54,13 +54,11 @@ Many of these have little that is of general interest, but there are a few
 goodies.
 
 *** Date
-
 **** Constants
-
-~FatCore~ adds two constants to the ~Date~ class, Date::BOT and Date::EOT.
-These represent the earliest and latest dates of practical commercial
-interest.  The exact values are rather arbitrary, but they prove useful in
-date ranges, for example.  They are defined as:
+~FatCore~ adds two date constants to the ~Date~ class, Date::BOT and
+Date::EOT.  These represent the earliest and latest dates of practical
+commercial interest.  The exact values are rather arbitrary, but they prove
+useful in date ranges, for example.  They are defined as:
 
 - ~Date::BOT~ :: January 1, 1900
 - ~Date::EOT~ :: December 31, 3000
@@ -69,7 +67,38 @@ date ranges, for example.  They are defined as:
 - ~Date::PRESIDENTIAL_FUNERALS~ :: an Array of dates of presidential funerals,
   which are observed with a closing of most federal agencies
 
-
+**** Ensure
+The ~Date.ensure~ class method tries to convert its argument to a ~Date~
+object by (1) applying the ~#to_date~ method or (2) applying the ~Date.parse~
+method to a String.  This is handy when you want to define a method that takes
+a date argument but want the caller to be able to supply anything that can
+reasonably be converted to a ~Date~:
+
+#+begin_src ruby
+  $:.unshift("~/src/fat_core/lib")
+  require 'fat_core/date'  # => true
+
+  def tomorow_tomorrow(arg)
+    from = Date.ensure(arg)  # => ArgumentError: cannot convert class 'Array' to a Date or DateTime
+    from + 2.days            # => Mon, 03 Jun 2024, Wed, 16 Oct 2024 05:47:30 -0500, Sun, 03 Mar 2024
+  end                        # => :tomorow_tomorrow
+
+  tomorow_tomorrow('June 1')  # => Mon, 03 Jun 2024
+  tomorow_tomorrow(Time.now)  # => Wed, 16 Oct 2024 05:47:30 -0500
+  # But it's only as good as Date.parse!
+  tomorow_tomorrow('Ides of March') # => Sun, 03 Mar 2024
+
+  tomorow_tomorrow([])
+  # =>
+
+  # ~> ArgumentError
+  # ~> cannot convert class 'Array' to a Date or DateTime
+  # ~>
+  # ~> /home/ded/src/fat_core/lib/fat_core/date.rb:1849:in `ensure_date'
+  # ~> /home/ded/src/fat_core/lib/fat_core/date.rb:1863:in `ensure'
+  # ~> /tmp/seeing_is_believing_temp_dir20241014-1457038-xj4k5x/program.rb:5:in `tomorow_tomorrow'
+  # ~> /tmp/seeing_is_believing_temp_dir20241014-1457038-xj4k5x/program.rb:14:in `<main>'
+#+end_src
 
 **** Formatting
 
@@ -88,7 +117,6 @@ that are often useful:
   puts "American: #{d.american}"
 #+end_SRC
 
-#+RESULTS:
 #+begin_example
 ISO: 1957-09-22
 All Numbers: 19570922
@@ -112,7 +140,7 @@ convention of using en-dashes to separate the components.
 
 Many of the methods provided by ~FatCore~ deal with various calendar periods
 that are less common than those provided by the Ruby Standard Library or gems
-such as ~active_suupor~.  This documentation refers to these calendar periods
+such as ~active_support~.  This documentation refers to these calendar periods
 as "chunks", and they are the following:
 
 - year,
@@ -134,7 +162,7 @@ or end of each of these chunks:
   tab = []
   d = Date.parse('2017-06-30')
   %i[beginning end].each do |side|
-    %i(year half quarter bimonth month semimonth biweek week ).each do |chunk|
+    %i(year half quarter bimonth month semimonth biweek week).each do |chunk|
       meth = "#{side}_of_#{chunk}?".to_sym
       tab << [d.iso, meth.to_s, "#{d.send(meth)}"]
     end
@@ -231,7 +259,6 @@ You can query which numerical half, quarter, etc. that a given date falls in:
 objects.
 
 ***** American Dates
-
 Americans often write dates in the form M/d/Y, and the normal parse method
 will parse such a string as d/M/Y, often resulting in invalid date errors.
 ~FatCore~ adds the specialty parsing method, ~Date.parse_american~ to handle
@@ -256,15 +283,140 @@ Date.parse_american('9/22/1957') => 1957-09-22
 #+end_example
 
 ***** Date Specs
-
-
+It is often desirable to get the first or last date of a specified time
+period.  For this ~FatCore~ provides the ~parse_spec~ method that takes a
+string and an optional ~spec_type~ parameter of either ~:from~, indicating
+that the first date of the period should be returned or ~:to~, indicating that
+the last date of the period should be returned.
+
+This method supports a rich set of ways to specify periods of time:
+
+- YYYY-MM-DD :: returns a single day as the time period,
+- YYYY-MM :: returns the specified month, beginning or end
+- YYYY :: returns the specified year, beginning or end
+- YYYY-ddd :: returns the ddd'th day of the specified year, beginning or end
+- MM :: returns the specified month of the current year, beginning or end
+- MM-DD :: returns the specified day of the specified month in the current
+  year, beginning or end,
+- YYYY-Wnn or YYYY-nnW :: returns the nn'th commercial week of the given year
+  according to the ISO 8601 standard, in which the week containing the first
+  Thursday of the year counts as the first commercial week, even if that week
+  started in the prior calendar year,
+- Wnn or nnW :: returns the nn'th commercial week of the current year,
+- YYYY-1H or YYYY-2H :: returns the specified half year for the given year,
+- 1H or 2H :: returns the specified half year for the current year,
+- YYYY-1Q, YYYY-2Q, etc  :: returns the calendar quarter for the given year,
+- 1Q, 2Q, etc  :: returns the calendar quarter for the current year,
+- YYYY-MM-I or YYYY-MM-II :: returns the semi-month for the given month and
+  year, where the first semi-month always runs from the 1st to the 15th and
+  the second semi-month always runs from the 16th to the last day of the given
+  month, regardless of the number of days in the month,
+- YYYY-MM-i or YYYY-MM-ii up to YYYY-MM-vi :: returns the given week within
+  the month, including any partial weeks,
+- MM-i or MM-ii up to MM-vi :: returns the given week within the month of the
+  current year, including any partial weeks,
+- i or ii up to vi :: returns the given week within the current month of the current
+  year, including any partial weeks,
+- YYYY-MM-nSu up to YYYY-MM-nSa  :: returns the single date that is the n'th
+  Sunday, Monday, etc., in the given month using the first two letters of the
+  English names for the days of the week,
+- MM-nSu up to MM-nSa  :: returns the single date that is the n'th Sunday,
+  Monday, etc., in the given month of the current year using the first two
+  letters of the English names for the days of the week,
+- nSu up to nSa  :: returns the single date that is the n'th Sunday, Monday,
+  etc., in the current month of the current year using the first two letters
+  of the English names for the days of the week,
+- YYYY-nnn :: is the nnn'th day of the given year, exactly three digits needed,
+- nnn :: is the nnn'th day of the current year, exactly three digits needed,
+- YYYY-E :: returns the single date of Easter in the Western church for the
+  given year,
+- E :: returns the single date of Easter in the Western church for the current
+  year,
+- YYYY-E-n or YYYY-E+n :: returns the single date that falls n days before (-)
+  or after (+) Easter in the Western church for the given year,
+- E-n or E+n :: returns the single date that falls n days before (-) or after
+  (+) Easter in the Western church for the current year,
+- yesterday or yesteryear or lastday or last_year, etc :: the relative
+  prefixes, 'last' or 'yester' prepended to any chunk name returns the period
+  named by the chunk that precedes today's date.
+- today or toyear or this-year or thissemimonth, etc :: the relative prefixes,
+  'to' or 'this' prepended to any chunk name returns the period named by
+  the chunk that contains today's date.
+- nextday or nextyear or next-year or nextsemimonth, etc :: the relative
+  prefixes, 'next' prepended to any chunk name returns the period named by the
+  chunk that follows today's date. As a special case, 'tomorrow' is treated as
+  equivalent to 'nextday'.
+- forever :: returns the period Date::BOT to Date::EOT, which, for financial
+  applications is meant to stand in for eternity.
+- never :: returns nil, representing no date.
+
+Some things to note with respect to ~Date.parse_spec~:
+
+1. The second argument should be either ~:from~ or ~:to~, but it defaults to
+   ~:from~.  If it is ~:from~, ~parse_spec~ returns the first date of the
+   specified period; if it is ~:to~, it returns the last date of the specified
+   period.  When the "period" resolves to a single day, both arguments return
+   the same date, so ~parse_spec('2024-E', :from)~ and ~parse_spec('2024-E',
+   :to)~ both result in March 31, 2024.
+2. Where relevant, ~parse_spec~ accepts letters of either upper or lower case:
+   so 2024-1Q can be written 2024-1q and 'yesteryear' can be written
+   'YeSterYeaR', and likewise for all components of the spec using letters.
+3. Date components can be separated with either a hyphen, as in the examples
+   above, or with a '/' as is common.  Thus, 2024-11-09 can also be
+   2024/11/09, or indeed, 2024/11-09 or 2024-11/09.
+4. The prefixes for relative periods can be separated from the period name by
+   a hyphen, and underscore, or by nothing at all.  Thus, yester-day,
+   yester_day, and yesterday are all acceptable.  Clearly neologisms such as
+   'yestermonth' are quaint, but not harmful.
+5. On the other hand, to get a day-of-year spec right, you must use exactly 3
+   digits: 2024-011 is the 11th day of 2024, but 2024-11 is November of 2024.
 
 **** Holidays and Workdays
-
-- weekend?
-- weekday?
-
-**** Weekdays in Month
+One of the original motivations for this library was to provide an easy way to
+determine whether a given date is a federal holiday in the United States or,
+nearly but not quite the same, a non-trading day on the New York Stock
+Exchange.  To that end, ~FatCore~ provides the following methods:
+
+- Date#weekend? -- is this date on a weekend?
+- Date#weekday? -- is this date on a week day?
+- Date#easter_this_year -- the date of Easter in the Date's year
+
+Methods concerning Federal holidays:
+
+- Date#fed_holiday? -- is this date a Federal holiday?  It knows about
+  obscurities such as holidays decreed by past Presidents, dates of
+  Presidential funerals, and the Federal rule for when holidays fall on a
+  weekend, whether it is moved to the prior Friday or the following Monday.
+- Date#fed_workday? -- is it a date when the Federal government is open?,
+  inverse of Date#fed_holiday?
+- Date#add_fed_workdays(n) -- n Federal workdays following (or preceding if n
+  negative) this date,
+- Date#next_fed_workday -- the next Federal workday following this date,
+- Date#prior_fed_workday -- the previous Federal workday before this date,
+- Date#next_until_fed_workday -- starting with this date, move forward until
+  we hit a Federal workday
+- Date#prior_until_fed_workday -- starting with this date, move back until
+  we hit a Federal workday
+
+And we have similar methods for "holidays" or non-trading days on the NYSE:
+
+- Date#nyse_holiday? -- is this date a NYSE holiday?
+- Date#nyse_workday? -- is it a date when the NYSE is open for trading?,
+  inverse of Date#nyse_holiday?
+- Date#add_nyse_workdays(n) -- n NYSE workdays following (or preceding if n
+  negative) this date,
+- Date#next_nyse_workday -- the next NYSE workday following this date,
+- Date#prior_nyse_workday -- the previous NYSE workday before this date,
+- Date#next_until_nyse_~~workday -- starting with this date, move forward until
+  we hit a NYSE workday
+- Date#prior_until_nyse_workday -- starting with this date, move back until
+  we hit a Federal workday
+
+**** Ordinal Weekdays in Month
+It is often useful to find the 1st, 2nd, etc, Sunday, Monday, etc. in a given
+month.  ~FatCore~ provides the class method ~Date.nth_wday_in_year_month(nth,
+wday, year, month)~ to return such dates.  The first parameter can be
+negative, which will count from the end of the month.
 
 **** Easter
 The ~Date~ class extension adds two methods for determining whether a given
@@ -325,7 +477,6 @@ coverage on one Range by an Array of other Ranges:
   (0..12).gaps([(0..2), (5..7), (10..12)])  => [(3..4), (8..9)]
 #+end_SRC
 
-**
 * Enumerable
 FatCore::Enumerable extends Enumerable with the ~#each_with_flags~ method that
 yields the elements of the Enumerable but also yields two booleans, ~first~ and

data/Rakefile

@@ -10,16 +10,23 @@ RDoc::Task.new do |rdoc|
 end
 
 YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb', 'README.md']
+  t.files = ['lib/**/*.rb', 'README.md']
   t.options << '--no-private'
   t.options << '--embed-mixins'
   t.options << '--markup=markdown'
   t.options << '--markup-provider=redcarpet'
-  #t.stats_options = ['--list-undoc']
+  # t.stats_options = ['--list-undoc']
 end
 
 RSpec::Core::RakeTask.new(:spec, :tag) do |t|
   t.rspec_opts = '--tag ~online -f p'
 end
 
-task :default => :spec
+########################################################################
+# Rubocop tasks
+########################################################################
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task :default => [:spec, :rubocop]

data/bin/easters

@@ -1,17 +1,27 @@
-#! /usr/bin/env ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'fat_core/date'
+#
+# This file was generated by Bundler.
+#
+# The application 'easters' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
 
-base = Date.new(30, 1, 1)
-3000.times do |k|
-  dt = Date.new(base.year + k, 1, 1)
-  easter = dt.easter_this_year
-  print "%04d: #{easter}" % dt.year
-  if easter.month == 3 && easter.day <= 23
-    print easter.day == 22 ? " <<<\n" : " <<\n"
-  elsif easter.month == 4 && easter.day >= 24
-    print easter.day == 25 ? " >>>\n" : " >>\n"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
   else
-    print "\n"
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
   end
 end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("fat_core", "easters")

data/fat_core.gemspec

@@ -25,16 +25,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/easter}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'debug', '>= 1.0.0'
-  spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'pry-doc'
-  spec.add_development_dependency 'rake'
-  spec.add_development_dependency 'redcarpet'
-  spec.add_development_dependency 'rspec'
-  spec.add_development_dependency 'simplecov'
-  spec.add_development_dependency 'solargraph'
-
-  spec.add_runtime_dependency 'activesupport'
-  spec.add_runtime_dependency 'damerau-levenshtein'
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'damerau-levenshtein'
 end