RubyGems - timeboss - Versions diffs - 0.0.6 → 0.1.0 - Mend

timeboss 0.0.6 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

checksums.yaml +4 -4
data/.github/ISSUE_TEMPLATE/bug_report.md +23 -0
data/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
data/.gitignore +2 -0
data/.travis.yml +4 -1
data/.yardopts +1 -0
data/CODE_OF_CONDUCT.md +76 -0
data/README.md +30 -18
data/bin/tbsh +15 -0
data/doc/TimeBoss.html +146 -0
data/doc/TimeBoss/Calendar.html +137 -0
data/doc/TimeBoss/Calendar/Day.html +594 -0
data/doc/TimeBoss/Calendar/Half.html +396 -0
data/doc/TimeBoss/Calendar/Month.html +396 -0
data/doc/TimeBoss/Calendar/Parser.html +386 -0
data/doc/TimeBoss/Calendar/Period.html +841 -0
data/doc/TimeBoss/Calendar/Quarter.html +396 -0
data/doc/TimeBoss/Calendar/Support.html +131 -0
data/doc/TimeBoss/Calendar/Support/Formatter.html +459 -0
data/doc/TimeBoss/Calendar/Support/MonthBased.html +591 -0
data/doc/TimeBoss/Calendar/Support/MonthBasis.html +437 -0
data/doc/TimeBoss/Calendar/Support/MonthlyUnit.html +591 -0
data/doc/TimeBoss/Calendar/Support/Navigable.html +723 -0
data/doc/TimeBoss/Calendar/Support/Shiftable.html +138 -0
data/doc/TimeBoss/Calendar/Support/Unit.html +1299 -0
data/doc/TimeBoss/Calendar/Waypoints.html +155 -0
data/doc/TimeBoss/Calendar/Waypoints/Absolute.html +1378 -0
data/doc/TimeBoss/Calendar/Waypoints/Relative.html +4308 -0
data/doc/TimeBoss/Calendar/Week.html +671 -0
data/doc/TimeBoss/Calendar/Year.html +319 -0
data/doc/TimeBoss/Calendars.html +336 -0
data/doc/TimeBoss/Calendars/Broadcast.html +221 -0
data/doc/TimeBoss/Calendars/Broadcast/Basis.html +278 -0
data/doc/TimeBoss/Calendars/Entry.html +399 -0
data/doc/TimeBoss/Support.html +115 -0
data/doc/TimeBoss/Support/Shellable.html +249 -0
data/doc/_index.html +416 -0
data/doc/class_list.html +51 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +496 -0
data/doc/file.README.html +299 -0
data/doc/file_list.html +56 -0
data/doc/frames.html +17 -0
data/doc/index.html +299 -0
data/doc/js/app.js +314 -0
data/doc/js/full_list.js +216 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +1139 -0
data/doc/top-level-namespace.html +110 -0
data/lib/tasks/calendars.rake +5 -0
data/lib/timeboss.rb +4 -0
data/lib/timeboss/calendar.rb +22 -0
data/lib/timeboss/calendar/day.rb +19 -6
data/lib/timeboss/calendar/half.rb +7 -2
data/lib/timeboss/calendar/month.rb +7 -2
data/lib/timeboss/calendar/parser.rb +1 -0
data/lib/timeboss/calendar/period.rb +26 -11
data/lib/timeboss/calendar/quarter.rb +7 -2
data/lib/timeboss/calendar/support.rb +8 -0
data/lib/timeboss/calendar/support/formatter.rb +1 -0
data/lib/timeboss/calendar/support/month_basis.rb +3 -0
data/lib/timeboss/calendar/support/{month_based.rb → monthly_unit.rb} +24 -18
data/lib/timeboss/calendar/support/navigable.rb +73 -0
data/lib/timeboss/calendar/support/shiftable.rb +3 -2
data/lib/timeboss/calendar/support/unit.rb +26 -0
data/lib/timeboss/calendar/waypoints.rb +6 -80
data/lib/timeboss/calendar/waypoints/absolute.rb +114 -0
data/lib/timeboss/calendar/waypoints/relative.rb +268 -0
data/lib/timeboss/calendar/week.rb +26 -18
data/lib/timeboss/calendar/year.rb +6 -5
data/lib/timeboss/calendars.rb +20 -3
data/lib/timeboss/version.rb +1 -1
data/spec/calendar/day_spec.rb +1 -1
data/spec/calendar/support/{month_based_spec.rb → monthly_unit_spec.rb} +18 -8
data/spec/calendar/week_spec.rb +5 -13
data/spec/calendars/broadcast_spec.rb +27 -7
data/spec/calendars_spec.rb +7 -1
data/timeboss.gemspec +1 -0
metadata +77 -8

data/doc/top-level-namespace.html ADDED

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.25
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+<script type="text/javascript">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="TimeBoss.html" title="TimeBoss (module)">TimeBoss</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Sun Jul 19 10:12:10 2020 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.25 (ruby-2.4.1).
+</div>
+    </div>
+  </body>
+</html>

data/lib/tasks/calendars.rake CHANGED

@@ -4,6 +4,11 @@ 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 shell with the #{entry.name} calendar"
         task shell: ['timeboss:init'] do
           require 'timeboss/support/shellable'

data/lib/timeboss.rb CHANGED

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

data/lib/timeboss/calendar.rb CHANGED

@@ -7,10 +7,32 @@ 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
+    # @!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
     protected
     attr_reader :basis

data/lib/timeboss/calendar/day.rb CHANGED

@@ -3,32 +3,45 @@ 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)
       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 - calendar.year_for(start_date).start_date).to_i + 1
+        @_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
-      def previous
+      private
+      def down
         self.class.new(calendar, start_date - 1.day)
       end
-      def next
+      def up
         self.class.new(calendar, start_date + 1.day)
       end
     end

data/lib/timeboss/calendar/half.rb CHANGED

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
-require_relative './support/month_based'
+require_relative './support/monthly_unit'
 module TimeBoss
   class Calendar
-    class Half < Support::MonthBased
+    # Representation of a 6-month period within a 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

data/lib/timeboss/calendar/month.rb CHANGED

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
-require_relative './support/month_based'
+require_relative './support/monthly_unit'
 module TimeBoss
   class Calendar
-    class Month < Support::MonthBased
+    # Representation of a single month within a 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

data/lib/timeboss/calendar/parser.rb CHANGED

@@ -1,6 +1,7 @@
 # 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 CHANGED

@@ -1,11 +1,32 @@
 # frozen_string_literal: true
 module TimeBoss
   class Calendar
+    # A calendar period represents a range of units.
     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 +35,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 +48,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 CHANGED

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
-require_relative './support/month_based'
+require_relative './support/monthly_unit'
 module TimeBoss
   class Calendar
-    class Quarter < Support::MonthBased
+    # Representation of a 3-month period within a 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

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module TimeBoss
+  module Calendar
+    # Provides modules and abstract base classes to facilitate calendar implementation.
+    module Support
+    end
+  end
+end

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

@@ -6,6 +6,7 @@ module TimeBoss
     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)
         attr_reader :unit, :periods

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

@@ -1,6 +1,9 @@
 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/{month_based.rb → monthly_unit.rb} RENAMED

@@ -4,7 +4,9 @@ require_relative './unit'
 module TimeBoss
   class Calendar
     module Support
-      class MonthBased < Unit
+      # 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
         def initialize(calendar, year_index, index, start_date, end_date)
@@ -13,30 +15,18 @@ module TimeBoss
           @index = index
         end
-        def next
-          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 previous
-          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
+        # 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, year_index, i + 1, base.start_date + (i * 7).days, base.start_date + ((i * 7) + 6).days) }
+          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
@@ -45,6 +35,22 @@ module TimeBoss
         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