periodical 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fec77aa23c72fb853689f5157e26f7f99e1d9cc
-  data.tar.gz: 9121f8a1b764ca0800904cee8fabc878298df225
+  metadata.gz: da0ceda3373a9c1cf5e18751ce263b9b0b476c16
+  data.tar.gz: 7d22d18c11b786f1bda8196d845f9d02d50e92da
 SHA512:
-  metadata.gz: d4a1cfc15f47f1c6f6db749bd988ae65d2bd88927e7af67e5588787765ab64f99f28add125f8cadd1ff4dac1bc9961137023098d1f0824389d1f40dfb6068f15
-  data.tar.gz: 5a3035e609a4abb6613ac897a282d088b3eaa571c671ab227e722c4eb85d46b2dbc88055797f82b79cfcf4ac39da7f316a5e3a6037b36f314b6f47b3a30bf56a
+  metadata.gz: 119d9eb7004ff7edf05efb77f27f9623ec812a1d9537d58736eeac68e3e648e7ab316f73739686e0f874aa36429fcae6f29ce038add39e8d15ebd2e253c68644
+  data.tar.gz: 1aadd82add21e3eb8f2c482a71d46bed39c1297e4b406e1ee604bc358ae2a362003e64bbbbe9e22cfcf2d4243c364525bf5d5a935b52e38bc300d722bd1a28d5

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format documentation
+--backtrace
+--warnings

data/.simplecov

@@ -0,0 +1,9 @@
+
+SimpleCov.start do
+	add_filter "/spec/"
+end
+
+if ENV['TRAVIS']
+	require 'coveralls'
+	Coveralls.wear!
+end

data/.travis.yml

@@ -1,7 +1,12 @@
 language: ruby
+sudo: false
 rvm:
-  - "2.0"
-  - "2.1"
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
+  - ruby-head
+  - rbx-2
+env: COVERAGE=true
 matrix:
   allow_failures:
-    - rvm: "1.9"
+    - rvm: "rbx-2"

data/Gemfile

@@ -1,4 +1,7 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in periodical.gemspec
 gemspec
+
+group :test do
+	gem 'coveralls', platforms: [:mri]
+end

data/README.md

@@ -2,19 +2,29 @@
 
 Periodical is a simple framework for working with durations and periods. A duration measures a range of time bounded by a `from` date and `to` date. A period is a relative unit of time such as `4 weeks`.
 
+[![Build Status](https://travis-ci.org/ioquatix/periodical.svg)](https://travis-ci.org/ioquatix/periodical)
+[![Code Climate](https://codeclimate.com/github/ioquatix/periodical.svg)](https://codeclimate.com/github/ioquatix/periodical)
+[![Coverage Status](https://coveralls.io/repos/ioquatix/periodical/badge.svg)](https://coveralls.io/r/ioquatix/periodical)
+
+## Motivation
+
+The original idea for this library came from a [Python script which performed backup rotation](http://www.scottlu.com/Content/Snapfilter.html) from 2009. In particular, I thought it had a novel way to retain backups according to a given policy (e.g. one backup every year for 10 years, one backup every month for 12 months, one backup every week for 8 weeks, one backup every day for 30 days). This is done by constructing a special slot based hash structure with keys based on the date being stored. This functionality is used by [LSync](https://github.com/ioquatix/LSync) for performing backup rotation (i.e. deleting old backups).
+
+In addition, I had a need to implement periodical billing in [Financier](https://github.com/ioquatix/financier). Not only can this gem advance a date by a given period, it can compute the number of periods between two dates. This is useful for invoicing, say, once every 6 months for a weekly or monthly service.
+
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'periodical'
+	gem 'periodical'
 
 And then execute:
 
-    $ bundle
+	$ bundle
 
 Or install it yourself as:
 
-    $ gem install periodical
+	$ gem install periodical
 
 ## Usage
 
@@ -41,7 +51,7 @@ The main use case for this framework involves periodic billing or accounting (e.
 
 Released under the MIT license.
 
-Copyright, 2010, 2014, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
+Copyright, 2010, 2014, 2016, by [Samuel G. D. Williams](http://www.codeotaku.com/samuel-williams).
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Rakefile

@@ -1,6 +1,14 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+RSpec::Core::RakeTask.new(:spec) do |task|
+	if ENV['COVERAGE']
+		begin
+			require('simplecov/version')
+			task.rspec_opts = %w{--require simplecov}
+		rescue LoadError
+		end
+	end
+end
 
 task :default => :spec

data/lib/periodical/duration.rb

@@ -21,17 +21,9 @@
 require 'date'
 
 module Periodical
-	class Duration
-		def initialize(from, to)
-			@from = from
-			@to = to
-		end
-		
-		attr :from
-		attr :to
-		
+	Duration = Struct.new(:from, :to) do
 		def days
-			@to - @from
+			to - from
 		end
 		
 		def weeks
@@ -39,29 +31,29 @@ module Periodical
 		end
 		
 		def whole_months
-			(@to.year * 12 + @to.month) - (@from.year * 12 + @from.month)
+			(to.year * 12 + to.month) - (from.year * 12 + from.month)
 		end
 		
 		def months
 			whole = self.whole_months
 			
-			partial_start = @from >> whole
-			partial_end = @from >> whole + 1
+			partial_start = from >> whole
+			partial_end = from >> whole + 1
 			
-			return whole + (@to - partial_start) / (partial_end - partial_start)
+			return whole + (to - partial_start) / (partial_end - partial_start)
 		end
 		
 		def whole_years
-			@to.year - @from.year
+			to.year - from.year
 		end
 		
 		def years
 			whole = self.whole_years
 			
-			partial_start = @from >> (whole * 12)
-			partial_end = @from >> ((whole + 1) * 12)
+			partial_start = from >> (whole * 12)
+			partial_end = from >> ((whole + 1) * 12)
 			
-			return whole + (@to - partial_start) / (partial_end - partial_start)
+			return whole + (to - partial_start) / (partial_end - partial_start)
 		end
 		
 		# Calculate the number of periods between from and to

data/lib/periodical/filter.rb

@@ -57,7 +57,7 @@ module Periodical
 			end
 
 			def key(t)
-				raise ArgumentError
+				raise NotImplementedError
 			end
 
 			def mktime(year, month=1, day=1, hour=0, minute=0, second=0)

data/lib/periodical/period.rb

@@ -19,83 +19,70 @@
 # THE SOFTWARE.
 
 module Periodical
-	class Period
-		VALID_UNITS = [:days, :weeks, :months, :years]
+	Period = Struct.new(:count, :unit) do
+		VALID_UNITS = [:days, :weeks, :months, :years].freeze
 		
-		# Accepts strings in the format of "2 weeks" or "weeks"
-		def self.parse(value)
-			if Array === value
-				parts = value
-			else
-				parts = value.to_s.split(/\s+/, 2)
-			end
-			
-			if parts.size == 1
-				if parts[0].to_i == 0
-					count = 1
-					unit = parts[0].to_sym
-				else
-					count = parts[0].to_i
-					unit = :days
-					
-					if count == 7
-						count = 1
-						unit = :weeks
-					end
-					
-					if count == 365
-						count = 1
-						unit = :years
-					end
-				end
+		# Plural is preferred, as in "1 or more days".
+		def initialize(count = 1, unit = :days)
+			super(count, unit)
+		end
+		
+		def to_s
+			if self.count != 1
+				"#{self.count} #{self.unit}"
 			else
-				count = parts[0].to_i
-				unit = parts[1].gsub(/\s+/, '_').downcase.to_sym
+				self.unit.to_s
 			end
-			
-			unless VALID_UNITS.include? unit
-				raise ArgumentError.new("Invalid unit specified #{unit}!")
-			end
-			
-			if count == 0
-				raise ArgumentError.new("Count must be non-zero!")
-			end
-			
-			return self.new(count, unit)
 		end
 		
-		def initialize(count = 1, unit = :days)
-			@count = count
-			@unit = unit
+		def advance(date, multiple = 1)
+			self.send("advance_#{unit}", date, multiple * self.count)
 		end
 		
-		def to_s
-			"#{@count} #{@unit}"
+		private
+		
+		def advance_days(date, count)
+			date + count
 		end
 		
-		def to_formatted_s
-			if @count == 1
-				@unit.to_s.gsub(/s$/, '')
-			else
-				to_s
-			end
+		def advance_weeks(date, count)
+			date + (7 * count)
 		end
 		
-		def advance(date, multiple = 1)
-			total = multiple * @count
+		def advance_months(date, count)
+			date >> count
+		end
+		
+		def advance_years(date, count)
+			date >> (12 * count)
+		end
+		
+		class << self
+			# Accepts strings in the format of "2 weeks" or "weeks"
+			def parse(string)
+				parts = string.split(/\s+/, 2)
+				
+				if parts.size == 1
+					count = 1
+					unit = parts[0]
+				else
+					count, unit = parts
+				end
+				
+				self.new(count.to_i, unit.to_sym)
+			end
 			
-			if unit == :days
-				date + total
-			elsif unit == :weeks
-				date + (total * 7)
-			elsif unit == :months
-				date >> total
-			elsif unit == :years
-				date >> (total * 12)
+			def load(string)
+				if string
+					string = string.strip
+					
+					parse(string) unless string.empty?
+				end
+			end
+			
+			def dump(period)
+				period.to_s if period
 			end
 		end
-		
-		attr :unit
-		attr :count
 	end
 end

data/lib/periodical/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Periodical
-	VERSION = "0.2.0"
+	VERSION = "1.0.0"
 end

data/periodical.gemspec

@@ -19,6 +19,6 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = '>= 2.0'
 	
 	spec.add_development_dependency "bundler", "~> 1.3"
-	spec.add_development_dependency "rspec", "~> 3.0.0"
+	spec.add_development_dependency "rspec", "~> 3.4.0"
 	spec.add_development_dependency "rake"
 end

data/spec/periodical/period_spec.rb

@@ -29,5 +29,36 @@ module Periodical::PeriodSpec
 			
 			expect(period.advance(duration.from, 12)).to be == duration.to
 		end
+		
+		it "should parse a singular period" do
+			period = Periodical::Period.parse("years")
+			
+			expect(period.count).to be == 1
+			expect(period.unit).to be == :years
+		end
+		
+		it "should parse a multiple count period" do
+			period = Periodical::Period.parse("5 days")
+			
+			expect(period.count).to be == 5
+			expect(period.unit).to be == :days
+		end
+		
+		it "can load nil" do
+			expect(Periodical::Period.load(nil)).to be == nil
+			expect(Periodical::Period.load("")).to be == nil
+		end
+		
+		it "can dump nil" do
+			expect(Periodical::Period.dump(nil)).to be == nil
+		end
+		
+		it "can load string" do
+			expect(Periodical::Period.load("5 weeks")).to be == Periodical::Period.new(5, :weeks)
+		end
+		
+		it "can dump nil" do
+			expect(Periodical::Period.dump(Periodical::Period.new(5, :weeks))).to be == "5 weeks"
+		end
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: periodical
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-19 00:00:00.000000000 Z
+date: 2016-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.4.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.4.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -59,6 +59,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
+- ".simplecov"
 - ".travis.yml"
 - Gemfile
 - README.md
@@ -92,7 +94,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Periodical is a simple framework for working with durations and periods.