timeboss 0.3.0

data/lib/tasks/calendars.rake

@@ -0,0 +1,22 @@
+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|
+          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)
+        end
+
+        task shell: ["timeboss:calendars:#{entry.name}:repl"]
+      end
+    end
+  end
+end

data/lib/tasks/timeboss.rake

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

data/lib/timeboss.rb

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

data/lib/timeboss/calendar.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+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'
+
+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
+    alias_method :to_s, :name
+
+    # 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
+
+    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
+
+    def initialize(basis:)
+      @basis = basis
+    end
+
+    private
+
+    def parser
+      @_parser ||= Parser.new(self)
+    end
+  end
+end

data/lib/timeboss/calendar/day.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+require_relative './support/unit'
+
+module TimeBoss
+  class Calendar
+    class Day < Support::Unit
+      def initialize(calendar, start_date)
+        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
+
+      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
+
+      private
+
+      def down
+        self.class.new(calendar, start_date - 1.day)
+      end
+
+      def up
+        self.class.new(calendar, start_date + 1.day)
+      end
+    end
+  end
+end

data/lib/timeboss/calendar/half.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require_relative './support/monthly_unit'
+
+module TimeBoss
+  class Calendar
+    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
+    end
+  end
+end

data/lib/timeboss/calendar/month.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require_relative './support/monthly_unit'
+
+module TimeBoss
+  class Calendar
+    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
+    end
+  end
+end

data/lib/timeboss/calendar/parser.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+module TimeBoss
+  class Calendar
+    class Parser
+      RANGE_DELIMITER = '..'
+      InvalidPeriodIdentifierError = Class.new(StandardError)
+      attr_reader :calendar
+
+      def initialize(calendar)
+        @calendar = calendar
+      end
+
+      def parse(identifier = nil)
+        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)
+      rescue ArgumentError
+        raise InvalidPeriodIdentifierError
+      end
+
+      private
+
+      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)
+      end
+
+      def parse_period(identifier)
+        return calendar.send(identifier) if calendar.respond_to?(identifier.to_s)
+        parse_term(identifier || Date.today.year.to_s)
+      end
+
+      def parse_term(identifier)
+        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
+        %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
+        end
+        period
+      end
+    end
+  end
+end

data/lib/timeboss/calendar/period.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+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)
+          text = "#{text} #{Parser::RANGE_DELIMITER} #{self.end.send(message)}" unless self.end == self.begin
+          text
+        end
+      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
+          entries = send(size.pluralize)
+          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
+
+      private
+
+      attr_reader :calendar
+
+      def initialize(calendar, begin_basis, end_basis = nil)
+        @calendar = calendar
+        @begin = begin_basis
+        @end = end_basis || @begin
+      end
+
+      def build_entries(entry)
+        return [] if entry.start_date > self.end.end_date
+        entries = [entry]
+        while entry.end_date < self.end.end_date
+          entry = entry.next
+          entries << entry
+        end
+        entries
+      end
+    end
+  end
+end

data/lib/timeboss/calendar/quarter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+require_relative './support/monthly_unit'
+
+module TimeBoss
+  class Calendar
+    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
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+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 = 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
+          base, text = 'year', unit.year.name
+          periods.each do |period|
+            sub = unit.send(period) or break
+            index = sub.send("in_#{base}")
+            text += "#{period[0].upcase}#{index}"
+            base = period
+          end
+          text
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+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
+
+        def initialize(year, month)
+          @year = year
+          @month = month
+        end
+
+        def to_range
+          @_to_range ||= start_date .. end_date
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+require_relative './unit'
+
+module TimeBoss
+  class Calendar
+    module Support
+      class MonthlyUnit < Unit
+        attr_reader :year_index, :index
+
+        def initialize(calendar, year_index, index, start_date, end_date)
+          super(calendar, start_date, end_date)
+          @year_index = year_index
+          @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
+          num_weeks.times.map { |i| Week.new(calendar, base.start_date + (i * 7).days, base.start_date + ((i * 7) + 6).days) }
+                         .select { |w| w.start_date.between?(start_date, end_date) }
+        end
+
+        private
+
+        def max_index
+          12 / self.class::NUM_MONTHS
+        end
+
+        def up
+          if index == max_index
+            calendar.send(self.class.type, year_index + 1, 1)
+          else
+            calendar.send(self.class.type, year_index, index + 1)
+          end
+        end
+
+        def down
+          if index == 1
+            calendar.send(self.class.type, year_index - 1, max_index)
+          else
+            calendar.send(self.class.type, year_index, index - 1)
+          end
+        end
+      end
+    end
+  end
+end