contraction 0.1.2 → 0.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a6acaeb85e36db1453f073fa71abf2c75fbf4079
+  data.tar.gz: dcfcd8b39e26bd1c4544f000ba13a3442911ccf6
+SHA512:
+  metadata.gz: 40dde6d63f5c70f67064246e74c57ce004475a4a8f7c26660e0e5e5659d9a83ffd342b945606f99f667c6e2221b801d8b3c24041700aed9a3b3aa27166892961
+  data.tar.gz: a7be353ccd6f064d4830d58e3cbe71ce4f33c2f80e94dbcf5fc603fbfb68525d88275b56f77302aa93f5d53a6564f17ebcbcffb4e696405aee3db562eab3adae

data/README.md

@@ -40,15 +40,50 @@ 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
-=======
+Ruby and the splendiferous always-open class
+============================================
+
+Because a class in Ruby can never really be "fully loaded", there are strange
+cases where Contraction may not build contracts for all the methods that you
+want it to. For example, if some third-party code modifies your class to add
+methods at run-time, after Contraction has already been loaded. In this case,
+if you would like contracts to be enabled for those classes, you can update the
+annotated methods by calling:
+
+```ruby
+class MySuperCoolClass
+  ...
+
+  include Contraction
+end
+
+...
+
+MySuperCoolClass.update_contracts
+```
+
+Please bear in mind that you will re-incur the overhead of parsing the RDoc
+docs for each method.
+
+Warning about speed/overhead
+============================
 
 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.
+added benefit of free documentation. It is recommended that you have some
+concept of environment (staging, dev, production, etc.), and only include
+Contraction in development-like environments:
+
+```ruby
+require 'rubygems'
+require 'contraction'
+
+class MySuperCoolClass
+  ...
+
+  include Contraction if Rails.env.development?
+end
+```
 
-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/lib/contract.rb

@@ -1,39 +1,76 @@
 module Contraction
-  private
-
   class Contract
-    attr_accessor :type, :name, :message, :contract
-    def initialize(args={})
-      @type = args[:type]
-      @name = args[:name]
-      @message = args[:message]
-      @contract = args[:contract] || ''
-
-      create_checkers!
+    attr_reader :rules, :mod, :method_name, :params
+
+    # @params [Array<TypedLine>] rules The individual lines that define the
+    # contract.
+    def initialize(rules, mod, method_name)
+      @rules       = rules
+      @mod         = mod
+      @method_name = method_name
+
+      update_rule_values
+      get_method_definition
     end
 
-    def check!(value, named_args)
-      @type_checker.call(value, named_args) if @type_checker
-      if @contract_checker
-        raise ArgumentError.new(contract_message(value)) unless @contract_checker.call(value, named_args)
+    # Test weather the arguments to a method are of the correct type, and meet
+    # the correct contractual obligations.
+    def valid_args?(*method_args)
+      return true if @rules.nil?
+      named_args = params.each_with_index.inject({}) do |h, (param, index)|
+        h[param.to_s] = method_args[index]
+      h
+      end
+
+      b = binding
+      param_rules.all? do |rule|
+        raise ArgumentError.new("#{rule.name} (#{named_args[rule.name].inspect}) must be a #{rule.type}") unless rule.valid?(named_args[rule.name])
+        rule.evaluate_in_context(b, method_name, named_args[rule.name])
       end
     end
 
-    private
+    # Tests weather or not the return value is of the correct type and meets
+    # the correct contractual obligations.
+    def valid_return?(*method_args, result)
+      named_args = params.each_with_index.inject({}) do |h, (param, index)|
+        h[param] = method_args[index]
+      h
+      end
 
-    def create_checkers!
-      if type
-        @type_checker = lambda { |value, named_args| raise ArgumentError.new(type_message(value)) unless value.is_a?(type) }
+      return true unless return_rule
+      unless return_rule.valid?(result)
+        raise ArgumentError.new("Return value of #{method_name} must be a #{return_rule.type}")
+      end
+      if return_rule.contract
+        b = binding
+        return_rule.evaluate_in_context(b, method_name, result)
       end
-      @contract_checker = eval("lambda { |result, named_args| #{contract} }") unless contract == ''
     end
 
-    def type_message(value)
-      "#{name} (#{value.inspect}) must be a #{type}"
+    private
+
+    def return_rule
+      @return_rule ||= @rules.select { |r| r.is_a?(Contraction::Parser::ReturnLine) }.first
+    end
+
+    def param_rules
+      @param_rules ||= @rules.select { |r| r.is_a?(Contraction::Parser::ParamLine) }
+    end
+
+    def get_method_definition
+      @params = mod.instance_method(method_name).parameters.map(&:last)
     end
 
-    def contract_message(value)
-      "#{name} (#{message}) must fullfill #{contract.inspect}, but is #{value.inspect}"
+    def update_rule_values
+      names = rules.map(&:name).compact.uniq
+
+      rules.each do |rule|
+        names.each do |name|
+          rule.contract.gsub!(name, "named_args['#{name}']")
+        end
+        rule.contract.gsub!('return', 'result')
+      end
     end
   end
 end
+

data/lib/contraction.rb

@@ -1,101 +1,48 @@
 require 'string'
-require 'contract'
+require 'parser'
+
 module Contraction
-  def self.patch_instance_method(mod, method_name)
+  # Call this method to update contracts for any methods that may have been
+  # added after the class/module file was loaded by some third-party code. It's
+  # unlikely that you will need this method, but I thought I would include it
+  # just in case.
+  # @param [Class] mod The module or class to update contracts for.
+  def self.update_contracts(mod)
     instance = mod.allocate
-    args, returns = parse_comments(instance.method(method_name).source_location)
-
-    arg_names = args.map(&:name)
-    arg_names.each do |name|
-      returns.contract = returns.contract.gsub(name, "named_args[#{name.inspect}]")
-    end
-
-    old_method = mod.instance_method(method_name)
-
-    mod.send(:define_method, method_name) do |*method_args|
-      named_args = args.each_with_index.inject({}) do |h, (arg, index)|
-        h[arg.name] = method_args[index]
-        h
-      end
+    instance_methods = (mod.instance_methods - Object.instance_methods - Contraction.instance_methods)
 
-      args.each { |arg| arg.check!(named_args[arg.name], named_args) }
-      result = old_method.bind(self).call(*method_args)
-      returns.check!(result, named_args)
+    instance_methods.each do |method_name|
+      file_contents, line_no = read_file_for_method(instance, method_name)
 
-      result
+      contract = Contraction::Parser.parse(file_contents[0..line_no-2].reverse, mod, method_name)
+      define_wrapped_method(mod, method_name, contract)
     end
   end
 
-  def self.patch_class_method(mod, method_name)
-    args, returns = parse_comments(mod.method(method_name).source_location)
-    arg_names = args.map(&:name)
-    arg_names.each do |name|
-      returns.contract = returns.contract.gsub(name, "named_args[#{name.inspect}]")
-    end
-
-    old_method = mod.method(method_name)
-
-    arg_checks = []
-    result_check = nil
-    mod.define_singleton_method(method_name) do |*method_args|
-      named_args = args.each_with_index.inject({}) do |h, (arg, index)|
-        h[arg.name] = method_args[index]
-        h
-      end
-
-      args.each { |arg| arg.check!(named_args[arg.name], named_args) }
-      result = old_method.call(*method_args)
-      returns.check!(result, named_args)
-
-      result
-    end
+  # Called by ruby when Contraction is included in a class.
+  def self.included(mod)
+    update_contracts(mod)
   end
 
-  def self.file_content(filename)
-    @file_contents ||= {}
-    @file_contents[filename] ||= File.read(filename)
-  end
+  private
 
-  def self.parse_comments(location)
-    file, line = location
+  def self.read_file_for_method(instance, method_name)
+    file, line = instance.method(method_name).source_location
     filename = File.expand_path(file)
-
-    args    = []
-    returns = Contraction::Contract.new()
-    file_content(filename).split("\n")[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+(\[[^\]]+\])?\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 = Contraction::Contract.new(type: type, name: 'returns', message: m[2], contract: contract)
-      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 << Contraction::Contract.new(type: type, name: m[2], message: m[3], contract: contract)
-      end
-    end
-    args.reverse!
-    return [args, returns]
+    file_contents = File.read(filename).split("\n")
+    return [file_contents, line]
   end
 
-  def self.included(mod)
-    instance_methods = (mod.instance_methods - Object.instance_methods - Contraction.instance_methods)
-
-    instance_methods.each do |method_name|
-      patch_instance_method(mod, method_name)
-    end
+  def self.define_wrapped_method(mod, method_name, contract)
+    old_method = mod.instance_method(method_name)
 
-    class_methods = (mod.methods - Object.methods - Contraction.methods)
-    class_methods.each do |method_name|
-      patch_class_method(mod, method_name)
+    arg_checks = []
+    result_check = nil
+    mod.send(:define_method, method_name) do |*method_args|
+      contract.valid_args?(*method_args)
+      result = old_method.bind(self).call(*method_args)
+      contract.valid_return?(*method_args, result)
+      result
     end
   end
 end

data/lib/parser.rb

@@ -0,0 +1,57 @@
+require 'string'
+require 'parser/type'
+require 'parser/lines'
+require 'contract'
+
+module Contraction
+  module Parser
+    RETURN_LINE_REGEX = /^#\s*@return\s+(?<type>\[[^\]]+\])?\s*(?<message>[^{]+)?(?<contract>\{([^}]+)\})?/
+    PARAM_LINE_REGEX  = /^#\s*@param\s+(?<type>\[[^\]]+\])?\s*(?<name>[^\s]+)\s+(?<message>[^{]+)?(?<contract>\{([^}]+)\})?/
+
+    # Parses text passed to it for a given method for RDoc @param and @return
+    # lines to build contracts.
+    # @param [Array,String] text The text to be parsed.
+    # @param [Class,Module] mod The class or module that the method is defined
+    # in.
+    # @param [Symbol,String] method_name The name of the method that the
+    # contracts/docs apply to
+    # @return [Contract] A Contract object that can be used to evaluate
+    # correctness at run-time.
+    def self.parse(text, mod, method_name)
+      lines = text.is_a?(String) ? text.split(/$/) : text
+      results = []
+      lines.each do |line|
+        line.strip!
+        break unless line.start_with? '#'
+        break if line.start_with? '##'
+        results << parse_line(line.strip)
+      end
+      results.compact!
+
+      Contract.new(results, mod, method_name)
+    end
+
+    # Parse a single line of text for @param and @return statements.
+    # @param [String] line The line of text to parse
+    # @return [TypedLine] An object that represents the parsed line including
+    # type information and contract.
+    def self.parse_line(line)
+      if m = line.match(PARAM_LINE_REGEX)
+        args = {
+          type: m['type'].to_s.gsub(/(\[|\])/, ''),
+          name: m['name'],
+          message: m['message'],
+          contract: (m['contract'] || 'true').gsub(/(^\{)|(\}$)/, '')
+        }
+        return ParamLine.new(args)
+      elsif m = line.match(RETURN_LINE_REGEX)
+        args = {
+          type: m['type'].to_s.gsub(/(\[|\])/, ''),
+          message: m['message'],
+          contract: (m['contract'] || 'true').gsub(/(^\{)|(\}$)/, '')
+        }
+        return ReturnLine.new(args)
+      end
+    end
+  end
+end

data/lib/parser/lines.rb

@@ -0,0 +1,64 @@
+# FIXME: There is an aweful lot of knowledge about which kind of TypedLine is
+# being used scattered around the system. I need to encapsulate that better;
+# the abstractions are leaking!
+module Contraction
+  module Parser
+    class TypedLine
+      attr_reader :type, :contract, :message, :types
+      attr_writer :contract
+
+      def initialize(args={})
+        @type     = args[:type]
+        @contract = args[:contract]
+        @message  = args[:message]
+        parse_type
+      end
+
+      def parse_type
+        parts = type.split(/(\>|\}|\)),/)
+        @types = []
+        parts.each do |part|
+          @types << Type.new(part)
+        end
+      end
+
+      def valid?(*value)
+        @types.each_with_index.all? do |t, i|
+          t.check(value[i])
+        end
+      end
+
+      def evaluate_in_context(context, method_name, value)
+        return if !contract || contract.to_s.strip == ''
+        raise contract_message(value, method_name) unless eval(contract, context)
+      end
+
+      def contract_message(value=nil, method_name=nil)
+        raise 'Not Implemented'
+      end
+    end
+
+    class ParamLine < TypedLine
+      attr_reader :name
+
+      def initialize(args={})
+        super(args)
+        @name = args[:name]
+      end
+
+      def contract_message(value, method_name=nil)
+        "#{name} (#{message}) must fullfill #{contract.inspect}, but is #{value.inspect}"
+      end
+    end
+
+    class ReturnLine < TypedLine
+      def name
+        nil
+      end
+
+      def contract_message(value, method_name=nil)
+        "Return value of #{method_name} (#{message}) must fullfill #{contract.inspect}, but is #{value}"
+      end
+    end
+  end
+end

data/lib/parser/type.rb

@@ -0,0 +1,138 @@
+module Contraction
+  module Parser
+    class Type
+      attr_reader :legal_types, :method_requirements, :length, :key_types, :value_types
+
+      def initialize(part)
+        @legal_types         = []
+        @method_requirements = []
+        @length              = -1
+        @key_types           = []
+        @value_types         = []
+
+        parse(part)
+      end
+
+      # Checks weather or not thing is a given type.
+      # @param [String] thing A string containing a type definition. For example:
+      #    Array<String>
+      def check(thing)
+        check_types(thing) &&
+        check_duck_typing(thing) &&
+        check_length(thing) &&
+        check_hash(thing)
+      end
+
+      private
+
+      def parse(line)
+        parse_typed_container(line) ||
+          parse_duck_type(line) ||
+          parse_fixed_list(line) ||
+          parse_hash(line) ||
+          parse_short_hash_or_reference(line) ||
+          parse_regular(line)
+      end
+
+      def parse_typed_container(line)
+        return unless line.include? '<'
+        # It's some kind of container that can only hold certain things
+        list = line.match(/\<(?<list>[^\>]+)\>/)['list']
+        list.split(',').each do |type|
+          @legal_types << Type.new(type.strip)
+        end
+        true
+      end
+
+      def parse_duck_type(line)
+        return unless line =~ /^#/
+        # It's a duck-typed object of some kind
+        methods = line.split(",").map { |p| p.strip.gsub(/^#/,'').to_sym }
+        @method_requirements += methods
+        true
+      end
+
+      def parse_fixed_list(line)
+        return unless line.include?('(')
+        # It's a fixed-length list
+        list = line.match(/\((?<list>[^\>]+)\)/)['list']
+        parts = list.split(',')
+        @length = parts.length
+        parts.each do |type|
+          @legal_types << Type.new(type.strip)
+        end
+        true
+      end
+
+      def parse_hash(line)
+        return unless line.include? 'Hash{'
+        # It's a hash with specific key-value pair types
+        parts = line.match(/\{(?<key_types>.+)\s*=\>\s*(?<value_types>[^\}]+)\}/)
+        @key_types = parts['key_types'].split(',').map { |t| t.include?('#') ? t.strip.gsub(/^#/, '').to_sym : t.strip.constantize }
+        @value_types = parts['value_types'].split(',').map { |t| t.include?('#') ? t.strip.gsub(/^#/, '').to_sym : t.strip.constantize }
+      end
+
+      def parse_short_hash_or_reference(line)
+        return unless line.include? '{'
+        if parts = line.match(/\{(?<key_types>.+)\s*=\>\s*(?<value_types>[^\}]+)\}/)
+          @key_types = parts['key_types'].split(',').map { |t| t.include?('#') ? t.strip.gsub(/^#/, '').to_sym : t.strip.constantize }
+          @value_types = parts['value_types'].split(',').map { |t| t.include?('#') ? t.strip.gsub(/^#/, '').to_sym : t.strip.constantize }
+        else
+          # It's a reference to another documented type defined someplace in
+          # the codebase. We can ignore the reference, and treat it like a
+          # normal type.
+          @legal_types << line.gsub(/\{|\}/, '').constantize
+        end
+        true
+      end
+
+      def parse_regular(line)
+        # It's a regular-ass type.
+        @legal_types << line.constantize
+      end
+
+      def check_hash(thing)
+        return true if @key_types.empty? or @value_types.empty?
+        return false unless thing.is_a?(Hash)
+        thing.keys.all? do |k|
+          @key_types.any? { |kt| kt.is_a?(Symbol) ? k.respond_to?(kt) : k.is_a?(kt) }
+        end &&
+        thing.values.all? do |v|
+          @value_types.any? { |vt| vt.is_a?(Symbol) ? v.respond_to?(vt) : v.is_a?(vt) }
+        end
+      end
+
+      def check_length(thing)
+        return true if @length == -1
+        thing.length == @length
+      end
+
+      def check_duck_typing(thing)
+        return true if @method_requirements.empty?
+        @method_requirements.all? do |m|
+          thing.respond_to? m
+        end
+      end
+
+      def check_types(thing)
+        return true if @legal_types.empty?
+        if thing.is_a? Enumerable
+          types = @legal_types.map { |t| t.respond_to?(:legal_types) ? t.legal_types : t }.flatten
+          return thing.all? { |th| types.include?(th.class) }
+        else
+          @legal_types.any? do |t|
+            if t.is_a?(Contraction::Parser::Type)
+              #  Given the fact that we check enumerables above, we should never be here.
+              next false
+            end
+            if thing.is_a?(Enumerable)
+              thing.all? { |th| th.is_a?(t) }
+            else
+              thing.is_a?(t)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/string.rb

@@ -1,5 +1,6 @@
 class String
   # This is taken strait copy-pasta from ActiveSupport. All praise be to them.
+  # @return [Object] The class or module named by the string.
   def constantize
     names = self.split('::')
     names.shift if names.empty? || names.first.empty?

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: contraction
 version: !ruby/object:Gem::Version
-  version: 0.1.2
-  prerelease: 
+  version: 0.2.2
 platform: ruby
 authors:
 - Thomas Luce
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-19 00:00:00.000000000 Z
+date: 2014-07-18 00:00:00.000000000 Z
 dependencies: []
 description: Using RDoc documentation as your contract definition, you get solid code,
   and good docs. Win-win!
@@ -23,32 +22,31 @@ files:
 - contraction.rb
 - lib/contract.rb
 - lib/contraction.rb
+- lib/parser.rb
+- lib/parser/lines.rb
+- lib/parser/type.rb
 - lib/string.rb
 homepage: https://github.com/thomasluce/contraction
 licenses: []
+metadata: {}
 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: 2360464299481397474
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.2.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: A simple desgin-by-contract library
 test_files: []