hystorical 0.0.1.alpha

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hystorical.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Joel Quenneville
+
+MIT License
+
+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

@@ -0,0 +1,100 @@
+# Hystorical
+
+Hystorical is a simple solution for managing explicit historical datasets. Provided that your records have a `start_date` and `end_date`, Hystorical will take care figuring which records are currently active, which were active during a particular date range and managing the archiving of records. It makes the following assumptions:
+
+* Objects in the collection have `start_date` and `end_date` attributes
+* `start_date` and `end_date` return a ruby `Date` object
+* the start and end dates can be accessed via either `[]` method or the `.` operator
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hystorical'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hystorical
+
+## Usage
+
+### current
+Hystorical returns the current object which is determined as those with `nil` end_date
+```ruby
+Hystorical.current(@subscriptions)
+# => returns enumerable collection of objects
+```
+
+### current_on
+
+Hystorical allows you to find which objects were current at a particular point in time.
+
+```ruby
+date = Date.new(2012, 01, 10)
+Hystorical.current_on(@subscriptions, date)
+# => returns enumerable collection of objects that were current on January 10th
+```
+
+
+## Examples
+
+### Pure Ruby
+
+```ruby
+Subscription = Struct.new(:start_date, :end_date)
+subscriptions = # collection of several Subscription objects
+
+Hystorical.current(subscriptions)
+# => returns enumerable collection of objects
+
+date = Date.new(2012, 01, 10)
+Hystorical.current_on(subscriptions, date)
+# => returns enumerable collection of objects that were current on January 10th
+```
+
+### Using Rails
+
+Hystorical accepts ActiveRecord::Relation collections. This means that all your scopes integrate fully with Hystorical.
+
+In a model
+```ruby
+class Subscription < ActiveRecord::Base
+  attr_accessible :user_id, :start_date, :end_date
+
+  def self.for_user(user_id)
+    where user_id: user_id
+  end
+
+  def self.user_subscription_count_on(user_id, date)
+    subscriptions = Subscription.for_user(user_id)
+    Hystorical.current subscriptions, date
+  end
+
+end
+```
+
+In a controller
+```ruby
+def index
+  @users_current_subscriptions = Hystorical.current Subscription.for_user(params[:user_id])
+end
+```
+
+## Philosophy
+This gem was created using TDD and README-driven development. The architecture was designed with a strong focus on modularity and extensibility. Using ruby's `Enumerable` methods to return current object was chosen because of it's great flexibility to adapt to all ruby projects. However, when working with large datasets stored in a relational database, using SQL would yield greater performance. Adding an adapter for ActiveRecord or any other ORM (such as DataMapper or Mongoid) is as simple as creating a new class that defines all the methods in the public api and adding a conditional in `Hystorical.delegate_class`.
+
+## TODO
+ * Add ability to search via SQL when passed `ActiveRecord::Relation`
+ * Add ability to pass in a block option that can further filter results
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/hystorical.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/hystorical', __FILE__)
+require File.expand_path('../lib/ruby_hystorical', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Joel Quenneville"]
+  gem.email         = ["joel.quen@gmail.com"]
+  gem.description   = %q{Hystorical is a simple solution for managing explicit historical datasets}
+  gem.summary       = %q{Hystorical is a simple solution for managing explicit historical datasets}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "hystorical"
+  gem.require_paths = ["lib"]
+  gem.version       = Hystorical::VERSION
+
+  gem.add_development_dependency "rspec"
+end

data/lib/hystorical.rb

@@ -0,0 +1,17 @@
+class Hystorical
+
+  VERSION = "0.0.1.alpha"
+  
+  def self.delegate_class
+    RubyHystorical
+    # add conditional to determine which subclass to use once other strategies are used (i.e. ActiveRecord)
+  end
+
+  def self.current(collection)
+    delegate_class.current(collection)
+  end
+
+  def self.current_on(collection, date)
+    delegate_class.current_on(collection, date)
+  end
+end

data/lib/ruby_hystorical.rb

@@ -0,0 +1,16 @@
+class RubyHystorical
+
+  def self.current(collection)
+    collection.select { |obj| obj.respond_to?(:[]) ? obj[:end_date].nil? : obj.end_date.nil? }
+  end
+
+  def self.current_on(collection, date)
+    collection.select do |obj|
+      if obj.respond_to?(:[])
+        obj[:start_date] <= date && obj[:end_date] >= date
+      else
+        obj.start_date <= date && obj.end_date >= date
+      end
+    end
+  end
+end

data/spec/hystorical_spec.rb

@@ -0,0 +1,25 @@
+describe Hystorical do
+
+  describe ".delegate_class" do
+    it "should return RubyHystorical" do
+      Hystorical.delegate_class.should be RubyHystorical
+    end
+  end
+
+  let(:collection) { stub }
+  before { Hystorical.stub(:delegate_class).and_return(RubyHystorical) }
+  describe ".current" do
+    it "send current message to delegate class" do
+      RubyHystorical.should_receive(:current).with(collection)
+      Hystorical.current(collection)
+    end
+  end
+
+  describe ".current_on" do
+    it "send current_on message to delegate class" do
+      date = stub
+      RubyHystorical.should_receive(:current_on).with(collection, date)
+      Hystorical.current_on(collection, date)
+    end
+  end
+end

data/spec/ruby_hystorical_spec.rb

@@ -0,0 +1,51 @@
+describe RubyHystorical do
+  class HistoricalObjet
+    attr_accessor :start_date, :end_date
+
+    def initialize(start_date, end_date)
+      @start_date = start_date
+      @end_date = end_date
+    end
+  end
+
+  let(:obj1) { {start_date: Date.new(2012, 8, 15), end_date: Date.new(2012, 8, 26)} }
+  let(:obj2) { {start_date: Date.new(2012, 8, 27), end_date: Date.new(2012, 9, 4)} }
+  let(:obj3) { {start_date: Date.new(2012, 9, 5), end_date: nil} }
+  let(:collection) { [obj1, obj2, obj3] }
+
+
+  let(:obj4) { HistoricalObjet.new(Date.new(2012, 8, 15), Date.new(2012, 8, 26)) }
+  let(:obj5) { HistoricalObjet.new(Date.new(2012, 8, 27), Date.new(2012, 9, 4)) }
+  let(:obj6) { HistoricalObjet.new(Date.new(2012, 9, 5), nil) }
+  let(:collection2) { [obj4, obj5, obj6] }
+
+  describe ".current" do
+    context "when attributes are accessed via []" do
+      it "should return the current object" do
+        RubyHystorical.current(collection).should eq [obj3]
+      end
+    end
+
+    context "when attributes are accessed via ." do
+      it "should return the current object" do
+        RubyHystorical.current(collection2).should eq [obj6]
+      end
+    end
+  end
+
+  describe ".current_on" do
+    let(:date) { Date.new(2012, 9, 1) }
+
+    context "when attributes are accessed via []" do
+      it "should return the current object" do
+        RubyHystorical.current_on(collection, date).should eq [obj2]
+      end
+    end
+
+    context "when attributes are accessed via ." do
+      it "should return the current object" do
+        RubyHystorical.current_on(collection2, date).should eq [obj5]
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require "hystorical"
+require "ruby_hystorical"

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: hystorical
+version: !ruby/object:Gem::Version
+  version: 0.0.1.alpha
+  prerelease: 6
+platform: ruby
+authors:
+- Joel Quenneville
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-09-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Hystorical is a simple solution for managing explicit historical datasets
+email:
+- joel.quen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- hystorical.gemspec
+- lib/hystorical.rb
+- lib/ruby_hystorical.rb
+- spec/hystorical_spec.rb
+- spec/ruby_hystorical_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Hystorical is a simple solution for managing explicit historical datasets
+test_files:
+- spec/hystorical_spec.rb
+- spec/ruby_hystorical_spec.rb
+- spec/spec_helper.rb