eventpublisher 0.1.0

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2010 Davy Brion (ralinx@davybrion.com)
+
+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

@@ -0,0 +1,70 @@
+The EventPublisher module enables you to define multiple events in a class, and have objects subscribe to them with either a Method instance, or a block.  Subscribers can obviously also unsubscribe Method instances, though blocks can't be unsubscribed.
+
+Here's a simple example that illustrates the usage of the EventPublisher module:
+
+class Publisher
+	include EventPublisher
+	event :first_event
+	event :second_event
+	
+	def trigger_events
+		trigger :first_event, "first event"
+		trigger :second_event, "second event", "extra argument"
+	end
+end
+
+class FirstSubscriber
+	def initialize(publisher)
+		@publisher = publisher
+		@publisher.subscribe_all self
+	end
+	
+	def stop_listening
+		@publisher.unsubscribe_all self
+	end
+	
+	def first_event_handler(args)
+		puts "first_event_handler of FirstSubscriber received #{args}"
+	end
+	
+	def second_event_handler(arg1, arg2)
+		puts "second_event_handler of FirstSubscriber received arg1 = #{arg1} arg2 = #{arg2}"
+	end
+end
+
+class SecondSubscriber
+	def initialize(publisher)
+		@publisher = publisher
+		@publisher.subscribe :first_event, method(:first_handler)
+		@publisher.subscribe(:second_event) { |arg1, arg2| puts "block from SecondSubscriber received: #{arg1} #{arg2}"}
+	end
+	
+	def stop_listening
+		@publisher.unsubscribe :first_event, method(:first_handler)
+	end
+	
+	def first_handler(args)
+		puts "first_handler of SecondSubscriber received #{args}"
+	end
+end
+
+
+publisher = Publisher.new
+first_subscriber = FirstSubscriber.new(publisher)
+second_subscriber = SecondSubscriber.new(publisher)
+puts "you should see 4 outputted strings when the events are triggered"
+publisher.trigger_events
+first_subscriber.stop_listening
+second_subscriber.stop_listening
+puts "you should still see 1 outputted string because the block is still subscribed, while the Method instances have been unsubscribed"
+publisher.trigger_events
+
+The output of running this code is the following:
+
+you should see 4 outputted strings when the events are triggered
+first_event_handler of FirstSubscriber received first event
+first_handler of SecondSubscriber received first event
+second_event_handler of FirstSubscriber received arg1 = second event arg2 = extra argument
+block from SecondSubscriber received: second event extra argument
+you should still see 1 outputted string because the block is still subscribed, while the Method instances have been unsubscribed
+block from SecondSubscriber received: second event extra argument

data/Rakefile

@@ -0,0 +1,33 @@
+require 'rake'
+require 'rake/gempackagetask'
+require 'rubygems'
+require 'spec/rake/spectask'
+
+gem_spec = Gem::Specification.new do |s|
+  s.name = 'eventpublisher'
+  s.version = '0.1.0'
+  s.has_rdoc = false
+  s.summary = 'A module which enables objects to publish multiple events, which other objects can subscribe to'
+  s.description = s.summary + ' See http://github.com/davybrion/EventPublisher for more information.'
+	s.homepage = "http://github.com/davybrion/EventPublisher"
+  s.author = 'Davy Brion'
+  s.email = 'ralinx@davybrion.com'
+  s.files = FileList['lib/**/*.rb', 'bin/*', '[A-Z]*', 'test/**/*'].to_a
+	s.require_path = "lib"
+	s.required_ruby_version = '>= 1.9.1'
+  s.bindir = "bin"
+end
+
+Rake::GemPackageTask.new(gem_spec) do |p|
+  p.gem_spec = gem_spec
+end
+
+Spec::Rake::SpecTask.new(:run_specs) do |t|
+  t.spec_files = FileList['test/*_spec.rb']
+	t.verbose = true
+	t.warning = true
+	t.spec_opts << "--format nested"
+end
+
+task :default  => :run_specs
+

data/lib/eventpublisher.rb

@@ -0,0 +1,94 @@
+module EventPublisher
+	class Event
+		attr_reader :name
+
+		def initialize(name)
+			@name = name
+			@handlers = []
+		end
+
+		def add(method=nil, &block)
+			@handlers << method if method
+			@handlers << block if block
+		end
+
+		def has?(method)
+			@handlers.include? method
+		end
+
+		def remove(method)
+			@handlers.delete method if method
+		end
+
+		def trigger(*args)
+			@handlers.each { |handler| handler.call *args }
+		end	
+	end	
+
+	def subscribe_all(subscriber)
+		each_suitable_handler(subscriber) do |event_symbol, method_symbol|
+			subscribe event_symbol, subscriber.method(method_symbol)
+		end
+	end
+	
+	def unsubscribe_all(subscriber)
+		each_suitable_handler(subscriber) do |event_symbol, method_symbol|
+			unsubscribe event_symbol, subscriber.method(method_symbol)
+		end
+	end
+	
+	def subscribe(symbol, method=nil, &block)
+		event = send(symbol)
+		event.add method if method
+		event.add block if block
+	end
+
+	def unsubscribe(symbol, method)
+		event = send(symbol)
+		event.remove method
+	end
+
+	def subscribed?(symbol, method)
+		event = send(symbol)
+		event.has? method
+	end
+
+	private
+	
+	def each_suitable_handler(subscriber)
+		possible_handlers = subscriber.class.instance_methods.select { |name| name =~ /\w_handler/ }
+		possible_handlers.each do |method_name|
+			event_name = /(?<event_name>.*)_handler/.match(method_name)[:event_name]	
+			if EVENTS.include? event_name.to_sym
+				yield event_name.to_sym, method_name.to_sym
+			end
+		end
+	end
+	
+	def trigger(symbol, *args)
+		event = send(symbol)
+		event.trigger *args
+	end
+	
+	self.class.class_eval do
+		EVENTS = []
+
+		def event(symbol)
+			getter = symbol
+			variable = :"@#{symbol}"
+			EVENTS << symbol
+
+			define_method getter do
+				if !instance_variable_defined? variable
+					event = Event.new(symbol.to_s)
+					instance_variable_set variable, event
+				end
+				
+				instance_variable_get variable
+			end
+			
+			private getter
+		end
+	end
+end
+

data/test/auto_subscription_spec.rb

@@ -0,0 +1,28 @@
+require_relative './publisher'
+require 'spec'
+
+describe EventPublisher, ": auto subscribing" do
+	before(:each) do
+	  @publisher = Publisher.new
+	  @publisher.subscribe_all self
+	end
+
+	def first_event_handler(args);end
+	def second_event_handler(arg1, arg2);end
+	def some_other_handler(args);end
+	
+	it "should subscribe all suitable methods" do
+		first_handler_subscribed = @publisher.subscribed? :first_event, method(:first_event_handler)
+		second_handler_subscribed = @publisher.subscribed? :second_event, method(:second_event_handler)
+		first_handler_subscribed.should be_true
+		second_handler_subscribed.should be_true
+	end
+	
+	it "should not subscribe unsuitable methods" do
+		non_event_handler_subscribed_to_first_event = @publisher.subscribed? :first_event, method(:some_other_handler)
+		non_event_handler_subscribed_to_second_event = @publisher.subscribed? :second_event, method(:some_other_handler)
+		non_event_handler_subscribed_to_first_event.should be_false
+		non_event_handler_subscribed_to_second_event.should be_false
+	end
+	
+end

data/test/auto_unsubscription_spec.rb

@@ -0,0 +1,22 @@
+require_relative './publisher'
+require 'spec'
+
+describe EventPublisher, ": auto unsubscribing" do
+	before(:each) do
+	  @publisher = Publisher.new
+		@publisher.subscribe_all self
+		@publisher.unsubscribe_all self
+	end
+
+	def first_event_handler(args);end
+	def second_event_handler(arg1, arg2);end
+	def some_other_handler(args);end
+	
+	it "should unsubscribe all suitable methods" do
+		first_handler_subscribed = @publisher.subscribed? :first_event, method(:first_event_handler)
+		second_handler_subscribed = @publisher.subscribed? :second_event, method(:second_event_handler)
+		first_handler_subscribed.should be_false
+		second_handler_subscribed.should be_false
+	end
+	
+end

data/test/publisher.rb

@@ -0,0 +1,16 @@
+require_relative '../lib/eventpublisher'
+
+# this class is used as an example event publisher class by the tests
+class Publisher
+	include EventPublisher
+	event :first_event
+	event :second_event
+	
+	def trigger_first_event(args)
+		trigger :first_event, args
+	end
+	
+	def trigger_second_event(arg1, arg2)
+		trigger :second_event, arg1, arg2
+	end
+end

data/test/subscribing_spec.rb

@@ -0,0 +1,28 @@
+require_relative './publisher'
+require 'spec'
+
+describe EventPublisher, ": subscribing" do
+	before(:each) do
+	  @publisher = Publisher.new
+	end
+
+	def first_event_handler(args);end
+	def second_event_handler(arg1, arg2);end
+
+	it "should not know about a method that isn't subscribed" do
+		subscribed = @publisher.subscribed? :first_event, method(:first_event_handler)
+		subscribed.should be_false
+	end
+
+	it "should know about the subscribed method for the correct event" do
+		@publisher.subscribe :first_event, method(:first_event_handler)
+		subscribed = @publisher.subscribed? :first_event, method(:first_event_handler)
+		subscribed.should be_true
+	end
+	
+	it "should not know about a subscribed method for a different event" do
+	  @publisher.subscribe :first_event, method(:first_event_handler)
+		subscribed = @publisher.subscribed? :second_event, method(:first_event_handler)
+		subscribed.should be_false
+	end
+end

data/test/triggering_events_spec.rb

@@ -0,0 +1,79 @@
+require_relative './publisher'
+require 'spec'
+
+describe EventPublisher, ": triggering event" do
+	before(:each) do
+	  @publisher = Publisher.new
+	end
+
+	it "should not fail without any subscribers" do
+	  @publisher.trigger_first_event "testing"
+	end
+
+	it "should pass single event arg correctly to subscribed method with one argument" do
+		@args = nil
+		def first_event_handler(args);
+			@args = args
+		end
+
+		@publisher.subscribe :first_event, method(:first_event_handler)
+		@publisher.trigger_first_event "testing!"
+		@args.should == "testing!"
+	end
+	
+	it "should pass multiple event args correctly to subscribed method with multiple arguments" do
+		@args2_1, @args2_2 = nil, nil
+		def second_event_handler(arg1, arg2)
+			@args2_1, @args2_2 = arg1, arg2
+		end
+		
+		@publisher.subscribe :second_event, method(:second_event_handler)
+		@publisher.trigger_second_event "second", "event"
+		@args2_1.should eql("second")
+		@args2_2.should eql("event")
+	end
+
+	it "should pass single event arg correctly to subscribed block with one argument" do
+		event_args = nil
+		@publisher.subscribe(:first_event) { |args| event_args = args }
+		@publisher.trigger_first_event "test"
+	  event_args.should eql("test")
+	end
+	
+	it "should pass multiple event args correctly to subscribed block with two arguments" do
+	  first_arg, second_arg = nil, nil
+		@publisher.subscribe(:second_event) { |arg1,arg2| first_arg, second_arg = arg1, arg2 }
+		@publisher.trigger_second_event "first", "second"
+		first_arg.should eql("first")
+		second_arg.should eql("second")
+	end
+	
+	it "should call subscribed method once for each time it was subscribed" do
+	  @counter1 = 0
+		def first_event_handler(args)
+			@counter1 += 1
+		end
+		
+		2.times { @publisher.subscribe :first_event, method(:first_event_handler) }
+		@publisher.trigger_first_event "test"
+		@counter1.should == 2
+	end
+	
+	it "should call all subscribed methods" do
+		@counter1, @counter2 = 0, 0
+		def handler1(args)
+			@counter1 += 1
+		end
+		
+		def handler2(args)
+			@counter2 += 1
+		end
+		
+		@publisher.subscribe :first_event, method(:handler1)
+		@publisher.subscribe :first_event, method(:handler2)
+		@publisher.trigger_first_event "first_event"
+		@counter1.should eql(1)
+		@counter2.should eql(1)
+	end
+	
+end

data/test/unsubscribing_spec.rb

@@ -0,0 +1,18 @@
+require_relative './publisher'
+require 'spec'
+
+describe EventPublisher, ": unsubscribing" do
+	before(:each) do
+	  @publisher = Publisher.new
+	end
+
+	def first_event_handler(args);end
+
+	it "should no longer know about an unsubscribed method for the correct event" do
+		@publisher.subscribe :first_event, method(:first_event_handler)
+		@publisher.unsubscribe :first_event, method(:first_event_handler)
+		subscribed = @publisher.subscribed? :first_event, method(:first_event_handler)
+		subscribed.should be_false
+	end
+	
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: eventpublisher
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Davy Brion
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-28 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: A module which enables objects to publish multiple events, which other objects can subscribe to See http://github.com/davybrion/EventPublisher for more information.
+email: ralinx@davybrion.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/eventpublisher.rb
+- LICENSE.txt
+- Rakefile
+- README
+- test/auto_subscription_spec.rb
+- test/auto_unsubscription_spec.rb
+- test/publisher.rb
+- test/subscribing_spec.rb
+- test/triggering_events_spec.rb
+- test/unsubscribing_spec.rb
+has_rdoc: true
+homepage: http://github.com/davybrion/EventPublisher
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 9
+      - 1
+      version: 1.9.1
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A module which enables objects to publish multiple events, which other objects can subscribe to
+test_files: []
+