timeboss 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b856796bb4e37e5776aeed86c19dd42832af3091b189f01878d907de5cbf1864
-  data.tar.gz: 824c18de591069e4c46d01dc14dc2c1a2ee54881b670218014adf3d4d220a0da
+  metadata.gz: 17c22a99ae9b02ecc3f435e99622a075c0a26af2d15f87070aefb1e6c0deb1c4
+  data.tar.gz: 774b9250575112756f30f9522bd98b36ed017a010cace574407a88b4f3316f98
 SHA512:
-  metadata.gz: 24bc5de8281c36802fb79b92b79a2381794710d320d2890d022c40f40aef4cedb1e3fe963085e3e1ea39fe9f51715994ccca4e5844c0e8bfb2784cbb65c2a339
-  data.tar.gz: a1fb6c4825ad05f9dd21a8514c6e6dc24a4904cb235a2a1d16b888e3664fa5f92c6ea8b4ccef3c09198c8e2aea272fb662610bd25fc5ed210f2b095feb90fab3
+  metadata.gz: 949de3a932fe24a8c34e8bf9ba89eed605ff6f8148ab5763600a6fb6ec00b822cfc2425b4aebce6982ecc62be43fb037723a264a6543539e626755dc39f1ec04
+  data.tar.gz: ac0312302c3e89d193bf16354ccf3593e3bed79e6e569b1580d78f82ad40bf663765f950078c86572d3e245f265047b947dbe70c1948b82bb958b205a73542af

data/PERIOD_SPECIFIERS.md

@@ -0,0 +1,70 @@
+# TimeBoss Period Specifiers
+Below is a list of examples for TimeBoss period specifiers. This list is by no means comprehensive, but hopefully serves as a guide to help
+you understand how to communicate with TimeBoss.
+
+All specifiers are resolved within the context of the utilized calendar (Gregorian, Broadcast, etc).
+
+## Absolute Periods
+An "absolute" period is one that never changes, regardless of the current date. "December of 2019" always references the same time period,
+regardless of what today is.
+
+_Assuming the Broadcast calendar is in use:_
+| Specifier                  | Description                         | Resolution              |
+| -------------------------- | ----------------------------------- | ----------------------- |
+| `2020Q3`                   | 3rd quarter of 2020                 | 6/29/2020 - 9/27/2020   |
+| `2022M1`                   | 1st month of 2022                   | 12/27/2021 - 1/30/2022  |
+| `2021H1M2`                 | 2nd month of the first half of 2021 | 2/1/2021 - 2/28/2021    |
+| `2020W40`                  | 40th week of 2020                   | 9/28/2020 - 10/4/2020   |
+| `2027`                     | 2027                                | 12/28/2026 - 12/26/2027 |
+| `1999-07-31` or `19990731` | July 31, 1999                       | 7/31/1999 - 7/31/1999   |
+
+The sub-identifiers for period granularities are:
+- `D`: day
+- `W`: week
+- `M`: month
+- `Q`: quarter
+- `H`: half
+
+## Relative Periods
+A "relative" period is one that changes based on the current date. "Last week" means something different today than it will a month from now.
+
+_Assuming today is April 29, 2022, in the Gregorian calendar:_
+| Specifier       | Description                         | Resolution            |
+| --------------- | ----------------------------------- | --------------------- |
+| `last_month`    | March 2022                          | 3/1/2022 - 3/31/2022  |
+| `this_month-2`  | February 2022                       | 2/1/2022 - 2/28/2022  |
+| `this_week`     | Week of April 25, 2022              | 4/25/2022 - 5/1/2022  |
+| `yesterday`     | April 28, 2022                      | 4/28/2022 - 4/28/2022 |
+| `today+4`       | May 3, 2022                         | 5/3/2022 - 5/3/2022   |
+| `next_year`     | 2023                                | 1/1/2023 - 12/31/2023 |
+
+The relative prefixes can be used in conjuction with any period granularity. The terms here should be joined with the underscore (`_`) character as in the examples above.
+
+Relative prefixes are:
+- `last`
+- `this`
+- `next`
+
+Period granularities are:
+- `day`
+- `week`
+- `month`
+- `quarter`
+- `half`
+- `year`
+
+Accepted single-day specifiers:
+- `yesterday`
+- `today`
+- `tomorrow`
+
+## Compound Periods
+Absolute and/or relative periods can be combined together to build "compound" periods by utilizing TimeBoss' "range" operator (`..`):
+
+_Assuming today is April 29, 2022, in the Gregorian calendar:_
+| Specifier                  | Description                                                              | Resolution            |
+| -------------------------- | ------------------------------------------------------------------------ | --------------------- |
+| `yesterday..today`         | Yesterday and Today                                                      | 4/28/2022 - 4/29/2022 |
+| `last_quarter..this_month` | From the first day of last quarter, through the end of the current month | 1/1/2022 - 4/30/2022  |
+| `this_week-2..next_week`   | From the first day of 2 weeks ago, through the last day of next week     | 4/11/2022 - 5/8/2022  |
+| `2022M2..this_year`        | From the first day of February, through the last day of this year        | 2/1/2022 - 12/31/2022 |

data/README.md

@@ -25,7 +25,7 @@ $ gem install timeboss
 ```
 
 ## Usage
-Supports `year`, `half`, `quarter`, `month`, `week` (non-gregorian calendars only), and `day`.
+Supports `year`, `half`, `quarter`, `month`, `week`, and `day`.
 
 Prepare your calendar for use:
 

data/lib/tasks/calendars.rake

@@ -1,3 +1,4 @@
+require "./lib/timeboss"
 require "./lib/timeboss/calendars"
 
 namespace :timeboss do

data/lib/timeboss/calendar/support/unit.rb

@@ -84,6 +84,15 @@ module TimeBoss
           @_to_range ||= start_date..end_date
         end
 
+        # Clamp this unit to the range of the provided unit.
+        # @return [Period]
+        def clamp(unit)
+          new_start_date = start_date.clamp(unit.start_date, unit.end_date)
+          new_end_date = end_date.clamp(unit.start_date, unit.end_date)
+          return unless new_start_date.between?(start_date, end_date) && new_end_date.between?(start_date, end_date)
+          calendar.parse("#{new_start_date}..#{new_end_date}")
+        end
+
         def inspect
           "#<#{self.class.name} start_date=#{start_date}, end_date=#{end_date}>"
         end

data/lib/timeboss/calendar/waypoints/absolute.rb

@@ -15,6 +15,7 @@ module TimeBoss
           end
 
           define_method "#{type}_for" do |date|
+            date = date.to_date
             window = public_send(type, date.year - 1, 1)
             loop do
               break window if window.to_range.include?(date)

data/lib/timeboss/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TimeBoss
-  VERSION = "1.1.2"
+  VERSION = "1.1.4"
 end

data/lib/timeboss.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support"
+require "active_support/all"
 require "timeboss/version"
 
 # TimeBoss

data/spec/lib/timeboss/calendar/support/unit_spec.rb

@@ -28,6 +28,57 @@ module TimeBoss
           end
         end
 
+        describe "#clamp" do
+          let(:clamp_start_date) { Date.parse("2018-06-21") }
+          let(:clamp_end_date) { Date.parse("2018-08-30") }
+          let(:result) { subject.clamp(described_class.new(calendar, clamp_start_date, clamp_end_date)) }
+          let(:period) { double }
+
+          context "open" do
+            it "does not restrict the returned period" do
+              expect(calendar).to receive(:parse).with("#{start_date}..#{end_date}").and_return period
+              expect(result).to eq period
+            end
+          end
+
+          context "left clamped" do
+            let(:clamp_start_date) { Date.parse("2018-06-30") }
+
+            it "brings the beginning date inward" do
+              expect(calendar).to receive(:parse).with("#{clamp_start_date}..#{end_date}").and_return period
+              expect(result).to eq period
+            end
+          end
+
+          context "right clamped" do
+            let(:clamp_end_date) { Date.parse("2018-07-30") }
+
+            it "brings the beginning date inward" do
+              expect(calendar).to receive(:parse).with("#{start_date}..#{clamp_end_date}").and_return period
+              expect(result).to eq period
+            end
+          end
+
+          context "fully clamped" do
+            let(:clamp_start_date) { Date.parse("2018-06-30") }
+            let(:clamp_end_date) { Date.parse("2018-07-30") }
+
+            it "brings the beginning date inward" do
+              expect(calendar).to receive(:parse).with("#{clamp_start_date}..#{clamp_end_date}").and_return period
+              expect(result).to eq period
+            end
+          end
+
+          context "obliterated" do
+            let(:clamp_start_date) { Date.parse("2018-09-01") }
+            let(:clamp_end_date) { Date.parse("2018-09-06") }
+
+            it "returns nil" do
+              expect(result).to be_nil
+            end
+          end
+        end
+
         context "periods" do
           before(:each) do
             allow(calendar).to receive(:days_for).with(subject).and_return %w[D1 D2 D3 D4 D5 D6 D7 D8]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timeboss
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Kevin McDonald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-18 00:00:00.000000000 Z
+date: 2022-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -184,6 +184,7 @@ files:
 - CODE_OF_CONDUCT.md
 - Gemfile
 - LICENSE.txt
+- PERIOD_SPECIFIERS.md
 - README.md
 - Rakefile
 - bin/tbsh