timeboss 0.1.0 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ad33c552922fb61c6b798d0c32ab7b125d561b1d0aae10eae486317d65ed624
-  data.tar.gz: 9744c0da3d9d10b28c3a23d6c384c48dd4b2cd8b2d910e97c362dcac9c9a3bf4
+  metadata.gz: 7a8966731f645860d665b2a333b2996dad5e1224d25703ddfdd4f155779645df
+  data.tar.gz: d087b039000b8b7999eaeae1ba98526618741aef3535238551314e79446d9b8d
 SHA512:
-  metadata.gz: 8d3a750e0901981ad30ec9bab9f3c155f13ea6689293ff5b46f574ae074ee79f712a2d5e3ba9f4dc0e10b492d4252a20b879f244d92afb1ce21417a2231530c1
-  data.tar.gz: 8d3c3d6b5f6e4df76b69e78853758a12a347c9e65957d1ee03d55229e9f04c526ddbfc912bdc1a89407635e306b6207b06e5f8d008eed2cec260e59c0948ce6b
+  metadata.gz: 31c77aac0422e2ba3da7c8422014ddfa0196388c27c4d9e78775909099a6a2461d0b6d86f5f2b265fda05718711e60818f33519c17f025f4952cf7ff950444e2
+  data.tar.gz: a5cbb8b93686382b75222a191405de36449d725dee28db2dd396c9d8e394fa41d8da7dd41229c3c9674d7ba6c2ad78f9fe03f720a3279d47f0f4cc14eb41d939

data/.gitignore

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

data/.replit

@@ -0,0 +1,2 @@
+language = "ruby"
+run = "rake timeboss:calendars:broadcast:repl"

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).
+# 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) [![Run on Repl.it](https://repl.it/badge/github/kevinstuffandthings/timeboss)](https://repl.it/github/kevinstuffandthings/timeboss)
+
+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:
 
@@ -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.
+
+### REPL
+To open a REPL for the broadcast calendar, use the `tbsh` executable, or the `timeboss:calendars:broadcast:repl` rake task.
+
+For the Gregorian calendar (or any other implemented calendars), supply the name on the command line.
+- `tbsh gregorian`
+- `rake timeboss:calendars:gregorian:repl`
 
-### 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:
+You will find yourself in the context of an instantiated `TimeBoss::Calendar` object:
 
 ```bash
 $ tbsh
@@ -147,7 +154,7 @@ $ tbsh
  => ["2020M7", "2020M8", "2020M9", "2020M10", "2020M11", "2020M12", "2021M1", "2021M2", "2021M3", "2021M4", "2021M5", "2021M6", "2021M7", "2021M8", "2021M9"]
 ```
 
-_Having trouble with the shell? If you are using the examples from the [Usage](#Usage) section, keep in mind that the shell is already in the context of the calendar -- so you don't need to specify the receiver!_
+_Having trouble with the REPL? If you are using the examples from the [Usage](#Usage) section, keep in mind that the REPL is already in the context of the calendar -- so you don't need to specify the receiver!_
 
 ## Creating new calendars
 To create a custom calendar, simply extend the `TimeBoss::Calendar` class, and implement a new `TimeBoss::Calendar::Support::MonthBasis` for it.

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/tasks/calendars.rake

@@ -9,11 +9,13 @@ namespace :timeboss do
           puts entry.calendar.parse(args[:expression])
         end
 
-        desc "Open a shell with the #{entry.name} calendar"
-        task shell: ['timeboss:init'] do
+        desc "Open a REPL with the #{entry.name} calendar"
+        task repl: ['timeboss:init'] do
           require 'timeboss/support/shellable'
           TimeBoss::Support::Shellable.open(entry.calendar)
         end
+
+        task shell: ["timeboss:calendars:#{entry.name}:repl"]
       end
     end
   end

data/lib/timeboss/calendar.rb

@@ -7,7 +7,6 @@ require 'active_support/core_ext/numeric/time'
 require_relative './calendar/support/month_basis'
 
 module TimeBoss
-  # A calendar is built upon a basis, and provides methods for period identification and navigation.
   class Calendar
     include Waypoints
 
@@ -26,6 +25,7 @@ module TimeBoss
     def name
       self.class.to_s.demodulize.underscore
     end
+    alias_method :to_s, :name
 
     # Get a friendly title for this calendar.
     # @return [String]
@@ -33,6 +33,14 @@ module TimeBoss
       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

@@ -3,7 +3,6 @@ require_relative './support/unit'
 
 module TimeBoss
   class Calendar
-    # Representation of a single day within a calendar.
     class Day < Support::Unit
       def initialize(calendar, start_date)
         super(calendar, start_date, start_date)

data/lib/timeboss/calendar/half.rb

@@ -3,7 +3,6 @@ require_relative './support/monthly_unit'
 
 module TimeBoss
   class Calendar
-    # Representation of a 6-month period within a calendar.
     class Half < Support::MonthlyUnit
       NUM_MONTHS = 6
 

data/lib/timeboss/calendar/month.rb

@@ -3,7 +3,6 @@ require_relative './support/monthly_unit'
 
 module TimeBoss
   class Calendar
-    # Representation of a single month within a calendar.
     class Month < Support::MonthlyUnit
       NUM_MONTHS = 1
 

data/lib/timeboss/calendar/parser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 module TimeBoss
   class Calendar
-    # The parser is responsible for the implementation of a calendar's identifier parsing abilities.
     class Parser
       RANGE_DELIMITER = '..'
       InvalidPeriodIdentifierError = Class.new(StandardError)

data/lib/timeboss/calendar/period.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 module TimeBoss
   class Calendar
-    # A calendar period represents a range of units.
     class Period
       attr_reader :begin, :end
 

data/lib/timeboss/calendar/quarter.rb

@@ -3,7 +3,6 @@ require_relative './support/monthly_unit'
 
 module TimeBoss
   class Calendar
-    # Representation of a 3-month period within a calendar.
     class Quarter < Support::MonthlyUnit
       NUM_MONTHS = 3
 

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

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-require_relative './shiftable'
+require_relative './translatable'
 
 module TimeBoss
   class Calendar
@@ -8,12 +8,13 @@ module TimeBoss
 
       # 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

@@ -2,8 +2,6 @@ module TimeBoss
   class Calendar
     module Support
       # @abstract
-      # Implementation of a month basis allows a custom calendar to be built.
-      # A month basis must return a start/end date for a given year and month index.
       class MonthBasis
         attr_reader :year, :month
 

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

@@ -4,8 +4,6 @@ require_relative './unit'
 module TimeBoss
   class Calendar
     module Support
-      # Units that are built off of month-granularities (months, quarters, etc).
-      # Days and weeks are not built from these.
       class MonthlyUnit < Unit
         attr_reader :year_index, :index
 

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

@@ -2,7 +2,6 @@
 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.

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

@@ -2,50 +2,239 @@
 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]
-
-        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}_ahead" 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}_ahead", 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