timeboss 0.3.0

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Support
+      module Navigable
+        # @overload previous
+        #   Fetch the previous unit relative to this unit.
+        #   @return [Unit]
+        # @overload previous(value)
+        #   Fetch some previous number of units relative to this unit
+        #   @param quantity [Integer]
+        #   @return [Array<Unit>]
+        def previous(quantity = nil)
+          return down if quantity.nil?
+          gather(:previous, quantity).reverse
+        end
+
+        # @overload next
+        #   Fetch the next unit relative to this unit.
+        #   @return [Unit]
+        # @overload next(value)
+        #   Fetch some next number of units relative to this unit
+        #   @param quantity [Integer]
+        #   @return [Array<Unit>]
+        def next(quantity = nil)
+          return up if quantity.nil?
+          gather(:next, quantity)
+        end
+
+        # Fetch the unit some number of units prior to this unit.
+        # @param quantity [Integer]
+        # @return [Unit]
+        def ago(quantity)
+          previous(quantity + 1).first
+        end
+
+        # Fetch the unit some number of units after this unit.
+        # @param quantity [Integer]
+        # @return [Unit]
+        def ahead(quantity)
+          self.next(quantity + 1).last
+        end
+
+        # Fetch a list of units from this unit until some date.
+        # @param end_date [Date]
+        # @return [Array<Unit>]
+        def until(end_date)
+          entry = self
+          [entry].tap do |entries|
+            until entry.end_date >= end_date
+              entry = entry.next
+              entries << entry
+            end
+          end
+        end
+
+        private
+
+        def gather(navigator, quantity)
+          [].tap do |entries|
+            entry = self
+            while quantity > 0
+              entries << entry
+              entry = entry.send(navigator)
+              quantity -= 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Support
+      module Shiftable
+        Support::Translatable::PERIODS.each do |period|
+          periods = period.pluralize
+
+          define_method("in_#{period}") do
+            base = send(periods)
+            return unless base.length == 1
+            base.first.send(self.class.type.to_s.pluralize).find_index { |p| p == self } + 1
+          end
+
+          define_method("#{periods}_ago") do |offset|
+            base_offset = send("in_#{period}") or return
+            (calendar.send("this_#{period}") - offset).send(self.class.type.to_s.pluralize)[base_offset - 1]
+          end
+
+          define_method("#{periods}_ahead") { |o| send("#{periods}_ago", o * -1) }
+
+          define_method("last_#{period}") { send("#{periods}_ago", 1) }
+          define_method("this_#{period}") { send("#{periods}_ago", 0) }
+          define_method("next_#{period}") { send("#{periods}_ahead", 1) }
+        end
+
+        alias_method :yesterday, :last_day
+        alias_method :today, :this_day
+        alias_method :tomorrow, :next_day
+
+        #
+        # i hate this
+        #
+
+        ### Days
+
+        # @!method in_day
+        # Get the index within the day that this unit falls in.
+        # Returns nil if no single day can be identified.
+        # @return [Integer, nil]
+
+        # @!method days_ago
+        # Get the index-relative day some number of days ago.
+        # Returns nil if no single day can be identified.
+        # @param offset [Integer] the number of days back to shift this period
+        # @return [Calendar::Day, nil]
+
+        # @!method days_ahead
+        # Get the index-relative day some number of days ahead.
+        # Returns nil if no single day can be identified.
+        # @param offset [Integer] the number of days forward to shift this period
+        # @return [Calendar::Day, nil]
+
+        # @!method last_day
+        # Get the index-relative day 1 day ago.
+        # Returns nil if no single day can be identified.
+        # @return [Calendar::Day, nil]
+
+        # @!method this_day
+        # Get the index-relative day for this day.
+        # Returns nil if no single day can be identified.
+        # @return [Calendar::Day, nil]
+
+        # @!method next_day
+        # Get the index-relative day 1 day forward.
+        # Returns nil if no single day can be identified.
+        # @return [Calendar::Day, nil]
+
+        ### Weeks
+
+        # @!method in_week
+        # Get the index within the week that this unit falls in.
+        # Returns nil if no single week can be identified.
+        # @return [Integer, nil]
+
+        # @!method weeks_ago
+        # Get the index-relative week some number of weeks ago.
+        # Returns nil if no single week can be identified.
+        # @param offset [Integer] the number of weeks back to shift this period
+        # @return [Calendar::Week, nil]
+
+        # @!method weeks_ahead
+        # Get the index-relative week some number of weeks ahead.
+        # Returns nil if no single week can be identified.
+        # @param offset [Integer] the number of weeks forward to shift this period
+        # @return [Calendar::Week, nil]
+
+        # @!method last_week
+        # Get the index-relative week 1 week ago.
+        # Returns nil if no single week can be identified.
+        # @return [Calendar::Week, nil]
+
+        # @!method this_week
+        # Get the index-relative week for this week.
+        # Returns nil if no single week can be identified.
+        # @return [Calendar::Week, nil]
+
+        # @!method next_week
+        # Get the index-relative week 1 week forward.
+        # Returns nil if no single week can be identified.
+        # @return [Calendar::Week, nil]
+
+        ### Months
+
+        # @!method in_month
+        # Get the index within the month that this unit falls in.
+        # Returns nil if no single month can be identified.
+        # @return [Integer, nil]
+
+        # @!method months_ago
+        # Get the index-relative month some number of months ago.
+        # Returns nil if no single month can be identified.
+        # @param offset [Integer] the number of months back to shift this period
+        # @return [Calendar::Month, nil]
+
+        # @!method months_ahead
+        # Get the index-relative month some number of months ahead.
+        # Returns nil if no single month can be identified.
+        # @param offset [Integer] the number of months forward to shift this period
+        # @return [Calendar::Month, nil]
+
+        # @!method last_month
+        # Get the index-relative month 1 month ago.
+        # Returns nil if no single month can be identified.
+        # @return [Calendar::Month, nil]
+
+        # @!method this_month
+        # Get the index-relative month for this month.
+        # Returns nil if no single month can be identified.
+        # @return [Calendar::Month, nil]
+
+        # @!method next_month
+        # Get the index-relative month 1 month forward.
+        # Returns nil if no single month can be identified.
+        # @return [Calendar::Month, nil]
+ 
+        ### Quarters
+
+        # @!method in_quarter
+        # Get the index within the quarter that this unit falls in.
+        # Returns nil if no single quarter can be identified.
+        # @return [Integer, nil]
+
+        # @!method quarters_ago
+        # Get the index-relative quarter some number of quarters ago.
+        # Returns nil if no single quarter can be identified.
+        # @param offset [Integer] the number of quarters back to shift this period
+        # @return [Calendar::Quarter, nil]
+
+        # @!method quarters_ahead
+        # Get the index-relative quarter some number of quarters ahead.
+        # Returns nil if no single quarter can be identified.
+        # @param offset [Integer] the number of quarters forward to shift this period
+        # @return [Calendar::Quarter, nil]
+
+        # @!method last_quarter
+        # Get the index-relative quarter 1 quarter ago.
+        # Returns nil if no single quarter can be identified.
+        # @return [Calendar::Quarter, nil]
+
+        # @!method this_quarter
+        # Get the index-relative quarter for this quarter.
+        # Returns nil if no single quarter can be identified.
+        # @return [Calendar::Quarter, nil]
+
+        # @!method next_quarter
+        # Get the index-relative quarter 1 quarter forward.
+        # Returns nil if no single quarter can be identified.
+        # @return [Calendar::Quarter, nil]
+ 
+        ### Halves
+
+        # @!method in_half
+        # Get the index within the half that this unit falls in.
+        # Returns nil if no single half can be identified.
+        # @return [Integer, nil]
+
+        # @!method halves_ago
+        # Get the index-relative half some number of halves ago.
+        # Returns nil if no single half can be identified.
+        # @param offset [Integer] the number of halves back to shift this period
+        # @return [Calendar::Half, nil]
+
+        # @!method halves_ahead
+        # Get the index-relative half some number of halves ahead.
+        # Returns nil if no single half can be identified.
+        # @param offset [Integer] the number of halves forward to shift this period
+        # @return [Calendar::Half, nil]
+
+        # @!method last_half
+        # Get the index-relative half 1 half ago.
+        # Returns nil if no single half can be identified.
+        # @return [Calendar::Half, nil]
+
+        # @!method this_half
+        # Get the index-relative half for this half.
+        # Returns nil if no single half can be identified.
+        # @return [Calendar::Half, nil]
+
+        # @!method next_half
+        # Get the index-relative half 1 half forward.
+        # Returns nil if no single half can be identified.
+        # @return [Calendar::Half, nil]
+ 
+        ### Years
+
+        # @!method in_year
+        # Get the index within the year that this unit falls in.
+        # Returns nil if no single year can be identified.
+        # @return [Integer, nil]
+
+        # @!method years_ago
+        # Get the index-relative year some number of years ago.
+        # Returns nil if no single year can be identified.
+        # @param offset [Integer] the number of years back to shift this period
+        # @return [Calendar::Year, nil]
+
+        # @!method years_ahead
+        # Get the index-relative year some number of years ahead.
+        # Returns nil if no single year can be identified.
+        # @param offset [Integer] the number of years forward to shift this period
+        # @return [Calendar::Year, nil]
+
+        # @!method last_year
+        # Get the index-relative year 1 year ago.
+        # Returns nil if no single year can be identified.
+        # @return [Calendar::Year, nil]
+
+        # @!method this_year
+        # Get the index-relative year for this year.
+        # Returns nil if no single year can be identified.
+        # @return [Calendar::Year, nil]
+
+        # @!method next_year
+        # Get the index-relative year 1 year forward.
+        # Returns nil if no single year can be identified.
+        # @return [Calendar::Year, nil]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Support
+      module Translatable
+        PERIODS = %w[day week month quarter half year]
+
+        PERIODS.each do |period|
+          periods = period.pluralize
+
+          define_method(periods) { calendar.send("#{periods}_for", self) }
+
+          define_method(period) do |index = nil|
+            entries = send(periods)
+            return entries[index - 1] unless index.nil?
+            return nil unless entries.length == 1
+            entries.first
+          end
+        end
+
+        #
+        # i hate this
+        #
+
+        ### Days
+
+        # @!method days
+        # Get a list of days that fall within this unit.
+        # @return [Array<Calendar::Day>]
+
+        # @!method day(index = nil)
+        # Get the day this unit represents.
+        # Returns nil if no single day can be identified.
+        # @return [Array<Calendar::Day>, nil]
+
+        ### Weeks
+
+        # @!method weeks
+        # Get a list of weeks that fall within this unit.
+        # @return [Array<Calendar::Week>]
+
+        # @!method week(index = nil)
+        # Get the week this unit represents.
+        # Returns nil if no single week can be identified.
+        # @return [Array<Calendar::Week>, nil]
+
+        ### Months
+
+        # @!method months
+        # Get a list of months that fall within this unit.
+        # @return [Array<Calendar::Month>]
+
+        # @!method month(index = nil)
+        # Get the month this unit represents.
+        # Returns nil if no single month can be identified.
+        # @return [Array<Calendar::Month>, nil]
+
+        ### Quarters
+
+        # @!method quarters
+        # Get a list of quarters that fall within this unit.
+        # @return [Array<Calendar::Quarter>]
+
+        # @!method quarter(index = nil)
+        # Get the quarter this unit represents.
+        # Returns nil if no single quarter can be identified.
+        # @return [Array<Calendar::Quarter>, nil]
+
+        ### Halves
+
+        # @!method halves
+        # Get a list of halves that fall within this unit.
+        # @return [Array<Calendar::Half>]
+
+        # @!method half(index = nil)
+        # Get the half this unit represents.
+        # Returns nil if no single half can be identified.
+        # @return [Array<Calendar::Half>, nil]
+
+        ### Years
+
+        # @!method years
+        # Get a list of years that fall within this unit.
+        # @return [Array<Calendar::Year>]
+
+        # @!method year(index = nil)
+        # Get the year this unit represents.
+        # Returns nil if no single year can be identified.
+        # @return [Array<Calendar::Year>, nil]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+require_relative './navigable'
+require_relative './translatable'
+require_relative './shiftable'
+require_relative './formatter'
+
+module TimeBoss
+  class Calendar
+    module Support
+      class Unit
+        include Navigable
+        include Translatable
+        include Shiftable
+        attr_reader :calendar, :start_date, :end_date
+
+        UnsupportedUnitError = Class.new(StandardError)
+
+        def self.type
+          self.name.demodulize.underscore
+        end
+
+        def initialize(calendar, start_date, end_date)
+          @calendar = calendar
+          @start_date = start_date
+          @end_date = end_date
+        end
+
+        # Is the specified unit equal to this one, based on its unit type and date range?
+        # @param entry [Unit] the unit to compare
+        # @return [Boolean] true when periods are equal
+        def ==(entry)
+          self.class == entry.class && self.start_date == entry.start_date && self.end_date == entry.end_date
+        end
+
+        # Format this period based on specified granularities.
+        # @param periods [Array<Symbol, String>] the periods to include (`half, week`, or `quarter`)
+        # @return [String] (e.g. "2020H2W7" or "2020Q3")
+        def format(*periods)
+          Formatter.new(self, periods.presence || Formatter::PERIODS).to_s
+        end
+
+        # Starting from this unit of time, build a period extending through the specified time unit.
+        # @param unit [Unit] the period to extend through
+        # @return [Period]
+        def thru(unit)
+          Period.new(calendar, self, unit)
+        end
+
+        # Does this period cover the current date?
+        # @return [Boolean]
+        def current?
+          Date.today.between?(start_date, end_date)
+        end
+
+        # Return the unit relative to this one by the specified offset.
+        # Offset values can be positive or negative.
+        # @param value [Integer]
+        # @return [Unit]
+        def offset(value)
+          method = value.negative? ? :previous : :next
+          base = self
+          value.abs.times { base = base.send(method) }
+          base
+        end
+
+        # Move some number of units forward from this unit.
+        # @param value [Integer]
+        # @return [Unit]
+        def +(value)
+          offset(value)
+        end
+
+        # Move some number of units backward from this unit.
+        # @param value [Integer]
+        # @return [Unit]
+        def -(value)
+          offset(-value)
+        end
+
+        # Express this period as a date range.
+        # @return [Range<Date, Date>]
+        def to_range
+          @_to_range ||= start_date .. end_date
+        end
+      end
+    end
+  end
+end