ruby_events 0.0.2 → 0.0.3

data/README.markdown

@@ -10,10 +10,75 @@ objects. It's simple, fast and remains Ruby-ish in style and usage.
 Using ruby_events is simple! Because all objects are automatically extended
 with the ruby_events functionality, it's as simple as:
 
+    require 'rubygems'
     require 'ruby_events'
 
-    x = Object.new
-    x.events.listen :test_event, Proc.new {|data_passed| puts 'hai!'; puts data_passed }
-    x.events.fire :test_event, :test_data => 'hello', :more_test_data => 'hey'
+    class Example
+      def initialize
+        events.listen(:test_event) do |event_data|
+          puts 'Hai there!'
+          puts event_data
+        end
+      end
 
-All ruby_events functionality is just an object.events call away.
+      def call_me
+        events.fire(:test_event, 'My name is Mr Test Man!')
+      end
+    end
+
+    e = Example.new
+    e.call_me # Fires the event, and our handler gets called!
+
+You can do cooler and more advanced things, like add listeners to an Array:
+
+    a = []
+    
+    class << a
+      alias_method :inject_old, :inject
+      
+      def inject(item)
+        events.fire(:injected, self, item)
+        inject_old(item)
+      end
+    end
+
+    a.events.listen(:injected) do |event_data|
+      puts event_data;
+    end
+    
+    a.inject('This is a test')
+
+But because this is a fairly common pattern, ruby_events does it for you with
+a little bit of sugar:
+
+    a = []
+    a.events.fire_on_method('<<'.to_sym, :item_injected)
+    a.events.listen(:injected) do |event_data|
+      puts event_data;
+    end
+    
+    a << 'this is a test'
+
+These method events will automatically be passed the arguments that were passed
+to that method when it was called. Don't let your imagination stop there. You
+can add an event to any class method, and because all ruby objects are passed by
+reference, you can set these arguments and change the outcome of the function.
+Effectively, you can use the events as callbacks on any method:
+
+    a = {:one => 1}
+    b = {:two => 3}
+
+    a.events.fire_on_method(:merge, :merged)
+    a.events.listen(:merged) do |items|
+      # This is the hard part: because the items variable is actually just an
+      # array of all variables passed to the function that fired the event,
+      # you need to access the argument you're interested in; in this case,
+      # Hash.merge only takes one argument, and we'll be using it.
+      items[0][:three] = 3
+      puts 'The hash will have the extra item.'
+      items
+    end
+
+    puts a.merge(b)
+
+All ruby_events functionality is just an object.events call away.

data/Rakefile

@@ -12,11 +12,11 @@ require 'rake/testtask'
 
 spec = Gem::Specification.new do |s|
   s.name = 'ruby_events'
-  s.version = '0.0.2'
+  s.version = '0.0.3'
   s.has_rdoc = true
   s.extra_rdoc_files = ['README.markdown']
   s.summary = 'A really simple event implementation that hooks into the Object class. Now all your objects can join in the fun of firing events!'
-  s.description = s.summary
+  s.description = s.summary + ' See http://github.com/nathankleyn/ruby_events for more information.'
   s.author = 'Nathan Kleyn'
   s.email = 'nathan@unfinitydesign.com'
   # s.executables = ['your_executable_here']

data/lib/ruby_events.rb

@@ -1,15 +1,18 @@
 module RubyEvents
   class Events
-    def initialize
+    def initialize(parent)
+      @parent = parent
       @events = {}
     end
 
-    def listen(event_type, events)
+    def listen(event_type, &event)
       @events[event_type] = [] unless @events.has_key? event_type
-      events = [events] unless events.respond_to? :each
-      events.each do |event|
-        @events[event_type] << event
-      end
+      # TODO: Can we allow both block and an array of Proc's here?
+#      events = [events] unless events.respond_to? :each
+#      events.each do |event|
+#        @events[event_type] << event
+#      end
+      @events[event_type] << event
     end
 
     def fire(event_type, *arguments)
@@ -19,6 +22,31 @@ module RubyEvents
         end
       end
     end
+    
+    def fire_on_method(method, event_type, &block)
+      old_method = (method.to_s + '_event_old').to_sym
+      if @parent && @parent.respond_to?(method) && !@parent.respond_to?(old_method)
+        @parent.class.class_eval do
+          alias_method old_method, method
+        end
+        
+        # FIXME: Without the internet, this is all I could remember; there is
+        # definitely a better way to do this, so please fix it!
+        #
+        # FIXME: We need to find a way to call the block that's been passed
+        # so they can define the arguments they want to pass to the event.
+        #
+        # We are using self.send instead of calling the method directory because
+        # methods like << can not be resolved as a method properly once they've
+        # had the _event_old suffix tacked on the end.
+        #
+        # Make sure the self.send is at the end, or we won't return what we
+        # are supposed to.
+        @parent.class.class_eval('def ' + method.to_s + '(*args); events.fire(:' + event_type.to_s + ', *args); self.send("' + old_method.to_s + '".to_sym, *args); end')
+      else
+        # TODO: Need to raise exception here.
+      end
+    end
 
     def remove(event_type, event)
       if @events.has_key?(event_type)
@@ -30,10 +58,10 @@ end
 
 class Object
   def events
-    @events || @events = RubyEvents::Events.new
+    @events || @events = RubyEvents::Events.new(self)
   end
 
   def events=(events)
     @events = events
   end
-end
+end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Nathan Kleyn
@@ -18,7 +18,7 @@ date: 2010-04-26 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
-description: A really simple event implementation that hooks into the Object class. Now all your objects can join in the fun of firing events!
+description: A really simple event implementation that hooks into the Object class. Now all your objects can join in the fun of firing events! See http://github.com/nathankleyn/ruby_events for more information.
 email: nathan@unfinitydesign.com
 executables: []