business 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5c69d99c21ef0905de463bc82315c5f3829f6c23
-  data.tar.gz: 2d333b66d2d26a1cd9664b7415033012ab898339
+  metadata.gz: ba9a77c99ec8b8d8d62ce8dd67e03cfbcadf3948
+  data.tar.gz: 0e9f3652c8bf6a17ec0200786a0fff9bb99f2a2a
 SHA512:
-  metadata.gz: a020144ad1d875fe40df7dfd91d2cec5fe5623134921a40cc45669202bc0c76a43f98cde0f9cf1da3f8334eaabbb245823f8f542ac3a6985b3055b869e8c663e
-  data.tar.gz: c0ce8a9993aad1a8be8378ae9bdeb77368979be818ca1cca84ccf9ed2eddd0ba2811c81d03dbdfb072da3134e63c9abe75ce9a7ff6e96138105f606439725db7
+  metadata.gz: c331e4584c468ff1760ef2d5e355355999eba3d5dbda0ce4ce172072be71e28b7dc98a279163b6b25c47b5aee4fc50a0ef3fabb6cbc47ccfc3b3442fdd7a8685
+  data.tar.gz: 625fd8b80ae09a43a4196477560997299f440fa3ddd1f2f6c77ee044c97ea472c8e8dfddba4ecee5ae8e0cea75aaa7f18d025ec51193f9946280f4879c41c3c5

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 GoCardless
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,13 +1,100 @@
-# BankTime
+# Business
 
-Date calculations based on bank calendars
+Date calculations based on business calendars.
 
-## Usage
+
+## But other libraries already do this
+
+Another gem, business_time, also exists for this purpose. We previously used
+business_time, but encountered several issues that prompted us to create
+business.
+
+Firstly, business_time works by monkey-patching `Date`, `Time`, and `FixNum`.
+While this enables syntax like `Time.now + 1.business_day`, it means that all
+configuration has to be global. GoCardless handles payments across multiple
+geographies, so being able to work with multiple working-day calendars is
+essential for us. Business provides a simple `Calendar` class, that is
+initialized with a configuration that specifies which days of the week are
+considered to be working days, and which dates are holidays.
+
+Secondly, business_time supports calculations on times as well as dates. For
+our purposes, date-based calculations are sufficient. Supporting time-based
+calculations as well makes the code significantly more complex. We chose to
+avoid this extra complexity by sticking solely to date-based mathematics.
+
+
+## Documentation
+
+### Getting started
+
+Get stareted with business by creating an instance of the calendar class,
+passing in a hash that specifies with days of the week are considered working
+days, and which days are holidays.
+
+```ruby
+calendar = Business::Calendar.new(
+  working_days: %w( mon tue wed thu fri ),
+  holidays: ["01/01/2014", "03/01/2014"]
+)
+```
+
+A few calendar configs are bundled with the gem. Load them by calling the
+`load` class method on `Calendar`. The `load_cached` variant of this method
+caches the calendars by name after loading them, to avoid reading and
+parsing the config file multiple times.
+
+```ruby
+calendar = Business::Calendar.load("weekdays")
+calendar = Business::Calendar.load_cached("weekdays")
+```
+
+### Checking for business days
+
+To check whether a given date is a business day (falls on one of the specified
+working days, and is not a holiday), use the `business_day?` method on
+`Calendar`.
+
+```ruby
+calendar.business_day?(Date.parse("Monday, 9 June 2014"))
+# => true
+calendar.business_day?(Date.parse("Sunday, 8 June 2014"))
+# => false
+```
+
+### Business day arithmetic
+
+The `add_business_days` and `subtract_business_days` are used to perform
+business day arithemtic on dates.
+
+```ruby
+date = Date.parse("Thursday, 12 June 2014")
+calendar.add_business_days(date, 4).strftime("%A, %d %B %Y")
+# => "Wednesday, 18 June 2014"
+calendar.subtract_business_days(date, 4).strftime("%A, %d %B %Y")
+# => "Friday, 06 June 2014"
+```
+
+The `roll_forward` and `roll_backward` methods snap a date to a nearby business
+day. If provided with a business day, they will return that date. Otherwise,
+they will advance (forward for `roll_forward` and backward for `roll_backward`)
+until a business day is found.
+
+```ruby
+date = Date.parse("Saturday, 14 June 2014")
+calendar.roll_forward(date).strftime("%A, %d %B %Y")
+# => "Monday, 16 June 2014"
+calendar.roll_backward(date).strftime("%A, %d %B %Y")
+# => "Friday, 13 June 2014"
+```
+
+To count the number of business days between two dates, pass the dates to
+`business_days_between`. This method counts from start of the first date to
+start of the second date. So, assuming no holidays, there would be two business
+days between a Monday and a Wednesday.
 
 ```ruby
-calendar = BankTime::Calendar.load('bacs')
-date = Date.parse("2013-10-18")
-calendar.add_business_days(date, 1)
-# => 2013-10-21
+date = Date.parse("Saturday, 14 June 2014")
+calendar.business_days_between(date, date + 7)
+# => 5
 ```
 

data/business.gemspec

@@ -8,9 +8,10 @@ Gem::Specification.new do |spec|
   spec.version       = Business::VERSION
   spec.authors       = ["Harry Marr"]
   spec.email         = ["engineering@gocardless.com"]
-  spec.description   = %q{Date calculations based on business calendars}
   spec.summary       = %q{Date calculations based on business calendars}
+  spec.description   = %q{Date calculations based on business calendars}
   spec.homepage      = "https://github.com/gocardless/business"
+  spec.licenses      = ["MIT"]
 
   spec.files         = `git ls-files`.split($/)
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
@@ -18,5 +19,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.3"
-  spec.add_development_dependency "rspec", "~> 2.14.1"
+  spec.add_development_dependency "rspec", "~> 3.0"
 end

data/lib/business/calendar.rb

@@ -6,7 +6,7 @@ module Business
       path = File.join(File.dirname(__FILE__), 'data', "#{calendar}.yml")
       raise "No such calendar '#{calendar}'" unless File.exists?(path)
       yaml = YAML.load_file(path)
-      self.new(holidays: yaml['holidays'], business_days: yaml['business_days'])
+      self.new(holidays: yaml['holidays'], working_days: yaml['working_days'])
     end
 
     @lock = Mutex.new
@@ -22,18 +22,18 @@ module Business
 
     DAY_NAMES = %( mon tue wed thu fri sat sun )
 
-    attr_reader :business_days, :holidays
+    attr_reader :working_days, :holidays
 
     def initialize(config)
-      set_business_days(config[:business_days])
+      set_working_days(config[:working_days])
       set_holidays(config[:holidays])
     end
 
-    # Return true if the date given is a business day (typically that means a
+    # Return true if the date given is a business day (typically that meanss a
     # non-weekend day) and not a holiday.
     def business_day?(date)
       date = date.to_date
-      return false unless business_days.include?(date.strftime('%a').downcase)
+      return false unless working_days.include?(date.strftime('%a').downcase)
       return false if holidays.include?(date)
       true
     end
@@ -114,13 +114,13 @@ module Business
       num_full_weeks, remaining_days = (date2 - date1).to_i.divmod(7)
 
       # First estimate for full week range based on # biz days in a week
-      num_biz_days = num_full_weeks * business_days.length
+      num_biz_days = num_full_weeks * working_days.length
 
       full_weeks_range = (date1...(date2 - remaining_days))
       num_biz_days -= holidays.count do |holiday|
         in_range = full_weeks_range.cover?(holiday)
         # Only pick a holiday if its on a working day (e.g., not a weekend)
-        on_biz_day = business_days.include?(holiday.strftime('%a').downcase)
+        on_biz_day = working_days.include?(holiday.strftime('%a').downcase)
         in_range && on_biz_day
       end
 
@@ -133,9 +133,9 @@ module Business
       date.is_a?(Date) ? 1 : 3600 * 24
     end
 
-    # Internal method for assigning business days from a calendar config.
-    def set_business_days(business_days)
-      @business_days = (business_days || default_business_days).map do |day|
+    # Internal method for assigning working days from a calendar config.
+    def set_working_days(working_days)
+      @working_days = (working_days || default_working_days).map do |day|
         day.downcase.strip[0..2].tap do |normalised_day|
           raise "Invalid day #{day}" unless DAY_NAMES.include?(normalised_day)
         end
@@ -147,8 +147,8 @@ module Business
       @holidays = (holidays || []).map { |holiday| Date.parse(holiday) }
     end
 
-    # If no business days are provided in the calendar config, these are used.
-    def default_business_days
+    # If no working days are provided in the calendar config, these are used.
+    def default_working_days
       %w( mon tue wed thu fri )
     end
   end

data/lib/business/data/bacs.yml

@@ -1,4 +1,4 @@
-business_days:
+working_days:
   - monday
   - tuesday
   - wednesday

data/lib/business/data/sepa.yml

@@ -1,4 +1,4 @@
-business_days:
+working_days:
   - monday
   - tuesday
   - wednesday

data/lib/business/data/weekdays.yml

@@ -1,4 +1,4 @@
-business_days:
+working_days:
   - monday
   - tuesday
   - wednesday

data/lib/business/version.rb

@@ -1,3 +1,3 @@
 module Business
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/spec/calendar_spec.rb

@@ -7,51 +7,51 @@ describe Business::Calendar do
       subject { Business::Calendar.load("weekdays") }
 
       it "loads the yaml file" do
-        YAML.should_receive(:load_file) do |path|
-          path.should match(/weekdays\.yml$/)
-        end.and_return({})
+        expect(YAML).to receive(:load_file) { |path|
+          expect(path).to match(/weekdays\.yml$/)
+        }.and_return({})
         subject
       end
 
-      it { should be_a Business::Calendar }
+      it { is_expected.to be_a Business::Calendar }
     end
 
     context "when given an invalid calendar" do
       subject { Business::Calendar.load("invalid-calendar") }
-      specify { ->{ subject }.should raise_error }
+      specify { expect{ subject }.to raise_error }
     end
   end
 
-  describe "#set_business_days" do
+  describe "#set_working_days" do
     let(:calendar) { Business::Calendar.new({}) }
-    let(:business_days) { [] }
-    subject { calendar.set_business_days(business_days) }
+    let(:working_days) { [] }
+    subject { calendar.set_working_days(working_days) }
 
-    context "when given valid business days" do
-      let(:business_days) { %w( mon fri ) }
+    context "when given valid working days" do
+      let(:working_days) { %w( mon fri ) }
       before { subject }
 
       it "assigns them" do
-        calendar.business_days.should == business_days
+        expect(calendar.working_days).to eq(working_days)
       end
 
       context "that are unnormalised" do
-        let(:business_days) { %w( Monday Friday ) }
+        let(:working_days) { %w( Monday Friday ) }
         it "normalises them" do
-          calendar.business_days.should == %w( mon fri )
+          expect(calendar.working_days).to eq(%w( mon fri ))
         end
       end
     end
 
     context "when given an invalid business day" do
-      let(:business_days) { %w( Notaday ) }
-      specify { ->{ subject }.should raise_exception }
+      let(:working_days) { %w( Notaday ) }
+      specify { expect{ subject }.to raise_exception }
     end
 
     context "when given nil" do
-      let(:business_days) { nil }
+      let(:working_days) { nil }
       it "uses the default business days" do
-        calendar.business_days.should == calendar.default_business_days
+        expect(calendar.working_days).to eq(calendar.default_working_days)
       end
     end
   end
@@ -65,16 +65,16 @@ describe Business::Calendar do
     context "when given valid business days" do
       let(:holidays) { ["1st Jan, 2013"] }
 
-      it { should_not be_empty }
+      it { is_expected.not_to be_empty }
 
       it "converts them to Date objects" do
-        subject.each { |h| h.should be_a Date }
+        subject.each { |h| expect(h).to be_a Date }
       end
     end
 
     context "when given nil" do
       let(:holidays) { nil }
-      it { should be_empty }
+      it { is_expected.to be_empty }
     end
   end
 
@@ -90,17 +90,17 @@ describe Business::Calendar do
 
       context "when given a business day" do
         let(:day) { date_class.parse("9am, Wednesday 2nd Jan, 2013") }
-        it { should be_true }
+        it { is_expected.to be_truthy }
       end
 
       context "when given a non-business day" do
         let(:day) { date_class.parse("9am, Saturday 5th Jan, 2013") }
-        it { should be_false }
+        it { is_expected.to be_falsey }
       end
 
       context "when given a business day that is a holiday" do
         let(:day) { date_class.parse("9am, Tuesday 1st Jan, 2013") }
-        it { should be_false }
+        it { is_expected.to be_falsey }
       end
     end
 
@@ -112,18 +112,18 @@ describe Business::Calendar do
 
       context "given a business day" do
         let(:date) { date_class.parse("Wednesday 2nd Jan, 2013") }
-        it { should == date }
+        it { is_expected.to eq(date) }
       end
 
       context "given a non-business day" do
         context "with a business day following it" do
           let(:date) { date_class.parse("Tuesday 1st Jan, 2013") }
-          it { should == date + day_interval }
+          it { is_expected.to eq(date + day_interval) }
         end
 
         context "followed by another non-business day" do
           let(:date) { date_class.parse("Saturday 5th Jan, 2013") }
-          it { should == date + 2 * day_interval }
+          it { is_expected.to eq(date + 2 * day_interval) }
         end
       end
     end
@@ -136,18 +136,18 @@ describe Business::Calendar do
 
       context "given a business day" do
         let(:date) { date_class.parse("Wednesday 2nd Jan, 2013") }
-        it { should == date }
+        it { is_expected.to eq(date) }
       end
 
       context "given a non-business day" do
         context "with a business day preceeding it" do
           let(:date) { date_class.parse("Tuesday 1st Jan, 2013") }
-          it { should == date - day_interval }
+          it { is_expected.to eq(date - day_interval) }
         end
 
         context "preceeded by another non-business day" do
           let(:date) { date_class.parse("Sunday 6th Jan, 2013") }
-          it { should == date - 2 * day_interval }
+          it { is_expected.to eq(date - 2 * day_interval) }
         end
       end
     end
@@ -160,18 +160,18 @@ describe Business::Calendar do
 
       context "given a business day" do
         let(:date) { date_class.parse("Wednesday 2nd Jan, 2013") }
-        it { should == date + day_interval }
+        it { is_expected.to eq(date + day_interval) }
       end
 
       context "given a non-business day" do
         context "with a business day following it" do
           let(:date) { date_class.parse("Tuesday 1st Jan, 2013") }
-          it { should == date + day_interval }
+          it { is_expected.to eq(date + day_interval) }
         end
 
         context "followed by another non-business day" do
           let(:date) { date_class.parse("Saturday 5th Jan, 2013") }
-          it { should == date + 2 * day_interval }
+          it { is_expected.to eq(date + 2 * day_interval) }
         end
       end
     end
@@ -186,23 +186,23 @@ describe Business::Calendar do
       context "given a business day" do
         context "and a period that includes only business days" do
           let(:date) { date_class.parse("Wednesday 2nd Jan, 2013") }
-          it { should == date + delta * day_interval }
+          it { is_expected.to eq(date + delta * day_interval) }
         end
 
         context "and a period that includes a weekend" do
           let(:date) { date_class.parse("Friday 4th Jan, 2013") }
-          it { should == date + (delta + 2) * day_interval }
+          it { is_expected.to eq(date + (delta + 2) * day_interval) }
         end
 
         context "and a period that includes a holiday day" do
           let(:date) { date_class.parse("Monday 31st Dec, 2012") }
-          it { should == date + (delta + 1) * day_interval }
+          it { is_expected.to eq(date + (delta + 1) * day_interval) }
         end
       end
 
       context "given a non-business day" do
         let(:date) { date_class.parse("Tuesday 1st Jan, 2013") }
-        it { should == date + (delta + 1) * day_interval }
+        it { is_expected.to eq(date + (delta + 1) * day_interval) }
       end
     end
 
@@ -216,23 +216,23 @@ describe Business::Calendar do
       context "given a business day" do
         context "and a period that includes only business days" do
           let(:date) { date_class.parse("Wednesday 2nd Jan, 2013") }
-          it { should == date - delta * day_interval }
+          it { is_expected.to eq(date - delta * day_interval) }
         end
 
         context "and a period that includes a weekend" do
           let(:date) { date_class.parse("Monday 31st Dec, 2012") }
-          it { should == date - (delta + 2) * day_interval }
+          it { is_expected.to eq(date - (delta + 2) * day_interval) }
         end
 
         context "and a period that includes a holiday day" do
           let(:date) { date_class.parse("Friday 4th Jan, 2013") }
-          it { should == date - (delta + 1) * day_interval }
+          it { is_expected.to eq(date - (delta + 1) * day_interval) }
         end
       end
 
       context "given a non-business day" do
         let(:date) { date_class.parse("Thursday 3rd Jan, 2013") }
-        it { should == date - (delta + 1) * day_interval }
+        it { is_expected.to eq(date - (delta + 1) * day_interval) }
       end
     end
 
@@ -250,35 +250,35 @@ describe Business::Calendar do
         context "ending on a business day" do
           context "including only business days" do
             let(:date_2) { date_class.parse("Thu 5/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
 
           context "including only business days & weekend days" do
             let(:date_2) { date_class.parse("Mon 9/6/2014") }
-            it { should == 5 }
+            it { is_expected.to eq(5) }
           end
 
           context "including only business days & holidays" do
             let(:date_1) { date_class.parse("Mon 9/6/2014") }
             let(:date_2) { date_class.parse("Fri 13/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Fri 13/6/2014") }
-            it { should == 8 }
+            it { is_expected.to eq(8) }
           end
         end
 
         context "ending on a weekend day" do
           context "including only business days & weekend days" do
             let(:date_2) { date_class.parse("Sun 8/6/2014") }
-            it { should == 5 }
+            it { is_expected.to eq(5) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Sat 14/6/2014") }
-            it { should == 9 }
+            it { is_expected.to eq(9) }
           end
         end
 
@@ -286,12 +286,12 @@ describe Business::Calendar do
           context "including only business days & holidays" do
             let(:date_1) { date_class.parse("Mon 9/6/2014") }
             let(:date_2) { date_class.parse("Thu 12/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Thu 12/6/2014") }
-            it { should == 8 }
+            it { is_expected.to eq(8) }
           end
         end
       end
@@ -303,31 +303,31 @@ describe Business::Calendar do
 
           context "including only business days & weekend days" do
             let(:date_2) { date_class.parse("Mon 9/6/2014") }
-            it { should == 0 }
+            it { is_expected.to eq(0) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Fri 13/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
         end
 
         context "ending on a weekend day" do
           context "including only business days & weekend days" do
             let(:date_2) { date_class.parse("Sun 8/6/2014") }
-            it { should == 0 }
+            it { is_expected.to eq(0) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Sat 14/6/2014") }
-            it { should == 4 }
+            it { is_expected.to eq(4) }
           end
         end
 
         context "ending on a holiday" do
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Thu 12/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
         end
       end
@@ -339,19 +339,19 @@ describe Business::Calendar do
 
           context "including only business days & holidays" do
             let(:date_2) { date_class.parse("Fri 13/6/2014") }
-            it { should == 0 }
+            it { is_expected.to eq(0) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Thu 19/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
         end
 
         context "ending on a weekend day" do
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Sun 15/6/2014") }
-            it { should == 1 }
+            it { is_expected.to eq(1) }
           end
         end
 
@@ -359,12 +359,12 @@ describe Business::Calendar do
           context "including only business days & holidays" do
             let(:date_1) { date_class.parse("Wed 18/6/2014") }
             let(:date_2) { date_class.parse("Fri 20/6/2014") }
-            it { should == 1 }
+            it { is_expected.to eq(1) }
           end
 
           context "including business, weekend days, and holidays" do
             let(:date_2) { date_class.parse("Wed 18/6/2014") }
-            it { should == 3 }
+            it { is_expected.to eq(3) }
           end
         end
       end
@@ -373,12 +373,12 @@ describe Business::Calendar do
         context "for a range less than a week long" do
           let(:date_1) { date_class.parse("Thu 19/6/2014") }
           let(:date_2) { date_class.parse("Tue 24/6/2014") }
-          it { should == 2 }
+          it { is_expected.to eq(2) }
         end
         context "for a range more than a week long" do
           let(:date_1) { date_class.parse("Mon 16/6/2014") }
           let(:date_2) { date_class.parse("Tue 24/6/2014") }
-          it { should == 4 }
+          it { is_expected.to eq(4) }
         end
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: business
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Harry Marr
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 2.14.1
+        version: '3.0'
 description: Date calculations based on business calendars
 email:
 - engineering@gocardless.com
@@ -47,6 +47,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- LICENSE
 - README.md
 - business.gemspec
 - lib/business.rb
@@ -57,7 +58,8 @@ files:
 - lib/business/version.rb
 - spec/calendar_spec.rb
 homepage: https://github.com/gocardless/business
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []