expectation 0.1.1

data/README.md

@@ -0,0 +1,23 @@
+# Expect
+
+## Installation
+
+    gem install expectations
+
+## Getting started
+
+This function expects a String argument starting with "http:", an Integer or Float argument, and a Hash
+with a String entry at key `:foo`, and either an Array or nil at key `:bar`.
+
+    def function(a, b, options = {})
+      expect! a => /^http:/, 
+              b => [Integer, Float], 
+              options => {
+                :foo => String,
+                :bar => [ Array, nil ]
+              }
+    end
+    
+## License
+
+The expectations gem is distributed under the terms of the Modified BSD License, see LICENSE.BSD for details.

data/lib/expectation/version.rb

@@ -0,0 +1,8 @@
+#--
+# 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.
+module Expectation
+  # The expectation gem's version.
+  VERSION="0.1.1"
+end

data/lib/expectation.rb

@@ -0,0 +1,120 @@
+#--
+# 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 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)
+# features, and should speed you up during development phases.
+#
+# == Example
+#
+# This function expects a String argument starting with <tt>"http:"</tt>, 
+# an Integer or Float argument, and a Hash with a String entry at key 
+# <tt>:foo</tt>, and either an Array or +nil+ at key <tt>:bar</tt>.
+# 
+#   def function(a, b, options = {})
+#     expect! a => /^http:/, 
+#             b => [Integer, Float], 
+#             options => {
+#               :foo => String,
+#               :bar => [ Array, nil ]
+#             }
+#   end
+
+module Expectation
+  # 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 expect!(*expectations, &block)
+    if block_given?
+      Expectation.verify! true, block
+    end
+    
+    expectations.each do |expectation|
+      case expectation
+      when Hash
+        expectation.each do |value, e|
+          Expectation.verify! value, e
+        end
+      else
+        Expectation.verify! expectation, :truish
+      end
+    end
+  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
+  
+  # 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
+  end
+
+  # Verifies a value against an expectation. Builds and raises
+  # an ArgumentError exception if the expectation is not met.
+  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
+    end
+    
+    # are we good?
+    return if good
+
+    # build exception with adjusted backtrace.
+    backtrace = caller[5 .. -1]
+    
+    e = ArgumentError.new "#{failed_value.inspect} does not meet expectation #{failed_expectation.inspect}#{message && ", #{message}"}"
+    e.singleton_class.send(:define_method, :backtrace) do
+      backtrace
+    end
+    raise e
+  end
+
+  # Enable the Expectation#expect method.
+  def self.enable
+    alias_method :expect, :expect!
+  end
+
+  # Disable the Expectation#expect method.
+  def self.disable
+    alias_method :expect, :expect_dummy!
+  end
+end
+
+Expectation.enable
+Object.send :include, Expectation

data/test/expect_test.rb

@@ -0,0 +1,119 @@
+# 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'
+
+class ExpectationTest < Test::Unit::TestCase
+  def assert_expectation!(*expectation, &block)
+    assert_nothing_raised do
+      expect! *expectation, &block
+    end
+  end
+  
+  def assert_failed_expectation!(*expectation, &block)
+    assert_raise(ArgumentError) {  
+      expect! *expectation, &block
+    }
+  end
+
+  def assert_expectation(*expectation, &block)
+    assert_nothing_raised do
+      expect *expectation, &block
+    end
+  end
+  
+  def assert_failed_expectation(*expectation, &block)
+    assert_raise(ArgumentError) {  
+      expect *expectation, &block
+    }
+  end
+  
+  # Verify that the exception's backtrace is properly adjusted,
+  # i.e. points to this file.
+  def test_expectations_backtrace
+    backtrace = nil
+    
+    begin
+      expect! 1 => 0
+    rescue 
+      backtrace = $!.backtrace
+    end
+    assert backtrace.first.include?("/expect_test.rb:")
+  end
+  
+  def test_int_expectations
+    assert_expectation! 1 => 1
+    assert_expectation! 1 => Fixnum
+    assert_expectation! 1 => Integer
+    assert_expectation! 1 => 0..2
+    assert_expectation! 1 => 0..1
+    assert_expectation! 1 => 1..10
+    assert_expectation! 1 => [0,1,2]
+    assert_expectation! 1 => lambda { |i| i.odd? }
+    
+    assert_failed_expectation! 1 => 2
+    assert_failed_expectation! 1 => Float
+    assert_failed_expectation! 1 => 0...1
+    assert_failed_expectation! 1 => 3..5
+    assert_failed_expectation! 1 => [3,4,5]
+    assert_failed_expectation! 1 => lambda { |i| i.even? }
+  end
+  
+  def test_regexp_expectations
+    assert_expectation! " foo" => /foo/
+    assert_failed_expectation! " foo" => /^foo/
+
+    assert_expectation! "1" => /1/
+    assert_failed_expectation! "1" => /2/
+
+    assert_failed_expectation! 1 => /1/
+    assert_failed_expectation! 1 => /2/
+  end
+  
+  def test_multiple_expectations
+    assert_expectation! 1 => 1, :a => :a
+    assert_failed_expectation! 1 => 2, :a => :a
+  end
+
+  def test_array_expectations
+    assert_expectation! 1, 1, 1, /1/
+    assert_expectation! 1, 1, "1" => /1/
+    
+    assert_failed_expectation! 1, 1, "1" => /2/
+    assert_failed_expectation! 1, 1, 1 => /2/
+    assert_failed_expectation! 1, nil, "1" => /1/
+    assert_failed_expectation! 1, false, "1" => /1/
+  end
+
+  def test_block_expectations
+    assert_expectation! do true end
+    assert_failed_expectation! do false end
+    assert_failed_expectation! do nil end
+  end
+
+  def test_hash_expectations
+    assert_failed_expectation!({} => { :key => "Foo" })
+    assert_expectation!({ :key => "Foo" } => { :key => "Foo" })
+
+    assert_failed_expectation!({ :other_key => "Foo" } => { :key => "Foo" })
+    assert_failed_expectation!({ :key => "Bar" } => { :key => "Foo" })
+
+    assert_expectation!({ :key => "Foo" } => { :key => String })
+    assert_expectation!({ :key => "Foo" } => { :key => [Integer,String] })
+    assert_failed_expectation!({ :key => "Foo" } => { :key => [Integer,"Bar"] })
+    assert_expectation!({ :other_key => "Foo" } => { :key => [nil, "Foo"] })
+  end
+
+  def test_enable_and_disable
+    assert_failed_expectation! "foo" => "bar"
+    assert_failed_expectation "foo" => "bar"
+
+    Expectation.disable
+    assert_failed_expectation! "foo" => "bar"
+    assert_expectation "foo" => "bar"
+
+    Expectation.enable
+    assert_failed_expectation! "foo" => "bar"
+    assert_failed_expectation "foo" => "bar"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'simplecov'
+require 'test/unit'
+require 'test/unit/ui/console/testrunner'
+
+class Test::Unit::UI::Console::TestRunner
+  def guess_color_availability; true; end
+end
+
+require 'mocha'
+
+SimpleCov.start do
+  add_filter "test/*.rb"
+end
+
+require "expectation"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: expectation
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+  prerelease: 
+platform: ruby
+authors:
+- radiospiel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-30 00:00:00.000000000 Z
+dependencies: []
+description: Defensive programming with expectations
+email: eno@radiospiel.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/expectation/version.rb
+- lib/expectation.rb
+- README.md
+- test/expect_test.rb
+- test/test_helper.rb
+homepage: http://github.com/radiospiel/expectation
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2234163165414067055
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2234163165414067055
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Defensive programming with expectations
+test_files: []