immutability 0.0.1 → 0.0.2

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YTQ3MDdmODU2NDZkZmYxMzJjY2E2OTExYTAzMmRlNzY1NmU5NmU4Mw==
-  data.tar.gz: !binary |-
-    MTc4MTk4OGVkOWY5NmQzMTNjNGRlMGRmMzk1ZTQwNzdmYzI5MjhhMQ==
+SHA1:
+  metadata.gz: 6d2abac3eae8fc1483402fc718dd899c83c929b1
+  data.tar.gz: 6dc9066776003a52641d4f2f0fbefd2a75363628
 SHA512:
-  metadata.gz: !binary |-
-    Yzc0NTMyOTM1MmY4ZTllOTMyZmE0N2QzOGFhNzg1YjBiZTE2ZmE1ZGQ4OWU1
-    N2QzMzVmZjQ2NWU0YzUzYmU1YTU3MTM1ZDE3OTU3OTg0NzhlZDIwYTAyN2Yx
-    NWU4NzM0ZjI5YWQ5MTRkOWIyOGY2MWM5Y2UxZDliZDE2ZWJkYTE=
-  data.tar.gz: !binary |-
-    ODg1NDUxY2UzM2VhOGE0M2E2NDQ0ZjlmMzk4NTRiMmM2NzgxN2RjMGM3MTIw
-    MjdlY2Q4M2NlYzZkMzU5NzE3MzE3MTFmMWYzNWNkNzcxNTEyMjc5ZmUwM2I4
-    YjM0NmZhODQ3ODA1MDk3MDczYzBjNTQ4ZDRkYzRmMWVmYzFjNDM=
+  metadata.gz: 8639bcd519dc339e392c5fc1b0614aeec9a9008a3457cba1c7adb8b24b0e918d3b4c669193b34a74ee945bbf7293869f58def5cb09c2b0530812f1660b6902aa
+  data.tar.gz: 4f4e84e41a2933701d3858a3d6293c2b8a74e7e7fc208247c02f67b2d98a2155e1b1db5566801627e98515c203129fd3fe04aca8066e3f92c39051e168daac43

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## v0.0.2 2015-09-24
+
+The version fixes some bugs and adds `#at` method fild past states of objects with memory.
+
+### Added
+
+- New decorator `Immutabitlity::Object` to iterate via past states of instance (nepalez)
+- New method `Imutability::WithMemory#at` to return a state in the past (nepalez)
+- Allow block to be send to initializer (nepalez)
+
+### Bugs fixed
+
+- Bug in rspec matcher `be_immutable` under rbx (nepalez)
+
+[Compare v0.0.1...v0.0.2](https://github.com/nepalez/immutability/compare/v0.0.1...v0.0.2)
+
 ## v0.0.1 2015-09-20
 
 First public release.

data/README.md

@@ -108,6 +108,25 @@ elder_andrew.version # => 1
 elder_andrew.parent.equal? young_andrew # => true
 ```
 
+You can check the previous state of the object using method `#at`:
+
+```ruby
+# relative from the current version
+elder_andrew.at(-2) == nil          # => true
+elder_andrew.at(-1) == young_andrew # => true
+
+# at some version in the past
+elder_andrew.at(0)  == young_andrew # => true
+elder_andrew.at(1)  == elder_andrew # => true
+elder_andrew.at(2)  == nil          # => true
+```
+
+This can be used to check whether two instances has a [cenancestor][cenancestor]:
+
+```ruby
+elder_andrew.at(0) == young_andrew.at(0) # => true
+```
+
 Notice, than no instances in the sequence can be garbage collected (they still refer to each other).
 
 Use `#forget_history` methods to reset version and free old instances for GC:
@@ -187,6 +206,7 @@ See the [MIT LICENSE](LICENSE).
 
 [are_we_there_yet]: http://www.infoq.com/presentations/Are-We-There-Yet-Rich-Hickey
 [aversion]: https://github.com/txus/aversion
+[cenancestor]: https://en.wikipedia.org/wiki/Last_universal_ancestor
 [codeclimate]: https://codeclimate.com/github/nepalez/immutability
 [coveralls]: https://coveralls.io/r/nepalez/immutability
 [gem]: https://rubygems.org/gems/immutability

data/Rakefile

@@ -22,12 +22,13 @@ end
 
 desc "Runs mutation metric for testing"
 task :mutant do
-  system "mutant -r immutability --use rspec Immutability* --fail-fast"
+  system "MUTANT=true mutant -r immutability --use rspec Immutability*" \
+         " --fail-fast"
 end
 
 desc "Exhort all evils"
 task :exhort do
-  system "mutant -r immutability --use rspec Immutability*"
+  system "MUTANT=true mutant -r immutability --use rspec Immutability*"
 end
 
 desc "Runs all the necessary metrics before making a commit"

data/lib/immutability.rb

@@ -2,6 +2,7 @@
 
 require "ice_nine"
 
+require_relative "immutability/object"
 require_relative "immutability/with_memory"
 
 # Makes the object immutable (deeply frozen) with possibility to remember
@@ -78,20 +79,13 @@ module Immutability
     # @api private
     #
     # @param [Object, Array<Object>] args
+    # @param [Proc] block
     #
     # @return [Object]
     #
-    def new(*args)
-      IceNine.deep_freeze __new__(*args)
-    end
-
-    private
-
-    def __new__(*args, &block)
-      allocate.tap do |instance|
-        instance.__send__(:initialize, *args)
-        instance.instance_eval(&block) if block_given?
-      end
+    def new(*args, &block)
+      instance = allocate.tap { |obj| obj.__send__(:initialize, *args, &block) }
+      IceNine.deep_freeze(instance)
     end
 
   end # module ClassMethods
@@ -105,14 +99,7 @@ module Immutability
   # @return [Object] the updated instance
   #
   def update(&block)
-    instance = dup
-    instance.instance_eval(&block) if block_given?
-    IceNine.deep_freeze(instance)
-  end
-
-  # @private
-  def self.included(klass)
-    klass.instance_exec(ClassMethods) { |mod| extend(mod) }
+    IceNine.deep_freeze dup.tap { |obj| obj.instance_eval(&block) if block }
   end
 
   # Returns the module extended by features to record history
@@ -123,4 +110,10 @@ module Immutability
     WithMemory
   end
 
+  private
+
+  def self.included(klass)
+    klass.instance_eval { extend ClassMethods }
+  end
+
 end # module Immutability

data/lib/immutability/object.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+module Immutability
+
+  # Describes the continuous object as a sequence of immutable snapshots
+  # with an option of searching the past state of the object
+  #
+  # @api private
+  #
+  # @author Andrew Kozin <Andrew.Kozin@gmail.com>
+  #
+  class Object
+
+    include Enumerable
+
+    # Initializes the object from the current state (snapshot)
+    #
+    # @param [#version, #parent] current
+    #
+    def initialize(current)
+      @current = current
+    end
+
+    # The current (last) version of the object
+    #
+    # The object knows nothing about its future
+    #
+    # @return [Integer]
+    #
+    def version
+      @current.version
+    end
+
+    # Iterates via object's snapshots from the current state to the past
+    #
+    # @return [Enumerator]
+    #
+    def each
+      return to_enum unless block_given?
+      state = @current
+      while state
+        yield(state)
+        state = state.parent
+      end
+    end
+
+    # Returns the state of the object at some point in the past
+    #
+    # @param [#to_i] point
+    #   Either a positive number of target version,
+    #   or a negative number of version (snapshots) before the current one
+    #   +0+ stands for the first version.
+    #
+    # @return [Object, nil]
+    #
+    def at(point)
+      ipoint = point.to_i
+      target = (ipoint < 0) ? (version + ipoint) : ipoint
+      return unless (0..version).include? target
+
+      detect { |state| target.equal? state.version }
+    end
+
+  end # class Object
+
+end # module Immutability

data/lib/immutability/version.rb

@@ -4,6 +4,6 @@ module Immutability
 
   # The semantic version of the gem.
   # @see http://semver.org/ Semantic versioning 2.0
-  VERSION = "0.0.1".freeze
+  VERSION = "0.0.2".freeze
 
 end # module Immutability

data/lib/immutability/with_memory.rb

@@ -8,39 +8,34 @@ module Immutability
   #
   module WithMemory
 
-    # @private
-    class << self
-      private
+    include Immutability
 
-      def included(klass)
-        klass.__send__ :include, Immutability
-        klass.__send__ :extend,  ClassMethods
-        klass.__send__ :define_method, :update, update
-      end
+    # Methods to be added to class, that included the `Immutability` module
+    #
+    # @api private
+    #
+    module ClassMethods
 
-      # Redefines the +update+ so that it increment version and refer
-      # to the previous snapshot of the continuous object
+      # Reloads instance's constructor to add version and parent and make
+      # the whole instance immutable
+      #
+      # @api private
+      #
+      # @param [Object, Array<Object>] args
+      # @param [Proc] block
       #
-      def update
-        proc do |&block|
-          current = [(version + 1), self]
-          super() do
-            @version, @parent = current
-            instance_eval(&block) if block
-          end
+      # @return [Object]
+      #
+      def new(*args, &block)
+        instance = allocate.tap do |obj|
+          obj.__send__(:initialize, *args, &block)
+          obj.instance_variable_set(:@version, 0)
+          obj.instance_variable_set(:@parent, nil)
         end
+        IceNine.deep_freeze(instance)
       end
-    end
 
-    # Adds version and parent variables to newly created instance
-    #
-    module ClassMethods
-      private
-
-      def __new__(*args)
-        super(*args) { @version, @parent = 0 }
-      end
-    end
+    end # module ClassMethods
 
     # @!attribute [r] version
     #
@@ -54,6 +49,19 @@ module Immutability
     #
     attr_reader :parent
 
+    # Redefines the +update+ so that it increment version and refer
+    # to the previous snapshot of the continuous object
+    #
+    # @param [Proc] block
+    #
+    def update(&block)
+      current = [version + 1, self]
+      super do
+        @version, @parent = current
+        instance_eval(&block) if block
+      end
+    end
+
     # Forgets the previous history of the object
     #
     # Returns a new instance with the same variables,
@@ -65,6 +73,23 @@ module Immutability
       update { @version, @parent = 0 }
     end
 
+    # Returns an ancestor of the instance at some point in the past
+    #
+    # @param [#to_i] point
+    #   Either a positive number of version, or a negative number of versions
+    #   (snapshots) before now. +0+ stands for the first version.
+    #
+    # @return [Object, nil]
+    #
+    def at(point)
+      Object.new(self).at(point)
+    end
+
+    # @private
+    def self.included(klass)
+      klass.instance_eval { extend ClassMethods }
+    end
+
   end # module WithMemory
 
 end # module Immutability

data/spec/shared/user.rb

@@ -3,11 +3,12 @@
 shared_examples :user do
   before do
     class User
-      attr_reader :name, :age
+      attr_reader :name, :age, :role
 
       def initialize(name, age)
         @name = name
         @age  = age
+        @role = block_given? ? yield : nil
       end
     end
   end

data/spec/spec_helper.rb

@@ -16,3 +16,11 @@ require "immutability/rspec"
 
 # Loads shared examples
 require_relative "shared/user"
+
+# @todo Remove after resolving of mutant PR#444
+# @see https://github.com/mbj/mutant/issues/444
+if ENV["MUTANT"]
+  RSpec.configure do |config|
+    config.around { |example| Timeout.timeout(0.5, &example) }
+  end
+end

data/spec/support/immutable.rb

@@ -9,7 +9,7 @@
 #
 RSpec::Matchers.define :be_immutable do
   match do |instance|
-    if instance.class.respond_to? :new
+    if instance && instance.class.respond_to?(:new)
       expect(instance).to be_frozen
       instance
         .instance_variables.map(&instance.method(:instance_variable_get))

data/spec/unit/immutability/object_spec.rb

@@ -0,0 +1,89 @@
+# encoding: utf-8
+describe Immutability::Object do
+  let(:object)      { described_class.new(instance) }
+
+  let(:instance)    { double :instance,    version: 2, parent: parent      }
+  let(:parent)      { double :parent,      version: 1, parent: grandparent }
+  let(:grandparent) { double :grandparent, version: 0, parent: nil         }
+
+  describe "#version" do
+    subject { object.version }
+
+    it "is delegated to instance" do
+      expect(subject).to eql instance.version
+    end
+  end # describe #version
+
+  describe "#each" do
+    context "without block" do
+      subject { object.each }
+
+      it { is_expected.to be_kind_of Enumerator }
+    end
+
+    context "with a block" do
+      subject { object.to_a }
+
+      it "iterates via ancestors" do
+        expect(subject).to eql [instance, parent, grandparent]
+      end
+    end
+  end # describe #each
+
+  describe "#at" do
+    subject { object.at(point) }
+
+    context "0" do
+      let(:point) { 0 }
+
+      it { is_expected.to eql grandparent }
+    end
+
+    context "positive number less than version" do
+      let(:point) { "1" }
+
+      it { is_expected.to eql parent }
+    end
+
+    context "positive number equal to version" do
+      let(:point) { 2 }
+
+      it { is_expected.to eql instance }
+    end
+
+    context "positive number greater than version" do
+      let(:point) { 3 }
+
+      it { is_expected.to be_nil }
+
+      it "doesn't check #parent" do
+        expect(instance).not_to receive(:parent)
+        subject
+      end
+    end
+
+    context "negative number less than version" do
+      let(:point) { -1 }
+
+      it { is_expected.to eql parent }
+    end
+
+    context "negative number equal to version" do
+      let(:point) { -2 }
+
+      it { is_expected.to eql grandparent }
+    end
+
+    context "negative number greater than version" do
+      let(:point) { -3 }
+
+      it { is_expected.to be_nil }
+
+      it "doesn't check #parent" do
+        expect(instance).not_to receive(:parent)
+        subject
+      end
+    end
+  end # describe #at
+
+end # describe Immutability::Object

data/spec/unit/immutability/with_memory_spec.rb

@@ -4,16 +4,22 @@ describe Immutability::WithMemory do
   include_context :user
   before { User.send :include, described_class }
 
-  let(:user) { User.new "Andrew", 44 }
+  let(:user) { User.new("Andrew", 44) { "admin" } }
 
   describe ".new" do
     subject { user }
 
+    it "calls the initializer" do
+      expect(subject.name).to eql "Andrew"
+      expect(subject.age).to  eql 44
+      expect(subject.role).to eql "admin"
+    end
+
     it { is_expected.to be_immutable }
 
     it "doesn't add hidden variables" do
       expect(subject.instance_variables).to contain_exactly(
-        :@name, :@age, :@version, :@parent
+        :@name, :@age, :@role, :@version, :@parent
       )
     end
   end # describe .new
@@ -23,7 +29,7 @@ describe Immutability::WithMemory do
 
     it "are expected" do
       expect(subject).to contain_exactly(
-        :name, :age, :version, :parent, :update, :forget_history
+        :name, :age, :role, :version, :parent, :update, :forget_history, :at
       )
     end
   end # describe #methods
@@ -98,4 +104,43 @@ describe Immutability::WithMemory do
     end
   end # describe #forget_history
 
+  describe "#at" do
+    subject { three.at(point) }
+
+    let(:zero)  { user }
+    let(:one)   { zero.update }
+    let(:two)   { one.update }
+    let(:three) { two.update }
+
+    context "0" do
+      let(:point) { 0 }
+
+      it { is_expected.to eql zero }
+    end
+
+    context "positive number less than version" do
+      let(:point) { 2 }
+
+      it { is_expected.to eql two }
+    end
+
+    context "positive number greater than version" do
+      let(:point) { 4 }
+
+      it { is_expected.to be_nil }
+    end
+
+    context "negative number less than version" do
+      let(:point) { -2 }
+
+      it { is_expected.to eql one }
+    end
+
+    context "negative number greater than version" do
+      let(:point) { -4 }
+
+      it { is_expected.to be_nil }
+    end
+  end # describe #at
+
 end # describe Immutability::WithMemory

data/spec/unit/immutability_spec.rb

@@ -4,7 +4,7 @@ describe Immutability do
   include_context :user
   before { User.send :include, described_class }
 
-  let(:user) { User.new name, 44 }
+  let(:user) { User.new(name, 44) { "admin" } }
   let(:name) { "Andrew" }
 
   describe "::with_memory" do
@@ -16,13 +16,19 @@ describe Immutability do
   describe ".new" do
     subject { user }
 
+    it "calls the initializer" do
+      expect(subject.name).to eql name
+      expect(subject.age).to  eql 44
+      expect(subject.role).to eql "admin"
+    end
+
     it { is_expected.to be_immutable }
   end # describe .new
 
   describe "#methods" do
     subject { user.methods - Object.instance_methods }
 
-    it { is_expected.to contain_exactly(:name, :age, :update) }
+    it { is_expected.to contain_exactly(:name, :age, :role, :update) }
   end # describe #methods
 
   describe "#update" do

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: immutability
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Andrew Kozin
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-20 00:00:00.000000000 Z
+date: 2015-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ice_nine
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.11.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: 0.11.1
 - !ruby/object:Gem::Dependency
   name: hexx-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0.5'
 description: 
@@ -46,13 +46,13 @@ extra_rdoc_files:
 - README.md
 - LICENSE
 files:
-- .coveralls.yml
-- .gitignore
-- .metrics
-- .rspec
-- .rubocop.yml
-- .travis.yml
-- .yardopts
+- ".coveralls.yml"
+- ".gitignore"
+- ".metrics"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- ".yardopts"
 - CHANGELOG.md
 - Gemfile
 - Guardfile
@@ -72,12 +72,14 @@ files:
 - config/metrics/yardstick.yml
 - immutability.gemspec
 - lib/immutability.rb
+- lib/immutability/object.rb
 - lib/immutability/rspec.rb
 - lib/immutability/version.rb
 - lib/immutability/with_memory.rb
 - spec/shared/user.rb
 - spec/spec_helper.rb
 - spec/support/immutable.rb
+- spec/unit/immutability/object_spec.rb
 - spec/unit/immutability/with_memory_spec.rb
 - spec/unit/immutability_spec.rb
 homepage: https://github.com/nepalez/immutability
@@ -90,23 +92,24 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Make instances immutable (deeply frozen) and versioned
 test_files:
 - spec/spec_helper.rb
 - spec/unit/immutability_spec.rb
+- spec/unit/immutability/object_spec.rb
 - spec/unit/immutability/with_memory_spec.rb
 - spec/support/immutable.rb
 - spec/shared/user.rb