peeek 1.0.1

data/lib/peeek/calls.rb

@@ -0,0 +1,43 @@
+class Peeek
+  class Calls < Array
+
+    # Filter the calls by name of a file.
+    #
+    # @param [String, Regexp] file name or pattern of a file
+    # @return [Peeek::Calls] filtered calls
+    def in(file)
+      Calls.new(select { |call| file === call.file })
+    end
+
+    # Filter the calls by line number.
+    #
+    # @param [Number, Range<Number>] line line number or range of lines
+    # @return [Peeek::Calls] filtered calls
+    def at(line)
+      Calls.new(select { |call| line === call.line })
+    end
+
+    # Filter the calls by a receiver.
+    #
+    # @param [Module, Class, Object] receiver
+    # @return [Peeek::Calls] filtered calls
+    def from(receiver)
+      Calls.new(select { |call| call.receiver == receiver })
+    end
+
+    # Filter only the calls that a value returned.
+    #
+    # @return [Peeek::Calls] filtered calls
+    def return_values
+      Calls.new(select(&:returned?))
+    end
+
+    # Filter only the calls that an exception raised.
+    #
+    # @return [Peeek::Calls] filtered calls
+    def exceptions
+      Calls.new(select(&:raised?))
+    end
+
+  end
+end

data/lib/peeek/hook.rb

@@ -0,0 +1,188 @@
+require 'peeek/hook/instance'
+require 'peeek/hook/singleton'
+require 'peeek/call'
+require 'peeek/calls'
+
+class Peeek
+  class Hook
+
+    # Create a hook to method of an object. The hook can apply to a instance
+    # method or a singleton method.
+    #
+    # @example Hook to an instance method
+    #   Peeek::Hook.create(IO, '#puts')
+    #     # => #<Peeek::Hook IO#puts>
+    #
+    #   # Hook implicitly to the instance method if the object is a module or
+    #   # a class.
+    #   Peeek::Hook.create(IO, :puts)
+    #     # => #<Peeek::Hook IO#puts>
+    #
+    #   # Can't hook to the instance method if the object is an instance of any
+    #   # class.
+    #   Peeek::Hook.create($stdout, '#puts')
+    #     # => raise #<ArgumentError: can't create a hook of instance method to an instance of any class>
+    #
+    # @example Hook to an singleton method
+    #   Peeek::Hook.create($stdout, '.puts')
+    #     # => #<Peeek::Hook #<IO:<STDOUT>>.puts>
+    #
+    #   # hook implicitly to the singleton method if the object is an instance
+    #   # of any class.
+    #   Peeek::Hook.create($stdout, :puts)
+    #     # => #<Peeek::Hook #<IO:<STDOUT>>.puts>
+    #
+    # @param [Module, Class, Object] object a target object that hook
+    # @param [String, Symbol] method_spec method specification of the object
+    # @yield [call] process a call to the method. give optionally
+    # @yieldparam [Peeek::Call] call a call to the method
+    # @return [Peeek::Hook] a hook to the method of the object
+    def self.create(object, method_spec, &process)
+      linker_class, method_name = parse(method_spec)
+      linker_class = any_module?(object) ? Instance : Singleton unless linker_class
+      new(object, method_name, linker_class, &process)
+    end
+
+    # Determine if an object is a module or a class.
+    #
+    # @param [Module, Class, Object] object an object
+    # @return whether an object is a module or a class
+    def self.any_module?(object)
+      object.class == Module || object.class == Class
+    end
+
+    # Determine if an object is an instance of any class.
+    #
+    # @param [Module, Class, Object] object an object
+    # @return whether an object is an instance of any class
+    def self.any_instance?(object)
+      !any_module?(object)
+    end
+
+    # Initialize the hook.
+    #
+    # @param [Module, Class, Object] object a target object that hook
+    # @param [Symbol] method_name method name of the object
+    # @param [Class] linker_class class of an object to link the hook
+    # @yield [call] process a call to the method. give optionally
+    # @yieldparam [Peeek::Call] call a call to the method
+    def initialize(object, method_name, linker_class, &process)
+      raise ArgumentError, "invalid as linker class, #{Linker.classes.join(' or ')} are valid" unless Linker.classes.include?(linker_class)
+      @object = object
+      @method_name = method_name
+      @linker = linker_class.new(object, method_name)
+      @process = process
+      @calls = Calls.new
+      raise ArgumentError, "can't create a hook of instance method to an instance of any class" if self.class.any_instance?(object) and instance?
+    end
+
+    # @attribute [r] object
+    # @return [Module, Class, Object] a target object that hook
+    attr_reader :object
+
+    # @attribute [r] method_name
+    # @return [Symbol] method name of the object
+    attr_reader :method_name
+
+    # @attribute [r] calls
+    # @return [Peeek::Calls] calls to the method that the hook captured
+    attr_reader :calls
+
+    # Determine if the hook to an instance method.
+    #
+    # @return whether the hook to an instance method
+    def instance?
+      @linker.is_a?(Instance)
+    end
+
+    # Determine if the hook to a singleton method.
+    #
+    # @return whether the hook to a singleton method
+    def singleton?
+      @linker.is_a?(Singleton)
+    end
+
+    # Determine if the method is defined in the object
+    #
+    # @return whether the method is defined in the object
+    def defined?
+      @linker.defined?
+    end
+
+    # Determine if the hook is linked to the method
+    #
+    # @return whether the hook is linked to the method
+    def linked?
+      instance_variable_defined?(:@original_method)
+    end
+
+    # Link the hook to the method.
+    def link
+      @original_method = @linker.link(&method(:call)) unless linked?
+      self
+    end
+
+    # Unlink the hook from the method.
+    def unlink
+      if linked?
+        @linker.unlink(@original_method)
+        remove_instance_variable(:@original_method)
+      end
+
+      self
+    end
+
+    def to_s
+      @object.inspect + @linker.method_prefix + @method_name.to_s
+    end
+
+    def inspect
+      state = []
+      state << 'linked' if linked?
+      state_string = state.empty? ? '' : " (#{state * ', '})"
+      "#<#{self.class} #{self}#{state_string}>"
+    end
+
+    private
+
+    INSTANCE_METHOD_PREFIXES  = %w(#)
+    SINGLETON_METHOD_PREFIXES = %w(. .# ::)
+    METHOD_PREFIXES           = INSTANCE_METHOD_PREFIXES + SINGLETON_METHOD_PREFIXES
+
+    def self.parse(method_spec)
+      method_spec = method_spec.to_s
+
+      method_prefix = METHOD_PREFIXES.sort_by(&:length).reverse.find do |method_prefix|
+        method_spec.start_with?(method_prefix)
+      end
+
+      return nil, method_spec.to_sym unless method_prefix
+
+      linker_class = INSTANCE_METHOD_PREFIXES.include?(method_prefix) ? Instance : Singleton
+      method_name = method_spec.to_s.sub(/^#{Regexp.quote(method_prefix || '')}/, '').to_sym
+      [linker_class, method_name]
+    end
+
+    class << self
+      private :parse
+    end
+
+    def call(backtrace, receiver, args)
+      method = @original_method.is_a?(UnboundMethod) ? @original_method.bind(receiver) : @original_method
+
+      result = begin
+                 Call::ReturnValue.new(method[*args])
+               rescue => e
+                 e.set_backtrace(backtrace)
+                 Call::Exception.new(e)
+               end
+
+      call = Call.new(self, backtrace, receiver, args, result)
+      @calls << call
+      @process[call] if @process
+      raise call.exception if call.raised?
+      call.return_value
+    end
+
+  end
+end

data/lib/peeek/hook/instance.rb

@@ -0,0 +1,51 @@
+require 'peeek/hook/linker'
+
+class Peeek
+  class Hook
+    class Instance < Linker
+      METHOD_PREFIX = '#'.freeze
+
+      # @attribute [r] method_prefix
+      # @return [String] method prefix for instance method. return always "#"
+      def method_prefix
+        METHOD_PREFIX
+      end
+
+      # Determine if the instance method is defined in the object.
+      #
+      # @return whether the instance method is defined in the object
+      def defined?
+        @object.method_defined?(@method_name) or @object.private_method_defined?(@method_name)
+      end
+
+      # Link the hook to the instance method.
+      #
+      # @yield [backtrace, receiver, args] callback for hook
+      # @yieldparam [Array<String>] backtrace backtrace the call occurred
+      # @yieldparam [Object] receiver object that received the call
+      # @yieldparam [Array] args arguments at the call
+      # @yieldreturn [Object] return value of the original method
+      # @return [UnboundMethod] the original method
+      def link
+        raise ArgumentError, 'block not supplied' unless block_given?
+        original_method = @object.instance_method(@method_name)
+        define_method { |*args| yield caller, self, args }
+        original_method
+      end
+
+      # Unlink the hook from the instance method.
+      #
+      # @param [UnboundMethod] original_method original method
+      def unlink(original_method)
+        define_method(original_method)
+      end
+
+      private
+
+      def define_method(*args, &block)
+        @object.__send__(:define_method, @method_name, *args, &block)
+      end
+
+    end
+  end
+end

data/lib/peeek/hook/linker.rb

@@ -0,0 +1,29 @@
+class Peeek
+  class Hook
+    class Linker
+      @classes = []
+
+      class << self
+
+        # @attribute [r] classes
+        # @return [Array<Class>] classes valid as linker
+        attr_reader :classes
+
+      end
+
+      def self.inherited(klass)
+        @classes << klass
+      end
+
+      # Initialize the linker.
+      #
+      # @param [Module, Class, Object] object a target object that hook
+      # @param [Symbol] method_name method name of the object
+      def initialize(object, method_name)
+        @object = object
+        @method_name = method_name
+      end
+
+    end
+  end
+end

data/lib/peeek/hook/singleton.rb

@@ -0,0 +1,52 @@
+require 'peeek/hook/linker'
+
+class Peeek
+  class Hook
+    class Singleton < Linker
+      METHOD_PREFIX = '.'.freeze
+
+      # @attribute [r] method_prefix
+      # @return [String] method prefix for singleton method. return always "."
+      def method_prefix
+        METHOD_PREFIX
+      end
+
+      # Determine if the method is defined in the object.
+      #
+      # @return whether the method is defined in the object
+      def defined?
+        @object.respond_to?(@method_name, true)
+      end
+
+      # Link the hook to the method.
+      #
+      # @yield [backtrace, receiver, args] callback for hook
+      # @yieldparam [Array<String>] backtrace backtrace the call occurred
+      # @yieldparam [Object] receiver object that received the call
+      # @yieldparam [Array] args arguments at the call
+      # @yieldreturn [Object] return value of the original method
+      # @return [Method] original method
+      def link
+        raise ArgumentError, 'block not supplied' unless block_given?
+        original_method = @object.method(@method_name)
+        define_method { |*args| yield caller, self, args }
+        original_method
+      end
+
+      # Unlink the hook from the method.
+      #
+      # @param [Method] original_method original method
+      def unlink(original_method)
+        define_method(&original_method)
+      end
+
+      private
+
+      def define_method(&block)
+        singleton_class = class << @object; self end
+        singleton_class.__send__(:define_method, @method_name, &block)
+      end
+
+    end
+  end
+end

data/lib/peeek/hooks.rb

@@ -0,0 +1,46 @@
+class Peeek
+  class Hooks < Array
+
+    # Get a hook by an object and a method name.
+    #
+    # @param [Module, Class, Object] object object of a hook to get
+    # @param [Symbol] method_name method name of a hook to get. get only the
+    #   hook by the object if omitted
+    # @return [Peeek::Hook] a hook to be got
+    # @return [nil] if a hook that corresponds to the object and the method name
+    #   doesn't exist
+    def get(object, method_name = nil)
+      if method_name.nil?
+        find { |hook| hook.object == object }
+      else
+        find { |hook| hook.object == object && hook.method_name == method_name }
+      end
+    end
+
+    # Clear the hooks.
+    def clear
+      each do |hook|
+        hook.unlink
+        hook.calls.clear
+      end
+
+      super
+    end
+
+    # Run process while circumvent the hooks.
+    #
+    # @yield any process that wants to run while circumvent the hooks
+    def circumvent
+      raise ArgumentError, 'block not supplied' unless block_given?
+
+      linked_hooks = select(&:linked?).each(&:unlink)
+
+      begin
+        yield
+      ensure
+        linked_hooks.each(&:link)
+      end
+    end
+
+  end
+end

data/lib/peeek/supervisor.rb

@@ -0,0 +1,120 @@
+require 'peeek/hooks'
+
+class Peeek
+  class Supervisor
+
+    # Create a supervisor for instance methods.
+    #
+    # @return [Peeek::Supervisor] a supervisor for instance methods
+    def self.create_for_instance
+      new(:method_added)
+    end
+
+    # Create a supervisor for singleton methods.
+    #
+    # @return [Peeek::Supervisor] a supervisor for singleton methods
+    def self.create_for_singleton
+      new(:singleton_method_added)
+    end
+
+    # Initialize the supervisor.
+    #
+    # @param [Symbol] callback_name name of the method that is called when
+    #   methods was added to object of a hook
+    def initialize(callback_name)
+      @callback_name = callback_name
+      @hooks = Hooks.new
+      @original_callbacks = {}
+    end
+
+    # @attribute [r] hooks
+    # @return [Peeek::Hooks] hooks that is registered to the supervisor
+    attr_reader :hooks
+
+    # @attribute [r] original_callbacks
+    # @return [Hash<Object, Method>] original callbacks of objects that is
+    #   supervising
+    attr_reader :original_callbacks
+
+    # Add hooks to target that is supervised.
+    #
+    # @param [Array<Peeek::Hook>] hooks hooks that is supervised
+    def add(*hooks)
+      @hooks.push(*hooks)
+
+      hooks.map(&:object).uniq.each do |object|
+        @original_callbacks[object] = proceed(object) unless proceeded?(object)
+      end
+
+      self
+    end
+    alias << add
+
+    # Clear the hooks and the objects that is supervising.
+    def clear
+      @hooks.clear
+      define_callbacks(@original_callbacks).clear
+      self
+    end
+
+    # Run process while circumvent supervision.
+    #
+    # @yield any process that wants to run while circumvent supervision
+    def circumvent(&process)
+      current_callbacks = @original_callbacks.keys.map do |object|
+        [object, object.method(@callback_name)]
+      end
+
+      define_callbacks(@original_callbacks)
+
+      begin
+        @hooks.circumvent(&process)
+      ensure
+        define_callbacks(Hash[current_callbacks])
+      end
+    end
+
+    private
+
+    def proceeded?(object)
+      !!@original_callbacks[object]
+    end
+
+    def proceed(object)
+      supervisor = self
+      hooks = @hooks
+      original_callbacks = @original_callbacks
+
+      object.method(@callback_name).tap do |original_callback|
+        define_callback(object) do |method_name|
+          hook = hooks.get(self, method_name)
+
+          if hook
+            hooks.delete(hook)
+
+            unless hooks.get(self)
+              original_callback = original_callbacks.delete(self)
+              supervisor.__send__(:define_callback, self, &original_callback)
+            end
+
+            hook.link
+          end
+
+          original_callback[method_name]
+        end
+      end
+    end
+
+    def define_callback(object, &proc)
+      singleton_class = class << object; self end
+      singleton_class.__send__(:define_method, @callback_name, &proc)
+    end
+
+    def define_callbacks(callbacks)
+      callbacks.each do |object, callback|
+        define_callback(object, &callback)
+      end
+    end
+
+  end
+end