ainterface 1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1a4ab42daca0488b11de9d97ac864b3f23dbec33
+  data.tar.gz: d2beab95da462a4c55b0ded37bb77d0c843557ab
+SHA512:
+  metadata.gz: c7051c8b8b7aac4f6842cf3ae58bcb94f1bcaefea487356375141ab362218040e03707241f6ad1601012cca584c7cb053b4c4d9f16f24d5f8b6264c341b424ea
+  data.tar.gz: 7067e03c873901d428715c792c45dad5434f7710c63bac3de2c1102d25742fed3ec841f290133c5762688b105f2aa164f9a7282d157392ed92935c98a4a7cf7c

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Fred Appelman
+
+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,146 @@
+
+<style> body {counter-reset: chapter; } H2:before {content: counter(chapter) ". "; counter-increment: chapter; } H2 {counter-reset: SectionH2; } H3:before {content: counter(chapter) "." counter(SectionH2) " "; counter-increment: SectionH2; } H3 {counter-reset: SectionH3; } H4:before {content: counter(chapter) "." counter(SectionH2) "." counter(SectionH3) " "; counter-increment: SectionH3; } H4 {counter-reset: SectionH4; } H5:before {content: counter(chapter) "." counter(SectionH2) "." counter(SectionH3) "." counter(SectionH4) " "; counter-increment: SectionH4; } H5 {counter-reset: SectionH5; } H6:before {content: counter(chapter) "." counter(SectionH2) "." counter(SectionH3) "." counter(SectionH4) "." counter(SectionH5) " "; counter-increment: SectionH5; } H6 {counter-reset: SectionH6; } </style>
+# Interface
+
+This Gem implements the concept of an abstract base class to Ruby.
+
+## References
+This code has been heavily influenced by the code from Mark Bates (<http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/>) and James Lopez (<https://github.com/bluegod/rint>).
+
+The classes provided by Mark Beates are not really "Gem ready". The `AbstractInterface` module referenced `Bicycle`. The work from James Lopez was much closer to what I wanted. The main problem I saw with his approach is that the `must_implement` were have to be provided in the `initialize` method which feels wrong and error prone. IMHO the statements should be on the module level. Hence this Gem to address this and work on the class and module level only.
+
+## Under the hood
+This Gem will rewrite the new method of the class that implements an Interface and that new method will just do the normal init followed by a check if all required methods are implemented.
+
+The new method now looks like this:
+
+```ruby
+def self.new(*args, &block)
+  obj = self.allocate
+  obj.send :initialize, *args, &block
+  obj.send :__check_interface_methods
+  obj
+end
+```
+
+where `__check_interface_methods()` does the actuall checking to see if the Abstract Interface has been fully implemented.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ainterface'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ainterface
+
+## Usage
+
+This Gem implements the concept of an abstract interface in `Ruby`.
+
+```ruby
+#!/usr/bin/env ruby
+require 'ainterface'
+
+# Define the abtract interface named Wheels
+# Any class that implements Wheels must implement
+# the methods 'number_of_wheels' and 'diameter'
+module Wheels
+  must_implement :number_of_wheels
+  must_implement :diameter
+end
+
+# This class implments wheels.
+class Car
+  implements Wheels
+  def number_of_wheels
+    4
+  end
+  def diameter
+    13
+  end
+end
+
+car = Car.new
+```
+
+In the above example Car fullfills the Wheels contract and will not raise any error.
+
+if for example the following code would have been written:
+
+```ruby
+class Bicycle
+  implements Wheels
+  def number_of_wheels
+    2
+  end
+end
+
+bicycle = Bicycle.new
+```
+
+The following error message would have been thrown:
+
+    (eval):4:in `block in __check_interface_methods': Expected Bicycle to implement diameter for interface Wheels (AInterface::Error::NotImplementedError)
+      from (eval):2:in `each'
+      from (eval):2:in `__check_interface_methods'
+      from (eval):4:in `new'
+
+In the above example `Wheels` was a module. If desired an Interface can also be implemented as a class.
+
+### Similar to include
+Any method that was defined by the Interface module is also added
+to the class that implements the interface
+
+For example:
+
+```ruby
+module Geometry
+  must_implement :width
+  must_implement :height
+
+  def outline
+    2 * width + 2 * height
+  end
+end
+
+class Rectangle
+  implements Geometry
+  def width
+    4
+  end
+  def height
+    3
+  end
+end
+
+rect = Rectangle.new
+p (rect.methods - Object.methods).sort
+puts "Outline = #{rect.outline}"
+```
+
+will product the following output:
+
+```ruby
+[:height, :outline, :width]
+Outline = 14
+```
+
+As such `implements` acts as an `include` statement.
+
+## Options
+The environment variable
+
+```shell
+DISABLE_RUBY_INTERFACE=1
+```
+
+can be set in order to globally disable the abstract interfaces - no Error will get thrown. This might be particularly useful in production for performance reasons if we are confident enough through tests that the interfaces are all implemented.
+

data/lib/ainterface.rb

@@ -0,0 +1,137 @@
+#
+# Monkey patch the standard Module class
+class Module
+  # Holds all methods that are in an interface
+  # for a given interface
+  # Use a long name to prevent accidental name conflicts
+  @@__interface_methods_per_interface = {}
+
+  # Called by a class to indicate it implements the specified
+  # interface(s)
+  #
+  # @param [AInterface] args One or more interface names that
+  #   are being implemented
+  #
+  # @return [void]
+  #
+  def implements(*args)
+    raise AInterface::Error::MissingArgument if args == []
+    # Gather the methods from all specified interfaces
+    m = []
+    args.each do |module_name|
+      raise AInterface::Error::NosuchInterface, module_name.to_s unless
+        @@__interface_methods_per_interface[module_name.to_s]
+      @@__interface_methods_per_interface[module_name.to_s].each do |method_name|
+        m << [module_name.name, method_name]
+      end
+    end
+
+    # Create a method that checks for the existence
+    # of all methods
+    t = <<-EOF
+      def __check_interface_methods
+        #{m}.each do |module_name, method_name|
+          next if respond_to? method_name
+          raise AInterface::Error::NotImplementedError.new(
+                self.class.name,
+                method_name,
+                module_name
+              )
+        end
+      end
+      private :__check_interface_methods
+    EOF
+    class_eval t unless disabled_interface?
+
+    # Redefine the new method
+    t = <<-EOF
+      def self.new(*args, &block)
+        obj = self.allocate
+        obj.send :initialize, *args, &block
+        obj.send :__check_interface_methods
+        obj
+      end
+    EOF
+    class_eval t unless disabled_interface?
+
+    args.each do |module_name|
+      prepend module_name
+    end
+  end
+
+  # Errors raised here identify the class_name that is not implementing
+  # the method required by the Interface.
+  #
+  #
+  # Specifies that an method for an interface must be
+  # implemented
+  #
+  # @param [Symbol] args One ore more methods that need implementation
+  #
+  # @return [void]
+  #
+  def must_implement(*args)
+    raise AInterface::Error::MissingArgument if args == []
+    @@__interface_methods_per_interface[self.name] ||= []
+    args.each do |method_name|
+      @@__interface_methods_per_interface[self.name] << method_name
+    end
+  end
+
+  #
+  # Checks if the Interface error message must be surpressed
+  #
+  #
+  # @return [Boolean] Return true if error messages should be
+  #   surpressed.
+  #
+  def disabled_interface?
+    ENV['DISABLE_RUBY_INTERFACE'] == '1'
+  end
+  private :disabled_interface?
+end
+
+#
+# Module AInterface provides some helper classes for the
+# abstract interface implementation.
+#
+# @author Fred Appelman <fred@appelman.net>
+#
+module AInterface
+  #
+  # Module Error provides error message handlers for the
+  # abstract interface implementation.
+  #
+  # @author Fred Appelman <fred@appelman.net>
+  #
+  module Error
+    #
+    # Class MissingArgument is raised when must_implement or
+    # implements is issued without an argument.
+    #
+    # @author Fred Appelman <fred@appelman.net>
+    #
+    class MissingArgument < StandardError; end
+
+    #
+    # Class NosuchInterface is raised when implements
+    # references a Interface that wasn't defined.
+    #
+    # @author Fred Appelman <fred@appelman.net>
+    #
+    class NosuchInterface < StandardError; end
+
+    # Raised when a method has not been implemented by a class that
+    # has used the implements <InterfaceName> method.
+    class NotImplementedError < NoMethodError
+      def initialize(class_name, method_name, interface_name)
+        super(error_message(class_name, method_name, interface_name), method_name)
+      end
+
+      def error_message(class_name, method_name, interface_name)
+        "Expected #{class_name} to implement #{method_name} for interface #{interface_name}"
+      end
+      private :error_message
+    end
+  end
+end

data/lib/ainterface/version.rb

@@ -0,0 +1,9 @@
+#
+# Module AInterfaceVersion provides a version number
+# for the gem AInterface
+#
+module AInterfaceVersion
+  #
+  # @return [String] The application version number
+  NUMBER = '1.0'
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: ainterface
+version: !ruby/object:Gem::Version
+  version: '1.0'
+platform: ruby
+authors:
+- Fred Appelman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-02-16 00:00:00.000000000 Z
+dependencies: []
+description: Provides an abstract interface to Ruby
+email: rubygems@appelman.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ainterface.rb
+- lib/ainterface/version.rb
+homepage: https://bitbucket.org/fappelman/ainterface
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: Provides the concept of an Abstract Interface for the Ruby language.
+test_files: []
+has_rdoc: false