expectation 0.3.1 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ba45fedcad85c3bc355804668620c834db45f2a1
+  data.tar.gz: 19766d7a77e76bd18e51e246ab1fee0ed0be3209
+SHA512:
+  metadata.gz: 321eeaddc541552fd4261b5b6b9ca5f2095280abdc974ef3cb104077f5fee924d4d53cdf3218d839decf553099073276e0fa3d22dae07af26ca1ca77030e1654
+  data.tar.gz: 6b40a3e8403b34dea1eac1d877b62c62a1a0d5d7de9798cda203e1492305e32fbe00ba5fc252803c746c6b9b4e47772a1c66d1787866f440e3a6f3aa88063551

data/lib/contracts.rb

@@ -0,0 +1,197 @@
+#--
+# Author::    radiospiel  (mailto:eno@radiospiel.org)
+# Copyright:: Copyright (c) 2011, 2012 radiospiel
+# License::   Distributes under the terms of the Modified BSD License, see LICENSE.BSD for details.
+#++
+
+# The Contract module provides annotation support. That basically
+# means you can define expectations outside (or, to be more specific, before)
+# the function definition.
+#
+# We currently support the following annotations:
+#
+# - expects!
+# - returns!
+#
+# == Example
+#
+#   class Foo
+#
+#     +Expects(value1: Fixnum, value2: /.@./)
+#     +Returns(Fixnum)
+#
+#     def bar(value1, value2)
+#     end
+#   end
+#
+module Contracts
+  class Error < ArgumentError; end
+
+  def self.current_contracts
+    Thread.current[:current_contracts] ||= []
+  end
+
+  def self.consume_current_contracts
+    r, Thread.current[:current_contracts] = Thread.current[:current_contracts], nil
+    r
+  end
+
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  class AnnotatedMethod
+    def initialize(method, annotations)
+      @method = method
+
+      @before_annotations     = annotations.select { |annotation| annotation.respond_to?(:before_call) }
+      @after_annotations      = annotations.select { |annotation| annotation.respond_to?(:after_call) }
+      @exception_annotations  = annotations.select { |annotation| annotation.respond_to?(:on_exception) }
+
+      annotations.each do |annotation|
+        annotation.method = method
+      end
+    end
+
+    def invoke(receiver, *args, &blk)
+      @before_annotations.each do |annotation|
+        annotation.before_call(receiver, *args, &blk)
+      end
+
+      # instance methods are UnboundMethod, class methods are Method.
+      rv = @method.is_a?(Method) ? @method.call(*args, &blk)
+                                 : @method.bind(receiver).call(*args, &blk)
+
+      @after_annotations.each do |annotation|
+        annotation.after_call(rv, receiver, *args, &blk)
+      end
+
+      return rv
+    rescue StandardError => exc
+      @exception_annotations.each do |annotation|
+        annotation.on_exception(exc, receiver, *args, &blk)
+      end
+      raise exc
+    end
+  end
+
+  module ClassMethods
+    def singleton_method_added(name)
+      if annotations = Contracts.consume_current_contracts
+        method = singleton_method(name)
+        annotated_method = Contracts::AnnotatedMethod.new(method, annotations)
+
+        klass = self
+
+        define_singleton_method name do |*args, &blk|
+          annotated_method.invoke klass, *args, &blk
+        end
+      end
+
+      super
+    end
+
+    def method_added(name)
+      if annotations = Contracts.consume_current_contracts
+        method = instance_method(name)
+        annotated_method = Contracts::AnnotatedMethod.new(method, annotations)
+
+        define_method name do |*args, &blk|
+          annotated_method.invoke self, *args, &blk
+        end
+      end
+
+      super
+    end
+  end
+
+  #
+  # A Base contract.
+  class Base
+    #
+    # This is the unary "+" operator. It adds the contract to the current_contracts array.
+    def +@
+      Contracts.current_contracts << self
+    end
+
+    #
+    # contains the method once the contract is initialized, which happens
+    # in the Class#{singleton_,}method_added callback.
+    attr :method, true
+
+    #
+    # Returns a description of the method; i.e. Class#name or Class.name
+    def method_name
+      if method.is_a?(Method)                               # A singleton method?
+        # The method owner is the singleton class of the class. Sadly, the
+        # the singleton class has no name; hence we try to construct the name
+        # from its to_s description.
+        klass_name = method.owner.to_s.gsub(/#<(.*?):(.*)>/, "\\2")
+        "#{klass_name}.#{method.name}"
+      else
+        "#{method.owner}##{method.name}"
+      end
+    end
+  end
+end
+
+require "expectation"
+
+class Contracts::Expects < Contracts::Base
+  attr :expectations
+
+  def initialize(expectations)
+    @expectations = expectations
+  end
+
+  def before_call(receiver, *args, &blk)
+    @parameter_names ||= method.parameters.map(&:last)
+
+    @parameter_names.each_with_index do |parameter_name, idx|
+      next unless expectation = expectations[parameter_name]
+
+      Expectation.match! args[idx], expectation
+    end
+  rescue Expectation::Error
+    raise Contracts::Error, "#{$!} in call to `#{method_name}`", caller[5..-1]
+  end
+end
+
+module Contracts::ClassMethods
+  def Expects(expectation)
+    expect! expectation => Hash
+    Contracts::Expects.new(expectation)
+  end
+end
+
+class Contracts::Returns < Contracts::Base
+  attr :expectation
+
+  def initialize(expectation)
+    @expectation = expectation
+  end
+
+  def after_call(rv, receiver, *args, &blk)
+    Expectation.match! rv, expectation
+  rescue Expectation::Error
+    raise Contracts::Error, "#{$!} in return of `#{method_name}`", caller[5..-1]
+  end
+end
+
+module Contracts::ClassMethods
+  def Returns(expectation)
+    Contracts::Returns.new(expectation)
+  end
+end
+
+class Contracts::Nothrows < Contracts::Base
+  def on_exception(rv, method, receiver, *args, &blk)
+    raise Contracts::Error, "Nothrow method `#{method_name}` raised exception: #{$!}", caller[5..-1]
+  end
+end
+
+module Contracts::ClassMethods
+  def Nothrow
+    Contracts::Nothrows.new
+  end
+end

data/lib/core/exception.rb

@@ -0,0 +1,15 @@
+#--
+# Author::    radiospiel  (mailto:eno@radiospiel.org)
+# Copyright:: Copyright (c) 2011, 2012 radiospiel
+# License::   Distributes under the terms of the Modified BSD License, see LICENSE.BSD for details.
+#++
+
+class Exception
+  # Create an ArgumentError with an adjusted backtrace. We don't want to 
+  # see the user all the annotation internals.
+  def reraise_with_current_backtrace!
+    set_backtrace caller[2..-1]
+    raise self
+  end
+end
+

data/lib/expectation/assertions.rb

@@ -3,24 +3,16 @@
 # Copyright:: Copyright (c) 2011, 2012 radiospiel
 # License::   Distributes under the terms of the Modified BSD License, see LICENSE.BSD for details.
 #++
-# By requiring "expectation/assertions" you add expect! und unexpect! assertions
-# to your test/unit testcases.
 
-if !defined?(::Expectation::Assertions)
-
-if !defined?(::Expectation)
-  require_relative "../expectation"
-end
 
 # The Expectation::Assertions module provides expect! and inexpect!
 # assertions to use from within test cases.
 #
 # == Example
-#
-#   require_relative 'test_helper'
-#   require 'expectation/assertions'
 # 
 #   class ExpectationTest < Test::Unit::TestCase
+#     include Expectation::Assertions
+#
 #     def test_one
 #     end
 #   end
@@ -28,23 +20,27 @@ end
 module Expectation::Assertions
   # verifies the passed in expectations
   def expect!(*expectation, &block)
-    good = Expectation.met_expectations?(*expectation, &block)
-    assert_block(Expectation.last_error) { good }
+    exc = nil
+
+    begin
+      Expectation.expect!(*expectation, &block)
+    rescue Expectation::Error
+      exc = $!
+    end
+
+    assert_block(exc && exc.message) { !exc }
   end
   
   # verifies the failure of the passed in expectations
   def inexpect!(*expectation, &block)
-    good = Expectation.met_expectations?(*expectation, &block)
-    assert_block("Expectation(s) should fail, but didn't") { !good }
-  end
-end
-
-end
+    exc = nil
 
-if !defined?(Test::Unit)
-  STDERR.puts "Please load 'test/unit' first"
-end
+    begin
+      Expectation.expect!(*expectation, &block)
+    rescue Expectation::Error
+      exc = $!
+    end
 
-class Test::Unit::TestCase
-  include Expectation::Assertions
+    assert_block("Expectation(s) should fail, but didn't") { exc }
+  end
 end

data/lib/expectation/version.rb

@@ -4,5 +4,5 @@
 # License::   Distributes under the terms of the Modified BSD License, see LICENSE.BSD for details.
 module Expectation
   # The expectation gem's version.
-  VERSION="0.3.1"
+  VERSION="1.0.0"
 end

data/lib/expectation.rb

@@ -3,6 +3,12 @@
 # Copyright:: Copyright (c) 2011, 2012 radiospiel
 # License::   Distributes under the terms of the Modified BSD License, see LICENSE.BSD for details.
 #++
+
+module Expectation; end
+
+require_relative "core/exception"
+require_relative "expectation/assertions"
+
 # The Expectation module implements methods to verify one or more values
 # against  set of expectations. This is a subset of
 # design-by-contract programming (see http://en.wikipedia.org/wiki/Design_by_contract)
@@ -24,136 +30,77 @@
 #   end
 
 module Expectation
-  def self.timeout=(timeout)
-    Thread.current[:expectation_timeout] = timeout
-  end
-
-  def self.timeout
-    Thread.current[:expectation_timeout]
-  end
-  
-  def self.last_error=(error)
-    Thread.current[:expectation_last_error] = error
-  end
-  
-  def self.last_error
-    Thread.current[:expectation_last_error]
-  end
-
-  def expect!(*expectations, &block)
-    return if Expectation.met_expectations?(*expectations, &block)
-
-    # build exception with adjusted backtrace.
-    backtrace = caller #[3 .. -1]
+  class Error < ArgumentError
+    attr :value, :expectation, :info
 
-    e = ArgumentError.new Expectation.last_error
-    e.singleton_class.send(:define_method, :backtrace) do
-      backtrace
+    def initialize(value, expectation, info = nil)
+      @value, @expectation, @info = 
+        value, expectation, info
+    end
+    
+    def to_s
+      message = "#{value.inspect} does not match #{expectation.inspect}"
+      message += ", #{info}" if info
+      message
     end
-
-    raise e
-  end  
-
-  # Verifies a number of expectations. If one or more expectations are 
-  # not met it raises an ArgumentError.
-  #
-  # This method can be enabled or disabled at runtime using 
-  # Expectation.enable and Expectation.disable.  
-  def expect(*expectations, &block)
-    expect!(*expectations, &block)
-  end
-  
-  # A do nothing expect method. This is the standin for expect, when
-  # Expectation are disabled.
-  def expect_dummy!(*expectations, &block) #:nodoc:
   end
 
-  # Verifies a number of expectations. Raises an ArgumentError if one
-  # or more expectations are not met.
   #
-  # In contrast to Expectation#expect this method can not be
-  # disabled at runtime.
-  def self.met_expectations?(*expectations, &block)
-    return false unless expectations.all? do |expectation|
-      case expectation
-      when Hash
-        expectation.all? { |value, e| Expectation.verify! value, e }
+  # Verifies a number of expectations. If one or more expectations are 
+  # not met it raises an ArgumentError (on the first failing expectation).
+  def expect!(*expectations, &block)
+    expectations.each do |expectation|
+      if expectation.is_a?(Hash)
+        expectation.all? do |actual, exp|
+          match! actual, exp
+        end
       else
-        Expectation.verify! expectation, :truish
+        match! expectation, :truish
       end
     end
 
-    return true unless block_given? 
-
-    # Dynamic expectation? When Expectation.timeout is set, we test the 
-    # dynamic expectation, i.e. the block, for a certain time period.
-    begin
-      timeout, Expectation.timeout = Expectation.timeout, nil
+    match! block, :__block if block
+  rescue Error
+    $!.reraise_with_current_backtrace!
+  end  
 
-      runs = timeout ? (timeout / 0.05).to_i : 0
-      runs = 1 if runs < 1
-      
-      runs.times.any? do
-        next true if Expectation.verify! 1, block
-        Thread.send :sleep, 0.05
-        false
-      end
-    ensure
-      Expectation.timeout = timeout
-    end
-  end
-  
-  # Does a value meet the expectation? Retruns +true+ or +false+. 
-  def self.met?(value, expectation) #:nodoc:
-    case expectation
-    when :truish  then !!value
-    when :fail    then false
-    when Array    then expectation.any? { |e| met?(value, e) }
-    when Proc     then expectation.arity == 0 ? expectation.call : expectation.call(value)
-    when Regexp   then value.is_a?(String) && expectation =~ value
-    else          expectation === value
-    end
+  #
+  # Does a value match an expectation?
+  def match?(value, expectation)
+    match! value, expectation
+    true
+  rescue Error
+    false
   end
 
-  # Verifies a value against an expectation; returns true if ok, 
-  # false if the expectation was not met. In case of an error 
-  # the Expectation.last_error value is set.
-  def self.verify!(value, expectation)
-    failed_value, failed_expectation, message = value, expectation, nil
-    
-    # Test expectation, collect failed_value, failed_expectation, failed_message
-    unless expectation.is_a?(Hash)
-      good = met?(value, expectation)
-    else
-      good = met?(value, Hash)
-      if good
-        good = expectation.all? do |key, expect|
-          next true if met?(value[key], expect)
-          
-          failed_value, failed_expectation, message = value[key], expect, "at key #{key.inspect}"
-          false
-        end
-      end
+  # Matches a value against an expectation. Raises an Expectation::Error
+  # if the expectation could not be matched.
+  def match!(value, expectation, key=nil)
+    match = case expectation
+      when :truish  then !!value
+      when :fail    then false
+      when Array    then expectation.any? { |e| _match?(value, e) }
+      when Proc     then expectation.arity == 0 ? expectation.call : expectation.call(value)
+      when Regexp   then value.is_a?(String) && expectation =~ value
+      when :__block then value.call
+      when Hash     then Hash === value && 
+                         expectation.each { |key, exp| match! value[key], exp, key }
+      else               expectation === value
     end
-    
-    # are we good?
-    return true if good
-    
-    Expectation.last_error = "#{failed_value.inspect} does not meet expectation #{failed_expectation.inspect}#{message && ", #{message}"}"
 
-    return false
-  end
+    return if match
 
-  # Enable the Expectation#expect method.
-  def self.enable
-    alias_method :expect, :expect!
+    raise Error.new(value, expectation, key && "at key #{key.inspect}")
   end
 
-  # Disable the Expectation#expect method.
-  def self.disable
-    alias_method :expect, :expect_dummy!
+  private
+
+  def _match?(value, expectation)
+    match! value, expectation
+    true
+  rescue Error
+    false
   end
 end
 
-Expectation.enable
 Object.send :include, Expectation

data/test/assertions_test.rb

@@ -2,9 +2,10 @@
 # Copyright:: Copyright (c) 2011, 2012 radiospiel
 # License::   Distributes under the terms  of the Modified BSD License, see LICENSE.BSD for details.
 require_relative 'test_helper'
-require "expectation/assertions"
 
 class AssertionsTest < Test::Unit::TestCase
+  include Expectation::Assertions
+
   def test_expectations
     expect! 1 => 1
     inexpect! 1 => 2

data/test/contracts_module_test.rb

@@ -0,0 +1,48 @@
+# Author::    radiospiel  (mailto:eno@radiospiel.org)
+# Copyright:: Copyright (c) 2011, 2012 radiospiel
+# License::   Distributes under the terms  of the Modified BSD License, see LICENSE.BSD for details.
+require_relative 'test_helper'
+
+require "contracts"
+
+class ContractsModuleTest < Test::Unit::TestCase
+  module M
+    include Contracts
+
+    +Expects(one: 1)
+    def needs_one(one)
+      one * 2
+    end
+  end
+
+  class Klass
+    extend M
+  end
+
+  class Instance
+    include M
+  end
+
+  def test_class_method
+    assert_nothing_raised() {
+      Klass.needs_one(1)
+    }
+
+    e = assert_raise(Contracts::Error) {
+      Klass.needs_one(2)
+    }
+    assert e.backtrace.first.include?("test/contracts_module_test.rb:")
+  end
+
+  def test_instance_method
+    instance = Instance.new
+    assert_nothing_raised() {
+      instance.needs_one(1)
+    }
+
+    e = assert_raise(Contracts::Error) {
+      instance.needs_one(2)
+    }
+    assert e.backtrace.first.include?("test/contracts_module_test.rb:")
+  end
+end

data/test/contracts_singleton_test.rb

@@ -0,0 +1,28 @@
+# Author::    radiospiel  (mailto:eno@radiospiel.org)
+# Copyright:: Copyright (c) 2011, 2012 radiospiel
+# License::   Distributes under the terms  of the Modified BSD License, see LICENSE.BSD for details.
+require_relative 'test_helper'
+
+require "contracts"
+
+class ContractsSingletonTest < Test::Unit::TestCase
+  class Foo
+    include Contracts
+
+    +Expects(one: 1)
+    def self.klass_method(one)
+      one * 2
+    end
+  end
+
+  def test_class_method
+    assert_nothing_raised() {
+      Foo.klass_method(1)
+    }
+
+    e = assert_raise(Contracts::Error) {
+      Foo.klass_method(2)
+    }
+    assert e.backtrace.first.include?("test/contracts_singleton_test.rb:")
+  end
+end

data/test/contracts_test.rb

@@ -0,0 +1,88 @@
+# Author::    radiospiel  (mailto:eno@radiospiel.org)
+# Copyright:: Copyright (c) 2011, 2012 radiospiel
+# License::   Distributes under the terms  of the Modified BSD License, see LICENSE.BSD for details.
+require_relative 'test_helper'
+
+require "contracts"
+
+class ContractsTest < Test::Unit::TestCase
+  class Foo
+    include Contracts
+
+    +Expects(a: 1)
+    def sum(a, b, c)
+      a + b + c
+    end
+
+    +Returns(2)
+    def returns_arg(r)
+      r
+    end
+
+    +Expects(v: Fixnum)
+    def throw_on_one(v)
+      raise if v == 1
+    end
+
+    +Nothrow()
+    def unexpected_throw_on_one(v)
+      raise if v == 1
+    end
+  end
+
+  attr :foo
+
+  def setup
+    @foo = Foo.new
+  end
+
+  def test_contracts_check_number_of_arguments
+    e = assert_raise(ArgumentError) {
+      foo.sum(1)        # scripts/test:67:in `f': wrong number of arguments (1 for 3) (ArgumentError)
+    }
+    assert e.backtrace.first.include?("test/contracts_test.rb:")
+  end
+
+  def test_expects_contract
+    rv = nil
+    assert_nothing_raised() { rv = foo.sum(1,2,3) }
+    assert_equal(rv, 6)
+
+    e = assert_raise(Contracts::Error) {
+      foo.sum(2,2,3)
+    }
+    assert e.backtrace.first.include?("test/contracts_test.rb:")
+  end
+
+  def test_returns_contract
+    assert_nothing_raised() {
+      foo.returns_arg(2)
+    }
+
+    e = assert_raise(Contracts::Error) {
+      foo.returns_arg(1)
+    }
+    assert e.backtrace.first.include?("test/contracts_test.rb:")
+  end
+
+  def test_nothrow_contract
+    assert_nothing_raised() {
+      foo.unexpected_throw_on_one(2)
+    }
+
+    e = assert_raise(Contracts::Error) {
+      foo.unexpected_throw_on_one(1)
+    }
+    assert e.backtrace.first.include?("test/contracts_test.rb:")
+  end
+
+  def test_still_throws_fine
+    assert_nothing_raised() {
+      foo.throw_on_one(2)
+    }
+
+    assert_raise(RuntimeError) {
+      foo.throw_on_one(1)
+    }
+  end
+end