sbf-dm-core 1.3.0.beta

data/lib/dm-core/support/equalizer.rb

@@ -0,0 +1,48 @@
+module DataMapper
+  module Equalizer
+    def equalize(*methods)
+      define_eql_method(methods)
+      define_equivalent_method(methods)
+      define_hash_method(methods)
+    end
+
+    private
+
+    def define_eql_method(methods)
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def eql?(other)
+          return true if equal?(other)
+          instance_of?(other.class) &&
+          #{methods.map { |method| "#{method}.eql?(other.#{method})" }.join(' && ')}
+        end
+      RUBY
+    end
+
+    def define_equivalent_method(methods)
+      respond_to = []
+      equivalent = []
+
+      methods.each do |method|
+        respond_to << "other.respond_to?(#{method.inspect})"
+        equivalent << "#{method} == other.#{method}"
+      end
+
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def ==(other)
+          return true if equal?(other)
+          return false unless kind_of?(other.class) || other.kind_of?(self.class)
+          #{respond_to.join(' && ')} &&
+          #{equivalent.join(' && ')}
+        end
+      RUBY
+    end
+
+    def define_hash_method(methods)
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def hash
+          self.class.hash ^ #{methods.map { |method| "#{method}.hash" }.join(' ^ ')}
+        end
+      RUBY
+    end
+  end
+end

data/lib/dm-core/support/ext/array.rb

@@ -0,0 +1,22 @@
+module DataMapper; module Ext
+  module Array
+    # Transforms an Array of key/value pairs into a {Mash}.
+    #
+    # This is a better idiom than using Mash[*array.flatten] in Ruby 1.8.6
+    # because it is not possible to limit the flattening to a single
+    # level.
+    #
+    # @param [Array] array
+    #   The array of key/value pairs to transform.
+    #
+    # @return [Mash]
+    #   A {Mash} where each entry in the Array is turned into a key/value.
+    #
+    # @api semipublic
+    def self.to_mash(array)
+      m = Mash.new
+      array.each { |k,v| m[k] = v }
+      m
+    end
+  end # class Array
+end; end

data/lib/dm-core/support/ext/blank.rb

@@ -0,0 +1,25 @@
+module DataMapper
+  module Ext
+    # Determines whether the specified +value+ is blank.
+    #
+    # An object is blank if it's false, empty, or a whitespace string.
+    # For example, "", "   ", +nil+, [], and {} are blank.
+    #
+    # @api semipublic
+    def self.blank?(value)
+      return value.blank? if value.respond_to?(:blank?)
+      case value
+      when ::NilClass, ::FalseClass
+        true
+      when ::TrueClass, ::Numeric
+        false
+      when ::Array, ::Hash
+        value.empty?
+      when ::String
+        value !~ /\S/
+      else
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+    end
+  end
+end

data/lib/dm-core/support/ext/hash.rb

@@ -0,0 +1,67 @@
+module DataMapper; module Ext
+  module Hash
+    # Creates a hash with *only* the specified key/value pairs from +hash+.
+    #
+    # @param [Hash] hash The hash from which to pick the key/value pairs.
+    # @param [Array] *keys The hash keys to include.
+    #
+    # @return [Hash] A new hash with only the selected keys.
+    #
+    # @example
+    #   hash = { :one => 1, :two => 2, :three => 3 }
+    #   Ext::Hash.only(hash, :one, :two) # => { :one => 1, :two => 2 }
+    #
+    # @api semipublic
+    def self.only(hash, *keys)
+      h = {}
+      keys.each {|k| h[k] = hash[k] if hash.has_key?(k) }
+      h
+    end
+
+    # Returns a hash that includes everything but the given +keys+.
+    #
+    # @param [Hash] hash The hash from which to pick the key/value pairs.
+    # @param [Array] *keys The hash keys to exclude.
+    #
+    # @return [Hash] A new hash without the specified keys.
+    #
+    # @example
+    #   hash = { :one => 1, :two => 2, :three => 3 }
+    #   Ext::Hash.except(hash, :one, :two) # => { :three => 3 }
+    #
+    # @api semipublic
+    def self.except(hash, *keys)
+      self.except!(hash.dup, *keys)
+    end
+
+    # Removes the specified +keys+ from the given +hash+.
+    #
+    # @param [Hash] hash The hash to modify.
+    # @param [Array] *keys The hash keys to exclude.
+    #
+    # @return [Hash] +hash+
+    #
+    # @example
+    #   hash = { :one => 1, :two => 2, :three => 3 }
+    #   Ext::Hash.except!(hash, :one, :two)
+    #   hash # => { :three => 3 }
+    #
+    # @api semipublic
+    def self.except!(hash, *keys)
+      keys.each { |key| hash.delete(key) }
+      hash
+    end
+
+    # Converts the specified +hash+ to a {Mash}.
+    #
+    # @param [Hash] hash The hash to convert.
+    # @return [Mash] The {Mash} for the specified +hash+.
+    #
+    # @api semipublic
+    def self.to_mash(hash)
+      h = Mash.new(hash)
+      h.default = hash.default
+      h
+    end
+  end
+end; end

data/lib/dm-core/support/ext/module.rb

@@ -0,0 +1,47 @@
+module DataMapper; module Ext
+  module Module
+
+    # @api semipublic
+    def self.find_const(mod, const_name)
+      if const_name[0..1] == '::'
+        DataMapper::Ext::Object.full_const_get(const_name[2..-1])
+      else
+        nested_const_lookup(mod, const_name)
+      end
+    end
+
+  private
+
+    # Doesn't do any caching since constants can change with remove_const
+    def self.nested_const_lookup(mod, const_name)
+      unless mod.equal?(::Object)
+        constants = []
+
+        mod.name.split('::').each do |part|
+          const = constants.last || ::Object
+          constants << const.const_get(part)
+        end
+
+        parts = const_name.split('::')
+
+        # from most to least specific constant, use each as a base and try
+        # to find a constant with the name const_name within them
+        constants.reverse_each do |const|
+          # return the nested constant if available
+          return const if parts.all? do |part|
+            const = if RUBY_VERSION >= '1.9.0'
+              const.const_defined?(part, false) ? const.const_get(part, false) : nil
+            else
+              const.const_defined?(part) ? const.const_get(part) : nil
+            end
+          end
+        end
+      end
+
+      # no relative constant found, fallback to an absolute lookup and
+      # use const_missing if not found
+      DataMapper::Ext::Object.full_const_get(const_name)
+    end
+
+  end
+end; end

data/lib/dm-core/support/ext/object.rb

@@ -0,0 +1,57 @@
+module DataMapper; module Ext
+  module Object
+    # Returns the value of the specified constant.
+    #
+    # @overload full_const_get(obj, name)
+    #   Returns the value of the specified constant in +obj+.
+    #   @param [Object] obj The root object used as origin.
+    #   @param [String] name The name of the constant to get, e.g. "Merb::Router".
+    #
+    # @overload full_const_get(name)
+    #   Returns the value of the fully-qualified constant.
+    #   @param [String] name The name of the constant to get, e.g. "Merb::Router".
+    #
+    # @return [Object] The constant corresponding to +name+.
+    #
+    # @api semipublic
+    def self.full_const_get(obj, name = nil)
+      obj, name = ::Object, obj if name.nil?
+
+      list = name.split("::")
+      list.shift if DataMapper::Ext.blank?(list.first)
+      list.each do |x|
+        # This is required because const_get tries to look for constants in the
+        # ancestor chain, but we only want constants that are HERE
+        obj = obj.const_defined?(x) ? obj.const_get(x) : obj.const_missing(x)
+      end
+      obj
+    end
+
+    # Sets the specified constant to the given +value+.
+    #
+    # @overload full_const_set(obj, name)
+    #   Sets the specified constant in +obj+ to the given +value+.
+    #   @param [Object] obj The root object used as origin.
+    #   @param [String] name The name of the constant to set, e.g. "Merb::Router".
+    #   @param [Object] value The value to assign to the constant.
+    #
+    # @overload full_const_set(name)
+    #   Sets the fully-qualified constant to the given +value+.
+    #   @param [String] name The name of the constant to set, e.g. "Merb::Router".
+    #   @param [Object] value The value to assign to the constant.
+    #
+    # @return [Object] The constant corresponding to +name+.
+    #
+    # @api semipublic
+    def self.full_const_set(obj, name, value = nil)
+      obj, name, value = ::Object, obj, name if value.nil?
+
+      list = name.split("::")
+      toplevel = DataMapper::Ext.blank?(list.first)
+      list.shift if toplevel
+      last = list.pop
+      obj = list.empty? ? ::Object : DataMapper::Ext::Object.full_const_get(list.join("::"))
+      obj.const_set(last, value) if obj && !obj.const_defined?(last)
+    end
+  end
+end; end

data/lib/dm-core/support/ext/string.rb

@@ -0,0 +1,24 @@
+module DataMapper; module Ext
+  module String
+    # Replace sequences of whitespace (including newlines) with either
+    # a single space or remove them entirely (according to param _spaced_).
+    #
+    #   compress_lines(<<QUERY)
+    #     SELECT name
+    #     FROM users
+    #   QUERY => "SELECT name FROM users"
+    #
+    # @param [String] string
+    #   The input string.
+    #
+    # @param [TrueClass, FalseClass] spaced (default=true)
+    #   Determines whether returned string has whitespace collapsed or removed.
+    #
+    # @return [String] The input string with whitespace (including newlines) replaced.
+    #
+    # @api semipublic
+    def self.compress_lines(string, spaced = true)
+      string.split($/).map { |line| line.strip }.join(spaced ? ' ' : '')
+    end
+  end
+end; end

data/lib/dm-core/support/ext/try_dup.rb

@@ -0,0 +1,12 @@
+module DataMapper
+  module Ext
+    def self.try_dup(value)
+      case value
+      when ::TrueClass, ::FalseClass, ::NilClass, ::Module, ::Numeric, ::Symbol
+        value
+      else
+        value.dup
+      end
+    end
+  end
+end

data/lib/dm-core/support/hook.rb

@@ -0,0 +1,388 @@
+module DataMapper
+  #
+  # TODO: Write more documentation!
+  #
+  # Overview
+  # ========
+  #
+  # The Hook module is a very simple set of AOP helpers. Basically, it
+  # allows the developer to specify a method or block that should run
+  # before or after another method.
+  #
+  # Usage
+  # =====
+  #
+  # Halting The Hook Stack
+  #
+  # Inheritance
+  #
+  # Other Goodies
+  #
+  # Please bring up any issues regarding Hooks with carllerche on IRC
+  #
+  module Hook
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.const_set('CLASS_HOOKS', {}) unless base.const_defined?('CLASS_HOOKS')
+      base.const_set('INSTANCE_HOOKS', {}) unless base.const_defined?('INSTANCE_HOOKS')
+      base.class_eval do
+        class << self
+          def method_added(name)
+            process_method_added(name, :instance)
+            super
+          end
+
+          def singleton_method_added(name)
+            process_method_added(name, :class)
+            super
+          end
+        end
+      end
+      super
+    end
+
+    module ClassMethods
+      extend DataMapper::LocalObjectSpace
+      include DataMapper::Assertions
+      # Inject code that executes before the target class method.
+      #
+      # @param target_method<Symbol>  the name of the class method to inject before
+      # @param method_sym<Symbol>     the name of the method to run before the
+      #   target_method
+      # @param block<Block>           the code to run before the target_method
+      #
+      # @note
+      #   Either method_sym or block is required.
+      # -
+      # @api public
+      def before_class_method(target_method, method_sym = nil, &block)
+        install_hook :before, target_method, method_sym, :class, &block
+      end
+
+      #
+      # Inject code that executes after the target class method.
+      #
+      # @param target_method<Symbol>  the name of the class method to inject after
+      # @param method_sym<Symbol>     the name of the method to run after the target_method
+      # @param block<Block>           the code to run after the target_method
+      #
+      # @note
+      #   Either method_sym or block is required.
+      # -
+      # @api public
+      def after_class_method(target_method, method_sym = nil, &block)
+        install_hook :after, target_method, method_sym, :class, &block
+      end
+
+      #
+      # Inject code that executes before the target instance method.
+      #
+      # @param target_method<Symbol>  the name of the instance method to inject before
+      # @param method_sym<Symbol>     the name of the method to run before the
+      #   target_method
+      # @param block<Block>           the code to run before the target_method
+      #
+      # @note
+      #   Either method_sym or block is required.
+      # -
+      # @api public
+      def before(target_method, method_sym = nil, &block)
+        install_hook :before, target_method, method_sym, :instance, &block
+      end
+
+      #
+      # Inject code that executes after the target instance method.
+      #
+      # @param target_method<Symbol>  the name of the instance method to inject after
+      # @param method_sym<Symbol>     the name of the method to run after the
+      #   target_method
+      # @param block<Block>           the code to run after the target_method
+      #
+      # @note
+      #   Either method_sym or block is required.
+      # -
+      # @api public
+      def after(target_method, method_sym = nil, &block)
+        install_hook :after, target_method, method_sym, :instance, &block
+      end
+
+      # Register a class method as hook-able. Registering a method means that
+      # before hooks will be run immediately before the method is invoked and
+      # after hooks will be called immediately after the method is invoked.
+      #
+      # @param hooks <Symbol> The name of the class method that should
+      #   be hook-able
+      # -
+      # @api public
+      def register_class_hooks(*hooks)
+        hooks.each { |hook| register_hook(hook, :class) }
+      end
+
+      # Register an instance method as hook-able. Registering a method means that
+      # before hooks will be run immediately before the method is invoked and
+      # after hooks will be called immediately after the method is invoked.
+      #
+      # @param hooks <Symbol> The name of the instance method that should
+      #   be hook-able
+      # -
+      # @api public
+      def register_instance_hooks(*hooks)
+        hooks.each { |hook| register_hook(hook, :instance) }
+      end
+
+      # Not yet implemented
+      def reset_hook!(_target_method, _scope)
+        raise NotImplementedError
+      end
+
+      # --- Alright kids... the rest is internal stuff ---
+
+      # Returns the correct HOOKS Hash depending on whether we are
+      # working with class methods or instance methods
+      def hooks_with_scope(scope)
+        case scope
+        when :class    then class_hooks
+        when :instance then instance_hooks
+        else raise ArgumentError, 'You need to pass :class or :instance as scope'
+        end
+      end
+
+      def class_hooks
+        const_get('CLASS_HOOKS')
+      end
+
+      def instance_hooks
+        const_get('INSTANCE_HOOKS')
+      end
+
+      # Registers a method as hook-able. Registering hooks involves the following
+      # process
+      #
+      # * Create a blank entry in the HOOK Hash for the method.
+      # * Define the methods that execute the before and after hook stack.
+      #   These methods will be no-ops at first, but everytime a new hook is
+      #   defined, the methods will be redefined to incorporate the new hook.
+      # * Redefine the method that is to be hook-able so that the hook stacks
+      #   are invoked appropriately.
+      def register_hook(target_method, scope)
+        if scope == :instance && !method_defined?(target_method)
+          raise ArgumentError, "#{target_method} instance method does not exist"
+        elsif scope == :class && !respond_to?(target_method)
+          raise ArgumentError, "#{target_method} class method does not exist"
+        end
+
+        hooks = hooks_with_scope(scope)
+
+        return unless hooks[target_method].nil?
+
+        hooks[target_method] = {
+          # We need to keep track of which class in the Inheritance chain the
+          # method was declared hook-able in. Every time a child declares a new
+          # hook for the method, the hook stack invocations need to be redefined
+          # in the original Class. See #define_hook_stack_execution_methods
+          before: [], after: [], in: self
+        }
+
+        define_hook_stack_execution_methods(target_method, scope)
+        define_advised_method(target_method, scope)
+      end
+
+      # Is the method registered as a hook-able in the given scope.
+      def registered_as_hook?(target_method, scope)
+        !hooks_with_scope(scope)[target_method].nil?
+      end
+
+      # Generates names for the various utility methods. We need to do this because
+      # the various utility methods should not end in = so, while we're at it, we
+      # might as well get rid of all punctuation.
+      def hook_method_name(target_method, prefix, suffix)
+        target_method = target_method.to_s
+
+        case target_method[-1, 1]
+        when '?' then "#{prefix}_#{target_method[0..-2]}_ques_#{suffix}"
+        when '!' then "#{prefix}_#{target_method[0..-2]}_bang_#{suffix}"
+        when '=' then "#{prefix}_#{target_method[0..-2]}_eq_#{suffix}"
+          # I add a _nan_ suffix here so that we don't ever encounter
+          # any naming conflicts.
+        else "#{prefix}_#{target_method}_nan_#{suffix}"
+        end
+      end
+
+      # This will need to be refactored
+      def process_method_added(method_name, scope)
+        hooks_with_scope(scope).each do |target_method, hooks|
+          define_hook_stack_execution_methods(target_method, scope) if hooks[:before].any? { |hook| hook[:name] == method_name }
+          define_hook_stack_execution_methods(target_method, scope) if hooks[:after].any? { |hook| hook[:name] == method_name }
+        end
+      end
+
+      # Defines two methods. One method executes the before hook stack. The other executes
+      # the after hook stack. This method will be called many times during the Class definition
+      # process. It should be called for each hook that is defined. It will also be called
+      # when a hook is redefined (to make sure that the arity hasn't changed).
+      def define_hook_stack_execution_methods(target_method, scope)
+        raise ArgumentError, "#{target_method} has not be registered as a hook-able #{scope} method" unless registered_as_hook?(target_method, scope)
+
+        hooks = hooks_with_scope(scope)
+
+        before_hooks = hooks[target_method][:before]
+        before_hooks = before_hooks.map { |info| inline_call(info, scope) }.join("\n")
+
+        after_hooks  = hooks[target_method][:after]
+        after_hooks  = after_hooks.map { |info| inline_call(info, scope) }.join("\n")
+
+        before_hook_name = hook_method_name(target_method, 'execute_before', 'hook_stack')
+        after_hook_name  = hook_method_name(target_method, 'execute_after',  'hook_stack')
+
+        hooks[target_method][:in].class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          #{(scope == :class) ? 'class << self' : ''}
+
+          private
+
+          remove_method :#{before_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
+          def #{before_hook_name}(*args)
+            #{before_hooks}
+          end
+
+          remove_method :#{after_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{after_hook_name} }
+          def #{after_hook_name}(*args)
+            #{after_hooks}
+          end
+
+          #{(scope == :class) ? 'end' : ''}
+        RUBY
+      end
+
+      # Returns ruby code that will invoke the hook. It checks the arity of the hook method
+      # and passes arguments accordingly.
+      def inline_call(method_info, scope)
+        DataMapper::Hook::ClassMethods.hook_scopes << method_info[:from]
+        name = method_info[:name]
+        if scope == :instance
+          args = (method_defined?(name) && instance_method(name).arity != 0) ? '*args' : ''
+          %(#{name}(#{args}) if self.class <= DataMapper::Hook::ClassMethods.object_by_id(#{method_info[:from].object_id}))
+        else
+          args = (respond_to?(name) && method(name).arity != 0) ? '*args' : ''
+          %(#{name}(#{args}) if self <= DataMapper::Hook::ClassMethods.object_by_id(#{method_info[:from].object_id}))
+        end
+      end
+
+      def define_advised_method(target_method, scope)
+        args = args_for(method_with_scope(target_method, scope))
+
+        renamed_target = hook_method_name(target_method, 'hookable_', 'before_advised')
+
+        source = <<-EOD
+          def #{target_method}(#{args})
+            retval = nil
+            catch(:halt) do
+              #{hook_method_name(target_method, 'execute_before', 'hook_stack')}(#{args})
+              retval = #{renamed_target}(#{args})
+              #{hook_method_name(target_method, 'execute_after', 'hook_stack')}(retval, #{args})
+              retval
+            end
+          end
+        EOD
+
+        if scope == :instance && instance_methods(false).none? { |m| m.to_sym == target_method }
+          send(:alias_method, renamed_target, target_method)
+
+          proxy_module = Module.new
+          proxy_module.class_eval(source, __FILE__, __LINE__)
+          send(:include, proxy_module)
+        else
+          source = %(alias_method :#{renamed_target}, :#{target_method}\n#{source})
+          source = %(class << self\n#{source}\nend) if scope == :class
+          class_eval(source, __FILE__, __LINE__)
+        end
+      end
+
+      # --- Add a hook ---
+
+      def install_hook(type, target_method, method_sym, scope, &block)
+        assert_kind_of 'target_method', target_method, Symbol
+        assert_kind_of 'method_sym',    method_sym,    Symbol unless method_sym.nil?
+        assert_kind_of 'scope',         scope,         Symbol
+
+        raise ArgumentError, "You need to pass 2 arguments to \"#{type}\"." if !block_given? && method_sym.nil?
+
+        raise ArgumentError, 'Methods ending in = cannot be hooks' if method_sym.to_s[-1, 1] == '='
+
+        raise ArgumentError, 'You need to pass :class or :instance as scope' unless %i(class instance).include?(scope)
+
+        if registered_as_hook?(target_method, scope)
+          hooks = hooks_with_scope(scope)
+
+          # if this hook is previously declared in a sibling or cousin we must move the :in class
+          # to the common ancestor to get both hooks to run.
+          unless hooks[target_method][:in] <=> self
+            before_hook_name = hook_method_name(target_method, 'execute_before', 'hook_stack')
+            after_hook_name  = hook_method_name(target_method, 'execute_after',  'hook_stack')
+
+            hooks[target_method][:in].class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              remove_method :#{before_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
+              def #{before_hook_name}(*args)
+                super
+              end
+
+              remove_method :#{after_hook_name} if instance_methods(false).any? { |m| m.to_sym == :#{before_hook_name} }
+              def #{after_hook_name}(*args)
+                super
+              end
+            RUBY
+
+            hooks[target_method][:in] = hooks[target_method][:in].superclass until hooks[target_method][:in] <=> self
+
+            define_hook_stack_execution_methods(target_method, scope)
+            hooks[target_method][:in].class_eval { define_advised_method(target_method, scope) }
+          end
+        else
+          register_hook(target_method, scope)
+          hooks = hooks_with_scope(scope)
+        end
+
+        # if we were passed a block, create a method out of it.
+        if block
+          method_sym = "__hooks_#{type}_#{quote_method(target_method)}_#{hooks[target_method][type].length}".to_sym
+          if scope == :class
+            singleton_class.instance_eval do
+              define_method(method_sym, &block)
+            end
+          else
+            define_method(method_sym, &block)
+          end
+        end
+
+        # Adds method to the stack an redefines the hook invocation method
+        hooks[target_method][type] << {name: method_sym, from: self}
+        define_hook_stack_execution_methods(target_method, scope)
+      end
+
+      # --- Helpers ---
+
+      def args_for(method)
+        if method.arity == 0
+          '&block'
+        elsif method.arity > 0
+          '_' << (1..method.arity).to_a.join(', _') << ', &block'
+        elsif (method.arity + 1) < 0
+          '_' << (1..method.arity.abs - 1).to_a.join(', _') << ', *args, &block'
+        else
+          '*args, &block'
+        end
+      end
+
+      def method_with_scope(name, scope)
+        case scope
+        when :class    then method(name)
+        when :instance then instance_method(name)
+        else raise ArgumentError, 'You need to pass :class or :instance as scope'
+        end
+      end
+
+      def quote_method(name)
+        name.to_s.gsub(/\?$/, '_q_').gsub(/!$/, '_b_').gsub(/=$/, '_eq_')
+      end
+    end
+  end
+end