armin-joellenbeck-rdbc 0.0.4

data/README

@@ -0,0 +1,99 @@
+=Design by Contract for Ruby
+
+This library supports Design by Contract for Ruby.
+
+=Installation
+
+Install the *rdbc* gem itself by the following command:
+
+  $ gem install rdbc
+
+=Usage
+
+A a standard example for Design by Contract consider the following Stack
+class and its contract StackContract.
+
+===stack.rb
+
+  :include:examples/stack.rb
+
+===stack_contract.rb
+
+  :include:examples/stack_contract.rb
+
+The mechanics are really simple. There is the class Stack.
+For instances of this class you can define a contract by subclassing
+<b>DesignByContract::Contract</b>, in the example the contract is named
+StackContract.
+Then connect the class Stack to its contract StackContract by using the line
+  contract StackContract
+in the class definition of Stack.
+
+Now the following happens for an instance method of Stack. Say its name is
+*method*. When it is called the the following calling of methods happens.
+
+* *method_pre* of the contract is called with the parameters:
+  * the object itself
+  * the parameters of the original method *method*
+* the original *method* is called
+* *method_post* of the contract is called with the parameters:
+  * the object before the execution of the original method
+  * the object after execution the original method
+  * the return value of the original method
+  * the parameters of the original method
+* *invariant* is called with the parameters:
+  * the object before the execution of the original method
+  * the object after execution the method
+
+The object before the execution of *method* in 3. and 4.
+is in fact a copy of the object before the execution. So you have to implement
+the method *initialize_copy* in the class under contract, i.e. the class
+Stack.
+
+In any of these contract methods you can use assertions as in Test::Unit tests.
+When an assertion fails, the exception Test::Unit::AssertionFailedError
+is raised.
+
+When the method is an operator the *_pre* and  *_post* suffixes are appended
+to the names of the operator according to the constant #Translate::OPERATOR.
+
+=Support
+
+The project home is at
+GitHub[http://github.com/armin-joellenbeck/rdbc/tree/master]:
+http://github.com/armin-joellenbeck/rdbc/tree/master
+
+Feel free to send:
+* bug reports
+* support requests
+* feature requests
+* patches
+
+=Copyright
+
+Copyright (c) 2007 - 2008 by Armin Jöllenbeck
+<armin@joellenbeck.net[mailto:armin@joellenbeck.net]>
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. The names of the contributors may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,31 @@
+require 'spec/rake/spectask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+
+
+task :default => [:spec]
+
+
+task :all =>  [:spec, :doc, :package]
+
+
+Spec::Rake::SpecTask.new do |t|
+  t.libs << 'spec' << 'examples' << 'lib'
+end
+
+
+Rake::RDocTask.new(:doc) do |t|
+  t.rdoc_dir = 'doc'
+  t.rdoc_files.include('README', 'lib/**/*.rb')
+  t.options = [
+    '--all',
+    '--charset', 'utf8',
+    '--inline-source',
+    '--main', 'README',
+    '--title', 'Design by Contract for Ruby'
+  ]
+end
+
+
+Rake::GemPackageTask.new(eval(File.read('rdbc.gemspec'))) do |pkg|
+end

data/examples/stack.rb

@@ -0,0 +1,44 @@
+require 'stack_contract'
+
+class Stack
+
+  contract StackContract
+
+  class NoPopForEmptyStack < RuntimeError
+  end
+
+  def initialize
+    @elements = []
+  end
+
+  def initialize_copy(orig)
+    @elements = orig.elements
+  end
+
+  def elements
+    @elements.dup
+  end
+
+  def size
+    @elements.size
+  end
+
+  def empty?
+    size == 0
+  end
+
+  def top
+    @elements.last
+  end
+
+  def push(element)
+    @elements.push(element)
+    nil
+  end
+
+  def pop
+    raise NoPopForEmptyStack if empty?
+    @elements.pop
+  end
+
+end

data/examples/stack_contract.rb

@@ -0,0 +1,36 @@
+require 'contract'
+
+class StackContract < Contract
+
+  def push_post(stack_pre, stack, exception, result, element)
+    assert_nil(result)
+    assert_equal(element, stack.top)
+    assert_equal(stack.size, stack_pre.size + 1)
+  end
+
+  def pop_pre(stack)
+    assert_operator(stack.size, :>=, 0)
+  end
+
+  def pop_post(stack_pre, stack, exception, result)
+    if stack_pre.empty?
+      assert_kind_of(Stack::NoPopForEmptyStack, exception)
+    else
+      assert_equal(stack_pre.top, result)
+      assert_equal(stack_pre.size - 1, stack.size)
+    end
+  end
+
+  def top_pre(stack)
+    assert_operator(stack.size, :>=, 1)
+  end
+
+  def top_post(stack_pre, stack, exception, result)
+    assert_equal(stack_pre.size, stack.size)
+  end
+
+  def invariant(stack)
+    assert_operator(stack.size, :>=, 0)
+  end
+
+end

data/lib/contract.rb

@@ -0,0 +1,22 @@
+require 'test/unit/assertions'
+
+class Contract
+  include Test::Unit::Assertions
+end
+
+
+require 'object'
+require 'proxy'
+
+class Class
+
+  def contract(klass)
+    old_new = self.method(:new)
+    self.define_singleton_method(:new) do |*args|
+      object = old_new.call(*args)
+      contract = klass.new
+      @proxy = Proxy.new(object, contract)
+    end
+  end
+
+end

data/lib/object.rb

@@ -0,0 +1,13 @@
+class Object
+
+  def singleton_class
+    class << self
+      self
+    end
+  end
+
+  def define_singleton_method(method, &block)
+    singleton_class.send(:define_method, method, &block)
+  end
+
+end

data/lib/proxy.rb

@@ -0,0 +1,46 @@
+require 'translate'
+
+class Proxy
+
+  def initialize(object, contract)
+    @object = object
+    @contract = contract
+  end
+
+  def method_missing(method, *args)
+    # clone the object under contract for use in the pre condition
+    object_pre = @object.clone
+
+    # call pre condition
+    method_pre = Translate.method_pre(method)
+    if @contract.respond_to?(method_pre)
+      @contract.send(method_pre, @object, *args)
+    end
+
+    # call the wrapped method
+    exception = nil
+    begin
+      result = @object.send(method, *args)
+    rescue => exception
+    end
+
+    # call the invariant condition
+    if @contract.respond_to?(:invariant)
+      @contract.invariant(@object)
+    end
+
+    # call the post condition
+    method_post = Translate.method_post(method)
+    if @contract.respond_to?(method_post)
+      @contract.send(method_post, object_pre, @object, exception, result, *args)
+    end
+
+    # return the return value of the wrapped method call or raise the exception
+    if exception.nil?
+      result
+    else
+      raise exception
+    end
+  end
+
+end

data/lib/translate.rb

@@ -0,0 +1,56 @@
+module Translate
+
+  OPERATOR = {
+    :[]  => :element_read,
+    :[]= => :element_write,
+    :**  => :power,
+    :~   => :not,
+    :+@  => :unary_plus,
+    :-@  => :unary_minus,
+    :*   => :product,
+    :/   => :quotient,
+    :%   => :modulo,
+    :+   => :plus,
+    :-   => :minus,
+    :>>  => :right_shift,
+    :<<  => :left_shift,
+    :&   => :and,
+    :^   => :xor,
+    :|   => :or,
+    :<=  => :less_or_equal,
+    :<   => :less,
+    :>   => :greater,
+    :>=  => :greater_or_equal,
+    :<=> => :comparison,
+    :==  => :eql,
+    :=== => :case_comparison,
+    :=~  => :match
+  }
+
+  def self.method_pre(method)
+    method_with_suffix(method, :pre)
+  end
+
+  def self.method_post(method)
+    method_with_suffix(method, :post)
+  end
+
+  def self.method_with_suffix(method, type)
+    operator = OPERATOR[method]
+    suffix = '_' + type.to_s
+    if operator.nil?
+      method_string = method.to_s
+      length = method_string.length
+      head = method_string[0...length-1]
+      tail = method_string[length-1...length]
+      if ['?', '!', '='].include?(tail)
+        (head + suffix + tail).to_sym
+      else
+        (method_string + suffix).to_sym
+      end
+    else
+      ('op_' + operator.to_s + suffix).to_sym
+    end
+  end
+
+end

data/rdbc.gemspec

@@ -0,0 +1,26 @@
+Gem::Specification.new do |s|
+  s.name = 'rdbc'
+  s.version = '0.0.4'
+  s.summary = 'Design by Contract for Ruby.'
+  s.author = 'Armin Joellenbeck'
+  s.email = 'armin@joellenbeck.net'
+  s.homepage = 'http://github.com/armin-joellenbeck/rdbc/tree/master'
+  s.description = <<-EOF
+  EOF
+  s.files = Dir.glob([
+    'README',
+    'Rakefile',
+    '*.gemspec',
+    'examples/**/*',
+    'lib/**/*',
+    'spec/**/*'
+  ])
+  s.has_rdoc = true
+  s.extra_rdoc_files << 'README'
+  s.rdoc_options = [
+    '--all',
+    '--charset', 'utf8',
+    '--main', 'README',
+    '--title', 'Design by Contract for Ruby'
+  ]
+end

data/spec/contract_spec.rb

@@ -0,0 +1,4 @@
+require 'contract'
+
+describe Contract do
+end

data/spec/object_spec.rb

@@ -0,0 +1,4 @@
+require 'object'
+
+describe Object do
+end

data/spec/proxy_spec.rb

@@ -0,0 +1,4 @@
+require 'proxy'
+
+describe Proxy do
+end

data/spec/spec.opts

@@ -0,0 +1,3 @@
+--colour
+--format
+specdoc

data/spec/stack_contract_spec.rb

@@ -0,0 +1,4 @@
+require 'stack_contract'
+
+describe StackContract do
+end

data/spec/stack_spec.rb

@@ -0,0 +1,30 @@
+require 'stack'
+
+describe Stack do
+
+  before do
+    @stack = Stack.new
+  end
+
+  it 'should be empty' do
+    @stack.should be_empty
+  end
+
+  it 'should have no element on top' do
+    lambda { @stack.top }.should raise_error(Test::Unit::AssertionFailedError)
+  end
+
+  it 'should not be possible to pop an element' do
+    lambda { @stack.pop }.should raise_error(Stack::NoPopForEmptyStack)
+  end
+
+  it 'a pushed element should be on the top' do
+    element = 0
+    @stack.push(element)
+    @stack.should_not be_empty
+    @stack.top.should be_equal(element)
+    @stack.pop.should be_equal(element)
+    @stack.should be_empty
+  end
+
+end

data/spec/translate_spec.rb

@@ -0,0 +1,45 @@
+require 'translate'
+
+describe Translate do
+
+  it 'should give the pre method for a normal method' do
+    Translate.method_pre(:method).should == :method_pre
+  end
+
+  it 'should give the pre method for a question method' do
+    Translate.method_pre(:method?).should == :method_pre?
+  end
+
+  it 'should give the pre method for an exclamation method' do
+    Translate.method_pre(:method!).should == :method_pre!
+  end
+
+  it 'should give the pre method for an assignment method' do
+    Translate.method_pre(:method=).should == :method_pre=
+  end
+
+  it 'should give the pre method for an operator' do
+    Translate.method_pre(:+).should == :op_plus_pre
+  end
+
+  it 'should give the post method for a normal method' do
+    Translate.method_post(:method).should == :method_post
+  end
+
+  it 'should give the post method for a question method' do
+    Translate.method_post(:method?).should == :method_post?
+  end
+
+  it 'should give the post method for an exclamation method' do
+    Translate.method_post(:method!).should == :method_post!
+  end
+
+  it 'should give the post method for an assignment method' do
+    Translate.method_post(:method=).should == :method_post=
+  end
+
+  it 'should give the post method for an operator' do
+    Translate.method_post(:+).should == :op_plus_post
+  end
+
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification 
+name: armin-joellenbeck-rdbc
+version: !ruby/object:Gem::Version 
+  version: 0.0.4
+platform: ruby
+authors: 
+- Armin Joellenbeck
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-08-13 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: ""
+email: armin@joellenbeck.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+- Rakefile
+- rdbc.gemspec
+- examples/stack_contract.rb
+- examples/stack.rb
+- lib/contract.rb
+- lib/translate.rb
+- lib/object.rb
+- lib/proxy.rb
+- spec/translate_spec.rb
+- spec/object_spec.rb
+- spec/proxy_spec.rb
+- spec/spec.opts
+- spec/contract_spec.rb
+- spec/stack_contract_spec.rb
+- spec/stack_spec.rb
+has_rdoc: true
+homepage: http://github.com/armin-joellenbeck/rdbc/tree/master
+post_install_message: 
+rdoc_options: 
+- --all
+- --charset
+- utf8
+- --main
+- README
+- --title
+- Design by Contract for Ruby
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Design by Contract for Ruby.
+test_files: []
+