contractual 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in contractual.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 TODO: Write your name
+
+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,78 @@
+# Contractual
+
+This gem provides limited support for the utilization of interfaces in Ruby. The approach here is 
+nearly idetnical to one suggested by Mark Bates at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.
+It didn't seem like this had been turned into a gem yet, so I thought I might go ahead and put it together in
+case others found the technique as helpful as I had. 
+
+## What's this all about?
+
+An **interface** is a logical description of the role of an entity within the system; basically it is a construct which specifies a contract for the behavior of a component in an application. You might be thinking: hey, I've got all these RSpec/Cucumber/etc. focused behavior descriptions -- surely you're not saying I *repeat* myself? Well, not exactly. Specifications give us programmatic descriptions of how a given entity should behave in certain situations. These can *include* contracts but potentially go significantly deeper, since they can specify just about any behavior you can imagine. An interface is somewhat simpler in comparison: it's more or less just a hint that a given method must be implemented by a subclass. So you specify 'implement this method' and 'implement that method' in order to have an 'official' whatever-kind-of-entity.
+
+The basic idea here is to give hints to developers extending your API that aren't just in the form of shared RSpec examples, but rather embedded in the source of the superclass. Effectively, this supports the 'L' in SOLID -- making it easier to substitute subclasses in a dynamic language, ensuring that certain methods are implemented.
+
+Please note that there are some limitations as to the utility of this approach, perhaps most importantly the one that Bates himself identified -- that the interface hints aren't going to show up, automagically anyway, in documentation. (As a note on good practice it probably makes sense to describe these as part of the documentation for the class.) Furthermore, please note that given there's no compiler for Ruby, the associated contractual warnings only 'kick in' the first time an unimplemented contractually-obligated method is invoked.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'contractual'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install contractual
+
+## Usage
+
+Consider a canonical superclass.
+
+  class Vehicle
+    def drive(passengers, destination)
+      load passengers
+      follow Route.new(@current_location, destination)
+      unload passengers
+    end
+  end
+  
+See all the methods have to be implemented for this to work? Let's specify these as part of the interface:
+
+  class Vehicle
+    
+    must_implement :load, :passengers
+    must_implement :follow, :route
+    must_implement :unload, :passengers
+    
+    def move(passengers, destination)
+      load passengers
+      follow Route.new(@current_location, destination)
+      unload passengers
+    end
+  end
+
+Let's suppose we've been handed this interface from another developer. How do we make a custom subclass? Our first attempt at implementing might look something like this:
+
+  class Zeppelin
+    
+    def load(passengers); @passengers << passengers; end
+    def unload(passengers); @current_location << passengers; @passengers = []; end
+    
+   end
+   
+So now when we try to invoke Zeppelin.move, we'll get an exception warning us that Zeppelin is obligated to implement a method 'follow' from the interface Vehicle. This is the 'hint' that the implementing developer has a bit more work to do before they can use this custom class smoothly with the rest of the system. 
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Thanks!
+
+Many thanks go to Mark Bates for the idea for this gem.

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/contractual.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/contractual/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Joseph Weissman"]
+  gem.email         = ["jweissman1986@gmail.com"]
+  gem.description   = %q{This gem provides limited support for the utilization of interfaces in Ruby. The approach here is 
+  nearly idetnical to one suggested by Mark Bates at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.
+It didn't seem like this had been turned into a gem yet, so I thought I might go ahead and put it together in case others found the technique as helpful as I had.}
+  gem.summary       = %q{Specify interface contracts for your Ruby classes.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "contractual"
+  gem.require_paths = ["lib"]
+  gem.version       = Contractual::VERSION
+end

data/lib/contractual.rb

@@ -0,0 +1,41 @@
+require "contractual/version"
+
+module Contractual
+  module Interface
+    class MethodNotImplementedError < NoMethodError; end
+
+    def self.included(klass)
+      klass.send(:include, Interface::Methods)
+      klass.send(:extend,  Interface::Methods)
+      klass.send(:extend,  Interface::ClassMethods)
+    end
+
+    module Methods
+      def does_not_implement_method(klass, method_name = nil)
+        if method_name.nil?
+          caller.first.match(/in \`(.+)\'/)
+          method_name = $1
+        end
+
+        klass_name = klass.class.name
+        interface_name = self.name
+
+        raise MethodNotImplementedError.new("#{klass.class.name} needs to implement '#{method_name}' for interface #{self.name}!")
+      end
+    end
+
+    module ClassMethods
+      def must_implement(method_name, *args)
+        this = self
+        self.class_eval do
+          define_method(method_name) do |*args|
+            this.does_not_implement_method(self, method_name)
+          end
+        end
+      end
+      
+      # helper alias
+      def must(method_name, *args); must_implement(method_name, args); end
+    end
+  end
+end

data/lib/contractual/version.rb

@@ -0,0 +1,3 @@
+module Contractual
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: contractual
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Joseph Weissman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-19 00:00:00.000000000 Z
+dependencies: []
+description: ! "This gem provides limited support for the utilization of interfaces
+  in Ruby. The approach here is \n  nearly idetnical to one suggested by Mark Bates
+  at http://metabates.com/2011/02/07/building-interfaces-and-abstract-classes-in-ruby/.\nIt
+  didn't seem like this had been turned into a gem yet, so I thought I might go ahead
+  and put it together in case others found the technique as helpful as I had."
+email:
+- jweissman1986@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- contractual.gemspec
+- lib/contractual.rb
+- lib/contractual/version.rb
+homepage: ''
+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.22
+signing_key: 
+specification_version: 3
+summary: Specify interface contracts for your Ruby classes.
+test_files: []