This gem provides limited support for the utilization of interfaces in Ruby. The approach here is nearly identical 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.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install contractual
Consider a canonical superclass.
class Vehicle class Route; end def take(passengers, destination) @passengers =  load passengers follow Route.new(@current_location, destination) unload passengers end end
Note all the methods have to be implemented for this to work (load, follow, unload). Let's go ahead and specify these as part of the interface:
class Vehicle include Contractual::Interface must :load, :passengers must :follow, :route must :unload, :passengers class Route; end def take(passengers, destination) @passengers =  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 < Vehicle def load(passengers); @passengers << passengers; end def unload(passengers); @current_location << passengers; @passengers = ; end end
So now when we try to invoke Zeppelin.take, 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.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Added some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
Many thanks go to Mark Bates for the idea for this gem.