availability 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b27f01102a6bdb5c8a7aa11844f3a9fd568c9d09
-  data.tar.gz: a8fc64785938d22e1751314441936f17e5b52b9b
+  metadata.gz: 8eaf871af31feb52dcf53dcf209011faa140849a
+  data.tar.gz: ea9daa4546d229bdd17b454d2ef51bac5e33bd1c
 SHA512:
-  metadata.gz: 691256a8b27a1dadb57fbac13b44855e5c65b7c891c554792c3cf99b16066a292043a0611be829ed2df4c1e5f846117615ca1afd2b6d78942a2e531c630a5e43
-  data.tar.gz: 324414f8022f9a464274d95b43788c9d523d449b86467b74bbc9c4b82b0894656d8294237aa37d0006b97862bb8c057faf83d6f498a89b1ff5e22257bebc3af2
+  metadata.gz: cac1e269b14a79478b15db2c34c11cb2166762c3c50b4a6dec66953e574d3500461f0fb5353ab14a6a6717c1197f258b0ba5cff07f3fd3da9d36ce9ab75e03fe
+  data.tar.gz: b9cfe1fc23f4b068a9244d65ef5f2c7543bbd17732429a856b8eeaa3e83008438a70cac2dc0b36cf21750b3af4ef9acc81c9edda7b098c7a7441037e841c3afc

data/AUTHORS

@@ -0,0 +1,2 @@
+* Jason Rogers <jacaetevha@gmail.com>
+* Devin McCabe <devin.mccabe@gmail.com>

data/CREDITS

@@ -1 +1,2 @@
 * Jason Rogers <jacaetevha@gmail.com>
+* Devin McCabe <devin.mccabe@gmail.com>

data/README.md

@@ -1,7 +1,9 @@
-# availability - easily and quickly calculate schedule availability
+# availability
+(easily and quickly calculate schedule availability)
 
 [![Build Status](https://travis-ci.org/upper-hand/availability.svg?branch=master)](https://travis-ci.org/upper-hand/availability)
 [![Gem Version](https://badge.fury.io/rb/availability.svg)](https://badge.fury.io/rb/availability)
+[read the docs][DOCS]
 
 This library uses modular arithmetic and residue classes to calculate schedule availability for dates. Time ranges within a date are handled differently. The goal is to create an easy-to-use API for schedule availability that is very fast and lightweight that is also easy and lightweight to persist in a database.
 
@@ -11,9 +13,46 @@ Shout out to @dpmccabe for his [original article](http://dmcca.be/2014/01/09/rec
 gem install availability
 ```
 
+Creating `Availability` instances is pretty simple. There are 5 variants of availabilities: `Availability::Once`, `Availability::Daily`, `Availability::Weekly`, `Availability::Monthly`, and `Availability::Yearly`. You can instantiate either of those directly (with the `#new` method), or you can use the equivalent factory methods exposed on `Availability` (e.g. `Availability.once`, `Availability.yearly`). Most availabilities will require at least an `interval`, a `start_time`, and a `duration` (see the [RDocs](http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#initialize-instance_method) for explanations of these).
+
+There are a few convenience factory methods beyond the main factory methods:
+  - `Availability.every_{day,week,month,year}` will create the appropriate availability with an interval of 1
+  - `Availability.every_two_{days,weeks,months,years}` and `Availability.every_other_{day,week,month,year}` will create the appropriate availability with an interval of 2
+  - There are other `every_*` factory methods for intervals of 3, 4, and 5 (e.g. `every_three_months`)
+
+## Primary API
+
+### [#occurs_at?/1][OCCURS_AT]
+This method takes a date or time and responds with a boolean indicating whether or not it is covered by the receiver.
+
+### [#corresponds_to?/1][CORRESPONDS_TO]
+This method takes another availability and responds with a boolean indicating whether or not it is covered by the receiver.
+
+### [#last_occurrence][LAST_OCCURRENCE]
+This returns the last occurrence of the receiver, or `nil` if `stops_by` is not set.
+
+### [#next_n_occurrences/2][NEXT_N_OCCURS]
+This returns an enumerable object of the next `N` occurrences of this availability from the given date or time. If `N` is greater than 1,000 a lazy enumerable is returned, otherwise the enumerable is an instance of `Array` with the occurrences.
+
+### [#next_occurrence/1][NEXT_OCCUR]
+This returns a single time object for the next occurrence on or after the given date or time. If no occurrence exists, `nil` is returned.
+
+## Examples
+
+```ruby
+# Every Monday from 9:00 AM to 10:00 AM starting on May 2, 2016
+Availability.every_other_week(start_time: Time.new(2016, 5, 2, 9), duration: 1.hour)
+
+# A business week starting on May 2, 2016 going from 1:30 PM until 2:00 PM every day
+Availability.daily(start_time: Time.new(2016, 5, 2, 13, 30), stops_by: Time.new(2016, 5, 6), duration: 30.minutes)
+
+# A semi-monthly availability occurring all day, without an end
+Availability.every_other_month(start_time: Time.new(2016, 1, 1), duration: 1.day)
+```
+
 ## TODO
 
-add more documentation
+* add more documentation
 
 ## Authors
 
@@ -49,3 +88,9 @@ see <http://unlicense.org/> or the accompanying [UNLICENSE]{UNLICENSE} file.
 [YARD]:             http://yardoc.org/
 [YARD-GS]:          http://rubydoc.info/docs/yard/file/docs/GettingStarted.md
 [PDD]:              http://lists.w3.org/Archives/Public/public-rdf-ruby/2010May/0013.html
+[DOCS]:             http://www.rubydoc.info/gems/availability
+[OCCURS_AT]:        http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#occurs_at%3F-instance_method
+[CORRESPONDS_TO]:   http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#corresponds_to%3F-instance_method
+[LAST_OCCURRENCE]:  http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#last_occurrence-instance_method
+[NEXT_N_OCCURS]:    http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#next_n_occurrences%3F-instance_method
+[NEXT_OCCUR]:       http://www.rubydoc.info/gems/availability/Availability/AbstractAvailability#next_occurrence%3F-instance_method

data/bin/release

@@ -0,0 +1,2 @@
+#!/bin/bash
+bundle exec rake release

data/examples/scheduler.rb

@@ -72,7 +72,7 @@ class Scheduler
 
   def validate_availabilities(availabilities)
     list = Array(availabilities).flatten.compact
-    return list if list.all? { |e| e.respond_to? :corresponds_to? }
+    return list if list.all? { |e| Availability.availability?(e) }
     raise ArgumentError, "expected a list of availabilities"
   end
 

data/examples/scheduler_spec.rb

@@ -94,16 +94,16 @@ RSpec.describe Scheduler do
           expect(bobs_schedule.allow? availability_request: ar).to be_truthy
         end
 
-        it 'does not allow an event request that is beyond the availability frequency' do
-          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 18, 9), frequency: 4)).to be_falsey
+        it 'does not allow an event request that is beyond the availability interval' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 18, 9), interval: 4)).to be_falsey
         end
 
-        it 'does not allow an event request that starts before the availability frequency' do
-          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), frequency: 4)).to be_falsey
+        it 'does not allow an event request that starts before the availability interval' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), interval: 4)).to be_falsey
         end
 
-        it 'does not allow an event request with a different frequency' do
-          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), frequency: 5)).to be_falsey
+        it 'does not allow an event request with a different interval' do
+          expect(bobs_schedule.allow? availability_request: one_hour_slot_per_week(start_time: T(2016, 4, 4, 9), interval: 5)).to be_falsey
         end
       end
 

data/lib/availability/abstract_availability.rb

@@ -1,27 +1,26 @@
 module Availability
+  # @abstract see concrete classes: Once, Daily, Weekly, Monthly and Yearly
   class AbstractAvailability
     private_class_method :new # :nodoc:
   
-    attr_accessor :capacity, :duration, :frequency, :stops_by
+    attr_accessor :capacity, :duration, :stops_by
     attr_reader :exclusions, :interval, :residue, :start_time
 
     #
     # Required arguments:
-    #   interval: an integer that is the interval of occurrences per frequency
-    #   start_time: a Time, Date, or DateTime that indicates when the availability begins
-    #   duration: an integer indicating how long the availability lasts in seconds
+    # @param [Fixnum] interval an integer that is the interval of occurrences per frequency
+    # @param [Time] start_time a Time, Date, or DateTime that indicates when the availability begins
+    # @param [Fixnum] duration an integer indicating how long the availability lasts in seconds
     #
     # Optional arguements:
-    #   frequency: a symbol, one of [:once, :daily, :monthly, :yearly]; defaults to :daily
-    #   stops_by: specific date by which the availability ends
+    # @param [Time] stops_by specific Date, Time, or DateTime by which the availability ends
     #
-    def initialize(capacity: Float::INFINITY, exclusions: nil, frequency: :daily, stops_by: nil, duration: , interval: , start_time: )
+    def initialize(capacity: Float::INFINITY, exclusions: nil, stops_by: nil, duration: , interval: , start_time: )
       raise ArgumentError, "start_time is required" if start_time.nil?
       raise ArgumentError, "duration is required" if duration.nil?
       raise ArgumentError, "interval is required" if interval.nil?
       @capacity = capacity
       @duration = duration
-      @frequency = frequency
       @interval = interval
       @start_time = start_time.to_time
       @stops_by = stops_by
@@ -42,8 +41,17 @@ module Availability
       self.class.beginning
     end
 
+    # @!group Testing
+
+    #
+    # Whether or not the availability is covered by the receiver
+    #
+    # @param [Availability::AbstractAvailability] availability the availability to test for coverage
+    #
+    # @return [Boolean] true or false
+    #
     def corresponds_to?(availability)
-      return unless occurs_at?(availability.start_time) && occurs_at?(availability.start_time + availability.duration)
+      return false unless occurs_at?(availability.start_time) && occurs_at?(availability.start_time + availability.duration)
       if !!stops_by
         that_last = availability.last_occurrence
         !that_last.nil? &&
@@ -55,39 +63,26 @@ module Availability
       end
     end
 
-    def end_time
-      start_time + duration
-    end
-
-    def exclusions=(exclusions)
-      @exclusions = Array(exclusions).flatten.compact + [
-        Exclusion.before_day(start_time),
-        Exclusion.before_time(start_time)
-      ]
-      if stops_by
-        @exclusions += [
-          Exclusion.after_day(stops_by),
-          Exclusion.after_time(stops_by)
-          # TODO: should previous be: Exclusion.after_time(start_time + duration)
-        ]
-      end
-      self
-    end
-
-    def interval
-      @interval
+    #
+    # Whether or not the given time is covered by the receiver
+    #
+    # @param [Time] time the Date, Time, or DateTime to test for coverage
+    #
+    # @return [Boolean] true or false
+    #
+    def occurs_at?(time)
+      residue_for(time) == @residue && time_overlaps?(time, start_time, start_time + duration)
     end
 
-    def interval=(interval)
-      @interval = interval
-      compute_residue
-      self
-    end
+    # @!endgroup
 
-    def interval_difference(first, second)
-      raise 'subclass responsibility'
-    end
+    # @!group Occurrences
 
+    #
+    # Calculates the last occurrence of an availability
+    #
+    # @return [Time] the last occurrence of the receiver, or nil if stops_by is not set
+    #
     def last_occurrence
       return nil unless stops_by
       unless @last_occurrence
@@ -98,10 +93,14 @@ module Availability
       @last_occurrence
     end
 
-    def move_by(time, amount)
-      raise 'subclass responsibility'
-    end
-
+    #
+    # Calculates a time for the next occurrence on or after the given date or time.
+    # If no occurrence exists, `nil` is returned.
+    #
+    # from_date: a Date, Time, or DateTime from which to start calculating
+    #
+    # @return [Time] the next occurrence (or nil)
+    #
     def next_occurrence(from_date)
       residue = @residue - residue_for(from_date)
       date = move_by from_date, residue.modulo(interval)
@@ -118,10 +117,12 @@ module Availability
     end
 
     #
-    # Returns an array of occurrences for n <= 1000, otherwise it returns a lazy enumerator
+    # Calculates occurrences for n <= 1000; where n > 1000, it returns a lazy enumerator
     #
-    # n: Fixnum, how many occurrences to get
-    # from_date: a Date, Time, or DateTime from which to start calculating
+    # @param [Fixnum] n how many occurrences to get
+    # @param [Date, Time, DateTime] from_date time from which to start calculating
+    #
+    # @return [Enumerable] an array of [Time] or lazy enumeration for n > 1000
     #
     def next_n_occurrences(n, from_date)
       first_next_occurrence = next_occurrence(from_date)
@@ -131,12 +132,34 @@ module Availability
       range.map &blk
     end
 
-    def occurs_at?(time)
-      residue_for(time) == @residue && time_overlaps?(time, start_time, start_time + duration)
+    # @!endgroup
+
+    # @!group Accessors
+
+    def end_time
+      start_time + duration
     end
 
-    def residue_for(time)
-      raise 'subclass responsibility'
+    def exclusions=(exclusions)
+      #TODO: should be a set of exclusions
+      @exclusions = Array(exclusions).flatten.compact + [
+        Exclusion.before_day(start_time),
+        Exclusion.before_time(start_time)
+      ]
+      if stops_by
+        @exclusions += [
+          Exclusion.after_day(stops_by),
+          Exclusion.after_time(stops_by)
+          # TODO: should previous be: Exclusion.after_time(start_time + duration)
+        ]
+      end
+      self
+    end
+
+    def interval=(interval)
+      @interval = interval
+      compute_residue
+      self
     end
 
     def start_time=(start_time)
@@ -145,6 +168,10 @@ module Availability
       self
     end
 
+    # @!endgroup
+
+    # @!group Helpers
+
     def time_overlaps?(time, start_time, end_time)
       that_start = time.seconds_since_midnight.to_i
       this_start = start_time.seconds_since_midnight.to_i
@@ -152,6 +179,24 @@ module Availability
       (this_start..this_end).include?(that_start)
     end
 
+    # @!endgroup
+
+    # @!group Subclass Responsibilities
+
+    def interval_difference(first, second)
+      raise 'subclass responsibility'
+    end
+
+    def move_by(time, amount)
+      raise 'subclass responsibility'
+    end
+
+    def residue_for(time)
+      raise 'subclass responsibility'
+    end
+
+    # @!endgroup
+
     private
 
     def compute_residue

data/lib/availability/createable.rb

@@ -6,7 +6,7 @@ module Availability
 
     def create(**args)
       frequency = name.split(':').last.downcase.to_sym
-      super **args.merge(frequency: frequency, event_class: self)
+      super **args.merge(event_class: self)
     end
   end
 end

data/lib/availability/factory_methods.rb

@@ -1,7 +1,7 @@
 module Availability
   module FactoryMethods
     def create(**args)
-      cls = args.delete(:event_class) || Availability::subclass_for(args[:frequency] ||= :daily)
+      cls = args.delete(:event_class) || Availability::subclass_for(args.delete(:frequency) || :daily)
       raise ArgumentError, "undefined frequency" if cls.nil?
       cls.send :new, **args
     end

data/lib/availability/monthly.rb

@@ -14,8 +14,6 @@ module Availability
     end
 
     def residue_for(time)
-      # date = time.to_date
-      # ((date.year - beginning.year) * 12 + (date.month - beginning.month)).modulo(@interval)
       interval_difference(beginning, time).modulo(@interval)
     end
   end

data/lib/availability/once.rb

@@ -7,7 +7,7 @@ module Availability
     def initialize(**args)
       raise ArgumentError, "start_time is required" unless args.has_key?(:start_time)
       raise ArgumentError, "duration is required" unless args.has_key?(:duration)
-      super **args, frequency: :once, interval: 0, stops_by: args[:start_time] + args[:duration]
+      super **args, interval: 0, stops_by: args[:start_time] + args[:duration]
     end
 
     def interval_difference(this, that)

data/lib/availability/version.rb

@@ -1,3 +1,3 @@
 module Availability
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/availability/weekly.rb

@@ -10,7 +10,7 @@ module Availability
 
     def interval_difference(first, second)
       first_date, second_date = [first.to_date, second.to_date].sort
-      (second_date - first_date).to_i #/ interval
+      (second_date - first_date).to_i
     end
 
     def move_by(time, amount)
@@ -18,7 +18,7 @@ module Availability
     end
 
     def residue_for(time)
-      (time.to_date - beginning.to_date).to_i.modulo(interval)
+      interval_difference(time, beginning).modulo(interval)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: availability
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Jason Rogers
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-02 00:00:00.000000000 Z
+date: 2016-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -93,6 +93,7 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
+- AUTHORS
 - CREDITS
 - Gemfile
 - README.md
@@ -101,6 +102,7 @@ files:
 - WAIVER
 - availability.gemspec
 - bin/console
+- bin/release
 - bin/setup
 - examples/scheduler.rb
 - examples/scheduler_spec.rb