timeboss 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a8966731f645860d665b2a333b2996dad5e1224d25703ddfdd4f155779645df
-  data.tar.gz: d087b039000b8b7999eaeae1ba98526618741aef3535238551314e79446d9b8d
+  metadata.gz: b0d4b9c100b0d59e5aa5b71152c390f59deedce0e071c0d5c82666dba445946d
+  data.tar.gz: dc533dd7884b186571322d2229823f47da014a623a1f50535a7c723f4d6c355c
 SHA512:
-  metadata.gz: 31c77aac0422e2ba3da7c8422014ddfa0196388c27c4d9e78775909099a6a2461d0b6d86f5f2b265fda05718711e60818f33519c17f025f4952cf7ff950444e2
-  data.tar.gz: a5cbb8b93686382b75222a191405de36449d725dee28db2dd396c9d8e394fa41d8da7dd41229c3c9674d7ba6c2ad78f9fe03f720a3279d47f0f4cc14eb41d939
+  metadata.gz: 0acc27cc7254a3e0d67df651ddf2462bb606e2e844e7076bf36fd9c5ce0eacb2ccf08963ee418f41204c60c6acd6d0783fed60871b4729b46870c6f133de28f3
+  data.tar.gz: '0281773958cbad85a0b10997c3ed058797906a5fed2f5452a572922492cabf27021871ea018aec5e8b85e078803a750a7f004f1d2b04ec1d6518002c0552360a'

data/.replit

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

data/README.md

@@ -40,7 +40,7 @@ You can ask simple questions of the calendar:
 
 ```ruby
 period = calendar.parse('2019Q4') # or '2018', or '2019-12-21', or '2020W32', or '2020M3W2'
-# => #<TimeBoss::Calendar::Quarter:0x007f82d50e2478>
+# => #<TimeBoss::Calendar::Quarter start_date=2019-09-30, end_date=2019-12-29>
 period.to_s
 # => "2019Q4: 2019-09-30 thru 2019-12-29"
 period.next.start_date.to_s # try previous, too!
@@ -117,6 +117,9 @@ week = calendar.parse('2014W29').this_week
 
 calendar.this_week.next_year.to_s # run 2020W29
 # => "2021W29: 2021-07-12 thru 2021-07-18"
+
+calendar.week(2016, this_week.in_year) # run 2020-07-22
+# => #<TimeBoss::Calendar::Week start_date=2016-07-18, end_date=2016-07-24>
 ```
 
 Complicated range expressions can be parsed using the `..` range operator, or evaluated with `thru`:
@@ -147,9 +150,9 @@ You will find yourself in the context of an instantiated `TimeBoss::Calendar` ob
 ```bash
 $ tbsh
 2.4.1 :001 > next_quarter
- => #<TimeBoss::Calendar::Quarter:0x007fe04c16a1c8 @calendar=#<TimeBoss::Calendars::Broadcast:0x007fe04c1a0458 @basis=TimeBoss::Calendars::Broadcast::Basis>, @year_index=2020, @index=4, @start_date=#<Date: 2020-09-28 ((2459121j,0s,0n),+0s,2299161j)>, @end_date=#<Date: 2020-12-27 ((2459211j,0s,0n),+0s,2299161j)>>
+ => #<TimeBoss::Calendar::Quarter start_date=2020-09-28, end_date=2020-12-27>
 2.4.1 :002 > last_year
- => #<TimeBoss::Calendar::Year:0x007fe04c161ca8 @calendar=#<TimeBoss::Calendars::Broadcast:0x007fe04c1a0458 @basis=TimeBoss::Calendars::Broadcast::Basis>, @year_index=2019, @index=1, @start_date=#<Date: 2018-12-31 ((2458484j,0s,0n),+0s,2299161j)>, @end_date=#<Date: 2019-12-29 ((2458847j,0s,0n),+0s,2299161j)>>
+ => #<TimeBoss::Calendar::Year start_date=2018-12-31, end_date=2019-12-29>
 2.4.1 :003 > parse('this_quarter .. this_quarter+4').months.map(&:name)
  => ["2020M7", "2020M8", "2020M9", "2020M10", "2020M11", "2020M12", "2021M1", "2021M2", "2021M3", "2021M4", "2021M5", "2021M6", "2021M7", "2021M8", "2021M9"]
 ```
@@ -221,9 +224,10 @@ With the new calendar implemented, it can be accessed in one of 2 ways:
 
     ```ruby
     require 'timeboss/calendars'
+    TimeBoss::Calendars.register(:august_fiscal, MyCalendars::AugustFiscal)
+
+    # You'll get a cached instance of your calendar here.
+    # Handy when switching back and forth between different calendar implementations.
     calendar = TimeBoss::Calendars[:august_fiscal]
     calendar.this_year
     ```
-
-## TODO
-- [ ] Add comprehensive documentation

data/lib/timeboss/calendar.rb

@@ -41,6 +41,12 @@ module TimeBoss
       true
     end
 
+    def self.register!
+      return unless TimeBoss::Calendars.method_defined?(:register)
+      TimeBoss::Calendars.register(self.name.to_s.demodulize.underscore, self)
+    end
+    private_class_method :register!
+
     protected
 
     attr_reader :basis

data/lib/timeboss/calendar/parser.rb

@@ -11,7 +11,8 @@ module TimeBoss
       end
 
       def parse(identifier = nil)
-        return parse_identifier(identifier.presence) unless identifier&.include?(RANGE_DELIMITER)
+        return nil unless (identifier || '').strip.length > 0
+        return parse_identifier(identifier) unless identifier&.include?(RANGE_DELIMITER)
         bases = identifier.split(RANGE_DELIMITER).map { |i| parse_identifier(i.strip) } unless identifier.nil?
         bases ||= [parse_identifier(nil)]
         Period.new(calendar, *bases)

data/lib/timeboss/calendar/period.rb

@@ -34,31 +34,106 @@ module TimeBoss
         end
       end
 
+      #
+      # i hate this
+      #
+
+      ### Days
+
+      # @!method days
+      # Get a list of days that fall within this period.
+      # @return [Array<Calendar::Day>]
+
+      # @!method day(index = nil)
+      # Get the day this period 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 period.
+      # @return [Array<Calendar::Week>]
+
+      # @!method week(index = nil)
+      # Get the week this period 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 period.
+      # @return [Array<Calendar::Month>]
+
+      # @!method month(index = nil)
+      # Get the month this period 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 period.
+      # @return [Array<Calendar::Quarter>]
+
+      # @!method quarter(index = nil)
+      # Get the quarter this period 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 period.
+      # @return [Array<Calendar::Half>]
+
+      # @!method half(index = nil)
+      # Get the half this period 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 period.
+      # @return [Array<Calendar::Year>]
+
+      # @!method year(index = nil)
+      # Get the year this period represents.
+      # Returns nil if no single year can be identified.
+      # @return [Array<Calendar::Year>, nil]
+
+      # Does this period cover the current date?
+      # @return [Boolean]
+      def current?
+        to_range.include?(Date.today)
+      end
+
       %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
         end
 
-        define_method(size) do
+        define_method(size) do |index = nil|
           entries = send(size.pluralize)
+          return entries[index - 1] unless index.nil?
           return nil unless entries.length == 1
           entries.first
         end
       end
 
-      # Does this period cover the current date?
-      # @return [Boolean]
-      def current?
-        to_range.include?(Date.today)
-      end
-
       # Express this period as a date range.
       # @return [Range<Date, Date>]
       def to_range
         @_to_range ||= start_date .. end_date
       end
 
+      def inspect
+        "#<#{self.class.name}[#{self.begin.inspect}..#{self.end.inspect}] start_date=#{start_date}, end_date=#{end_date}>"
+      end
+
       private
 
       attr_reader :calendar

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

@@ -2,6 +2,8 @@ module TimeBoss
   class Calendar
     module Support
       # @abstract
+      # A MonthBasis must define a `#start_date` and `#end_date` method.
+      # These methods should be calculated based on the incoming `#year` and `#month` values.
       class MonthBasis
         attr_reader :year, :month
 

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

@@ -10,8 +10,9 @@ module TimeBoss
 
           define_method(periods) { calendar.send("#{periods}_for", self) }
 
-          define_method(period) do
+          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
@@ -27,7 +28,7 @@ module TimeBoss
         # Get a list of days that fall within this unit.
         # @return [Array<Calendar::Day>]
 
-        # @!method 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]
@@ -38,7 +39,7 @@ module TimeBoss
         # Get a list of weeks that fall within this unit.
         # @return [Array<Calendar::Week>]
 
-        # @!method 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]
@@ -49,7 +50,7 @@ module TimeBoss
         # Get a list of months that fall within this unit.
         # @return [Array<Calendar::Month>]
 
-        # @!method 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]
@@ -60,7 +61,7 @@ module TimeBoss
         # Get a list of quarters that fall within this unit.
         # @return [Array<Calendar::Quarter>]
 
-        # @!method 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]
@@ -71,7 +72,7 @@ module TimeBoss
         # Get a list of halves that fall within this unit.
         # @return [Array<Calendar::Half>]
 
-        # @!method 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]
@@ -82,7 +83,7 @@ module TimeBoss
         # Get a list of years that fall within this unit.
         # @return [Array<Calendar::Year>]
 
-        # @!method 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]

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

@@ -82,6 +82,10 @@ module TimeBoss
         def to_range
           @_to_range ||= start_date .. end_date
         end
+
+        def inspect
+          "#<#{self.class.name} start_date=#{start_date}, end_date=#{end_date}>"
+        end
       end
     end
   end

data/lib/timeboss/calendars.rb

@@ -1,28 +1,33 @@
 # frozen_string_literal: true
-require 'active_support/core_ext/class/subclasses'
 require_relative 'calendar'
 
-Dir[File.expand_path('../calendars/*.rb', __FILE__)].each { |f| require f }
-
 module TimeBoss
   module Calendars
     extend self
     extend Enumerable
     delegate :each, :length, to: :all
 
+    # Register a new calendar
+    # @return [Entry]
+    def register(name, klass)
+      Entry.new(name.to_sym, klass).tap do |entry|
+        (@entries ||= {})[name.to_sym] = entry
+      end
+    end
+
     # Retrieve a list of all registered calendars.
     # @return [Array<Entry>]
     def all
-      @_all ||= TimeBoss::Calendar.subclasses.map do |klass|
-        Entry.new(klass.to_s.demodulize.underscore.to_sym, klass)
-      end
+      return if @entries.nil?
+      @entries.values.sort_by { |e| e.name.to_s }
     end
 
     # Retrieve an instance of the specified named calendar.
     # @param name [String, Symbol] the name of the calendar to retrieve.
     # @return [Calendar]
     def [](name)
-      find { |e| e.name == name&.to_sym }&.calendar
+      return if @entries.nil?
+      @entries[name&.to_sym]&.calendar
     end
 
     private
@@ -44,3 +49,5 @@ module TimeBoss
     end
   end
 end
+
+Dir[File.expand_path('../calendars/*.rb', __FILE__)].each { |f| require f }

data/lib/timeboss/calendars/broadcast.rb

@@ -4,6 +4,8 @@ require_relative '../calendar'
 module TimeBoss
   module Calendars
     class Broadcast < Calendar
+      register!
+
       def initialize
         super(basis: Basis)
       end

data/lib/timeboss/calendars/gregorian.rb

@@ -4,6 +4,8 @@ require_relative '../calendar'
 module TimeBoss
   module Calendars
     class Gregorian < Calendar
+      register!
+
       def initialize
         super(basis: Basis)
       end

data/lib/timeboss/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module TimeBoss
-  VERSION = "0.2.3"
+  VERSION = "1.0.0"
 end

data/spec/calendars/broadcast_spec.rb

@@ -493,10 +493,9 @@ module TimeBoss
         expect(date.end_date).to eq Date.parse('2017-04-08')
       end
 
-      it 'gives you this year if you give it nothing' do
-        year = subject.this_year
-        expect(subject.parse(nil)).to eq year
-        expect(subject.parse('')).to eq year
+      it 'gives you nothing if you give it nothing' do
+        expect(subject.parse(nil)).to be nil
+        expect(subject.parse('')).to be nil
       end
     end
 

data/spec/calendars/gregorian_spec.rb

@@ -475,10 +475,9 @@ module TimeBoss
         expect(date.end_date).to eq Date.parse('2017-04-08')
       end
 
-      it 'gives you this year if you give it nothing' do
-        year = subject.this_year
-        expect(subject.parse(nil)).to eq year
-        expect(subject.parse('')).to eq year
+      it 'gives you nothing if you give it nothing' do
+        expect(subject.parse(nil)).to be nil
+        expect(subject.parse('')).to be nil
       end
     end
 

data/spec/calendars_spec.rb

@@ -1,11 +1,13 @@
 module TimeBoss
   describe Calendars do
-    class MyTestCalendar < TimeBoss::Calendar
+    class MyCal < TimeBoss::Calendar
       def initialize
         super(basis: nil)
       end
     end
 
+    TimeBoss::Calendars.register(:my_amazing_calendar, MyCal)
+
     describe '#all' do
       let(:all) { described_class.all }
 
@@ -17,7 +19,7 @@ module TimeBoss
 
       context 'enumerability' do
         it 'can get a list of names' do
-          expect(described_class.map(&:name)).to include(:broadcast, :my_test_calendar)
+          expect(described_class.map(&:name)).to include(:broadcast, :my_amazing_calendar)
         end
       end
     end
@@ -34,10 +36,10 @@ module TimeBoss
       end
 
       it 'can return a new calendar' do
-        c1 = described_class[:my_test_calendar]
-        expect(c1).to be_instance_of MyTestCalendar
-        expect(c1.name).to eq 'my_test_calendar'
-        expect(c1.title).to eq 'My Test Calendar'
+        c1 = described_class[:my_amazing_calendar]
+        expect(c1).to be_instance_of MyCal
+        expect(c1.name).to eq 'my_cal'
+        expect(c1.title).to eq 'My Cal'
       end
 
       it 'can graceully give you nothing' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timeboss
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Kevin McDonald
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-20 00:00:00.000000000 Z
+date: 2020-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport