evalhook

= evalhook - Alternate eval which hook all methods (and more) in the evaluated code

== Installation

=== Gem installation

Run in the terminal:

sudo gem install evalhook

OR

• Download the last version of the gem from http://github.com/tario/evalhook/downloads
• Install the gem with the following;

sudo gem install evalhook-X.X.X.gem.

== Documentation

Full API documentation can be found on: http://tario.github.com/evalhook/doc/

== Usage

This examples and more can be found in examples directory

=== Basic Example

Hook of method calls

require "rubygems"
require "evalhook"

class Hook < EvalHook::HookHandler
	def handle_method(klass, recv, method_name)
		print "called #{klass}##{method_name} over #{recv}\n"
		nil
	end
end

h = Hook.new
h.evalhook('print "hello world\n"')

=== Basic Example 2

Hook of global variables and constants

require "rubygems"
require "evalhook"

class Hook < EvalHook::HookHandler
	# global variable assignment/creation
	def handle_gasgn( global_name, new_value)
		print "assignment of #{global_name} = #{new_value}\n"
		nil
	end

	# constant assignment/creation
	def handle_cdecl( container, const_name, new_value)
		print "assignment of #{container}::#{const_name} = #{new_value}\n"
		nil
	end
end

h = Hook.new
h.evalhook('
$a = 4
A = 4', binding)

=== Basic Example 3

Redirect of method calls

require "rubygems"
require "evalhook"

class Hook < EvalHook::HookHandler
	
	include RedirectHelper
	
	def handle_method(klass, recv, method_name)
		print "called #{klass}##{method_name} over #{recv}\n"
		
		if method_name == :print
			# change the method_name to alternative_print
			Redirect.new(klass, recv, "alternative_print")
		else
			nil # do nothing
		end
		
	end
end

module Kernel
	def alternative_print(*args)
		print "alternative ", *args
	end
end

h = Hook.new
h.evalhook('print "hello world\n"')

=== MultiHookHandler Example (new feature since 0.2.0)

require "rubygems"
require "evalhook"

include EvalHook

class Hook1 < HookHandler
	def handle_method(klass,recv,method_name)
		
		if method_name == :foo
			redirect_method(klass,recv,:bar)
		else
			nil
		end
	end
end

class Hook2 < HookHandler
	def handle_method(klass,recv,method_name)

		if method_name == :bar
			redirect_method(klass,recv,:test1)
		else
			nil
		end
	end
end

class X
	def foo
		print "foo\n"
	end
	
	def bar
		print "bar\n"
	end
	
	def test1
		print "test1\n"
	end
end


x = X.new
x.foo # foo

mmh = MultiHookHandler.new
mmh.add( Hook1.new )	# :foo => :bar
mmh.add( Hook2.new )   # :bar => :test1

mmh.evalhook("x.foo") # test1
mmh.evalhook("x.bar") # test1

=== MultiHookHandler Example 2

require "rubygems"
require "evalhook"

include EvalHook

class DenyFooFilter < HookHandler
	def handle_method(klass,recv,method_name)
	
		if method_name == :foo
			raise SecurityError
		else
			nil
		end
	end
end

class RedirectFooToBar < HookHandler
	def handle_method(klass,recv,method_name)

		if method_name == :foo
			redirect_method(klass,recv,:bar)
		else
			nil
		end
	end
end

class X
	def foo
		print "foo\n"
	end
	
	def bar
		print "bar\n"
	end
end


x = X.new
x.foo # foo

mmh = MultiHookHandler.new
mmh.add( DenyFooFilter.new )	
mmh.add( RedirectFooToBar.new )

begin
mmh.evalhook("x.foo")
rescue SecurityError
print "foo method filtered by a SecurityError exception\n"
end


mmh = MultiHookHandler.new
mmh.add( RedirectFooToBar.new )
mmh.add( DenyFooFilter.new )	

mmh.evalhook("x.foo")

== Copying

Copyright (c) 2010-2011 Dario Seminara, released under the GPL License (see LICENSE)