interfaces 0.0.2.pre → 0.2.0

data/README.md

@@ -1,7 +1,5 @@
 # Interfaces
 
-TODO: Write a gem description
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -29,9 +27,9 @@ Let's role play a development scenario.  Let's say you are writing an applicatio
       # some options specifically for sending mail
       attr_accessor :email_server, :use_ssl?, :port, :use_html?
 
-	  def email_sent_callback(mailer)
-	  	# do something after mail is sent
-	  end
+  	  def email_sent_callback(mailer)
+	   	  # do something after mail is sent
+	    end
     end
 
 And we create a MailerService to send mail:
@@ -52,39 +50,26 @@ And we create a MailerService to send mail:
       end
     end
 
-This works, but we've needlessly coupled our MailerService to our User model.  The Mailer service does not really need a User, what it needs is configuration.  To be slightly more explicit then we could simply rename the first parameter to 'configuration':
+We can call the Mailer service and pass it a user:
 
-    class MailerService
-      attr_accessor :configuration, :to, :subject, :message
+  MailerService.new(user, 'bob@example.com', 'test message', 'hello world!').deliver
 
-      def initialize(configuration, to, subject, message)
-      	self.configuration = configuration
-      	self.to = to
-      	self.subject = subject
-      	self.message = message
-      end
+Looking at the line of code above, one might wonder why a user is being passed into the mailer service.  One might also wonder what properties of 'user' the mailer service is actually using.  Is the mailer only reading properties of my user or is it *changing* the user?  What if another developer comes along, noticing that the mailer is receiving a User model, and inadvertantly tightly couples MailerService to the User model?  That may not cause immediate problems, but down the road services and models can become more and more tightly coupled.  When you find yourself needing to use your service somewhere else you might find the de-coupling refactor to be a daunting task...
 
-      def deliver
-        # ... implement mail sending here
-      end
-    end
-
-This also works fine.  We can call the Mailer service and pass it a user:
-
-	MailerService.new(user, 'bob@example.com', 'test message', 'hello world!').deliver
-
-The problem isn't that it doesn't work, it does.  The problem is that the readability is low.  Looking at the line of code above, one might wonder why a user is being passed into the mailer service.  One might also wonder what properties of 'user' the mailer service is actually using.  Is the mailer only reading properties of my user or is it *changing* the user?  What if another developer comes along, noticing that the mailer is receiving a User model, and inadvertantly tightly couples MailerService to the User model?  That may not cause immediate problems, but down the road services and models can become more and more tightly coupled.  When you find yourself needing to use your service somewhere else you might find the de-coupling refactor to be a daunting task...
-
-So let's re-write this code using Interfaces.  First, let's define an interface:
+The Mailer service does not really need a User, what it needs is configuration.  So let's re-write this code using Interfaces.  First, let's define an interface:
 
 	class MailerConfiguration < Interface
 		abstract :email_server, :use_ssl?, :port, :use_html?, :email_sent_callback
 	end
 
-Then, when we call our mailer service we cast the 'user' object to be a MailerConfiguration object:
+Then, when we call our mailer service it will cast whatever object is passed in to be a MailerConfiguration object:
 
-	MailerService.new(user.as(MailerConfiguration), 'bob@example.com', 'test message', 'hello world!').deliver
+    class MailerService
+      attr_accessor :config, :to, :subject, :message
 
+      def initialize(config, to, subject, message)
+        self.config = config.as(MailerConfiguration)
+        ...
 
 Now it's clear that the user is being passed in because it contains configuration information.  Further, there is enforcement taking place-- if User did not implement one of the four required methods, a clear exception would be fired at runtime.  And if MailerService tries to call another method of User that is not defined in the MailerConfiguration interface, an exception will be thrown.  Lastly, there's one place to look to determine what methods are needed by MailerConfiguration-- the code is self documenting.
 
@@ -132,6 +117,11 @@ An interface may contain optional methods. If they are defined by a class then t
     TestInterface.new.field2
     => nil
 
+## Checking conformance
+
+    User.conforms_to?(TestInterface)
+    => true
+
 ## Typed accessors
 
 The typed_attr_accessor and typed_attr_writer helpers make it easy to create attributes that always conform to an interface:

data/lib/interfaces/castable.rb

@@ -20,6 +20,14 @@ module Interfaces
       end
     end
 
+    # returns true if an object conforms to the given interface (implements the abstract methods)
+    def conforms_to?(interface)
+      # interface must be an Interface
+      raise InterfaceError, "#{interface} is not an Interface" unless interface < Interface
+      interface.abstract_methods.all? { |method| self.respond_to?(method) }
+    end
+
+    # casts an object to an instance of a particular Interface
     def as(interface)
       # interface must be a class
       raise InterfaceError, "#{interface} is not a class" unless interface.is_a?(Class)

data/lib/interfaces/version.rb

@@ -1,3 +1,3 @@
 module Interfaces
-  VERSION = "0.0.2.pre"
+  VERSION = "0.2.0"
 end

data/spec/castable_spec.rb

@@ -31,6 +31,10 @@ describe Interfaces::Castable do
     let(:instance) { ClassConformingToTestInterface.new }
     let(:casted_instance) { instance.as(TestInterface) }
 
+    it 'instance should conform_to the TestInteface' do
+      instance.conforms_to?(TestInterface).should be_true
+    end
+
     it 'casted_instance should be an instance of TestInterface' do
       casted_instance.should be_a(TestInterface)
     end

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: interfaces
 version: !ruby/object:Gem::Version
-  version: 0.0.2.pre
-  prerelease: 6
+  version: 0.2.0
+  prerelease: 
 platform: ruby
 authors:
 - Justin Schumacher
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-05 00:00:00.000000000 Z
+date: 2014-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -101,9 +101,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23
@@ -116,4 +116,3 @@ test_files:
 - spec/interface_spec.rb
 - spec/spec_helper.rb
 - spec/typed_accessor_spec.rb
-has_rdoc: