carats 0.3.0

data/lib/carat-dev/interface_work/contracts/contract/doc/rdoc-style.css

@@ -0,0 +1,208 @@
+
+body {
+    font-family: Verdana,Arial,Helvetica,sans-serif;
+    font-size:   90%;
+    margin: 0;
+    margin-left: 40px;
+    padding: 0;
+    background: white;
+}
+
+h1,h2,h3,h4 { margin: 0; color: #efefef; background: transparent; }
+h1 { font-size: 150%; }
+h2,h3,h4 { margin-top: 1em; }
+
+a { background: #eef; color: #039; text-decoration: none; }
+a:hover { background: #039; color: #eef; }
+
+/* Override the base stylesheet's Anchor inside a table cell */
+td > a {
+  background: transparent;
+  color: #039;
+  text-decoration: none;
+}
+
+/* and inside a section title */
+.section-title > a {
+  background: transparent;
+  color: #eee;
+  text-decoration: none;
+}
+
+/* === Structural elements =================================== */
+
+div#index {
+    margin: 0;
+    margin-left: -40px;
+    padding: 0;
+    font-size: 90%;
+}
+
+
+div#index a {
+    margin-left: 0.7em;
+}
+
+div#index .section-bar {
+   margin-left: 0px;
+   padding-left: 0.7em;
+   background: #ccc;
+   font-size: small;
+}
+
+
+div#classHeader, div#fileHeader {
+    width: auto;
+    color: white;
+    padding: 0.5em 1.5em 0.5em 1.5em;
+    margin: 0;
+    margin-left: -40px;
+    border-bottom: 3px solid #006;
+}
+
+div#classHeader a, div#fileHeader a {
+    background: inherit;
+    color: white;
+}
+
+div#classHeader td, div#fileHeader td {
+    background: inherit;
+    color: white;
+}
+
+
+div#fileHeader {
+    background: #057;
+}
+
+div#classHeader {
+    background: #048;
+}
+
+
+.class-name-in-header {
+  font-size:  180%;
+  font-weight: bold;
+}
+
+
+div#bodyContent {
+    padding: 0 1.5em 0 1.5em;
+}
+
+div#description {
+    padding: 0.5em 1.5em;
+    background: #efefef;
+    border: 1px dotted #999;
+}
+
+div#description h1,h2,h3,h4,h5,h6 {
+    color: #125;;
+    background: transparent;
+}
+
+div#validator-badges {
+    text-align: center;
+}
+div#validator-badges img { border: 0; }
+
+div#copyright {
+    color: #333;
+    background: #efefef;
+    font: 0.75em sans-serif;
+    margin-top: 5em;
+    margin-bottom: 0;
+    padding: 0.5em 2em;
+}
+
+
+/* === Classes =================================== */
+
+table.header-table {
+    color: white;
+    font-size: small;
+}
+
+.type-note {
+    font-size: small;
+    color: #DEDEDE;
+}
+
+.xxsection-bar {
+    background: #eee;
+    color: #333;
+    padding: 3px;
+}
+
+.section-bar {
+   color: #333;
+   border-bottom: 1px solid #999;
+    margin-left: -20px;
+}
+
+
+.section-title {
+    background: #79a;
+    color: #eee;
+    padding: 3px;
+    margin-top: 2em;
+    margin-left: -30px;
+    border: 1px solid #999;
+}
+
+.top-aligned-row {  vertical-align: top }
+.bottom-aligned-row { vertical-align: bottom }
+
+/* --- Context section classes ----------------------- */
+
+.context-row { }
+.context-item-name { font-family: monospace; font-weight: bold; color: black; }
+.context-item-value { font-size: small; color: #448; }
+.context-item-desc { color: #333; padding-left: 2em; }
+
+/* --- Method classes -------------------------- */
+.method-detail {
+    background: #efefef;
+    padding: 0;
+    margin-top: 0.5em;
+    margin-bottom: 1em;
+    border: 1px dotted #ccc;
+}
+.method-heading {
+  color: black;
+  background: #ccc;
+  border-bottom: 1px solid #666;
+  padding: 0.2em 0.5em 0 0.5em;
+}
+.method-signature { color: black; background: inherit; }
+.method-name { font-weight: bold; }
+.method-args { font-style: italic; }
+.method-description { padding: 0 0.5em 0 0.5em; }
+
+/* --- Source code sections -------------------- */
+
+a.source-toggle { font-size: 90%; }
+div.method-source-code {
+    background: #262626;
+    color: #ffdead;
+    margin: 1em;
+    padding: 0.5em;
+    border: 1px dashed #999;
+    overflow: hidden;
+}
+
+div.method-source-code pre { color: #ffdead; overflow: hidden; }
+
+/* --- Ruby keyword styles --------------------- */
+
+.standalone-code { background: #221111; color: #ffdead; overflow: hidden; }
+
+.ruby-constant  { color: #7fffd4; background: transparent; }
+.ruby-keyword { color: #00ffff; background: transparent; }
+.ruby-ivar    { color: #eedd82; background: transparent; }
+.ruby-operator  { color: #00ffee; background: transparent; }
+.ruby-identifier { color: #ffdead; background: transparent; }
+.ruby-node    { color: #ffa07a; background: transparent; }
+.ruby-comment { color: #b22222; font-weight: bold; background: transparent; }
+.ruby-regexp  { color: #ffa07a; background: transparent; }
+.ruby-value   { color: #7fffd4; background: transparent; }

data/lib/carat-dev/interface_work/contracts/contract/lib/contract.rb

@@ -0,0 +1,88 @@
+require 'test/unit/testcase'
+require 'test/unit/testresult'
+require 'test/unit/testsuite'
+
+require 'contract/exception'
+require 'contract/overrides'
+require 'contract/assertions'
+require 'contract/integration'
+
+# Represents a contract between Objects as a collection of test cases.
+# Objects are said to fulfill a contract if all test cases suceed. This
+# is useful for ensuring that Objects your code is getting behave in a
+# way that you expect them to behave so you can fail early or execute
+# different logic for Objects with different interfaces.
+#
+# The tests of the test suite will be run on a copy of the tested Object
+# so you can safely test its behavior without having to fear data loss.
+# By default Contracts obtain deep copies of Objects by serializing and
+# unserializing them with Ruby's +Marshal+ functionality. This will work
+# in most cases but can fail for Objects containing unserializable parts
+# like Procs, Files or Sockets. In those cases it is currently of your
+# responsibility to provide a fitting implementation by overwriting the
+# Contract.deep_copy method. In the future the contract library might
+# provide different implementations of it via Ruby's mixin mechanism.
+class Contract < Test::Unit::TestCase
+  id = %q$Id: contract.rb 52 2005-01-26 16:19:39Z flgr $
+  # The Version of the contract library you are using.
+  Version = id.split(" ")[2].to_i
+
+  # Returns true if the given object fulfills this contract.
+  # This is useful for implementing dispatching mechanisms where you
+  # want to hit different code branches based on whether an Object has
+  # one or another interface.
+  def self.fulfilled_by?(object)
+    self.test(object).nil?
+  end
+
+  class << self
+    alias :=== :fulfilled_by?
+  end
+
+  # Enforces that object implements this contract. If it does not an
+  # Exception will be raised. This is useful for example useful when
+  # you need to ensure that the arguments given to a method fulfill a
+  # given contract.
+  def self.enforce(object)
+    reason = self.test(object)
+    raise reason if reason
+  end
+
+  # Tests whether the given Object fulfils this contract.
+  #
+  # Note: This will return the first reason for the Object not fulfilling
+  # the contract or +nil+ in case it fulfills it.
+  def self.test(object, return_all = false)
+    reasons = []
+
+    result = Test::Unit::TestResult.new
+    result.add_listener(Test::Unit::TestResult::FAULT) do |fault|
+      reason = Contract.fault_to_exception(fault, object, self)
+      return reason unless return_all
+      reasons << reason
+    end
+
+    self.suite.run(result, object)
+
+    return reasons unless result.passed?
+  end
+
+  # Same as Contract.test, but will return all reasons for the Object not
+  # fulfilling the contract in an Array or nil in case of fulfillment.
+  # (as an Array of Exceptions) or +nil+ in the case it does fulfill it.
+  def self.test_all(object)
+    test(object, true)
+  end
+
+  # This method is used internally for getting a copy of Objects that
+  # the contract is checked against. By default it uses Ruby's +Marshal+
+  # functionality for obtaining a copy, but this can fail if the Object
+  # contains unserializable parts like Procs, Files or Sockets. It is
+  # currently your responsibility to provide a fitting implementation
+  # of this by overwriting the method in case the default implementation
+  # does not work for you. In the future the contract library might offer
+  # different implementations for this via Ruby's mixin mechanism.
+  def self.deep_copy(object)
+    Marshal.load(Marshal.dump(object))
+  end
+end

data/lib/carat-dev/interface_work/contracts/contract/lib/contract/assertions.rb

@@ -0,0 +1,37 @@
+# This file provides a few new assertions and class methods for expressing
+# contracts in a comfortable way that does not require manually writing test
+# methods.
+
+
+class Contract < Test::Unit::TestCase
+  # Tests that the tested Object provides the specified methods with
+  # the specified behavior.
+  #
+  # This can be used like this:
+  #   class ListContract < Contract
+  #     provides :size do
+  #       assert(@object.size >= 0, "#size should never be negative.")
+  #     end
+  #
+  #     provides :include? 
+  #
+  #     provides :each do
+  #       count = 0
+  #       @object.each do |item|
+  #         assert(@object.include?(item),
+  #           "#each should only yield items that the list includes.")
+  #         count += 1
+  #       end
+  #       assert_equal(@object.size, count,
+  #         "#each should yield #size items.")
+  #     end
+  #   end
+  def self.provides(*symbols, &block)
+    symbols.each do |symbol|
+      define_method(:"test_provides_#{symbol}") do
+        assert_respond_to(@object, symbol)
+        instance_eval(&block) if block
+      end
+    end
+  end
+end

data/lib/carat-dev/interface_work/contracts/contract/lib/contract/exception.rb

@@ -0,0 +1,92 @@
+# This file contains things needed to map Test::Unit status objects to 
+# Exceptions, Exception related infrastructure and similar things.
+
+
+class Contract < Test::Unit::TestCase
+  # Exceptions raised by Contract contain some usual meta-information.
+  # This module is mixed into Exceptions that provide such information.
+  module ContractException
+    def ce_initialize(original_message, backtrace, test_object,
+      test_method, test_contract, *more) # :nodoc:
+      @original_message = original_message
+      message = original_message.dup
+      detail = " for #{test_object.inspect} in " +
+        "#{test_contract.inspect}"
+      message[/(\s*)[.!?]?\s*\Z/, 1] = detail
+      Exception.instance_method(:initialize).bind(self).call(message)
+
+      set_backtrace(backtrace)
+      @test_object = test_object
+      @test_method = test_method
+      @test_contract = test_contract
+    end
+    private :ce_initialize
+
+    # What object was tested when this Exception was raised?
+    attr_reader :test_object
+    # What method implemented that test?
+    attr_reader :test_method
+    # What contract was that method part of?
+    attr_reader :test_contract
+    # The original, unfiltered exception message.
+    attr_reader :original_message
+  end
+
+  # Represents a failed test in a contract. This means that an object
+  # simply does not fulfill one of the parts of a contract. Subclass of
+  # TypeError.
+  class ContractMismatch < TypeError
+    def initialize(*args) # :nodoc:
+      ce_initialize(*args)
+    end
+
+    include ContractException
+  end
+
+  # Represents an unexpected failure while processing a contract test.
+  # This is more critical than ContractMismatch and usually means that
+  # something is wrong with the test itself.
+  class ContractError < StandardError
+    def initialize(*args) # :nodoc:
+      @type = args.pop
+      ce_initialize(*args)
+    end
+
+    # The type of the original Exception that triggered the unexpected
+    # failure.
+    attr_reader :type
+
+    include ContractException
+  end
+
+
+  # Maps a Test::Unit::Failure instance to an actual Exception with the
+  # specified meta data.
+  def self.failure_to_exception(failure, object, contract) # :nodoc:
+    ContractMismatch.new(failure.message, failure.location, object,
+      extract_method_name(failure.test_name), contract)
+  end
+
+  # Maps a Test::Unit::Error instance to an actual Exception with the
+  # specified meta data.
+  def self.error_to_exception(error, object, contract) # :nodoc:
+    original = error.exception
+    ContractError.new(original.message, original.backtrace, object,
+      extract_method_name(error.test_name), contract, original.class)
+  end
+
+  # Maps a Test::Unit fault (either a Failure or Error) to an actual
+  # exception with the specified meta data.
+  def self.fault_to_exception(fault, *args) # :nodoc:
+    if fault.is_a?(Test::Unit::Failure) then
+      failure_to_exception(fault, *args)
+    else
+      error_to_exception(fault, *args)
+    end
+  end
+
+  # Extracts the method name from a Test::Unit test_name style String.
+  def self.extract_method_name(test_name) # :nodoc:
+    test_name[/\A(.+?)\(.+?\)\Z/, 1]
+  end
+end

data/lib/carat-dev/interface_work/contracts/contract/lib/contract/integration.rb

@@ -0,0 +1,132 @@
+# This file contains code for integrating the contract library with built-in
+# classes and methods.
+
+
+class Contract < Test::Unit::TestCase
+  class << self
+    # Whether signatures should be checked. By default signatures are checked
+    # only when the application is run in $DEBUG mode. (By specifying the -d
+    # switch on the invocation of Ruby.)
+    #
+    # Note: If you want to change this you need to do so before doing any
+    # signature calls or it will not be applied.
+    attr_accessor :check_signatures
+    alias :check_signatures? :check_signatures
+  end
+  self.check_signatures = $DEBUG if self.check_signatures.nil?
+end
+
+class Module
+  # Checks that the arguments and return value of a method match the
+  # specified signature.
+  #
+  # Usage:
+  #   signature(:to_s) # no arguments
+  #   signature(:+, :any) # one argument, type unchecked
+  #   signature(:+, Fixnum) # one argument, type Fixnum
+  #   signature(:+, NumericContract)
+  #   signature(:+, 1 .. 10)
+  #
+  #   signature(:each, :block => true) # has to have block
+  #   signature(:to_i, :block => false) # not allowd to have block
+  #   signature(:to_i, :result => Fixnum) # return value must be Fixnum
+  #   signature(:zip, :allow_trailing => true) # unchecked trailing args
+  #   signature(:zip, :repeated => [Enumerable]) # repeated trailing args
+  def signature(method, *args)
+    return unless Contract.check_signatures?
+
+    options = {}
+    signature = args.dup
+    options.update(signature.pop) if signature.last.is_a?(Hash)
+
+    old_method = instance_method(method)
+    remove_method(method)
+
+    if old_method.arity < signature.size then
+      raise(ArgumentError, "signature isn't compatible with arity")
+    end
+
+    if options.include?(:repeated)
+      if options[:repeated].size == 0 then
+        raise(ArgumentError, "repeated arguments may not be an empty Array")
+      end
+    end
+
+    # We need to keep around references to our arguments because we will
+    # need to access them via ObjectSpace._id2ref so that they do not
+    # get garbage collected.
+    @signatures ||= Hash.new
+    @signatures[method] = args + [method]
+
+    # We have to use class_eval so that signatures can be specified for
+    # methods taking blocks in Ruby 1.8. (This will be obsolete in 1.9)
+    # We also make the checks as efficient as we can.
+    class_eval %{
+      def #{method}(*args, &block)
+        old_args = args.dup
+
+        #{if options.include?(:block) then
+            if options[:block] then
+              %{raise(ArgumentError, "no block given") unless block}
+            else
+              %{raise(ArgumentError, "block given") if block}
+            end
+          end
+        }
+
+        #{unless options[:allow_trailing] or options.include?(:repeated)
+            msg = "wrong number of arguments (\#{args.size} for " +
+              "#{signature.size})"
+            %{if args.size != #{signature.size} then
+                raise(ArgumentError, "#{msg}")
+              end
+            }
+          else
+            msg = "wrong number of arguments (\#{args.size} for " +
+              "at least #{signature.size}"
+            %{if args.size < #{signature.size} then
+                raise(ArgumentError, "#{msg}")
+              end
+            }
+          end
+        }
+
+        #{index = 0
+          signature.map do |part|
+            next if part == :any
+            index += 1
+            msg = "argument #{index} (\#{arg.inspect}) does not match " +
+              "#{part.inspect}"
+            %{unless ObjectSpace._id2ref(#{part.object_id}) === (arg = args.shift)
+                raise(ArgumentError, "#{msg}")
+              end
+            }
+          end
+        }
+
+        #{if repeated = options[:repeated] then %{
+            %{args.each_with_index do |arg, index|
+                part = ObjectSpace._id2ref(#{repeated.object_id})
+                if part != :any and not part[index % #{repeated.size}] === arg
+                  raise(ArgumentError, "argument \#{index + #{signature.size}}" +
+                    "(\#{arg.inspect}) does not match \#{part.inspect}")
+                end
+              end
+            }
+          } end
+        }
+
+        result = ObjectSpace._id2ref(#{old_method.object_id}).bind(self).
+          call(*old_args, &block)
+        #{if rt = options[:return] and rt != :any then
+            msg = "return value (\#{result.inspect}) does not match #{rt.inspect}"
+            %{unless ObjectSpace._id2ref(#{rt.object_id}) === rt
+                raise(StandardError, "#{msg}")
+              end
+            }
+          end
+        }
+      end
+    }, "(signature check for #{old_method.inspect[/: (.+?)>\Z/, 1]})"
+  end
+end