contraction 0.1.0

data/README.md

@@ -0,0 +1,54 @@
+Contraction
+===========
+
+A code-by-contract library for ruby, using RDoc documentation to enforce the contract requirements
+
+Basic usage
+===========
+
+Just include Contraction at the bottom of your class/module:
+
+```ruby
+
+require 'rubygems'
+require 'contraction'
+
+class MySuperCoolClass
+  ##
+  # The foobar function takes a string and an integer between 1 and 100 and
+  # joins them, returning the result.
+  #
+  # @param [String] foo A string to which we add the number
+  # @param [Fixnum] bar A number to add to foo { bar >= 0 and bar <= 100 }
+  # @return [String] The concatonation of foo and bar { return.start_with?(foo) and return.include?(bar.to_s) }
+  def foobar(foo, bar)
+    "#{foo} #{bar.to_s}"
+  end
+
+  include Contraction
+end
+
+```
+
+And you're done.
+
+You define your normal documentation (you do document your code, don't you?)
+using regular RDoc syntax. For the params and returns, however, you can add an
+extra bit of information at the end. Any code put in between curly braces
+(`{}`) is evaluated as the contract for that param or return. You just use the
+names of the params for their values, and `return` for the return value. If you
+provide a type for either the param or the return, type-checking will be
+enforced as well. A full-qualified type is recommended (`Foo::Bar` instead of `Bar`.)
+
+Warning
+=======
+
+This will slow things down. All-in-all you're looking at about an 8x increase
+in overhead vs just calling a function. It is not recommended that you use this
+for every method in a deeply-nested code-path. This overhead is more-or-less
+in-line with other Ruby design-by-contract libraries, however, and with the
+added benefit of free documentation.
+
+Also, this is not super-heavily tested. I've been using it myself and thought I
+would release it to the world, but I don't do a lot of RDoc-fu, so YMMV.
+Pull-requests welcome.

data/contraction.rb

@@ -0,0 +1,2 @@
+require 'lib/string'
+require 'lib/contraction'

data/lib/contraction.rb

@@ -0,0 +1,92 @@
+require 'string'
+module Contraction
+  def self.included(mod)
+    instance = mod.allocate
+    instance_methods = (mod.instance_methods - Object.instance_methods - Contraction.instance_methods)
+
+    file_contents_by_filename = {}
+    instance_methods.each do |method_name|
+      file, line = instance.method(method_name).source_location
+      filename = File.expand_path(file)
+      file_contents = file_contents_by_filename[filename] || File.read(filename).split("\n")
+      file_contents_by_filename ||= file_contents
+
+      args    = []
+      returns = [Object, '', 'true']
+      file_contents[0..line-2].reverse.each do |line|
+        line = line.strip
+        next if line == ''
+        break unless line.start_with?('#')
+        break if line.start_with?('##')
+
+        # if m = /^#\s*@return\s+(?<type>\[[^\]]+\])?\s*(?<message>[^{]+)?(\{(?<contract>[^}]+)\})?/.match(line)
+        if m = /^#\s*@return\s+(\[[^\]]+\])?\s*([^{]+)?(\{([^}]+)\})?/.match(line)
+          type = m[1].to_s.gsub(/(\[|\])/, '')
+          type = type == '' ? Object : type.constantize
+          contract = m[4].to_s.strip.gsub('return', "result")
+          contract = contract == '' ? 'true' : contract
+          returns = [type, m[2], contract]
+        # elsif m = /^#\s*@param\s+(?<type>\[[^\]]+\])?\s*(?<name>[^\s]+)\s+(?<message>[^{]+)?(\{(?<contract>[^}]+)\})?/.match(line)
+        elsif m = /^#\s*@param\s+(\[[^\]]+\])?\s*([^\s]+)\s+([^{]+)?(\{([^}]+)\})?/.match(line)
+          type = m[1].to_s.gsub(/(\[|\])/, '')
+          type = type == '' ? Object : type.constantize
+          contract = m[5].to_s.strip.gsub(m[2], "named_args[#{m[2].inspect}]")
+          contract = contract == '' ? 'true' : contract
+          args << [type, m[2], m[3], contract]
+        end
+      end
+      args.reverse!
+      arg_names = args.map { |a| a[1] }
+      arg_names.each do |name|
+        returns[-1] = returns[-1].gsub(name, "named_args[#{name.inspect}]")
+      end
+
+      old_method = mod.instance_method(method_name)
+
+      arg_checks = []
+      result_check = nil
+      mod.send(:define_method, method_name) do |*method_args|
+        named_args = args.each_with_index.inject({}) do |h, (arg, index)|
+          type, name, message, contract = arg
+          h[name] = method_args[index]
+          h
+        end
+
+        b = binding
+        if arg_checks.empty?
+          arg_checks = args.map do |arg|
+            type, name, message, contract = arg
+            value = named_args[name]
+            checker = nil
+            lambda { |named_args|
+              raise ArgumentError.new("#{name} (#{value.inspect}) must be a #{type}") unless value.is_a?(type)
+              checker = eval("lambda { |named_args| #{contract} }", b) if checker.nil?
+              unless checker.call(named_args)
+                raise ArgumentError.new("#{name} (#{message}) must fullfill #{contract.inspect}, but is #{value.inspect}")
+              end
+            }
+          end
+        end
+        arg_checks.each { |c| c.call(named_args) }
+
+        result = old_method.bind(self).call(*method_args)
+
+        if result_check.nil?
+          checker = nil
+          result_check = lambda { |named_args|
+            type, message, contract = returns
+            raise ArgumentError.new("Return value of #{method_name} must be a #{type}") unless result.is_a?(type)
+            checker = eval("lambda { |named_args| #{contract} }", b) if checker.nil?
+            unless checker.call(named_args)
+              raise ArgumentError.new("Return value of #{method_name} (#{message}) must fullfill #{contract.inspect}, but is #{result.inspect}")
+            end
+          }
+        end
+        result_check.call(named_args)
+
+        result
+      end
+    end
+  end
+end
+

data/lib/string.rb

@@ -0,0 +1,13 @@
+class String
+  # This is taken strait copy-pasta from ActiveSupport. All praise be to them.
+  def constantize
+    names = self.split('::')
+    names.shift if names.empty? || names.first.empty?
+
+    constant = Object
+    names.each do |name|
+      constant = constant.const_defined?(name) ? constant.const_get(name) : constant.const_missing(name)
+    end
+    constant
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: contraction
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Thomas Luce
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-18 00:00:00.000000000 Z
+dependencies: []
+description: Using RDoc documentation as your contract definition, you get solid code,
+  and good docs. Win-win!
+email: thomas.luce@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- contraction.rb
+- lib/contraction.rb
+- lib/string.rb
+homepage: 
+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: 2451511498111927596
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A simple desgin-by-contract library
+test_files: []