plyushkin 0.0.5 → 0.0.6

data/.gitignore

@@ -1,4 +1,5 @@
 .bundle
 .DS_Store
 *.swp
+*.swo
 plyushkin*.gem

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm: 1.9.3
+script: bundle exec rake spec

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    plyushkin (0.0.4)
+    plyushkin (0.0.5)
       activerecord (~> 3.2.12)
 
 GEM

data/README.md

@@ -1,6 +1,9 @@
 # Plyushkin
 
-TODO: Write a gem description
+[![Code Climate](https://codeclimate.com/github/OnlifeHealth/plyushkin.png)](https://codeclimate.com/github/OnlifeHealth/plyushkin) [![Gem Version](https://badge.fury.io/rb/plyushkin.svg)](http://badge.fury.io/rb/plyushkin)
+[![Build Status](https://travis-ci.org/OnlifeHealth/plyushkin.png)](https://travis-ci.org/OnlifeHealth/plyushkin)
+
+Plyushkin provides a way to capture historical data in an ActiveRecord class.
 
 ## Installation
 
@@ -18,7 +21,7 @@ Or install it yourself as:
 
 ## Usage
 
-Configure the backend service that plyushkin will use in your environments/<environment>.rb file.  
+Configure the backend service that plyushkin will use in your environments/&lt;environment&gt;.rb file.  
 For example, to configure the stub service for running specs, the following code would go in your 
 config/environments/test.rb file of a Rails application.
 
@@ -27,20 +30,216 @@ config/environments/test.rb file of a Rails application.
     end
 
 To use plyushkin against a live web service,
-assign an instance of ``Plyushkin::Service::Web.new(:url => 'http://yourservice.com')``
+
+    config.before_initialize do |c|
+      Plyushkin::Service.service =
+        Plyushkin::Service::Web.new(:url => 'http://yourservice.com')
+    end
+
+## Quick start
+To add a property, use the `hoards` class macro on a class that inherits from ActiveRecord::Base.
+
+    class Vehicle < ActiveRecord::Base
+      hoards :mechanic
+    end
+    
+This will add a mechanic attribute to the Vehicle class. To set the mechanic for the vehicle
+
+    v = Vehicle.new
+    v.mechanic.create(:value => 'Mike')
+
+This will update the in-memory version of the vehicle, but has not yet persisted the change.  To
+save the change to the plyushkin-service
+
+    v.save
+
+To get the value of the vehicle's mechanic
+
+    v.mechanic.last.value  # => 'Mike'
+
+To get the date that the mechanic was last set
+
+    v.mechanic.last.date   # => Wed, 09 Jul 2014 11:52:12 -0500
+
+Every Plyushkin value has a `date` attribute.
+
+Once we change the mechanic on the vehicle, we will now have historical data and can view all the
+mechanics that worked on the vehicle.
+
+    v.mechanic.create(:value => 'Joe')
+    v.mechanic.all.map(&:value) # => ['Mike', 'Joe']
+
+#### Setting past values
+
+To store a property using a DateTime other than the current time
+
+    v.mechanic.create(:value => 'Sally', :date => 3.days.ago)
+    v.mechanic.last.date # => Sun, 06 Jul 2014 11:52:12 -0500
+
+#### Value types
+
+In the example above, we needed to use `last` and `all` methods to see the mechanic.  This is
+because the property getter returns a `Plyushkin::Property`.  A property consists of
+instances of classes that derive from `Plyushkin::BaseValue`.
+
+`Plyushkin::BaseValue` provides basic value functionality.  It provides a `date` attribute, that is
+required for all Plyushkin values.  And, it provides four formatters, `to_i`, `to_f`,
+`to_date` and `to_bool`.
+
+When not specifying a value type when calling `hoards`, Plyushkin will use a 
+`Plyushkin::StringValue` as the value type.  In addition to the base implementation, this basic
+implementation includes one attribute, `value`, which uses no formatter.
+
+In most applications, you will not want to use `Plyushkin::StringValue`, and instead would want
+to create your own value type implementation that derives from `Plyushkin::BaseValue` and use custom
+value types.
+
+##### Creating a custom value type
+
+In our vehicle example, if we wanted to capture oil change history, we would start by creating a
+custom value type.
+
+    class OilChangeValue < Plyushkin::BaseValue
+      persisted_attr :mileage, :formatter => :to_i
+      persisted_attr :oil_type
+    end
+
+The `OilChangeValue` will have a mileage attribute that uses the `to_i` formatter.  Formatters attempt to
+convert the attribute assignment to a specified format.  If no formatter is provided, the attribute will be
+stored as a string.
+
+We can now add this to our vehicle
+
+    class Vehicle < ActiveRecord::Base
+      hoards :mechanic
+      hoards :oil_change, :type => OilChangeValue
+    end
+
+To set the oil_change
+
+    v.oil_change.create(:mileage => '1234', :oil_type => '10W30')
+
+To get the latest oil change details
+
+    v.oil_change.last.mileage  # => 1234
+    v.oil_change.last.oil_type # => '10W30'
+
+##### Specifiying a callback after a value is stored
+
+When defining a hoards property, you can set a callback for after the value is persisted.  For example,
+if the vehicle table contains a `next_oil_change_mileage` column, we might want to update it whenever
+an oil_change is saved.  
+
+    class Vehicle < ActiveRecord::Base
+      hoards :oil_change, :type => OilChangeValue,
+             :after_create => :calculate_next_oil_change_mileage
+
+      def calculate_next_oil_change_mileage
+        next_oil_change_mileage = oil_change.last.mileage + 3000
+      end
+    end
+
+##### Ignoring unchanged values
+
+There may be a case where we don't need to track history when a value is set, but is the same as the
+previous value.  For example, if the mechanic for your last maintenance is Mike and Mike again
+performs the maintenance, we don't need two data points recorded.
+
+In the current configuration, calling create twice would create two values
+    
+    v.mechanic.create(:value => 'Joe')
+    v.mechanic.create(:value => 'Mike')
+    v.mechanic.create(:value => 'Mike')
+    v.mechanic.all.map(&:value) # => [ 'Joe', 'Mike', 'Mike' ]
+
+By setting the `:ignore_unchanged_values` option, we can change this behavior.
+
+    class Vehicle < ActiveRecord::Base
+      hoards :mechanic, :ignore_unchanged_values => true
+    end
+
+    v.mechanic.create(:value => 'Joe')
+    v.mechanic.create(:value => 'Mike')
+    v.mechanic.create(:value => 'Mike')
+    v.mechanic.all.map(&:value) # => [ 'Joe', 'Mike' ]
+
+In this example, the date of the last value will be the date that `mechanic` was first assigned 'Mike'.
+
+###### Validation
+
+Validation is done with `ActiveModel::Validations`.  This is included in `Plyushkin::BaseValue`.
+
+    class OilChangeValue < Plyushkin::BaseValue
+      persisted_attr :oil_type
+      persisted_attr :mileage
+
+      validates :oil_type, :inclusion    => { :in => ['10W30', '5W40'] }
+      validates :mileage,  :numericality => { :only_integer             => true,
+                                              :greater_than_or_equal_to => 0 }
+    end
+
+###### Adding behavior
+
+`Plyushkin::BaseValue` and it's subclasses are classes and additional behavior can be added to 
+encapsulate functionality.
+
+    class OilChange < Plyushkin::BaseValue
+      persisted_attr :mileage
+
+      def mileage_as_km
+        mileage / 0.6214
+      end
+    end
+
+    v.oil_change.create(:mileage => 10000)
+    v.oil_change.last.mileage       # => 10000
+    v.oil_change.last.mileage_as_km # => 6214
+
+##### Accessing a property that has not had any values assigned
+
+`Plyushkin::NilValue` is a special case used when no value has been assigned to a property yet.
+
+    v = Vehicle.new
+    v.mechanic.last            # => Plyushkin::NilValue
+    v.mechanic.last.value      # => nil
+    v.oil_change.last          # => Plyushkin::NilValue
+    v.oil_change.last.mileage  # => nil
+    v.oil_change.last.oil_type # => nil
+
+This is necessary so that consumers of the property do not need to check if a value is nil before trying
+to access an attribute of the value.
+
+In addition, `Plyushkin::Property` has a property `empty?` to indicate whether any values have been assigned
+
+    v.mechanic.empty?   # => true
+    v.oil_change.empty? # => true
 
 ## Testing
 
 Plyushkin provides RSpec matchers for testing class macros.  To use these matchers, 
-add ``config.include Plyushkin::Test::Matchers`` to your RSpec.configure in spec_helper.
+add `config.include Plyushkin::Test::Matchers` to your RSpec.configure in spec_helper.
+
+#### Testing custom value types
+To test Plyushkin configuration in your custom value type:
+
+    describe OilChangeValue do
+      it { should persist_attribute(:mileage) }
+      it { should persist_attribute(:mileage).with_format(:to_i) }
+      it { should_not persist_attribute(:air_filter) }
+      it { should persist_attribute(:oil_type) }
+      it { should_not persist_attribute(:oil_type).with_format(:to_f) }
+
+      # RSpec Shoulda matchers also work to test validations here.
+    end
 
 To test Plyushkin configuration in your model:
 
-    describe YourModel do
-      it { should persist_attribute(:your_attribute) }
-      it { should_not persist_attribute(:your_non_plyushkin_attribute) }
-      it { should persist_attribute(:your_attribute).with_format(:to_date) }
-      it { should_not persist_attribute(:your_attribute).with_format(:not_a_formatter) }
+    describe Vehicle do
+      it { should hoard(:mechanic) }
+      it { should hoard(:mechanic).and_ignore_unchanged_values }
+      it { should hoard(:oil_change).of_type(OilChangeValue) }
+      it { should hoard(:oil_change).of_type(OilChangeValue).
+        and_after_create_call(:calculate_next_oil_change_mileage) }
     end
 
 ## Contributing

data/Rakefile

@@ -1 +1,6 @@
 require "bundler/gem_tasks"
+
+desc "Run rspec spec for those accustomed to the rake task"
+task :spec do
+  sh 'rspec spec'
+end

data/lib/plyushkin/base_value.rb

@@ -93,8 +93,8 @@ class Plyushkin::BaseValue
   end
 
   def to_bool(value)
-    return true if value == "true"
-    return false if value == "false"
+    return true if [1, "1", "true"].include?(value)
+    return false if [0, "0", "false"].include?(value)
     return value
   end
 

data/lib/plyushkin/cache.rb

@@ -11,4 +11,5 @@ module Plyushkin::Cache
 end
 
 require File.dirname(File.expand_path(__FILE__)) + "/cache/stub"
+require File.dirname(File.expand_path(__FILE__)) + "/cache/null"
 require File.dirname(File.expand_path(__FILE__)) + "/cache/rails_cache"

data/lib/plyushkin/cache/null.rb

@@ -0,0 +1,10 @@
+class Plyushkin::Cache::Null
+  def write(key, value)
+  end
+
+  def read(key)
+  end
+
+  def clear
+  end
+end

data/lib/plyushkin/property.rb

@@ -73,14 +73,16 @@ class Plyushkin::Property
   end
 
   def value_hashes
-    value_hashes = {}
+    all_value_hashes = []
     all.each do |value|
+      value_hash = {}
       value_type.persisted_attributes.each do |attr|
-        value_hashes[attr] = value.send(attr) 
+        value_hash[attr] = value.send(attr) 
       end
+      all_value_hashes << value_hash
     end
 
-    value_hashes == {} ? [] : [value_hashes]
+    all_value_hashes 
   end
 
   def nil?

data/lib/plyushkin/test/value_types.rb

@@ -26,4 +26,7 @@ module Plyushkin::Test
     persisted_attr :value, :formatter => :to_date
   end
 
+  class Plyushkin::Test::ComplexModel < ActiveRecord::Base
+    hoards :coordinate, :type => Plyushkin::Test::CoordinateValue
+  end
 end

data/lib/plyushkin/version.rb

@@ -1,3 +1,3 @@
 module Plyushkin
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/spec/lib/base_value_spec.rb

@@ -172,11 +172,27 @@ describe Plyushkin::BaseValue do
 
     describe '#to_bool' do
       it 'should return true if string true is passed in' do
-        Plyushkin::BaseValue.new.to_bool("true").should be_true
+        Plyushkin::BaseValue.new.to_bool("true").should == true
+      end
+
+      it 'should return true if "1" is passed in' do
+        Plyushkin::BaseValue.new.to_bool("1").should == true
+      end
+
+      it 'should return false if "0" is passed in' do
+        Plyushkin::BaseValue.new.to_bool("0").should == false
+      end
+
+      it 'should return true if 1 is passed in' do
+        Plyushkin::BaseValue.new.to_bool(1).should == true
+      end
+
+      it 'should return false if 0 is passed in' do
+        Plyushkin::BaseValue.new.to_bool(0).should == false
       end
 
       it 'should return false if string false is passed in' do
-        Plyushkin::BaseValue.new.to_bool("false").should be_false
+        Plyushkin::BaseValue.new.to_bool("false").should == false
       end
 
       it 'should return nil if nil is passed in' do

data/spec/lib/persistence_spec.rb

@@ -43,6 +43,13 @@ describe Plyushkin::Persistence do
       service.get("widget", 1)["name"].last["value"].should == "Mike"
     end
 
+    it 'should save multiple new values of the same property' do
+      persistence.properties[:name].create(:value => 'Bob')
+      persistence.save(1)
+      persistence.load(1)
+      persistence.properties[:name].all.length.should == 2
+    end
+
     it 'should mark all properties as persisted' do
       persistence.properties[:name].create(:value => "Mike")
       persistence.properties[:weight].create(:value => "150")

data/spec/lib/property_spec.rb

@@ -227,13 +227,46 @@ describe Plyushkin::Property do
     end
   end
 
-  it '#insert_position' do
-    property = Plyushkin::Property.new(:property_name)
-    value1 = property.create(:value => 7, :date => DateTime.now - 7.days)
-    value2 = property.create(:value => 5, :date => DateTime.now - 5.days)
-    property.insert_position(DateTime.now).should == 2
-    property.insert_position(DateTime.now - 6.days).should == 1
-    property.insert_position(DateTime.now - 8.days).should == 0
+  describe '#insert_position' do
+    it 'should get position in date order' do
+      property = Plyushkin::Property.new(:property_name)
+      value1 = property.create(:value => 7, :date => DateTime.now - 7.days)
+      value2 = property.create(:value => 5, :date => DateTime.now - 5.days)
+      property.insert_position(DateTime.now).should == 2
+      property.insert_position(DateTime.now - 6.days).should == 1
+      property.insert_position(DateTime.now - 8.days).should == 0
+    end
+  end
+
+  describe '#value_hashes' do
+    let(:property) { Plyushkin::Property.new(:property_name) }
+
+    it 'should include all values as hashes in an array' do
+
+      p1 = property.create(:value => 1)
+      p2 = property.create(:value => 2)
+      property.value_hashes.should == [
+        { :date => p1.date, :value => 1 },
+        { :date => p2.date, :value => 2 }
+      ]
+    end
+
+    it 'should include all attributes in value hash' do
+      property = Plyushkin::Property.new(:property_name, :type => Plyushkin::Test::CoordinateValue)
+
+      c1 = property.create(:x => 5,  :y => 10)
+      c2 = property.create(:x => 15, :y => 20)
+      property.value_hashes.should == [
+        { :date => c1.date, :x => 5,  :y => 10 },
+        { :date => c2.date, :x => 15, :y => 20 }
+      ]
+
+    end
+
+    it 'should be an empty array if no values are set' do
+      property.value_hashes.should == []
+    end
+
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: plyushkin
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-19 00:00:00.000000000 Z
+date: 2014-07-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -70,6 +70,7 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .rspec
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -78,6 +79,7 @@ files:
 - lib/plyushkin.rb
 - lib/plyushkin/base_value.rb
 - lib/plyushkin/cache.rb
+- lib/plyushkin/cache/null.rb
 - lib/plyushkin/cache/rails_cache.rb
 - lib/plyushkin/cache/stub.rb
 - lib/plyushkin/core_ext/active_record_base.rb