tario / evalhook

Alternate eval which hook all methods executed in the evaluated code

= 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)