lawyer 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e99be433808f11cb424f36b57b3ac474f2cd810e
+  data.tar.gz: 9eeebb6c71f45d45e054aa3a66a310409de86587
+SHA512:
+  metadata.gz: 6c2f4dd3603a8dd235adfd3efb6c7ad08a075f2410cb7b835e7c9b78a876e0194ed00c9bb2c6c9359b64d3fbc1764d982bc1e962c081a852d08452b93630f4df
+  data.tar.gz: 681467aa0759581e4410d1524ce7c67e6c0fc1148cb736417d057478d2b28910dbc7a50c850e6caa9bbf8efcfb881267724361aabf23369286494a660d5d107f

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/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require "spec_helper"

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 John Cinnamond
+
+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,141 @@
+# Lawyer
+
+Strong Duck Typing for Ruby.
+
+Lawyer allows you to create contracts that specify how an object behaves.
+
+	require 'lawyer'
+
+	class Pingable < Lawyer::Contract
+	  confirm :ping
+	end
+
+You can then ensure that your class implements the contract:
+
+	require 'pingable'
+
+    class Foo
+	  def ping
+	    puts "ping"
+	  end
+
+	  def pong
+	    puts "pong"
+	  end
+	end
+
+	Foo.implements(Pingable)
+
+...but this works best when you write loosely coupled objects and then define the
+interfaces between them. You can then write specs to check that a class implements
+a particular contract:
+
+    require 'foo'
+	require 'pingable'
+
+	describe Foo do
+	  it { should implement(Pingable) }
+	end
+
+...and use mocks to test methods that expect to receive objects that conform to
+a particular contract:
+
+	describe Pinger do
+	  let(:pingable) { contract_double(Pingable) }
+	  subject(:pinger) { Pinger.new(pingable) }
+
+	  it "pings the pingable" do
+	    subject.run
+		expect(:pingable).to have_received(:ping)
+	  end
+
+      it "can't call methods that aren't part of the contract" do
+	    expect { pingable.pong }.to raise_error(NoMethodError)
+	  end
+	end
+
+...all based off a single definition of the contract.
+
+This helps you to write loosely coupled code that relies on well defined interfaces.
+By declaring the contract up front and then using that in your tests you can ensure
+that any mismatches between the expected interface and the actual impelmentations are
+caught as you modify your codebase.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'lawyer'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install laywer
+
+## Usage
+
+First up, create a contract that specifies the methods available in an interface:
+
+    require 'lawyer'
+
+	module Contracts
+	  class Person < Lawyer::Contract
+	    check :name                               # check that the method exists
+		check :name= => 1                         # check the method arity
+		check :rename => [:firstname, :lastname]  # check required named parameters (ruby 2.1 only)
+	  end
+	end
+
+
+Add Laywer to your spec_helper:
+
+	require 'lawyer/rspec'
+
+	RSpec.configure do |config|
+	  config.include Lawyer::RSpec::Matchers
+      config.include Lawyer::RSpec::ContractDouble
+
+      # ...
+    end
+
+Test an implementation:
+
+    require 'contracts/person'
+	require 'person_record'
+
+	describe PersonRecord do
+	  it { should implement(Contracts::Person) }
+
+      # test the implementation
+	end
+
+And test a receiver:
+
+    require 'contracts/person'
+	require 'namer'
+
+    describe Namer do
+	  let(:person) { contract_double(Contracts::Person) }
+	  subject(:namer) { Namer.new(person) }
+
+      it "sets the name" do
+	    expect(person).to receive(:name=).with("John Smith")
+		namer.set_name("John Smith")
+	  end
+	end
+
+## Credits
+
+Many thanks to Jakub Oboza (http://lambdacu.be) for suggesting an original
+implementation of this idea and for discussing the motivations behind it.
+
+## Contributing
+
+1. Fork it ( http://github.com/jcinnamond/lawyer/fork )
+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,8 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+# If you want to make this the default task
+task :default => :spec

data/lawyer.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lawyer/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "lawyer"
+  spec.version       = Lawyer::VERSION
+  spec.authors       = ["John Cinnamond"]
+  spec.email         = ["jc@panagile.com"]
+  spec.summary       = %q{Strong Duck Typing for Ruby}
+  spec.homepage      = "http://github.com/jcinnamond/lawyer"
+  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.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
+end

data/lib/lawyer/broken_contract.rb

@@ -0,0 +1,38 @@
+module Lawyer
+  class BrokenContract < StandardError
+    def initialize(subject, contract, violations)
+      @subject = subject.name
+      @contract = contract.name
+      @method_missing_violations = violations.select { |v| v.is_a?(MethodMissingViolation) }
+      @wrong_arity_violations = violations.select { |v| v.is_a?(WrongArityViolation) }
+      @wrong_signature_violations = violations.select { |v| v.is_a?(WrongSignatureViolation) }
+    end
+
+    def to_s
+      str = "#{@subject} does not implement <#{@contract}>\n"
+      str << explain_violations(@method_missing_violations, "missing")
+      str << "\n" if @method_missing_violations &&
+                    (@wrong_arity_violations || @wrong_signature_violations)
+      str << explain_violations(@wrong_arity_violations, "with the wrong arity")
+      str << "\n" if (@method_missing_violations || @wrong_arity_violations) &&
+                     @wrong_signature_violations
+      str << explain_violations(@wrong_signature_violations, "with the wrong signature")
+      str
+    end
+
+    def explain_violations(violations, type)
+      str = ""
+      if violations.any?
+        count = violations.count
+        str << "\t(#{count} #{methods(count)} #{type})\n"
+        str << violations.map(&:to_s).join("\n")
+        str << "\n"
+      end
+      str
+    end
+
+    def methods(count)
+      count == 1 ? "method" : "methods"
+    end
+  end
+end

data/lib/lawyer/clause.rb

@@ -0,0 +1,72 @@
+require 'lawyer/method_missing_violation'
+require 'lawyer/wrong_arity_violation'
+require 'lawyer/wrong_signature_violation'
+
+module Lawyer
+  class Clause
+    attr_reader :name
+
+    def initialize(params)
+      @arity = nil
+      @signature = nil
+
+      if params.is_a?(Hash)
+        (@name, details) = params.first
+        case details
+        when Fixnum
+          @arity = details
+        when Array
+          @signature = details
+        end
+      else
+        @name = params.to_sym
+      end
+    end
+
+    def check(subject)
+      if missing_method?(subject)
+        Lawyer::MethodMissingViolation.new(@name)
+      elsif wrong_arity?(subject)
+        Lawyer::WrongArityViolation.new(@name, expected: @arity, actual: actual_arity(subject))
+      elsif wrong_signature?(subject)
+        Lawyer::WrongSignatureViolation.new(@name,
+          missing: missing_parameters(subject),
+          extra: extra_parameters(subject))
+      else
+        nil
+      end
+    end
+
+    def missing_method?(subject)
+      !subject.instance_methods.include?(@name)
+    end
+
+    def wrong_arity?(subject)
+      @arity && @arity != actual_arity(subject)
+    end
+
+    def actual_arity(subject)
+      method_from(subject).arity
+    end
+
+    def wrong_signature?(subject)
+      @signature && (missing_parameters(subject).any? || extra_parameters(subject).any?)
+    end
+
+    def missing_parameters(subject)
+      @signature - actual_signature(subject)
+    end
+
+    def extra_parameters(subject)
+      actual_signature(subject) - @signature
+    end
+
+    def actual_signature(subject)
+      method_from(subject).parameters.select { |p| p[0] == :keyreq }.map(&:last) || []
+    end
+
+    def method_from(subject)
+      subject.instance_method(@name)
+    end
+  end
+end

data/lib/lawyer/contract.rb

@@ -0,0 +1,28 @@
+require 'lawyer/clause'
+
+module Lawyer
+  class Contract
+    class << self
+      def clauses
+        @clauses ||= []
+      end
+
+      def confirm(clause)
+        self.clauses << Lawyer::Clause.new(clause)
+      end
+
+      def check!(subject)
+        klass = subject.is_a?(Class) ? subject : subject.class
+
+        violations = self.clauses.map do |clause|
+          clause.check(klass)
+        end
+        violations.compact!
+
+        if violations.any?
+          raise Lawyer::BrokenContract.new(klass, self, violations)
+        end
+      end
+    end
+  end
+end

data/lib/lawyer/method_missing_violation.rb

@@ -0,0 +1,11 @@
+module Lawyer
+  class MethodMissingViolation
+    def initialize(name)
+      @name = name
+    end
+
+    def to_s
+      "\t[missing] #{@name}"
+    end
+  end
+end

data/lib/lawyer/rspec/contract_double.rb

@@ -0,0 +1,13 @@
+module Lawyer
+  module RSpec
+    module ContractDouble
+      def contract_double(contract)
+        methods = {}
+        contract.clauses.each do |clause|
+          methods[clause.name] = true
+        end
+        double(contract.name, methods)
+      end
+    end
+  end
+end

data/lib/lawyer/rspec/matchers.rb

@@ -0,0 +1,25 @@
+require 'rspec/expectations'
+
+module Lawyer
+  module RSpec
+    module Matchers
+      extend ::RSpec::Matchers::DSL
+
+      matcher :implement do |contract|
+        match do |implementation|
+          begin
+            contract.check!(implementation)
+            true
+          rescue Lawyer::BrokenContract => e
+            @exception = e
+            false
+          end
+        end
+
+        failure_message_for_should do |actual|
+          @expectation.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lawyer/rspec.rb

@@ -0,0 +1,2 @@
+require 'lawyer/rspec/matchers'
+require 'lawyer/rspec/contract_double'

data/lib/lawyer/version.rb

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

data/lib/lawyer/wrong_arity_violation.rb

@@ -0,0 +1,13 @@
+module Lawyer
+  class WrongArityViolation
+    def initialize(name, expected:, actual:)
+      @name = name
+      @expected = expected
+      @actual = actual
+    end
+
+    def to_s
+      "\t[wrong arity] #{@name} (takes #{@actual}, requires #{@expected})"
+    end
+  end
+end

data/lib/lawyer/wrong_signature_violation.rb

@@ -0,0 +1,16 @@
+module Lawyer
+  class WrongSignatureViolation
+    def initialize(name, missing:, extra:)
+      @name = name
+      @missing = missing
+      @extra = extra
+    end
+
+    def to_s
+      details = []
+      details << "missing #{@missing}" if @missing.any?
+      details << "extra #{@extra}" if @extra.any?
+      "\t[wrong signature] #{@name} (#{details.join(', ')})"
+    end
+  end
+end

data/lib/lawyer.rb

@@ -0,0 +1,8 @@
+require 'lawyer/version'
+require 'lawyer/contract'
+require 'lawyer/broken_contract'
+
+require 'monkey_patch/module'
+
+module Lawyer
+end

data/lib/monkey_patch/module.rb

@@ -0,0 +1,5 @@
+class Module
+  def implements(contract)
+    contract.check!(self)
+  end
+end

data/spec/lib/lawyer/contract_spec.rb

@@ -0,0 +1,73 @@
+class TestContract < Lawyer::Contract
+  confirm :ping
+  confirm :pong => 2
+  confirm :pung => [:name, :size]
+end
+
+describe TestContract do
+  before :each do
+    # Stop modifications to the TestObject from leaking into other specs.
+    Object.send(:remove_const, :TestObject) if Object.const_defined?(:TestObject)
+    class TestObject;
+      def pong(a1); end
+      def pung(name:, hats:); end
+    end
+  end
+
+  describe "#check!" do
+    context "with a compliant object" do
+      before :each do
+        # Reopen the class and define the required methods
+        class TestObject;
+          def ping; end
+          def pong(a1, a2); end
+          def pung(name:, size:); end
+        end
+      end
+
+      it "does not raise an exception when checking a class" do
+        expect { TestContract.check!(TestObject) }.not_to raise_error
+      end
+
+      it "does not raise an exception when checking an object" do
+        expect { TestContract.check!(TestObject.new) }.not_to raise_error
+      end
+    end
+
+    context "with a non-compliant object" do
+      it "raises a BrokenContract exception when checking a class" do
+        expect { TestContract.check!(TestObject) }.to raise_error(Lawyer::BrokenContract)
+      end
+
+      it "raises a BrokenContract exception when checking an object" do
+        expect { TestContract.check!(TestObject.new) }.to raise_error(Lawyer::BrokenContract)
+      end
+
+      describe "the exception" do
+        before :each do
+          begin
+            TestContract.check!(TestObject)
+          rescue Lawyer::BrokenContract => e
+            @exception = e
+          end
+        end
+
+        it "includes the offending class and contract" do
+          expect(@exception.to_s).to include("TestObject does not implement <TestContract>\n")
+        end
+
+        it "includes the missing method details in the exception" do
+          expect(@exception.to_s).to include("\t(1 method missing)\n\t[missing] ping\n")
+        end
+
+        it "includes the incorrect arity details in the exception" do
+          expect(@exception.to_s).to include("\t(1 method with the wrong arity)\n\t[wrong arity] pong (takes 1, requires 2)\n")
+        end
+
+        it "includes required argument mismatch details in the exception" do
+          expect(@exception.to_s).to include("\t(1 method with the wrong signature)\n\t[wrong signature] pung (missing [:size], extra [:hats])\n")
+        end
+      end
+    end
+  end
+end

data/spec/lib/lawyer/rspec/contract_double_spec.rb

@@ -0,0 +1,15 @@
+require 'lawyer/rspec'
+
+class DoublableContract < Lawyer::Contract
+  confirm :ping
+end
+
+describe Lawyer::RSpec::ContractDouble do
+  include Lawyer::RSpec::ContractDouble
+
+  subject { contract_double(DoublableContract)  }
+
+  it { should be_a(RSpec::Mocks::Mock) }
+  it { should respond_to(:ping) }
+  it { should_not respond_to(:pong) }
+end

data/spec/lib/lawyer/rspec/matchers_spec.rb

@@ -0,0 +1,28 @@
+require 'lawyer/rspec'
+
+describe Lawyer::RSpec::Matchers do
+  include Lawyer::RSpec::Matchers
+  let(:subject) { double("Module", name: "Module") }
+  let(:contract) { double("contract", check!: true, name: "Contract") }
+
+  it "defines 'implement'" do
+    expect(subject).to implement(contract)
+  end
+
+  it "calls checks the subject against the contract" do
+    expect(contract).to receive(:check!).with(subject)
+    expect(subject).to implement(contract)
+  end
+
+  context "with violations" do
+    let(:broken_contract) { Lawyer::BrokenContract.new(subject, contract, []) }
+
+    before :each do
+      allow(contract).to receive(:check!).and_raise(broken_contract)
+    end
+
+    it "fails the matcher" do
+      expect(subject).not_to implement(contract)
+    end
+  end
+end

data/spec/module_spec.rb

@@ -0,0 +1,11 @@
+describe Module do
+  describe "#implements" do
+    it "checks the module against the contract" do
+      class A; end
+
+      contract = double("contract")
+      expect(contract).to receive(:check!).with(A)
+      A.implements(contract)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'lawyer'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: lawyer
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- John Cinnamond
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-01-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+description: 
+email:
+- jc@panagile.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lawyer.gemspec
+- lib/lawyer.rb
+- lib/lawyer/broken_contract.rb
+- lib/lawyer/clause.rb
+- lib/lawyer/contract.rb
+- lib/lawyer/method_missing_violation.rb
+- lib/lawyer/rspec.rb
+- lib/lawyer/rspec/contract_double.rb
+- lib/lawyer/rspec/matchers.rb
+- lib/lawyer/version.rb
+- lib/lawyer/wrong_arity_violation.rb
+- lib/lawyer/wrong_signature_violation.rb
+- lib/monkey_patch/module.rb
+- spec/lib/lawyer/contract_spec.rb
+- spec/lib/lawyer/rspec/contract_double_spec.rb
+- spec/lib/lawyer/rspec/matchers_spec.rb
+- spec/module_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/jcinnamond/lawyer
+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.0
+signing_key: 
+specification_version: 4
+summary: Strong Duck Typing for Ruby
+test_files:
+- spec/lib/lawyer/contract_spec.rb
+- spec/lib/lawyer/rspec/contract_double_spec.rb
+- spec/lib/lawyer/rspec/matchers_spec.rb
+- spec/module_spec.rb
+- spec/spec_helper.rb