duckpond 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 515a4dbf8c5dfcc7ac533ebc75579053972755fe
+  data.tar.gz: 2b99253f7d6f981e307a01fa324ba20d3bb0dc87
+SHA512:
+  metadata.gz: 21b5db87d898f1c3759fed7c1beb9b254d57e32646daddaff7808d072ee42ca206d6f128b96656bd29d6996b1e565863ac0ca5a4aa1c14e43056ad751b3defae
+  data.tar.gz: 8a4f5c3892a69fbc10bb59deee0d20f0bdec7e046fb31ce0076d7dc7b8eb7a8c8bd767b8469aa8aea676d9fd31c6f6193ded7b5e3b3a03f7d6afc903edf08f0e

data/.gitignore

@@ -0,0 +1,34 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,17 @@
+PATH
+  remote: .
+  specs:
+    duckpond (1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (10.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.3)
+  duckpond!
+  rake

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Mikey Hogarth
+
+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 @@
+# Duckpond
+
+Explicit duck typing for ruby.
+
+
+## Inspiration
+
+Duck Typing can make code confusing and unreadable, particularly 
+when multiple developers are working on the same project or when 
+projects are inherited by new developers. 
+
+The spec folder has two files that go through the purpose of this gem
+in spec form. This would be a good place to start, although there is a crash 
+course below.
+
+* [the_problem_spec](spec/the_problem_spec.rb) - This outlines the problems with duck typing.
+
+* [the_solution_spec](spec/the_solution_spec.rb) - This outlines how duckpond gets around these problems.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'duckpond'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install duckpond
+
+
+## Usage
+
+Usage is demonstrated in 'the_solution_spec', but in a nutshell you can create 
+"duck" classes by inheriting from DuckPond::Duck. This file should be commented
+extensively as it describes the contract the duck represents. 
+
+    class MyDuck < DuckPond::Duck
+      quacks_like :length
+    end
+
+Once you've declared a duck, you can use "binoculars" to see if objects quack like
+that duck:
+
+    obj = "Hello World"
+    sighting = DuckPond::Binoculars.identify(obj)
+    sighting.quacks_like? MyDuck
+    => true
+
+There are other syntaxes:
+
+    #This syntax gets all the comparison done in one line
+    DuckPond::Binoculars.confirm(obj, MyDuck)
+    => true
+
+    #This syntax does the same thing, but raises an excaption instead of returning false 
+    DuckPond::Binoculars.confirm!(obj, MyDuck)
+
+
+Ducks can be combined into composite "super ducks" using the looks_like method - ducks which are made up of various other ducks:
+
+    class MySuperDuck < DuckPond::Duck
+      looks_like MyDuck
+      looks_like MyOtherDuck
+    end
+
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/duckpond.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'duckpond/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "duckpond"
+  spec.version       = Duckpond::VERSION
+  spec.authors       = ["Mikey Hogarth"]
+  spec.email         = ["mikehogarth20@hotmail.com"]
+  spec.description   = %q{Explicit duck-typing for ruby}
+  spec.summary       = %q{Explicit duck-typing for ruby}
+  spec.homepage      = "https://github.com/mikeyhogarth/duckpond"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(spec)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake", "~> 0"
+end

data/lib/duckpond/binoculars.rb

@@ -0,0 +1,57 @@
+#
+# DuckPond::Binoculars
+#
+# Binoculars are the users interface to the ducks themselves and 
+# are responsible for building "sightings" out of objects. There
+# are also a couple of convinience methods on here to perform 
+# common duck-spotting tasks.
+#
+module DuckPond
+  class Binoculars
+    class WrongDuckError < TypeError;end
+
+    # The sighted object
+    attr_reader :sighting
+
+    #
+    # identify (class and instance level version)
+    #
+    # receives any ruby object, returns a "sighting" of that object
+    #
+    def identify(obj)
+      @sighting = DuckPond::Sighting.new(obj)
+    end
+
+    def self.identify(obj)
+      DuckPond::Sighting.new(obj)
+    end
+
+    #
+    # confirm
+    #
+    # receives any ruby object and a duck class
+    # returns true if the object quacks like the duck, 
+    # otherwise false.
+    #
+    def self.confirm(obj, duck)
+      binoculars = DuckPond::Binoculars.new
+      sighting = binoculars.identify(obj)
+      return false unless sighting.quacks_like?(duck)
+      true
+    end
+
+    #
+    # confirm!
+    #
+    # does exactly the same as the standard confirm
+    # method, but raises an exception if the object
+    # does not quack like the duck.
+    #
+    def self.confirm!(obj, duck)
+      raise WrongDuckError unless confirm(obj, duck)
+    end
+
+  end
+end
+
+

data/lib/duckpond/duck.rb

@@ -0,0 +1,43 @@
+# 
+# DuckPond::Duck
+#
+# Ducks are essentially "contracts" or "interfaces". They are not intended
+# to ever be instantiated, and are completely configured at the class level.
+#
+module DuckPond
+  class Duck
+    class << self
+
+      def quacks
+        @quacks ||= []
+      end
+      
+      #
+      # quacks_like
+      #
+      # Use this to specify that this duck quacks with
+      # a certain method.
+      #
+      def quacks_like(method)
+        quacks << method
+      end
+
+      #
+      # looks_like
+      #
+      # Use this to specify that this duck looks like
+      # another duck.
+      #
+      def looks_like(other_duck)
+        other_duck.quacks.each do |other_ducks_quacking|
+          quacks_like other_ducks_quacking
+        end
+      end
+
+      def quacks_like?(method)
+        quacks.include?(method)
+      end
+
+    end
+  end
+end

data/lib/duckpond/sighting.rb

@@ -0,0 +1,36 @@
+#
+# DuckPond::Sighting
+#
+# The duckpond sighting class is essentially just a wrapper for the sighted
+# object, used here to avoid un-nessecary monkey patching.
+#
+module DuckPond
+  class Sighting
+
+    # the wrapped object
+    attr_reader :sighted_object
+
+    #
+    # initialize
+    #
+    # Construct with any ruby object. 
+    #
+    def initialize(sighted_object)
+      @sighted_object = sighted_object
+    end
+
+    # 
+    # quacks_like? 
+    #
+    # receives exactly one duck, and returns true/false if
+    # the sighted object responds to the same methods indicated
+    # by the duck's quacks.
+    #
+    def quacks_like?(duck)
+      duck.quacks.each do |quack|
+        return false unless @sighted_object.respond_to? quack
+      end
+      true
+    end
+  end
+end

data/lib/duckpond/version.rb

@@ -0,0 +1,3 @@
+module Duckpond
+  VERSION = "1.0.0"
+end

data/lib/duckpond.rb

@@ -0,0 +1,7 @@
+require 'duckpond/version'
+require 'duckpond/duck'
+require 'duckpond/binoculars'
+require 'duckpond/sighting'
+
+module Duckpond
+end

data/spec/binoculars_spec.rb

@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+module DuckPond
+  describe Binoculars do
+  
+    let(:obj) { Object.new }
+
+    describe '#identify' do
+      it 'returns any ruby object, in "sighting" form' do
+        bins = Binoculars.new
+        sighting = bins.identify(obj)
+        expect(sighting).to be_a Sighting
+        expect(sighting.sighted_object). to be obj
+      end
+    end
+
+    describe ".identify" do
+      it 'returns any ruby object, in "sighting" form' do
+        sighting = Binoculars.identify(obj)
+        expect(sighting).to be_a Sighting
+        expect(sighting.sighted_object). to be obj
+      end
+    end
+
+    describe '.confirm' do
+
+      class StringDuck < Duck
+        quacks_like :to_s
+        quacks_like :length
+      end
+
+      context 'when given a ruby object and a duck class that it quacks like' do
+        it 'returns true' do
+          expect(DuckPond::Binoculars.confirm("Hello World", StringDuck)).to be true
+        end
+      end
+
+      context 'when given a ruby object and a duck class that it doesnt quacks like' do
+        it 'returns false' do
+          expect(DuckPond::Binoculars.confirm(Object.new, StringDuck)).to be false
+        end
+      end
+    end
+
+    describe '.confirm!' do
+      it 'behaves like the un-banged version, but raises an error if it doesnt quack right' do
+        expect {DuckPond::Binoculars.confirm!(Object.new, StringDuck)}.to raise_error
+      end
+    end
+
+  end
+end

data/spec/classes/fooinator.rb

@@ -0,0 +1,10 @@
+module Duckpond
+  module Test
+    class Fooinator
+      def bar(obj)
+        obj
+      end
+    end
+  end
+end
+

data/spec/duck_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+module DuckPond
+
+  describe Duck do
+    describe 'attributes' do
+      context '.quackings' do
+        it 'responds to and memoizes the result' do
+          expect(Duck).to respond_to :quacks
+          expect(Duck.quacks).to be_an Array
+          expect(Duck.quacks).to be_empty
+        end
+      end
+    end
+  end
+
+  class MyDuck < Duck
+    quacks_like :foo
+    quacks_like :bar
+  end
+
+  describe MyDuck do
+    context '.quackings' do
+      it 'quacks like foo and bar' do
+        quacks = MyDuck.quacks
+        expect(quacks.length).to eq 2
+        expect(quacks).to include :foo
+        expect(quacks).to include :bar
+      end
+    end
+
+    describe '.quacks_like?' do
+      it 'returns true if the argument is in the quackings' do
+        expect(MyDuck.quacks_like? :foo).to be true
+        expect(MyDuck.quacks_like? :chunky_bacon).to be false
+      end
+    end
+  end
+
+  class MySimilarDuck < Duck
+    looks_like MyDuck
+    quacks_like :chunky_bacon
+  end
+
+  describe MySimilarDuck do
+    it 'retains its parents quackings' do
+      expect(MySimilarDuck.quacks_like? :chunky_bacon).to be true
+      expect(MySimilarDuck.quacks_like? :foo).to be true
+      expect(MySimilarDuck.quacks_like? :bar).to be true
+    end
+  end
+
+end

data/spec/sighting_spec.rb

@@ -0,0 +1,38 @@
+require 'ostruct'
+
+module DuckPond
+  describe Sighting do
+
+    describe '#initialize' do
+      it 'is constructed using any ruby object' do
+        obj = Object.new
+        sighting = Sighting.new(obj)
+        expect(sighting.sighted_object).to be obj
+      end
+    end
+
+    describe '#quacks_like?' do
+
+      class MyChunkyBaconDuck < Duck
+        quacks_like :chunky_bacon
+      end
+
+      context 'when the sighted object quacks like the duck' do
+        it 'returns true' do
+          obj = OpenStruct.new(:chunky_bacon => :mmm)
+          sighting = Sighting.new(obj)
+          expect(sighting.quacks_like? MyChunkyBaconDuck).to be true
+        end
+      end
+
+      context 'when the sighted object does not quack like the duck' do
+        it 'returns false' do
+          obj = OpenStruct.new(:vegan_fallafal => :yuck)
+          sighting = Sighting.new(obj)
+          expect(sighting.quacks_like? MyChunkyBaconDuck).to be false
+        end
+      end
+
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'duckpond'
+require 'classes/fooinator'

data/spec/the_problem_spec.rb

@@ -0,0 +1,120 @@
+require 'spec_helper'
+
+module Duckpond
+  describe 'The Problem' do
+    context 'when a method is called' do
+      it 'is often difficult to see what parameters are allowed' do
+
+        # 
+        # Take this class for instance...
+        #
+        # It has a single method which;
+        #
+        # * Calls an instance method on its parameter.
+        # * Sends its parameter off to some other object.
+        # * Creates an instance variable with the result.
+        #
+
+        class Foo
+          def self.bar(obj)
+            obj.foo!
+            fooinator = Test::Fooinator.new
+            @fooified_obj = fooinator.foo(obj)
+          end
+        end
+
+        # 
+        # From an architectural perspective, there is really nothing
+        # wrong with this class/method. Even from a design perspective
+        # the only thing that you can really criticize is that the 
+        # method is a little vague in terms of what it does, and that's just 
+        # because we don't know what "fooing" is.
+        # 
+        # But there are a few other problems.
+        #
+        # You will often hear rubyists talking about the wonder of
+        # "duck typing". Developers can pass anything they want to the "bar" 
+        # method above and it'll still work so long as the parameter responds 
+        # to certain methods etc.
+        #
+        # You will almost as often hear programmers freaking out about how 
+        # chaotic and crazy this approach is! Arguments about such matters usually
+        # eventually gravitate towards the problem being that ruby is not 
+        # strongly typed. The knowledge about what "ducks" can be sent to the
+        # :bar method is not stored anywhere: it's implicit in obj's usage. Great if
+        # you were the developer of the method and you understand it completely, 
+        # but what if it's someone else?
+        #
+        # In the above example, in order to see which type of object they can 
+        # pass to the "bar" method, a developer would at the very least need
+        # to:
+        #
+        # * Grep for "foo!" to see what the hell it does
+        # * See what the hell a "Fooinator" does
+        # * Look at the fooinator#foo method to see what the hell THAT does
+        # * Look for all instances of @fooified_obj and see what the hell THOSE DO
+        #
+        # And even if they do all that, there's a chance they might miss something.
+        # If they do miss something, this will likely manifest itself in an error
+        # further up the stack, such as method missing exceptions etc., in places
+        # OTHER than where the actual mistake was made. 
+        #
+        # Nightmare!
+        #
+        # Wouldn't it be nice if the "bar" method did a check or two, or even  raised 
+        # an exception when it was passed an object that wasn't compatible with its 
+        # functionality? You could do this yourself manually:
+        #
+        
+        class Foo
+          def self.bar(obj)
+            raise TypeError unless obj.respond_to?(:foo!) && obj.respond_to?(:chunky_bacon)
+
+            obj.foo!
+            fooinator = Test::Fooinator.new
+            @fooified_obj = fooinator.foo(obj)
+          end
+        end
+
+        # 
+        # But now you've got more problems!
+        #
+        # * The method is now becoming longer and messier.
+        # * The "knowledge" about what :bar can receive is stored within the
+        # :bar method itself, but that knowledge may be needed elsewhere. 
+        #
+        # Wouldn't it be nice if there was a neat way to store knowledge about all 
+        # our ducks in one place, and to be able to reference them whenever we need to.
+        #
+        # Although duck typing is seen as a ruby technique, it is actually 
+        # used in other languages too but the contract in strongly typed languages
+        # is made explicit through the use of interfaces. In c#, for example:
+        #
+        # public string foo(IMyInterface interface)
+        # {
+        #   //your implementation here. A confused developer
+        #   //could go off and look in IMyInterface to see what
+        #   //this "duck" is meant to do. 
+        # }
+        #
+        # As ruby is not strongly typed, you don't have this reference and the code
+        # becomes impossible for other developers to use!
+        #
+        # This is the problem duckpond hopes to solve.
+        #
+
+        class Reader
+          def intrigued?
+            true
+          end
+        end
+
+        the_reader = Reader.new
+        expect(the_reader).to be_intrigued
+
+      end
+    end
+  end
+end
+
+

data/spec/the_solution_spec.rb

@@ -0,0 +1,102 @@
+require "spec_helper"
+
+module DuckPond
+  describe "The Solution" do
+    context 'when a method is called' do
+      it 'pays to use duckpond' do
+
+        #
+        # First, declare a duck.
+        #
+
+        class ObjDuck < DuckPond::Duck
+          quacks_like :to_s
+          quacks_like :length
+        end
+
+        #
+        # Grab a pair of binoculars...
+        #
+        
+        binoculars = DuckPond::Binoculars.new
+
+        # 
+        # Now, lets say you have an object...
+        #
+
+        obj = "Hello World"
+
+        #
+        # You can "spot" it with your binoculars...
+        #
+
+        sighting = binoculars.identify(obj)
+
+        #
+        # And now you can compare your sightings with your ducks!
+        #
+
+        result = sighting.quacks_like?(ObjDuck)
+        expect(result).to be true
+
+        #
+        # You could check all of this within a method:
+        #
+
+        binoculars = DuckPond::Binoculars.new
+        sighting = binoculars.identify(obj)
+        raise TypeError unless sighting.quacks_like?(ObjDuck)
+       
+        #
+        # But because this trio of lines are so common, a
+        # convinience method exists to perform all three at
+        # once:
+        #
+
+        result = DuckPond::Binoculars.confirm(obj, ObjDuck)
+        expect(result).to be true
+
+        #
+        # The "bang" version will raise an error if the object isn't the duck.
+        #
+        
+        expect { DuckPond::Binoculars.confirm!(Object.new, ObjDuck) }.to raise_error TypeError
+
+
+        #
+        # So, going back to that example from the problem_spec
+        #
+        
+        class Foo
+          def self.bar(obj)
+            DuckPond::Binoculars.confirm!(obj,ObjDuck) 
+
+            obj.foo!
+            fooinator = Test::Fooinator.new
+            @fooified_obj = fooinator.foo(obj)
+          end
+        end
+
+
+        #
+        # Viola!
+        #
+        # Final Tips: 
+        #
+        # * Ducks should be commented liberally. They form the descripiton
+        # of a contract just as interfaces would in strongly typed languages.
+        # Developers will be prompted to consult the duck when they see a pair
+        # of binoculars in your code, so make sure they find what they're looking
+        # for.
+        #
+        # * Rather than writing the duckpond functionality directly within the methods
+        # themselves, you could easily put them in hooks or method aliases. If you do this
+        # though, remember that the point of this app is to make things *more* visible, not
+        # less, so don't go tucking these duck checks too far away from where they are needed
+        # or leave an obvious trail if you do!
+        #
+
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: duckpond
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Mikey Hogarth
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Explicit duck-typing for ruby
+email:
+- mikehogarth20@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- duckpond.gemspec
+- lib/duckpond.rb
+- lib/duckpond/binoculars.rb
+- lib/duckpond/duck.rb
+- lib/duckpond/sighting.rb
+- lib/duckpond/version.rb
+- spec/binoculars_spec.rb
+- spec/classes/fooinator.rb
+- spec/duck_spec.rb
+- spec/sighting_spec.rb
+- spec/spec_helper.rb
+- spec/the_problem_spec.rb
+- spec/the_solution_spec.rb
+homepage: https://github.com/mikeyhogarth/duckpond
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Explicit duck-typing for ruby
+test_files:
+- spec/binoculars_spec.rb
+- spec/classes/fooinator.rb
+- spec/duck_spec.rb
+- spec/sighting_spec.rb
+- spec/spec_helper.rb
+- spec/the_problem_spec.rb
+- spec/the_solution_spec.rb