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

timeboss 0.0.10 → 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 (71) hide show

checksums.yaml +4 -4
data/.gitignore +1 -0
data/.yardopts +1 -0
data/README.md +1 -1
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/timeboss.rb +4 -0
data/lib/timeboss/calendar.rb +14 -0
data/lib/timeboss/calendar/day.rb +10 -3
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} +7 -1
data/lib/timeboss/calendar/support/navigable.rb +25 -1
data/lib/timeboss/calendar/support/shiftable.rb +3 -2
data/lib/timeboss/calendar/support/unit.rb +24 -0
data/lib/timeboss/calendar/waypoints.rb +6 -55
data/lib/timeboss/calendar/waypoints/absolute.rb +114 -0
data/lib/timeboss/calendar/waypoints/relative.rb +268 -0
data/lib/timeboss/calendar/week.rb +11 -0
data/lib/timeboss/calendar/year.rb +6 -5
data/lib/timeboss/calendars.rb +16 -0
data/lib/timeboss/version.rb +1 -1
data/spec/calendar/support/{month_based_spec.rb → monthly_unit_spec.rb} +7 -7
data/spec/calendars/broadcast_spec.rb +7 -7
data/timeboss.gemspec +1 -0
metadata +70 -7

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/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,14 +7,28 @@ 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

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

@@ -3,27 +3,34 @@ 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 - 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

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,10 +15,14 @@ module TimeBoss
           @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

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

@@ -2,25 +2,49 @@
 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.
+        #   @return [Unit]
+        # @overload previous(value)
+        #   Fetch some previous number of units relative to this unit
+        #   @param quantity [Integer]
+        #   @return [Array<Unit>]
         def previous(quantity = nil)
           return down if quantity.nil?
           gather(:previous, quantity).reverse
         end
+        # @overload next
+        #   Fetch the next unit relative to this unit.
+        #   @return [Unit]
+        # @overload next(value)
+        #   Fetch some next number of units relative to this unit
+        #   @param quantity [Integer]
+        #   @return [Array<Unit>]
         def next(quantity = nil)
           return up if quantity.nil?
           gather(:next, quantity)
         end
+        # Fetch the unit some number of units prior to this unit.
+        # @param quantity [Integer]
+        # @return [Unit]
         def ago(quantity)
           previous(quantity + 1).first
         end
-        def hence(quantity)
+        # Fetch the unit some number of units after this unit.
+        # @param quantity [Integer]
+        # @return [Unit]
+        def ahead(quantity)
           self.next(quantity + 1).last
         end
+        # Fetch a list of units from this unit until some date.
+        # @param end_date [Date]
+        # @return [Array<Unit>]
         def until(end_date)
           entry = self
           [entry].tap do |entries|

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

@@ -2,6 +2,7 @@
 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]
@@ -37,12 +38,12 @@ module TimeBoss
             send("#{periods}_ago", 0)
           end
-          define_method "#{periods}_hence" do |offset|
+          define_method "#{periods}_ahead" do |offset|
             send("#{periods}_ago", offset * -1)
           end
           define_method "next_#{period}" do
-            send("#{periods}_hence", 1)
+            send("#{periods}_ahead", 1)
           end
         end
       end