timeboss 0.3.0 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a66336923993e3b4319dd8d0dc925d936ba7e6897f50f1c679a23f37a35e8f8
-  data.tar.gz: 3925a5fd244c6fac67ba026f0f3738398bc67f6cc75e015f8eea21caf78f5d84
+  metadata.gz: cd2408c9c89006534d10c61c485b8adf4adc5fb8d3fd819ce904ed99c8985db8
+  data.tar.gz: e27776f25a4fae89655cc04c07e91e8b607fcc50eb65090be0e6ecd16349c4e3
 SHA512:
-  metadata.gz: 87ebf1f8c61e12cd086c33336abca2b5a76ee59cc6117711f166672bd9958c753eb68e38e29ed6aeaccb927520eabaf819da50a62b11879186778f97c982c632
-  data.tar.gz: 5bc4914fb3f90bb391fb0e3bb852d25764f926492fccc74ff4ecc56ba321fbad9030fb3812423d4c2ed8bc2c61b2e79b9def7ed34a7789061a2367f122888da1
+  metadata.gz: 5b7e5694b2955fbf6043d2e52bc8d0e6e15cbedc8fdee19123473b0487f2a9ba48b88b5cf8bd6e0eeb93db2537724e12a9aeb00378e9cad4022dbc9fc01c8887
+  data.tar.gz: aefad770303d38a8d2b31baa406cccee9ababea5b2415d6599ec2645e5fca418c61ccbe8f4b6f4aa29a7ead7aea3200b2bce0b83f58f6e6416fb7fb3c9f38b21

data/.github/workflows/gem-push.yml

@@ -0,0 +1,31 @@
+name: Ruby Gem
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build + Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby 2.6
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6.x
+
+    - name: Publish to RubyGems
+      run: |
+        mkdir -p $HOME/.gem
+        touch $HOME/.gem/credentials
+        chmod 0600 $HOME/.gem/credentials
+        printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+        gem build *.gemspec
+        gem push *.gem
+      env:
+        GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/.github/workflows/ruby.yml

@@ -0,0 +1,35 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0']
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: bundle exec rspec

data/.travis.yml

@@ -1,14 +1,15 @@
 language: ruby
 rvm:
-- 2.4
 - 2.5
 - 2.6
+- 2.7
+- 3.0
 script:
 - bundle exec rspec
 deploy:
   provider: rubygems
   api_key:
-    secure: jUWa2Jx0HRVv7Dl0zYPTskHQ+RJGy2TUcBWOjyFbBUbeDKiRh8J/NnbMuCOvmL94htSaFk5lcs6k74Itu6jW12+KyT98OAnOardFPFuI0cHHhIMEhF6ms8EhyOCZ0vvR9zav11gfNzyF716qO09DQSDuoKWWNdhrYj8a5paLdbHuRqQiw3YUmnjVQ/v9SPYaZ7ziXC4X4tBxQhK2ujNsNfztSVrpYb6pnsXnt+hFQOnskzi0+er4854iymykeyNVgB71KgivrE3T55ZTXPPglshsZQE7M7FlYA5L3bwzR7SlA202yFYHB3hUN3obwO3BjO4OiAdKQnSosBHaXI13ZvCOz02AfEJhwoxkBXw1/2CvSQ12QQPVgqkpxWY03h+URk+gGHCV+JaqZPCV9excmVWg/IOQou0IJ6h84VFViyVc2aFVN2AIdoaG3NsppbV3j4VuLG6J2VVpNmUzN3pGgi5YSjVq9Hp+huXZFfWpnUgAxc680hKgcFajE3JNANG+NbNEeoDmITvZyV5kvJklgUKPsl2wNk+wY/GGrSBgNOVlyXqTWLZb/8Z/cSrN5DEc6D5BIS/SG95wlCRT8jUqbyEPjT+H77TH2ySfwWZzblLqbIxaLiZr3hX16oMdUx7Cya5LKLFgQBpU6cFUxvZX7SqHwjk1vnuG592Kxd9GkX4=
+    secure: f7s86k3ZRgaao32goumx0EFSquj8v8vwLBQP0uPd5lZ5OlDjUIbzAGCLpP4IARFf7MhYUUxWqwU7A0Z2MJHgmf4hT2VdVco4kGC4WztMgSI2JwY8Uo21/QJgI82jIfZ6yfSjF8OC3eh9irqJxXfhzspO9DY4p+nJkMJnpG5Y1e5FjS9zM3gS80TD9fauIMEi3fOLDNYEZ95SgjrkX2MHDYQWN1nfFlkRtybSHJ2u2Ad3Ulr5c/1gIoJviJCm8l5Bwo3MnvBtSuHHjFOaH9UTcmDUGpBjr7GMoqn3m053aB1F3ImYwL9+il0rtj+PE1lNaVbUM/QDKp8gDcbo433m8oMiGRpouz0fdIi95fqsshZmSU9sZX6HPiOuURXXwrjW7n3bj71+qZ7zWPTyZB8p3Y6ocp/r6Aj0ewELJksjnbYqSuyYv0o5sKTh2AUMawcqWAnDlZWgMq4UqKQiaWlhZMN1guQIWO6Xq9xdoiIxcqRUTJ7dUAGsfv+GIs2iPLvh20DHudYN70J5b4xzZLFgPQOJbTGlQQtC18m2PaYvcdsZ1qzttQIs0fcgeKno1Ltcman6/yqbAdKsSjifLUcdqHiWOUk5Dh5l4S+iSVazILVFFHwV89JI1+ipuS1nnIaRcmfIkV3GB+aXcbwwYc89mLkXBVmezs+scygK0KUhoyU=
   gem: timeboss
   on:
     tags: true

data/Gemfile

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
-source 'https://rubygems.org'
+
+source "https://rubygems.org"
 gemspec

data/README.md

@@ -1,4 +1,4 @@
-# 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)
+# TimeBoss ![Build Status](https://github.com/kevinstuffandthings/timeboss/actions/workflows/ruby.yml/badge.svg) [![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.
 
@@ -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`:
@@ -136,7 +139,7 @@ period = calendar.parse('2020W3..2020Q1')
 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.
+To open a [REPL](https://repl.it/github/kevinstuffandthings/timeboss) locally 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`
@@ -147,13 +150,19 @@ 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"]
 ```
 
+If you want to try things out locally without installing the gem or updating your ruby environment, you can use [Docker](https://docker.com):
+
+```bash
+$ docker run --rm -it ruby:2.6.6-slim /bin/bash -c "gem install timeboss >/dev/null && tbsh"
+```
+
 _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
@@ -229,5 +238,6 @@ With the new calendar implemented, it can be accessed in one of 2 ways:
     calendar.this_year
     ```
 
-## TODO
-- [ ] Add comprehensive documentation
+# Problems?
+Please submit an [issue](https://github.com/kevinstuffandthings/timeboss/issues).
+We'll figure out how to get you up and running with TimeBoss as smoothly as possible.

data/Rakefile

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+
 require "bundler/setup"
 require "bundler/gem_tasks"
+require "standard/rake"
 
-Dir.glob('lib/tasks/*.rake').each { |r| load r }
+Dir.glob("lib/tasks/*.rake").each { |r| load r }

data/bin/tbsh

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require 'timeboss/calendars'
-require 'timeboss/support/shellable'
+require 'shellable'
 
 calendar = if ARGV.length == 1
              TimeBoss::Calendars[ARGV.first]
@@ -12,4 +12,4 @@ calendar = if ARGV.length == 1
 abort "Unknown calendar" if calendar.nil?
 
 puts "Active calendar: #{calendar.title}"
-TimeBoss::Support::Shellable.open(calendar)
+Shellable.open(calendar)

data/lib/tasks/calendars.rake

@@ -1,18 +1,18 @@
-require './lib/timeboss/calendars'
+require "./lib/timeboss/calendars"
 
 namespace :timeboss do
   namespace :calendars do
     TimeBoss::Calendars.each do |entry|
       namespace entry.name do
         desc "Evaluate an expression for the #{entry.name} calendar"
-        task :evaluate, %i[expression] => ['timeboss:init'] do |_, args|
+        task :evaluate, %i[expression] => ["timeboss:init"] do |_, args|
           puts entry.calendar.parse(args[:expression])
         end
 
         desc "Open a REPL with the #{entry.name} calendar"
-        task repl: ['timeboss:init'] do
-          require 'timeboss/support/shellable'
-          TimeBoss::Support::Shellable.open(entry.calendar)
+        task repl: ["timeboss:init"] do
+          require "shellable"
+          Shellable.open(entry.calendar)
         end
 
         task shell: ["timeboss:calendars:#{entry.name}:repl"]

data/lib/tasks/timeboss.rake

@@ -1,6 +1,6 @@
 namespace :timeboss do
   task :init do
-    require './lib/timeboss'
-    require './lib/timeboss/calendars'
+    require "./lib/timeboss"
+    require "./lib/timeboss/calendars"
   end
 end

data/lib/timeboss.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "timeboss/version"
 
 # TimeBoss

data/lib/timeboss/calendar.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
-require 'active_support/inflector'
-require 'active_support/core_ext/numeric/time'
+
+require "active_support/inflector"
+require "active_support/core_ext/numeric/time"
 
 %w[day week month quarter half year].each { |f| require_relative "./calendar/#{f}" }
 %w[waypoints period parser].each { |f| require_relative "./calendar/#{f}" }
-require_relative './calendar/support/month_basis'
+require_relative "./calendar/support/month_basis"
 
 module TimeBoss
   class Calendar
@@ -43,7 +44,7 @@ module TimeBoss
 
     def self.register!
       return unless TimeBoss::Calendars.method_defined?(:register)
-      TimeBoss::Calendars.register(self.name.to_s.demodulize.underscore, self)
+      TimeBoss::Calendars.register(name.to_s.demodulize.underscore, self)
     end
     private_class_method :register!
 

data/lib/timeboss/calendar/day.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require_relative './support/unit'
+
+require_relative "./support/unit"
 
 module TimeBoss
   class Calendar
@@ -17,7 +18,7 @@ module TimeBoss
       # Get a "pretty" representation of this day.
       # @return [String] (e.g. "August 3, 2020")
       def title
-        start_date.strftime('%B %-d, %Y')
+        start_date.strftime("%B %-d, %Y")
       end
 
       alias_method :to_s, :name

data/lib/timeboss/calendar/half.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require_relative './support/monthly_unit'
+
+require_relative "./support/monthly_unit"
 
 module TimeBoss
   class Calendar

data/lib/timeboss/calendar/month.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require_relative './support/monthly_unit'
+
+require_relative "./support/monthly_unit"
 
 module TimeBoss
   class Calendar

data/lib/timeboss/calendar/parser.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
+
 module TimeBoss
   class Calendar
     class Parser
-      RANGE_DELIMITER = '..'
+      RANGE_DELIMITER = ".."
       InvalidPeriodIdentifierError = Class.new(StandardError)
       attr_reader :calendar
 
@@ -11,7 +12,7 @@ module TimeBoss
       end
 
       def parse(identifier = nil)
-        return nil unless (identifier || '').strip.length > 0
+        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)]
@@ -24,13 +25,13 @@ module TimeBoss
 
       def parse_identifier(identifier)
         captures = identifier&.match(/^([^-]+)(\s*[+-]\s*[0-9]+)$/)&.captures
-        base, offset = captures || [identifier, '0']
-        period = parse_period(base&.strip) or raise InvalidPeriodIdentifierError
-        period.offset(offset.gsub(/\s+/, '').to_i)
+        base, offset = captures || [identifier, "0"]
+        (period = parse_period(base&.strip)) || raise(InvalidPeriodIdentifierError)
+        period.offset(offset.gsub(/\s+/, "").to_i)
       end
 
       def parse_period(identifier)
-        return calendar.send(identifier) if calendar.respond_to?(identifier.to_s)
+        return calendar.public_send(identifier) if calendar.respond_to?(identifier.to_s)
         parse_term(identifier || Date.today.year.to_s)
       end
 
@@ -38,13 +39,13 @@ module TimeBoss
         return Day.new(calendar, Date.parse(identifier)) if identifier.match?(/^[0-9]{4}-?[01][0-9]-?[0-3][0-9]$/)
 
         raise InvalidPeriodIdentifierError unless identifier.match?(/^[HQMWD0-9]+$/)
-        period = if identifier.to_i == 0 then calendar.this_year else calendar.year(identifier.to_i) end
+        period = identifier.to_i == 0 ? calendar.this_year : calendar.year(identifier.to_i)
         %w[half quarter month week day].each do |size|
           prefix = size[0].upcase
           next unless identifier.include?(prefix)
           junk, identifier = identifier.split(prefix)
           raise InvalidPeriodIdentifierError if junk.match?(/\D/)
-          period = period.send(size.pluralize)[identifier.to_i - 1] or raise InvalidPeriodIdentifierError
+          (period = period.public_send(size.pluralize)[identifier.to_i - 1]) || raise(InvalidPeriodIdentifierError)
         end
         period
       end

data/lib/timeboss/calendar/period.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module TimeBoss
   class Calendar
     class Period
@@ -28,35 +29,110 @@ module TimeBoss
 
       %i[name title to_s].each do |message|
         define_method(message) do
-          text = self.begin.send(message)
-          text = "#{text} #{Parser::RANGE_DELIMITER} #{self.end.send(message)}" unless self.end == self.begin
+          text = self.begin.public_send(message)
+          text = "#{text} #{Parser::RANGE_DELIMITER} #{self.end.public_send(message)}" unless self.end == self.begin
           text
         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)
+          entry = calendar.public_send("#{size}_for", self.begin.start_date)
           build_entries entry
         end
 
-        define_method(size) do
-          entries = send(size.pluralize)
+        define_method(size) do |index = nil|
+          entries = public_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
+        @_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