adherence 0.1.0

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rspec", "~> 2.11.0"

data/Gemfile.lock

@@ -0,0 +1,24 @@
+PATH
+  remote: .
+  specs:
+    adherence (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.2)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  adherence!
+  rspec (~> 2.11.0)

data/README.md

@@ -0,0 +1,141 @@
+# Adherence
+
+Adherence adds simple interface-like behavior to Ruby.
+
+## Description
+
+A common practice in object oriented programming languages is to declare abstract behavior in a certain type whose actual behavior must be defined by types implementing the abstract type.
+
+In Java, for example, this is abstract behavior may be defined in an abstract class or an interface. In many dynamically types languages, like Ruby, duck typing makes these abstract types unneccessary. However, it is common to see in Ruby programs the following abstract-like method pattern:
+
+```ruby
+class Validator
+  def validate(record)
+    raise NotImplementedError, "Subclasses must implement a validate(record) method."
+  end
+end
+```
+
+Adherence provides a simple means of declaring abstract behavior in Ruby modules and enforcing their complete implementation in any class adhereing to this module.
+
+## Usage
+
+A class may adhere to any number of modules by use of the adheres_to method.
+
+```ruby
+module ElectronicDevice
+  def on() end
+
+  def off() end
+
+  def self.compatible?(device1, device2) end
+end
+
+module Calculator
+  def add(x1, x2) end
+
+  def subtract(x1, x2) end
+
+  def multiply(x1, x2) end
+
+  def divide(x1, x2) end
+end
+
+class TexasInstruments
+  def on
+    @power = true
+  end
+
+  def off
+    @power = false
+  end
+
+  def add(x1, x2)
+    x1 + x2
+  end
+
+  def subtract(x1, x2)
+    x1 - x2
+  end
+
+  def multiply(x1, x2)
+    x1 * x2
+  end
+
+  def divide(x1, x2)
+    x1 / x2
+  end
+
+  def self.compatible?(device1, device2)
+    device1.respond_to?(:add) && device2.respond_to?(:add)
+  end
+
+  adheres_to ElectronicDevice, Calculator
+end
+```
+
+A class must define all instance and class methods of all visibilities defined in each module passed to adheres_to or an error is raised. Not only must all methods be defined, but their method signitures must match those of the specified module(s). Failure to implement all methods will result in a NotImplementedError when the class is loaded. Failure to incorrectly declare a message signature will result in a Adherence::NotAdheredError when the class is loaded. Because the methods defined in the class must be inspected, adheres_to must be called after the methods are defined in the class.
+
+Similarly, a module may adhere to other modules:
+
+```ruby
+module ScientificCalculator
+  adhere_to Calculator
+
+  def factorial(n) end
+
+  def power(base, exponent) end
+end
+```
+
+In this case, the module is not expected to redefine the methods defined in the modules passed to adheres_to, rather these methods will be redefined within the calling module to raise an error when invoked directly. Thus the module ScientificCalculator in the example above will be redefined to look like this:
+
+```ruby
+module ScientificCalculator
+  def on
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def off
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def add(x1, x2)
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def subtract(x1, x2)
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def multiply(x1, x2)
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def divide(x1, x2)
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def self.compatible?(device1, device2)
+    raise NotImplementedError, "This method must be defined in the calling class."
+  end
+
+  def factorial(n) end
+
+  def power(base, exponent) end
+end
+```
+
+So if any class that includes or extends ScientificCalculator and does not override these methods, a NotImplementedError would be raised if any of them were called.
+
+## Requirements
+
+Due to some of the methods used to inspect method signatures, Adherence is only compatible with Ruby version >= 1.9.2-p180.
+
+## Installation
+
+    gem install adherence
+
+## License
+
+Adherence is released under the [MIT license](http://www.opensource.org/licenses/MIT). Copyright (c) 2012 Mike Bradford.

data/adherence.gemspec

@@ -0,0 +1,13 @@
+Gem::Specification.new do |spec|
+  spec.name         = "adherence"
+  spec.version      = "0.1.0"
+  spec.date         = "2012-08-30"
+  spec.summary      = "Adds simple interface-like behavior to Ruby"
+  spec.authors      = ["Mike Bradford"]
+  spec.email        = "mbradford@47primes.com"
+  spec.files        = Dir["#{File.dirname(__FILE__)}/**/*"]
+  spec.test_files   = Dir.glob("spec/*_spec.rb")
+  spec.homepage     = "http://github.com/47primes/adherence"
+
+  spec.add_development_dependency "rspec", "~> 2.11.0"
+end

data/lib/adherence.rb

@@ -0,0 +1,12 @@
+Dir.glob(File.dirname(__FILE__) + "/adherence/*.rb").each {|f| require f}
+
+module Adherence
+end
+
+class Module
+  include Adherence::Module
+end
+
+class Class
+  include Adherence::Class
+end

data/lib/adherence/class.rb

@@ -0,0 +1,38 @@
+module Adherence
+  class NotAdheredError < NotImplementedError; end
+  module Class
+
+    def adheres_to(*args)
+      args.each {|mod| adheres_to_module mod}
+    end
+
+    private
+
+    def adheres_to_module(mod)
+      raise ArgumentError, "Module expected" unless mod.class.to_s == "Module"
+
+      (mod.instance_methods(false) + mod.private_instance_methods(false)).each do |method|
+        if !(instance_methods + private_instance_methods).include?(method)
+          raise NotImplementedError, "#{self.class} must define #{method}"
+        end
+        if !equal? instance_method(method), mod.instance_method(method)
+          raise NotAdheredError, "Signature does not match #{mod}##{method}"
+        end
+      end
+
+      module_class_methods = mod.singleton_class.instance_methods(false) + mod.singleton_class.private_instance_methods(false)
+      module_class_methods.each do |method|
+        if !(singleton_class.instance_methods + singleton_class.private_instance_methods).include?(method)
+          raise NotImplementedError, "#{self.class} must define self.#{method}"
+        end
+        if !equal? singleton_class.instance_method(method), mod.singleton_class.instance_method(method)
+          raise NotAdheredError, "Signature does not match #{mod}.#{method}"
+        end
+      end
+    end
+
+    def equal?(method1, method2)
+      method1.name == method2.name && method1.parameters == method2.parameters ? true : false
+    end
+  end
+end

data/lib/adherence/module.rb

@@ -0,0 +1,63 @@
+module Adherence
+  class ModuleTerminatedError < StandardError; end
+  module Module
+
+    def adheres_to(*args)
+      args.each { |mod| adheres_to_module(mod) }
+    end
+
+    private
+
+    def adheres_to_module(mod)
+      raise ArgumentError, "Module expected" unless mod.class.to_s == "Module"
+
+      mod.public_instance_methods(false).each do |method|
+        add_method mod.instance_method(method)
+      end
+
+      mod.protected_instance_methods(false).each do |method|
+        add_method mod.instance_method(method)
+      end
+      protected *mod.protected_instance_methods(false)
+
+      mod.private_instance_methods(false).each do |method|
+        add_method mod.instance_method(method)
+      end
+      private *mod.private_instance_methods(false)
+
+      mod.singleton_class.public_instance_methods(false).each do |method|
+        add_method mod.singleton_class.instance_method(method), true
+      end
+
+      mod.singleton_class.protected_instance_methods(false).each do |method|
+        add_method mod.singleton_class.instance_method(method), true
+      end
+      singleton_class.send :protected, *mod.singleton_class.protected_instance_methods(false)
+
+      mod.singleton_class.private_instance_methods(false).each do |method|
+        add_method mod.singleton_class.instance_method(method), true
+      end
+      private_class_method *mod.singleton_class.private_instance_methods(false)
+    end
+
+    def add_method(method, singleton_method=false)
+        name   = method.name
+        params = method.parameters.reduce([]) do |memo, word|
+                    arity, param = word
+                    case arity
+                    when :req then memo << "#{param}"
+                    when :opt then memo << "#{param}=nil"
+                    when :block then memo << "&#{param}"
+                    when :rest then memo << "*#{param}"
+                    end
+                  end.join(", ")
+        
+        module_eval <<-DEF
+          def #{"self." if singleton_method}#{name}(#{params})
+            raise NotImplementedError, "This method must be defined in the calling class."
+          end
+        DEF
+    end
+
+  end
+end

data/spec/adherence_class_spec.rb

@@ -0,0 +1,104 @@
+require "adherence"
+
+module Animal
+  def speak() end
+
+  def move(feet) end
+
+  private
+
+  def life_expectancy() end
+
+  class <<self
+    def build(name, &block) end
+  end
+end
+
+describe Object, "adheres_to" do
+
+  before do
+    class Duck
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def speak
+        "quack"
+      end
+
+      def move(feet)
+        "waddle #{feet} feet"
+      end
+
+      private
+
+      def life_expectancy
+        10
+      end
+
+      def self.build(name, &block)
+        Duck.new(name)
+      end
+    end
+  end
+
+  it "should succeed if the object has defined all behavior from the module" do
+    expect do 
+      class Duck
+        adheres_to Animal
+      end
+    end.to_not raise_error
+  end
+
+  it "should raise an error if argument is not a module" do
+    expect do 
+      class Duck 
+        adheres_to Class.new
+      end
+    end.to raise_error(ArgumentError)
+  end
+
+  it "should raise an error if all methods are not implemented" do
+    Duck.send(:remove_method, :speak)
+
+    expect do 
+      class Duck
+        adheres_to Animal
+      end
+    end.to raise_error(NotImplementedError)
+  end
+
+  it "should raise an error if all private methods are not implemented" do
+    Duck.send(:remove_method, :life_expectancy)
+
+    expect do 
+      class Duck
+        adheres_to Animal
+      end
+    end.to raise_error(NotImplementedError)
+  end
+
+  it "should raise an error if all class methods are not implemented" do
+    Duck.singleton_class.send(:remove_method, :build)
+
+    expect { Duck.adheres_to(Animal) }.to raise_error(NotImplementedError)
+  end
+
+  it "should raise an error if methods are implemented with an invalid signature" do
+    Duck.send(:remove_method, :move)
+    Duck.class_eval do
+      def move(distance)
+        "waddle #{distance} feet"
+      end
+    end
+
+    expect do 
+      class Duck
+        adheres_to Animal
+      end
+    end.to raise_error(Adherence::NotAdheredError)
+  end
+
+end

data/spec/adherence_module_spec.rb

@@ -0,0 +1,133 @@
+require "adherence"
+
+module Vehicle
+  def initialize(make, model) end
+
+  def start() end
+
+  def stop() end
+
+  def accellerate(speed) end
+
+  def turn(orientation, speed=5, *args) end
+
+  protected
+
+  def repair(area, &block) end
+
+  module ClassMethods
+    class <<self
+      def build(*args, &block) end
+
+      protected
+
+      def run() end
+
+      private
+
+      def helper(object) end
+    end
+  end
+end
+
+module Watercraft
+  adheres_to Vehicle, Vehicle::ClassMethods
+
+  def dock() end
+end
+
+describe Module, "adheres_to" do
+  it "should raise an error if argument is not a module" do
+    expect { Module.new { adheres_to(Class.new())} }.to raise_error(ArgumentError)
+  end
+
+  it "should define public instance methods based on module" do
+    Watercraft.instance_method(:start).parameters.should == []
+    Watercraft.instance_method(:stop).parameters.should == []
+    Watercraft.instance_method(:accellerate).parameters.should == [[:req, :speed]]
+    Watercraft.instance_method(:turn).parameters.should == [[:req, :orientation], [:opt, :speed], [:rest, :args]]
+  end
+
+  it "should define protected instance methods based on module" do
+    Watercraft.protected_method_defined?(:repair).should be_true
+    Watercraft.instance_method(:repair).parameters.should == [[:req, :area], [:block, :block]]
+  end
+
+  it "should define private instance methods based on module" do
+    Watercraft.private_method_defined?(:initialize).should be_true
+    Watercraft.instance_method(:initialize).parameters.should == [[:req, :make], [:req, :model]]
+  end
+
+  it "should define public class methods based on module" do
+    Watercraft.singleton_class.public_instance_method(:build).parameters.should == [[:rest, :args], [:block, :block]]
+  end
+
+  it "should define protected class methods based on module" do
+    Watercraft.singleton_class.protected_instance_methods.include?(:run).should be_true
+    Watercraft.singleton_class.instance_method(:run).parameters.should == []
+  end
+
+  it "should define private class methods based on module" do
+    Watercraft.singleton_class.private_instance_methods.include?(:helper).should be_true
+    Watercraft.singleton_class.instance_method(:helper).parameters.should == [[:req, :object]]
+  end
+
+  it "should define all public instance methods to raise an error when called directly" do
+    JetSki = Class.new do
+      include Watercraft
+
+      def initialize(make, model)
+      end
+    end
+
+    jet_ski = JetSki.new("Kawasaki","Ultra 300LX")
+
+    expect { jet_ski.start }.to raise_error(NotImplementedError)
+    expect { jet_ski.stop }.to raise_error(NotImplementedError)
+    expect { jet_ski.accellerate(10) }.to raise_error(NotImplementedError)
+    expect { jet_ski.turn(90, -5) }.to raise_error(NotImplementedError)
+  end
+
+  it "should define all protected instance methods to raise an error when called directly" do
+    OceanLiner = Class.new do
+      include Watercraft
+
+      def initialize(make, model)
+      end
+    end
+
+    expect { OceanLiner.new("RMS","Titanic").send(:repair, "stern") }.to raise_error(NotImplementedError)
+  end
+
+  it "should define all private instance methods to raise an error when called directly" do
+    RowBoat = Class.new do
+      include Watercraft
+    end
+
+    expect { RowBoat.new("Freebooter","Row Boat") }.to raise_error(NotImplementedError)
+  end
+
+  it "should define all public class methods to raise an error when called directly" do
+    Automobile = Module.new do
+      adheres_to Vehicle::ClassMethods
+    end
+
+    expect { Automobile.build("Cadillac") {|c| c.year = 2012} }.to raise_error(NotImplementedError)
+  end
+
+  it "should define all protected class methods to raise an error when called directly" do
+    Locomotive = Module.new do
+      adheres_to Vehicle::ClassMethods
+    end
+
+    expect { Locomotive.send(:run) }.to raise_error(NotImplementedError)
+  end
+
+  it "should define all private class methods to raise an error when called directly" do
+    Bicycle = Module.new do
+      adheres_to Vehicle::ClassMethods
+    end
+
+    expect { Bicycle.send(:helper, "object") }.to raise_error(NotImplementedError)
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: adherence
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Mike Bradford
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-30 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: 2.11.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.11.0
+description: 
+email: mbradford@47primes.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ./adherence.gemspec
+- ./Gemfile
+- ./Gemfile.lock
+- ./lib/adherence/class.rb
+- ./lib/adherence/module.rb
+- ./lib/adherence.rb
+- ./README.md
+- ./spec/adherence_module_spec.rb
+- ./spec/adherence_class_spec.rb
+- spec/adherence_module_spec.rb
+- spec/adherence_class_spec.rb
+homepage: http://github.com/47primes/adherence
+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: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Adds simple interface-like behavior to Ruby
+test_files:
+- spec/adherence_module_spec.rb
+- spec/adherence_class_spec.rb