timeboss 0.0.10 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a46b4d08fd0e17154dbb9f2f806d74e3e0dd83ad2a6dff04102dd5142a975809
-  data.tar.gz: e231795ad178299e99475a03f7fc589d234373ce672f525653b9e67c209d00cc
+  metadata.gz: 9d4c953bb1ef449bdc7d37f0ac3061da752b28a9f4df8c1901f9507c447ac89b
+  data.tar.gz: 752abd38f0afee607b6529894eec4189dfbbc462f5a27ddb4a6238720db35b4e
 SHA512:
-  metadata.gz: b4a01cd350e3df24190b5818e0cc71ea09b15e57ae73db9620e812b138b9badcb8acd8fb5fa33a35c52049e7893e37cf7a3beed40c8eebbbfddd46158d0ff72f
-  data.tar.gz: 493dd68afa5bd7df4b49c36881946ef869844f538a791780da86a966988be349debd9077a35cb0f834a20b5f0920088da2547cac33de1ec7618783d5f8f69b74
+  metadata.gz: b1d04714bcb3514b386fda20f1aaad42f1db96382719848ef9ee5cf889b5c855a26bbb6c6039f50e08ce2484194924ceb8a2ee32f0242b1e3bbc928a9156a0b8
+  data.tar.gz: 1662c699fc80d9b37744a2f7f4fffa5d72e64d912bab4e19b1d113ba466a16201c003e32b26d1d8697da8c2feb21d4e16be344bc2bacdb2358f2a46ed6646c49

data/.gitignore

@@ -1,3 +1,5 @@
-/*.gem
-/Gemfile.lock
-/.bundle
+*.gem
+Gemfile.lock
+.bundle
+.yardoc
+doc

data/.yardopts

@@ -0,0 +1 @@
+--protected lib/**/*.rb

data/README.md

@@ -1,5 +1,7 @@
 # TimeBoss [![Build Status](https://travis-ci.com/kevinstuffandthings/timeboss.svg?branch=master)](https://travis-ci.com/kevinstuffandthings/timeboss) [![Gem Version](https://badge.fury.io/rb/timeboss.svg)](https://badge.fury.io/rb/timeboss)
-A gem providing convenient navigation of the [Broadcast Calendar](https://en.wikipedia.org/wiki/Broadcast_calendar).
+
+A gem providing convenient navigation of the [Broadcast Calendar](https://en.wikipedia.org/wiki/Broadcast_calendar), the standard Gregorian calendar, and is easily extensible to support multiple financial calendars.
+
 Originally developed for [Simulmedia](https://simulmedia.com).
 
 ## Installation
@@ -23,7 +25,7 @@ $ gem install timeboss
 ```
 
 ## Usage
-Supports `year`, `half`, `quarter`, `month`, `week`, and `day`.
+Supports `year`, `half`, `quarter`, `month`, `week` (non-gregorian calendars only), and `day`.
 
 Prepare your calendar for use:
 
@@ -62,7 +64,7 @@ calendar.years_back(2).map { |y| y.start_date.to_s } # run in 2020
 calendar.months_ago(3).name # run in 2020M7
 # => "2020M4"
 
-calendar.weeks_hence(3).name # run in 2020W29
+calendar.weeks_ahead(3).name # run in 2020W29
 # => "2020W32"
 ```
 
@@ -131,11 +133,16 @@ period = calendar.parse('2020W3..2020Q1')
 # => "2020W3 .. 2020Q1: from 2020-01-13 thru 2020-03-29 (current=false)"
 ```
 
-The examples above are just samples. Try different periods, operators, etc.
+The examples above are just samples. Try different periods, operators, etc. All of the non-week-based operations will work similarly on the `TimeBoss::Calendars::Gregorian` calendar.
 
 ### Shell
 To open an IRB shell for the broadcast calendar, use the `tbsh` executable, or the `timeboss:calendars:broadcast:shell` rake task.
-You will find yourself in the context of an instantiated `TimeBoss::Calendars::Broadcast` object:
+
+For the Gregorian calendar (or any other implemented calendars), supply the name on the command line.
+- `tbsh gregorian`
+- `rake timeboss:calendars:gregorian:shell`
+
+You will find yourself in the context of an instantiated `TimeBoss::Calendar` object:
 
 ```bash
 $ tbsh

data/bin/tbsh

@@ -4,7 +4,7 @@ require 'timeboss/calendars'
 require 'timeboss/support/shellable'
 
 calendar = if ARGV.length == 1
-             TimeBoss::Calendars[ARGV.first]&.calendar
+             TimeBoss::Calendars[ARGV.first]
            else
              TimeBoss::Calendars.first.calendar
            end

data/lib/timeboss.rb

@@ -1,2 +1,6 @@
 # frozen_string_literal: true
 require "timeboss/version"
+
+# TimeBoss
+module TimeBoss
+end

data/lib/timeboss/calendar.rb

@@ -9,16 +9,37 @@ require_relative './calendar/support/month_basis'
 module TimeBoss
   class Calendar
     include Waypoints
+
+    # @!method parse
+    # Parse an identifier into a unit or period.
+    #   Valid identifiers can include simple units (like "2020Q3", "2020M8W3", "last_quarter"),
+    #   mathematical expressions (like "this_month+6"),
+    #   or period expressions (like "2020W1..2020W8", "this_quarter-2..next_quarter")
+    # @param identifier [String]
+    # @return [Support::Unit, Period]
+
     delegate :parse, to: :parser
 
+    # Get a name by which this calendar can be referenced.
+    # @return [String]
     def name
       self.class.to_s.demodulize.underscore
     end
 
+    # Get a friendly title for this calendar.
+    # @return [String]
     def title
       name.titleize
     end
 
+    # Can this calendar support weeks?
+    # For custom calendars, this value can generally not be overridden.
+    # But for calendars like our Gregorian implementation, weeks are irrelevant, and should be suppressed.
+    # @return [Boolean]
+    def supports_weeks?
+      true
+    end
+
     protected
 
     attr_reader :basis

data/lib/timeboss/calendar/day.rb

@@ -8,22 +8,28 @@ module TimeBoss
         super(calendar, start_date, start_date)
       end
 
+      # Get a simple representation of this day.
+      # @return [String] (e.g. "2020-08-03")
       def name
         start_date.to_s
       end
 
+      # Get a "pretty" representation of this day.
+      # @return [String] (e.g. "August 3, 2020")
       def title
         start_date.strftime('%B %-d, %Y')
       end
 
-      def to_s
-        name
-      end
+      alias_method :to_s, :name
 
+      # Get the index of this day within its containing year.
+      # @return [Integer]
       def index
         @_index ||= (start_date - year.start_date).to_i + 1
       end
 
+      # Get the year number for this day.
+      # @return [Integer] (e.g. 2020)
       def year_index
         @_year_index ||= year.year_index
       end

data/lib/timeboss/calendar/half.rb

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

data/lib/timeboss/calendar/month.rb

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

data/lib/timeboss/calendar/period.rb

@@ -3,9 +3,29 @@ module TimeBoss
   class Calendar
     class Period
       attr_reader :begin, :end
+
+      # @!method start_date
+      # Get the start date of this period.
+      # @return [Date]
       delegate :start_date, to: :begin
+
+      # @!method end_date
+      # Get the end date of this period.
+      # @return [Date]
       delegate :end_date, to: :end
 
+      # @!method name
+      # Get a simple representation of this period.
+      # @return [String]
+
+      # @!method title
+      # Get a "pretty" representation of this period.
+      # @return [String]
+
+      # @!method to_s
+      # Get a stringified representation of this period.
+      # @return [String]
+
       %i[name title to_s].each do |message|
         define_method(message) do
           text = self.begin.send(message)
@@ -14,7 +34,7 @@ module TimeBoss
         end
       end
 
-      %w[week month quarter half year].each do |size|
+      %w[day week month quarter half year].each do |size|
         define_method(size.pluralize) do
           entry = calendar.send("#{size}_for", self.begin.start_date)
           build_entries entry
@@ -27,20 +47,14 @@ module TimeBoss
         end
       end
 
+      # Does this period cover the current date?
+      # @return [Boolean]
       def current?
         to_range.include?(Date.today)
       end
 
-      def days
-        to_range.map { |d| Day.new(calendar, d) }
-      end
-
-      def day
-        entries = days
-        return nil unless entries.length == 1
-        entries.first
-      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/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,18 +1,20 @@
 # 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)
           @unit = unit
           @periods = PERIODS & periods.map(&:to_sym).push(unit.class.type.to_sym)
+          @periods -= [:week] unless unit.calendar.supports_weeks?
         end
 
         def to_s

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,10 +13,14 @@ module TimeBoss
           @index = index
         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

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

@@ -3,24 +3,47 @@ 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
 
-        def hence(quantity)
+        # 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|

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