timeboss 0.0.7 → 0.1.1

data/lib/timeboss/calendar/quarter.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
-require_relative './support/month_based'
+require_relative './support/monthly_unit'
 
 module TimeBoss
   class Calendar
-    class Quarter < Support::MonthBased
+    class Quarter < Support::MonthlyUnit
       NUM_MONTHS = 3
 
+      # Get a simple representation of this quarter.
+      # @return [String] (e.g. "2020Q3")
       def name
         "#{year_index}Q#{index}"
       end
 
+      # Get a "pretty" representation of this quarter.
+      # @return [String] (e.g. "Q3 2020")
       def title
         "Q#{index} #{year_index}"
       end

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

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
-require_relative './shiftable'
+require_relative './translatable'
 
 module TimeBoss
   class Calendar
     module Support
       private
 
+      # The formatter is responsible for the implementation of name formatting for a unit.
       class Formatter
-        PERIODS = Shiftable::PERIODS.reverse.map(&:to_sym).drop(1)
+        PERIODS = Translatable::PERIODS.reverse.map(&:to_sym).drop(1)
         attr_reader :unit, :periods
 
         def initialize(unit, periods)

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

@@ -1,6 +1,7 @@
 module TimeBoss
   class Calendar
     module Support
+      # @abstract
       class MonthBasis
         attr_reader :year, :month
 

data/lib/timeboss/calendar/support/{month_based.rb → monthly_unit.rb}

@@ -4,7 +4,7 @@ require_relative './unit'
 module TimeBoss
   class Calendar
     module Support
-      class MonthBased < Unit
+      class MonthlyUnit < Unit
         attr_reader :year_index, :index
 
         def initialize(calendar, year_index, index, start_date, end_date)
@@ -13,30 +13,18 @@ module TimeBoss
           @index = index
         end
 
-        def next
-          if index == max_index
-            calendar.send(self.class.type, year_index + 1, 1)
-          else
-            calendar.send(self.class.type, year_index, index + 1)
-          end
-        end
-
-        def previous
-          if index == 1
-            calendar.send(self.class.type, year_index - 1, max_index)
-          else
-            calendar.send(self.class.type, year_index, index - 1)
-          end
-        end
-
+        # Get a stringified representation of this unit.
+        # @return [String] (e.g. "2020Q3: 2020-06-29 thru 2020-09-27")
         def to_s
           "#{name}: #{start_date} thru #{end_date}"
         end
 
+        # Get a list of weeks contained within this period.
+        # @return [Array<Week>]
         def weeks
           base = calendar.year(year_index)
           num_weeks = (((base.end_date - base.start_date) + 1) / 7.0).to_i
-          num_weeks.times.map { |i| Week.new(calendar, year_index, i + 1, base.start_date + (i * 7).days, base.start_date + ((i * 7) + 6).days) }
+          num_weeks.times.map { |i| Week.new(calendar, base.start_date + (i * 7).days, base.start_date + ((i * 7) + 6).days) }
                          .select { |w| w.start_date.between?(start_date, end_date) }
         end
 
@@ -45,6 +33,22 @@ module TimeBoss
         def max_index
           12 / self.class::NUM_MONTHS
         end
+
+        def up
+          if index == max_index
+            calendar.send(self.class.type, year_index + 1, 1)
+          else
+            calendar.send(self.class.type, year_index, index + 1)
+          end
+        end
+
+        def down
+          if index == 1
+            calendar.send(self.class.type, year_index - 1, max_index)
+          else
+            calendar.send(self.class.type, year_index, index - 1)
+          end
+        end
       end
     end
   end

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

@@ -3,48 +3,238 @@ module TimeBoss
   class Calendar
     module Support
       module Shiftable
-        PERIODS = %w[day week month quarter half year]
-
-        PERIODS.each do |period|
+        Support::Translatable::PERIODS.each do |period|
           periods = period.pluralize
 
-          define_method periods do
-            calendar.send("#{periods}_for", self)
-          end
-
-          define_method period do
-            entries = send(periods)
-            return nil unless entries.length == 1
-            entries.first
-          end
-
-          define_method "in_#{period}" do
+          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|
+          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 "last_#{period}" do
-            send("#{periods}_ago", 1)
-          end
+          define_method("#{periods}_ahead") { |o| send("#{periods}_ago", o * -1) }
 
-          define_method "this_#{period}" do
-            send("#{periods}_ago", 0)
-          end
+          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
 
-          define_method "#{periods}_hence" do |offset|
-            send("#{periods}_ago", offset * -1)
-          end
+        alias_method :yesterday, :last_day
+        alias_method :today, :this_day
+        alias_method :tomorrow, :next_day
 
-          define_method "next_#{period}" do
-            send("#{periods}_hence", 1)
-          end
-        end
+        #
+        # 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