peeek 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1d9163af655c3a81a95497b5b85dbba4806d38a8
+  data.tar.gz: 94d66998484a454134c8c41041e593f4b458b458
+SHA512:
+  metadata.gz: e4593100bd8419742be0174883536e40f7628211411f124259eef776481968486a387a2916dc958510239a7be27b266ce004f094a8b5fc87d059095d435f51cf
+  data.tar.gz: 2263f4beddadacbc497b4cc1c47a076b34c755c8ef9e8cda003b7e8ad55d7eef423fdbd427bfe014a5314bbf456feb905fd52e5fb49e76d894162221e2fc7ae6

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hoook.gemspec
+gemspec
+
+gem 'ruby18_source_location', :group => :development, :platforms => :ruby_18

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Takahiro Kondo
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+Peeek
+=====
+
+Peeek peeks at calls of a method
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'peeek'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install peeek
+
+Usage
+-----
+
+You can peek at calls of a method by `Object#peeek` (or `Peeek#hook`).
+
+    require 'peeek'
+
+    String.peeek(:%) # or Peeek.current.hook(String, :%)
+
+    format = '%s (%d)'
+    puts format % ['Koyomi',  18]
+    puts format % ['Karen',   14]
+    puts format % ['Tsukihi', 14]
+
+    puts Peeek.current.calls # => String#% from "%s (%d)" with ["Koyomi", 18] returned "Koyomi (18)" in peeek-example.rb at 6
+                             # => String#% from "%s (%d)" with ["Karen", 14] returned "Karen (14)" in peeek-example.rb at 7
+                             # => String#% from "%s (%d)" with ["Tsukihi", 14] returned "Tsukihi (14)" in peeek-example.rb at 8
+
+### How to hook to a method
+
+Call `Object#peeek` to any module or any class, hook to their instance methods.
+
+    String.peeek(:%)
+
+Also for an instance of any class, hook to its singleton methods.
+
+    $stdout.peeek(:write)
+
+If want to choose whether to hook to either instance method or singleton method,
+add "#" before in the method name in instance method, add "." in singleton
+method.
+
+    String.peeek('#%')
+    $stdout.peeek('.write')
+    Regexp.peeek('.quote')
+
+Even if the method isn't defined at the time you call `Object#peeek`, enable the
+hook when the method is defined.
+
+    Kernel.peeek(:pp)
+    require 'pp' # enable the hook
+    pp {'Koyomi' => 18, 'Karen' => 14, 'Tsukihi' => 14}
+
+### Localize a Peeek object
+
+`Peeek.local` enables hooks only in a block.
+
+    require 'peeek'
+
+    format = '%s (%d)'
+
+    calls = Peeek.local do
+      String.peeek(:%)
+      puts format % ['Koyomi', 18]
+      Peeek.current.calls
+    end
+
+    puts calls # => String#% from "%s (%d)" with ["Koyomi", 18] returned "Koyomi (18)" in peeek-local.rb at 7
+
+    puts format % ['Karen', 14] # not captured
+
+Hook to methods at head of the block, and return the calls, then use
+`Peeek.capture`.
+
+    require 'peeek'
+
+    format = '%s (%d)'
+
+    calls = Peeek.capture(String => :%) do
+      puts format % ['Koyomi',  18]
+    end
+
+    puts calls # => String#% from "%s (%d)" with ["Koyomi", 18] returned "Koyomi (18)" in peeek-capture.rb at 6
+
+    puts format % ['Karen', 14] # not captured
+
+### Filter calls
+
+`Peeek#calls` or `Peeek.local` return an instance of `Peeek::Calls`. It has
+implemented methods to filter by attributes of the call.
+
+    require 'peeek'
+
+    format = '%s (%d)'
+
+    calls = Peeek.capture(String => :%) do
+      puts format % ['Koyomi', 18]
+      puts format % ['Karen'] rescue $!
+    end
+
+    puts calls.in('peeek-calls.rb') # filter by file name
+    puts calls.in(/\.rb/)           # can also use regular expressions
+    puts calls.at(6)                # filter by line number
+    puts calls.at(1..10)            # can also use range
+    puts calls.from('%s (%d)')      # filter by receiver
+    puts calls.return_values        # filter only calls that returned a value
+    puts calls.exceptions           # filter only calls that raised an exception
+
+
+Contributing
+------------
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/peeek

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+require 'stringio'
+require 'peeek'
+
+path = ARGV.first
+
+original_stdout = $stdout
+$stdout = StringIO.new
+
+calls = begin
+          Peeek.capture(String => :%) { load path } # want to be you can specify
+        ensure
+          $stdout = original_stdout
+        end
+
+puts calls

data/lib/peeek.rb

@@ -0,0 +1,147 @@
+require 'peeek/version'
+require 'peeek/hook'
+require 'peeek/hooks'
+require 'peeek/supervisor'
+require 'peeek/calls'
+
+class Peeek
+
+  # @attribute [r] global
+  # @return [Peeek] the global Peeek object
+  def self.global
+    @global ||= new
+  end
+
+  # @attribute [r] current
+  # @return [Peeek] the current Peeek object
+  #
+  # @see Peeek.local
+  def self.current
+    @current ||= global
+  end
+
+  # Run process to switch to a local Peeek object from the current Peeek
+  # object. The local Peeek object doesn't inherit the registered hooks and
+  # supervision from the current Peeek object. The current Peeek object reverts
+  # after ran the process.
+  #
+  # @yield any process that want to run to switch
+  def self.local
+    raise ArgumentError, 'block not supplied' unless block_given?
+
+    old = current
+    @current = new
+
+    old.circumvent do
+      begin
+        yield
+      ensure
+        current.release
+        @current = old
+      end
+    end
+  end
+
+  # Capture all calls to hook targets.
+  #
+  # @param [Hash{Module, Class, Object => String, Array<String>, Symbol, Array<Symbol>}]
+  #   object_and_method_specs an object and method specification(s) that be
+  #                           target of hook
+  # @yield any process that want to run to capture
+  # @return [Peeek::Calls] calls that were captured in the block
+  def self.capture(object_and_method_specs)
+    raise ArgumentError, 'block not supplied' unless block_given?
+
+    local do
+      object_and_method_specs.each { |object, method_specs| current.hook(object, *method_specs) }
+      yield
+      current.calls
+    end
+  end
+
+  # Initialize the Peeek object.
+  def initialize
+    @hooks = Hooks.new
+    @instance_supervisor = Supervisor.create_for_instance
+    @singleton_supervisor = Supervisor.create_for_singleton
+  end
+
+  # @attribute [r] hooks
+  # @return [Peeek::Hooks] the registered hooks
+  attr_reader :hooks
+
+  # @attribute [r] calls
+  # @return [Peeek::Calls] calls to the methods that the registered hooks
+  #   captured
+  def calls
+    Calls.new(@hooks.map(&:calls).inject([], &:+))
+  end
+
+  # Register a hook to methods of an object.
+  #
+  # @param [Module, Class, Object] object a target object that hook
+  # @param [Array<String>, Array<Symbol>] method_specs method specifications of
+  #   the object. see also examples of {Peeek::Hook.create}
+  # @yield [call] process a call to the methods. give optionally
+  # @yieldparam [Peeek::Call] call a call to the methods
+  # @return [Peeek::Hooks] registered hooks at calling
+  #
+  # @see Peeek::Hook.create
+  def hook(object, *method_specs, &process)
+    hooks = method_specs.map do |method_spec|
+      Hook.create(object, method_spec, &process).tap do |hook|
+        if hook.defined?
+          hook.link
+        elsif hook.instance?
+          @instance_supervisor << hook
+        elsif hook.singleton?
+          @singleton_supervisor << hook
+        end
+      end
+    end
+
+    @hooks.push(*hooks)
+    Hooks.new(hooks)
+  end
+
+  # Release the registered hooks and supervision.
+  def release
+    @hooks.clear
+    @instance_supervisor.clear
+    @singleton_supervisor.clear
+    self
+  end
+
+  # Run process while circumvent the registered hooks and supervision.
+  #
+  # @yield any process that want to run while circumvent the registered hooks
+  #   and supervision
+  def circumvent(&process)
+    raise ArgumentError, 'block not supplied' unless block_given?
+
+    @singleton_supervisor.circumvent do
+      @instance_supervisor.circumvent do
+        @hooks.circumvent(&process)
+      end
+    end
+  end
+
+  module Readily
+
+    # Register a hook to methods of self to the current Peeek object.
+    #
+    # @param [Array<String>, Array<Symbol>] method_specs method specifications
+    #   of the object. see also examples of {Peeek::Hook.create}
+    # @yield [call] process a call to the methods. give optionally
+    # @yieldparam [Peeek::Call] call a call to the methods
+    #
+    # @see Peeek#hook
+    def peeek(*method_specs, &process)
+      Peeek.current.hook(self, *method_specs, &process)
+    end
+
+  end
+
+  Object.__send__(:include, Readily)
+
+end

data/lib/peeek/call.rb

@@ -0,0 +1,134 @@
+class Peeek
+  class Call
+
+    # Initialize the call.
+    #
+    # @param [Peeek::Hook] hook hook the call occurred
+    # @param [Array<String>] backtrace backtrace the call occurred
+    # @param [Module, Class, Object] receiver object that received the call
+    # @param [Array] arguments arguments at the call
+    # @param [Peeek::Call::Result] result result of the call
+    def initialize(hook, backtrace, receiver, arguments, result)
+      raise ArgumentError, 'invalid as result' unless result.is_a?(Result)
+      @hook = hook
+      @backtrace = backtrace
+      @file, @line = extract_file_and_line(backtrace.first)
+      @receiver = receiver
+      @arguments = arguments
+      @result = result
+    end
+
+    # @attribute [r] hook
+    # @return [Peeek::Hook] hook the call occurred
+    attr_reader :hook
+
+    # @attribute [r] backtrace
+    # @return [Array<String>] backtrace the call occurred
+    attr_reader :backtrace
+
+    # @attribute [r] file
+    # @return [String] name of file the call occurred
+    attr_reader :file
+
+    # @attribute [r] line
+    # @return [Integer] line number the call occurred
+    attr_reader :line
+
+    # @attribute [r] receiver
+    # @return [Module, Class, Object] object that received the call
+    attr_reader :receiver
+
+    # @attribute [r] arguments
+    # @return [Array] arguments at the call
+    attr_reader :arguments
+
+    # @attribute [r] result
+    # @return [Peeek::Call::Result] result of the call
+    attr_reader :result
+
+    # @attribute [r] return_value
+    # @return [Object] value that the call returned
+    def return_value
+      raise TypeError, "the call didn't return a value" unless returned?
+      @result.value
+    end
+
+    # @attribute [r] exception
+    # @return [StandardError] exception that raised from the call
+    def exception
+      raise TypeError, "the call didn't raised an exception" unless raised?
+      @result.value
+    end
+
+    # Determine if the result is a return value.
+    #
+    # @return whether the result is a return value
+    def returned?
+      @result.is_a?(ReturnValue)
+    end
+
+    # Determine if the result is an exception.
+    #
+    # @return whether the result is an exception
+    def raised?
+      @result.is_a?(Exception)
+    end
+
+    def to_s
+      parts = [@hook.to_s]
+      parts << "from #{@receiver.inspect}"
+
+      if @arguments.size == 1
+        parts << "with #{@arguments.first.inspect}"
+      elsif @arguments.size > 1
+        parts << "with (#{@arguments.map(&:inspect) * ', '})"
+      end
+
+      if returned?
+        parts << "returned #{return_value.inspect}"
+      elsif raised?
+        parts << "raised #{exception.inspect}"
+      end
+
+      parts << "in #{@file}"
+      parts << "at #{@line}"
+      parts * ' '
+    end
+
+    private
+
+    def extract_file_and_line(string)
+      _, file, line = /^(.+):(\d+)(?::in\s+|$)/.match(string).to_a
+      raise ArgumentError, 'invalid as string of backtrace' unless file and line
+      [file, line.to_i]
+    end
+
+    class Result
+
+      # Initialize the result.
+      #
+      # @param [Object] value value of the result
+      def initialize(value)
+        @value = value
+      end
+
+      # @attribute [r] value
+      # @return [Object] value of the result
+      attr_reader :value
+
+      def ==(other)
+        self.class == other.class && @value == other.value
+      end
+      alias eql? ==
+
+      def hash
+        (self.class.hash << 32) + @value.hash
+      end
+
+    end
+
+    class ReturnValue < Result; end
+    class Exception < Result; end
+
+  end
+end