timeboss 0.0.6 → 0.1.0

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Support
+      # Provides navigational abilities for units within a calendar.
+      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

@@ -2,6 +2,7 @@
 module TimeBoss
   class Calendar
     module Support
+      # Provides the ability to take a unit, and shift it into a different period, relative to today.
       module Shiftable
         PERIODS = %w[day week month quarter half year]
 
@@ -37,12 +38,12 @@ module TimeBoss
             send("#{periods}_ago", 0)
           end
 
-          define_method "#{periods}_hence" do |offset|
+          define_method "#{periods}_ahead" do |offset|
             send("#{periods}_ago", offset * -1)
           end
 
           define_method "next_#{period}" do
-            send("#{periods}_hence", 1)
+            send("#{periods}_ahead", 1)
           end
         end
       end

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

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
+require_relative './navigable'
 require_relative './shiftable'
 require_relative './formatter'
 
 module TimeBoss
   class Calendar
     module Support
+      # A unit is the lowest-level base of all days/weeks/months, etc.
       class Unit
+        include Navigable
         include Shiftable
         attr_reader :calendar, :start_date, :end_date
 
@@ -19,22 +22,37 @@ module TimeBoss
           @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
@@ -42,14 +60,22 @@ module TimeBoss
           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

data/lib/timeboss/calendar/waypoints.rb

@@ -1,87 +1,13 @@
 # frozen_string_literal: true
+
+%w[absolute relative].each { |f| require_relative "./waypoints/#{f}" }
+
 module TimeBoss
   class Calendar
+    # Provides implementations for known periods within a calendar.
     module Waypoints
-      %i[month quarter half year].each do |type|
-        klass = TimeBoss::Calendar.const_get(type.to_s.classify)
-        size = klass.const_get("NUM_MONTHS")
-
-        define_method type do |year_index, index = 1|
-          month = (index * size) - size + 1
-          months = (month .. month + size - 1).map { |i| basis.new(year_index, i) }
-          klass.new(self, year_index, index, months.first.start_date, months.last.end_date)
-        end
-
-        define_method "#{type}_for" do |date|
-          window = send(type, date.year - 1, 1)
-          while true
-            break window if window.to_range.include?(date)
-            window = window.next
-          end
-        end
-      end
-
-      %i[day week month quarter half year].each do |type|
-        define_method("this_#{type}") { send("#{type}_for", Date.today) }
-        define_method("last_#{type}") { send("this_#{type}").previous }
-        define_method("next_#{type}") { send("this_#{type}").next }
-
-        define_method "#{type.to_s.pluralize}_for" do |entry|
-          first = send("#{type}_for", entry.start_date)
-          constituents = [first]
-          until first.end_date >= entry.end_date
-            first = first.next
-            constituents << first
-          end
-          constituents
-        end
-
-        define_method "#{type.to_s.pluralize}_back" do |quantity|
-          windows = []
-          window = send("this_#{type}")
-          while quantity > 0
-            windows << window.dup
-            window = window.previous
-            quantity -= 1
-          end
-          windows.reverse
-        end
-
-        define_method "#{type.to_s.pluralize}_ago" do |quantity|
-          send("#{type.to_s.pluralize}_back", quantity + 1).first
-        end
-
-        define_method type.to_s.pluralize do |quantity|
-          windows = []
-          window = send("this_#{type}")
-          while quantity > 0
-            windows << window.dup
-            window = window.next
-            quantity -= 1
-          end
-          windows
-        end
-
-        define_method "#{type.to_s.pluralize}_hence" do |quantity|
-          send(type.to_s.pluralize, quantity + 1).last
-        end
-      end
-
-      %i[yesterday today tomorrow].each do |period|
-        define_method(period) { Day.new(self, Date.send(period)) }
-      end
-
-      def day(year_index, index)
-        year(year_index).days[index - 1]
-      end
-
-      def day_for(date)
-        Day.new(self, date)
-      end
-
-      def week_for(date)
-        year_for(date).weeks.find { |w| w.to_range.include?(date) }
-      end
+      include Absolute
+      include Relative
     end
   end
 end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Waypoints
+      # Provides implementation for absolute periods within a calendar.
+      module Absolute
+        %i[month quarter half year].each do |type|
+          klass = TimeBoss::Calendar.const_get(type.to_s.classify)
+          size = klass.const_get("NUM_MONTHS")
+
+          define_method type do |year_index, index = 1|
+            month = (index * size) - size + 1
+            months = (month .. month + size - 1).map { |i| basis.new(year_index, i) }
+            klass.new(self, year_index, index, months.first.start_date, months.last.end_date)
+          end
+
+          define_method "#{type}_for" do |date|
+            window = send(type, date.year - 1, 1)
+            while true
+              break window if window.to_range.include?(date)
+              window = window.next
+            end
+          end
+        end
+
+        # Get the specified week by index within the specified year.
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the week within the year
+        # @return [Calendar::Week]
+        def week(year_index, index)
+          year(year_index).weeks[index - 1]
+        end
+
+        # Get the week that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar week
+        # @return [Calendar::Week]
+        def week_for(date)
+          year_for(date).weeks.find { |w| w.to_range.include?(date) }
+        end
+
+        # Get the specified day by index within the specified year.
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the day within the year
+        # @return [Calendar::Day]
+        def day(year_index, index)
+          year(year_index).days[index - 1]
+        end
+
+        # Get the day that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar day
+        # @return [Calendar::Day]
+        def day_for(date)
+          Day.new(self, date)
+        end
+
+        #
+        # i hate this
+        #
+
+        ### Month
+
+        # @!method month
+        # Get the specified month by index within the specified year
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the month within the year
+        # @return [Calendar::Month]
+
+        # @!method month_for
+        # Get the month that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar month
+        # @return [Calendar::Month]
+
+        ### Quarter
+
+        # @!method quarter
+        # Get the specified quarter by index within the specified year
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the quarter within the year
+        # @return [Calendar::Quarter]
+
+        # @!method quarter_for
+        # Get the quarter that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar quarter
+        # @return [Calendar::Quarter]
+
+        ### Half
+
+        # @!method half
+        # Get the specified half by index within the specified year
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the half within the year
+        # @return [Calendar::Half]
+
+        # @!method half_for
+        # Get the half that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar half
+        # @return [Calendar::Half]
+
+        ### Year
+
+        # @!method year
+        # Get the specified year by index within the specified year
+        # @param year_index [Integer] the year to examine
+        # @param index [Integer] the index of the year within the year
+        # @return [Calendar::Year]
+
+        # @!method year_for
+        # Get the year that contains the specified date.
+        # @param date [Date] the date for which to locate the calendar year
+        # @return [Calendar::Year]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    module Waypoints
+      # Provides implementation for periods relative to today within a calendar.
+      module Relative
+        %i[day week month quarter half year].each do |type|
+          types = type.to_s.pluralize
+
+          define_method("this_#{type}") { send("#{type}_for", Date.today) }
+          define_method("last_#{type}") { send("this_#{type}").previous }
+          define_method("next_#{type}") { send("this_#{type}").next }
+
+          define_method("#{types}_for") { |p| send("#{type}_for", p.start_date).until(p.end_date) }
+
+          define_method("#{types}_back") { |q| send("this_#{type}").previous(q) }
+          define_method("#{types}_ago") { |q| send("this_#{type}").ago(q) }
+
+          define_method("#{types}_forward") { |q| send("this_#{type}").next(q) }
+          define_method("#{types}_ahead") { |q| send("this_#{type}").ahead(q) }
+          alias_method types.to_sym, "#{types}_forward".to_sym
+        end
+
+        alias_method :yesterday, :last_day
+        alias_method :today, :this_day
+        alias_method :tomorrow, :next_day
+
+        #
+        # i hate this
+        #
+
+        ### Days
+
+        # @!method this_day
+        # Get the current day within the active calendar.
+        # @return [Calendar::Day]
+
+        # @!method last_day
+        # Get the previous day within the active calendar.
+        # @return [Calendar::Day]
+
+        # @!method next_day
+        # Get the next day within the active calendar.
+        # @return [Calendar::Day]
+
+        # @!method days_for
+        # Get a list of days within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Day>]
+
+        # @!method days_back
+        # Get a quantity of days back from today.
+        # @param quantity [Integer] the number of days requested
+        # @return [Array<Calendar::Day>]
+
+        # @!method days_ago
+        # Get the day that occurred the specified number of days ago.
+        # @param quantity [Integer] the number of days before today
+        # @return [Calendar::Day]
+
+        # @!method days_forward
+        # Get a quantity of days forward from today.
+        # @param quantity [Integer] the number of days requested
+        # @return [Array<Calendar::Day>]
+
+        # @!method days_ahead
+        # Get the day that occurred the specified number of days ahead.
+        # @param quantity [Integer] the number of days after today
+        # @return [Calendar::Day]
+ 
+        ### Weeks
+
+        # @!method this_week
+        # Get the current week within the active calendar.
+        # @return [Calendar::Week]
+
+        # @!method last_week
+        # Get the previous week within the active calendar.
+        # @return [Calendar::Week]
+
+        # @!method next_week
+        # Get the next week within the active calendar.
+        # @return [Calendar::Week]
+
+        # @!method weeks_for
+        # Get a list of weeks within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Week>]
+
+        # @!method weeks_back
+        # Get a quantity of weeks back from this week.
+        # @param quantity [Integer] the number of weeks requested
+        # @return [Array<Calendar::Week>]
+
+        # @!method weeks_ago
+        # Get the week that occurred the specified number of weeks ago.
+        # @param quantity [Integer] the number of weeks before this week
+        # @return [Calendar::Week]
+
+        # @!method weeks_forward
+        # Get a quantity of weeks forward from this week.
+        # @param quantity [Integer] the number of weeks requested
+        # @return [Array<Calendar::Week>]
+
+        # @!method weeks_ahead
+        # Get the week that occurred the specified number of weeks ahead.
+        # @param quantity [Integer] the number of weeks after this week
+        # @return [Calendar::Week]
+ 
+        ### Months
+
+        # @!method this_month
+        # Get the current month within the active calendar.
+        # @return [Calendar::Month]
+
+        # @!method last_month
+        # Get the previous month within the active calendar.
+        # @return [Calendar::Month]
+
+        # @!method next_month
+        # Get the next month within the active calendar.
+        # @return [Calendar::Month]
+
+        # @!method months_for
+        # Get a list of months within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Month>]
+
+        # @!method months_back
+        # Get a quantity of months back from this month.
+        # @param quantity [Integer] the number of months requested
+        # @return [Array<Calendar::Month>]
+
+        # @!method months_ago
+        # Get the month that occurred the specified number of months ago.
+        # @param quantity [Integer] the number of months before this month
+        # @return [Calendar::Month]
+
+        # @!method months_forward
+        # Get a quantity of months forward from this month.
+        # @param quantity [Integer] the number of months requested
+        # @return [Array<Calendar::Month>]
+
+        # @!method months_ahead
+        # Get the month that occurred the specified number of months ahead.
+        # @param quantity [Integer] the number of months after this month
+        # @return [Calendar::Month]
+ 
+        ### Quarters
+
+        # @!method this_quarter
+        # Get the current quarter within the active calendar.
+        # @return [Calendar::Quarter]
+
+        # @!method last_quarter
+        # Get the previous quarter within the active calendar.
+        # @return [Calendar::Quarter]
+
+        # @!method next_quarter
+        # Get the next quarter within the active calendar.
+        # @return [Calendar::Quarter]
+
+        # @!method quarters_for
+        # Get a list of quarters within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Quarter>]
+
+        # @!method quarters_back
+        # Get a quantity of quarters back from this quarter.
+        # @param quantity [Integer] the number of quarters requested
+        # @return [Array<Calendar::Quarter>]
+
+        # @!method quarters_ago
+        # Get the quarter that occurred the specified number of quarters ago.
+        # @param quantity [Integer] the number of quarters before this quarter
+        # @return [Calendar::Quarter]
+
+        # @!method quarters_forward
+        # Get a quantity of quarters forward from this quarter.
+        # @param quantity [Integer] the number of quarters requested
+        # @return [Array<Calendar::Quarter>]
+
+        # @!method quarters_ahead
+        # Get the quarter that occurred the specified number of days ahead.
+        # @param quantity [Integer] the number of quarters after this quarter
+        # @return [Calendar::Quarter]
+ 
+        ### Halves
+
+        # @!method this_half
+        # Get the current half within the active calendar.
+        # @return [Calendar::Half]
+
+        # @!method last_half
+        # Get the previous half within the active calendar.
+        # @return [Calendar::Half]
+
+        # @!method next_half
+        # Get the next half within the active calendar.
+        # @return [Calendar::Half]
+
+        # @!method halves_for
+        # Get a list of halves within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Half>]
+
+        # @!method halves_back
+        # Get a quantity of halves back from this half.
+        # @param quantity [Integer] the number of halves requested
+        # @return [Array<Calendar::Half>]
+
+        # @!method halves_ago
+        # Get the half that occurred the specified number of halves ago.
+        # @param quantity [Integer] the number of halves before this half
+        # @return [Calendar::Half]
+
+        # @!method halves_forward
+        # Get a quantity of halves forward from this half.
+        # @param quantity [Integer] the number of halves requested
+        # @return [Array<Calendar::Half>]
+
+        # @!method halves_ahead
+        # Get the half that occurred the specified number of halves ahead.
+        # @param quantity [Integer] the number of halves after this half
+        # @return [Calendar::Half]
+ 
+        ### Years
+
+        # @!method this_year
+        # Get the current year within the active calendar.
+        # @return [Calendar::Year]
+
+        # @!method last_year
+        # Get the previous year within the active calendar.
+        # @return [Calendar::Year]
+
+        # @!method next_year
+        # Get the next year within the active calendar.
+        # @return [Calendar::Year]
+
+        # @!method years_for
+        # Get a list of years within the specified period unit.
+        # @param period [Calendar::Support::Unit] the containing period unit
+        # @return [Array<Calendar::Year>]
+
+        # @!method years_back
+        # Get a quantity of years back from this year.
+        # @param quantity [Integer] the number of years requested
+        # @return [Array<Calendar::Year>]
+
+        # @!method years_ago
+        # Get the year that occurred the specified number of years ago.
+        # @param quantity [Integer] the number of years before this year
+        # @return [Calendar::Year]
+
+        # @!method years_forward
+        # Get a quantity of years forward from this year.
+        # @param quantity [Integer] the number of years requested
+        # @return [Array<Calendar::Year>]
+
+        # @!method years_ahead
+        # Get the year that occurred the specified number of years ahead.
+        # @param quantity [Integer] the number of years after this year
+        # @return [Calendar::Year]
+      end
+    end
+  end
+end