adamantium 0.0.1

data/lib/adamantium.rb

@@ -0,0 +1,249 @@
+require 'ice_nine'
+
+# Allows objects to be made immutable
+module Adamantium
+
+  # Storage for memoized methods
+  Memory = Class.new(::Hash)
+
+  # Hook called when module is included
+  #
+  # @param [Module] descendant
+  #   the module or class including Adamantium
+  #
+  # @return [self]
+  #
+  # @api private
+  def self.included(descendant)
+    super
+    descendant.extend ModuleMethods if descendant.kind_of?(Module)
+    descendant.extend ClassMethods  if descendant.kind_of?(Class)
+    self
+  end
+
+  # Attempt to freeze an object
+  #
+  # @example using a value object
+  #   Adamantium.freeze_object(12345)  # => noop
+  #
+  # @example using a normal object
+  #   Adamantium.freeze_object({})  # => duplicate & freeze object
+  #
+  # @param [Object] object
+  #   the object to freeze
+  #
+  # @return [Object]
+  #   if supported, the frozen object, otherwise the object directly
+  #
+  # @api public
+  def self.freeze_object(object)
+    case object
+    when Numeric, TrueClass, FalseClass, NilClass, Symbol
+      object
+    else
+      freeze_value(object)
+    end
+  end
+
+  # Returns a frozen value
+  #
+  # @param [Object] value
+  #   a value to freeze
+  #
+  # @return [Object]
+  #   if frozen, the value directly, otherwise a frozen copy of the value
+  #
+  # @api private
+  def self.freeze_value(value)
+    value.frozen? ? value : IceNine.deep_freeze(value.dup)
+  end
+
+  private_class_method :freeze_value
+
+  # Freeze the object
+  #
+  # @example
+  #   object.freeze  # object is now frozen
+  #
+  # @return [Object]
+  #
+  # @api public
+  def freeze
+    memory  # initialize memory
+    super
+  end
+
+  # Get the memoized value for a method
+  #
+  # @example
+  #   hash = object.memoized(:hash)
+  #
+  # @param [Symbol] name
+  #   the method name
+  #
+  # @return [Object]
+  #
+  # @api public
+  def memoized(name)
+    memory[name]
+  end
+
+  # Sets a memoized value for a method
+  #
+  # @example
+  #   object.memoize(:hash, 12345)
+  #
+  # @param [Symbol] name
+  #   the method name
+  # @param [Object] value
+  #   the value to memoize
+  #
+  # @return [self]
+  #
+  # @api public
+  def memoize(name, value)
+    store_memory(name, value) unless memory.key?(name)
+    self
+  end
+
+  # A noop #dup for immutable objects
+  #
+  # @example
+  #   object.dup  # => self
+  #
+  # @return [self]
+  #
+  # @api public
+  def dup
+    self
+  end
+
+private
+
+  # The memoized method results
+  #
+  # @return [Hash]
+  #
+  # @api private
+  def memory
+    @__memory ||= Memory.new
+  end
+
+  # Store the value in memory
+  #
+  # @param [Symbol] name
+  #   the method name
+  # @param [Object] value
+  #   the value to memoize
+  #
+  # @return [self]
+  #
+  # @return [value]
+  #
+  # @api private
+  def store_memory(name, value)
+    memory[name] = Adamantium.freeze_object(value)
+  end
+
+  # Methods mixed in to adamantium modules
+  module ModuleMethods
+
+    # Hook called when module is included
+    #
+    # @param [Module] mod
+    #   the module including ModuleMethods
+    #
+    # @return [self]
+    #
+    # @api private
+    def included(mod)
+      Adamantium.included(mod)
+      self
+    end
+
+    # Memoize a list of methods
+    #
+    # @example
+    #   memoize :hash
+    #
+    # @param [Array<#to_s>] *methods
+    #   a list of methods to memoize
+    #
+    # @return [self]
+    #
+    # @api public
+    def memoize(*methods)
+      methods.each { |method| memoize_method(method) }
+      self
+    end
+
+  private
+
+    # Memoize the named method
+    #
+    # @param [#to_s] method
+    #   a method to memoize
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def memoize_method(method)
+      visibility = method_visibility(method)
+      define_memoize_method(method)
+      send(visibility, method)
+    end
+
+    # Define a memoized method that delegates to the original method
+    #
+    # @param [Symbol] method
+    #   the name of the method
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def define_memoize_method(method)
+      original = instance_method(method)
+      undef_method(method)
+      define_method(method) do |*args|
+        if memory.key?(method)
+          memoized(method)
+        else
+          store_memory(method, original.bind(self).call(*args))
+        end
+      end
+    end
+
+    # Return the method visibility of a method
+    #
+    # @param [String, Symbol] method
+    #   the name of the method
+    #
+    # @return [String]
+    #
+    # @api private
+    def method_visibility(method)
+      if    private_method_defined?(method)   then 'private'
+      elsif protected_method_defined?(method) then 'protected'
+      else                                         'public'
+      end
+    end
+
+  end # module ModuleMethods
+
+  # Methods mixed in to adamantium classes
+  module ClassMethods
+
+    # Instantiate a new frozen object
+    #
+    # @example
+    #   object = AdamantiumClass.new  # object is frozen
+    #
+    # @return [Object]
+    #
+    # @api public
+    def new(*)
+      IceNine.deep_freeze(super)
+    end
+
+  end # module ClassMethods
+end # module Adamantium

data/lib/adamantium/version.rb

@@ -0,0 +1,3 @@
+module Adamantium
+  VERSION = '0.0.1'.freeze
+end

data/spec/rcov.opts

@@ -0,0 +1,7 @@
+--exclude-only "spec/,^/"
+--sort coverage
+--callsites
+--xrefs
+--profile
+--text-summary
+--failure-threshold 100

data/spec/shared/command_method_behavior.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+shared_examples_for 'a command method' do
+  it 'returns self' do
+    should equal(object)
+  end
+end

data/spec/shared/each_method_behaviour.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+shared_examples_for 'an #each method' do
+  it_should_behave_like 'a command method'
+
+  context 'with no block' do
+    subject { object.each }
+
+    it { should be_instance_of(to_enum.class) }
+
+    it 'yields the expected values' do
+      subject.to_a.should eql(object.to_a)
+    end
+  end
+end

data/spec/shared/hash_method_behavior.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+shared_examples_for 'a hash method' do
+  it_should_behave_like 'an idempotent method'
+
+  specification = proc do
+    should be_instance_of(Fixnum)
+  end
+
+  it 'is a fixnum' do
+    instance_eval(&specification)
+  end
+
+  it 'memoizes the hash code' do
+    subject.should eql(object.memoized(:hash))
+  end
+end

data/spec/shared/idempotent_method_behavior.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+
+shared_examples_for 'an idempotent method' do
+  it 'is idempotent' do
+    should equal(instance_eval(&self.class.subject))
+  end
+end

data/spec/shared/invertible_method_behaviour.rb

@@ -0,0 +1,9 @@
+# encoding: utf-8
+
+shared_examples_for 'an invertible method' do
+  it_should_behave_like 'an idempotent method'
+
+  it 'is invertible' do
+    subject.inverse.should equal(object)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+require 'adamantium'
+require 'spec'
+require 'spec/autorun'
+
+# require spec support files and shared behavior
+Dir[File.expand_path('../{support,shared}/**/*.rb', __FILE__)].each { |f| require f }
+
+Spec::Runner.configure do |config|
+end

data/spec/unit/adamantium/class_methods/freeze_object_spec.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Adamantium, '.freeze_object' do
+  subject { object.freeze_object(value) }
+
+  let(:object) { self.class.described_type }
+
+  context 'with a numeric value' do
+    let(:value) { 1 }
+
+    it { should equal(value) }
+  end
+
+  context 'with a true value' do
+    let(:value) { true }
+
+    it { should equal(value) }
+  end
+
+  context 'with a false value' do
+    let(:value) { false }
+
+    it { should equal(value) }
+  end
+
+  context 'with a nil value' do
+    let(:value) { nil }
+
+    it { should equal(value) }
+  end
+
+  context 'with a symbol value' do
+    let(:value) { :symbol }
+
+    it { should equal(value) }
+  end
+
+  context 'with a frozen value' do
+    let(:value) { String.new.freeze }
+
+    it { should equal(value) }
+  end
+
+  context 'with an unfrozen value' do
+    let(:value) { String.new }
+
+    it { should_not equal(value) }
+
+    it { should be_instance_of(String) }
+
+    it { should == value }
+
+    it { should be_frozen }
+  end
+end

data/spec/unit/adamantium/class_methods/new_spec.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+require 'spec_helper'
+require File.expand_path('../../fixtures/classes', __FILE__)
+
+describe Adamantium::ClassMethods, '#new' do
+  subject { object.new }
+
+  let(:object) { AdamantiumSpecs::Object }
+
+  it { should be_instance_of(object) }
+
+  it { should be_frozen }
+end

data/spec/unit/adamantium/dup_spec.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+require 'spec_helper'
+require File.expand_path('../fixtures/classes', __FILE__)
+
+describe Adamantium, '#dup' do
+  subject { object.dup }
+
+  let(:described_class) { AdamantiumSpecs::Object }
+  let(:object)          { described_class.new    }
+
+  it { should equal(object) }
+end

data/spec/unit/adamantium/fixtures/classes.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+
+module AdamantiumSpecs
+  class Object
+    include Adamantium
+
+    def test
+      'test'
+    end
+
+    def public_method
+      caller
+    end
+
+  protected
+
+    def protected_method
+      caller
+    end
+
+  private
+
+    def private_method
+      caller
+    end
+
+  end # class Object
+end # module AdamantiumSpecs