psychic 0.1.1

data/README

@@ -0,0 +1,48 @@
+
+psychic is a metaprogramming module which inject a listener interface into any object.
+it was first intented to be used to make ordinary arrays listenable, but of course may 
+be used for other purposes.
+
+for example: 
+	a = [:a,:b,:c]
+	Psychic.connect(a,:delete, {|obj,method,value,*args,&proc|
+		puts "#{method}->#{obj.inspect}"}
+	a.delete :a
+	#will call proc when delete is called.
+=> delete->:a
+
+	#(the proc is called following the method)
+	#parameters to the proc are as follows:
+	#object -> the object which is being listened to.
+	#method -> name of the method which was called
+	#value -> value returned by method
+	#args -> arguements to method
+	#proc -> the proc passed to the method (if applicable)
+
+Psychic can remove procs as well, but you need to retain the reference to the proc so you must call it in a different style:
+
+	p = proc {|obj,method,*args,&proc|}
+	Psychic.connect(object,method_names,.., &p)
+	#note that the proc can be injected into many methods at once.
+
+	#now, disconnect Psychic like this:
+	Psychic.disconnect(object,method_names,.., &p)
+
+	#now the proc p will no longer be called
+	
+multiple blocks can be injected into the same methods by repeated calls to Psychic.connect()
+
+also, I have included a convience method which wraps all the methods which change the state of String,Array, and Hash
+
+	Psychic.connect_mutable(object,&proc)
+
+this is a easy way to create a listener who is notified of changes of state of a Array, String or Hash.
+
+this is my first gem. any questions/suggestions/encouragement/requests please email. dominic.tarr@gmail.com
+
+cheers!
+
+	
+
+
+	

data/lib/psychic.rb

@@ -0,0 +1,81 @@
+
+module Psychic
+	def self.make_args (arity)
+		args = []
+		var = nil
+		if(arity == 0)
+			return "&block"
+		elsif (arity < 0)
+			var = "*args"
+			arity = (arity + 1) * -1
+		end
+		arity.times{|i| args << "arg#{i}"}
+		if var then args << var; end
+		args << "&block"
+		return args.join(",")
+	end
+
+	def self.connect (object,*methods,&block)
+		prefix = "psychic_"
+
+		unless psyc_c = object.send(:instance_variable_get,:@psychic_connections) then
+			object.send(:instance_variable_set,:@psychic_connections,psyc_c = Hash.new)
+		end
+		if block.nil? then
+			raise "cannot make a psychic connection to #{object.inspect} without a block"
+		end
+
+		methods.each {|m|
+			old_m = "#{prefix}#{m}"
+	
+			unless psyc_c[m] and !(psyc_c[m].empty?) then
+
+			object.instance_eval "alias :\"#{old_m}\" :\"#{m}\""
+			psyc_c[m] = [block]
+			def object.psychic_connection (method, value,*args,&block)
+				if psy = @psychic_connections[method] then
+					psy.each{|b|
+# argh! i've found another bug in ruby!
+# def f (a,b,&block);end
+# method(:f).arity == 2
+# proc {|a,b,&block|}.arity == 1
+					unless b.arity == -4 or (b.arity == 1 and b.is_a?(Proc)) then 
+						raise "psychic connection needs arity of block to be -4, was=#{b.arity} 
+	suggest these arguments: |object,method,value,*args,&block|"
+					end
+					b.call(self,method,value,*args,&block)
+					}
+				end
+			end
+
+			args = make_args(object.method(m).arity)
+			object.instance_eval "def #{m}(#{args})
+					value = method(:\"#{old_m}\").call(#{args})
+					psychic_connection(:\"#{m}\",value,#{args})
+					return value		
+					end"
+			else
+			psyc_c[m] << block
+			end
+		}
+	end
+	def self.disconnect (object,*methods,&block)
+		psyc_c = object.send(:instance_variable_get,:@psychic_connections)
+		methods.each {|m|
+			psyc_c[m].delete block
+		}
+	end
+	def self.connect_mutable(object,&block) # connect to all mutable methods on certain core types.
+		if object.is_a? Array then
+			methods = [:"[]=",:"<<",:delete,:delete_at,:delete_if,:"flatten!",:insert,:"map!",:"collect!",:"slice!",:"uniq!",:"reverse!",:"compact!"]
+			
+		elsif object.is_a? Hash
+			methods = [:"[]=",:"default=",:"merge!",:"reject!"]
+		
+		elsif object.is_a? String
+			methods = [:"[]=",:"<<",:"capitalize!",:"chomp!",:"downcase!",:"gsub!",:"upcase!"]
+		end
+			connect(object,*methods,&block)
+	end
+end
+

data/test/test_psychic.rb

@@ -0,0 +1,168 @@
+require 'test/unit'
+require 'psychic/psychic'
+
+class TestPsychic < Test::Unit::TestCase
+include Test::Unit
+	#Psychic can make observe any object. 
+	#it's powers from from metaprogramming the subject, 
+	#aliasing mutable methods with methods which call's a closure
+	#and then calling the old method.
+
+	def test_simple
+		called = false
+		Psychic.connect(h = "Hello", :length) {|obj,method,value,*args|
+			assert_equal h,obj
+			assert_equal :length,method
+			assert_equal 5,value
+			assert_equal [],args #also test on something wit args
+			called = true
+		}
+		assert_equal 5,h.length
+		assert called, "expected psychic connection on \"#{h}\".length"
+	end
+
+	def test_with_args
+		called = 0
+		deleted = []
+		Psychic.connect(h = [:a,:b,:c], :delete) {|obj,method,value,*args,&block|
+			assert_equal h,obj
+			assert_equal :delete,method
+			assert  Symbol === value
+			assert_equal [value] ,args
+			deleted << value
+			called = called + 1
+		}
+		h.delete :a
+		h.delete :b
+		h.delete :c
+
+		assert_equal 3,called
+		assert_equal deleted,[:a,:b,:c]
+	end 
+
+	def test_multiple_connections
+
+		b_delete = b_called = called = 0
+		deleted = []
+		
+		Psychic.connect(h = [:a,:b,:c], :delete) {|obj,method,value,*args|
+			assert_equal h,obj
+			assert_equal :delete,method
+			assert  Symbol === value
+			assert_equal [value] ,args
+			deleted << value
+			called = called + 1
+		}
+		Psychic.connect(h,:"<<", :delete) {|obj,method,value,*args|
+			assert_equal h,obj
+			b_called = b_called + 1
+			if method == :delete then
+				b_delete = b_delete + 1
+			end
+		}
+		h.delete :a
+		h.delete :b
+		h.delete :c
+		h << :d
+		h << :e
+		h << :f
+
+		assert_equal 3,called
+		assert_equal 6,b_called
+		assert_equal 3,called
+		assert_equal deleted,[:a,:b,:c]
+	end
+
+	def test_disconnect
+		h = "Hello"
+		called = false
+		p = proc {|obj,method,value,*args,&block|
+			assert_equal h,obj
+			assert_equal :length,method
+			assert_equal 5,value
+			assert_equal [],args #also test on something wit args
+			called = true
+		}
+		Psychic.connect(h, :length,&p)
+
+		assert_equal 5,h.length
+		assert called, "expected psychic connection on \"#{h}\".length"
+		Psychic.disconnect(h,:length,&p)
+		called = false
+		assert_equal 5,h.length
+		assert !called, "expected psychic connection disconnected on \"#{h}\".length"
+		
+	end
+
+
+	def expect (state,code)
+		assert state, "closure was not called for opperation: \"#{code}\""
+		false
+	end	
+
+	def test_mutable(klass,code)#checks that result actually changes, and the block is called.
+		before = nil		
+		a = klass.new
+		c = false
+		Psychic.connect_mutable(a) {|object,method,value,*args,&block|
+			puts "#{before.inspect}.#{method}(#{args.join(',')}) => #{object.inspect}"
+			c = true
+		}
+		b = binding
+		code.split("\n").each{|s| 
+			before = a.dup
+			eval(s,b); 
+			c = expect(c,s)
+			assert a != before, "expected opperation: #{s} to alter #{a.inspect} from #{before.inspect}"
+		}
+
+	end
+
+	def test_array
+	code = "a << :a
+		a.delete :a
+		a << :a
+		a << :b
+		a << :c
+		a.reverse!
+		a.reverse!
+		a[1] = 2
+		a[2] = 0
+		a << [1,2,3]
+		a << nil
+		a.compact!
+		a.flatten!
+		a.slice!(1,4)
+		a << a.dup
+		a.flatten!
+		a.map! {|x| x.to_s + '!'}
+		a.uniq!"
+		test_mutable(Array,code)	
+	end
+
+	def test_hash
+		test_mutable(Hash,"a[1] = 123
+		a[2] = 1231
+		a[3] = 325235
+		a.reject! {|k,v| v > 2000}
+		a.merge! ({:a => :b})")	
+	end
+
+	def test_string
+		test_mutable(String,"a << 'hello'
+		a.capitalize!
+		a.upcase!
+		a.downcase!
+		a['e'] = 'XXX'
+		a << 'XXX'
+		a.gsub!(/X/,'_')
+		a.chomp!('_')")	
+		#what about genetic algorithm to figure out test for when a function will change a state?
+		#example, [:a].delete :a will change state, because [:a].include? :a
+		# << will always change the state
+		#also, we can discover what will produce errors.
+		#or inductively prove that a method can't make errors.
+		#it it's found an error, find most concise test which predicts error.
+	end
+
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+name: psychic
+version: !ruby/object:Gem::Version 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Dominic Tarr
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-16 00:00:00 +12:00
+default_executable: 
+dependencies: []
+
+description: "      can inject a block into any method on any object, which will be called back when that method is called.\n      for example, may be used to listen to state changes on Array's, Hash's etc.\n"
+email: dominic.tarr@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/psychic.rb
+- test/test_psychic.rb
+- README
+has_rdoc: true
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: inject listener block into any methods on any object
+test_files: []
+