callbacks_attachable 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 81a1654f014d9e55c862d04cddc2220b77d08fc2
-  data.tar.gz: 38e878bb95354ecbc13fcae519e8a35dc70c0779
+  metadata.gz: 8b3cbb8d4bd7ce32583ce955de64c50b6c573df8
+  data.tar.gz: 9f7a8fa43ff82a24fad63277df0a8966fff4bc9e
 SHA512:
-  metadata.gz: 41df492f40cc6746035513c53a4e503d647359db01bd3b88697eb324b258a5d500178b90a26db91ecff10e4ee4b3814a7fed0f2b5f4df16cf4c907714f4e3fae
-  data.tar.gz: 9dc191acaa137a6478b245039b7586c7ca30d73ebbfce741207ff64e4105078d54bc0075223f4f4315af37cab71837aac1882437de343c699a3f90aebc34e3d3
+  metadata.gz: 04afd03c6c374d2cbd40052dafd3c92f9884d8a77303643aec0b91dec3a4655887e27d5d881d5eeb78419765313040cf2e658b6f2e842a33a82a92cf7cc228b6
+  data.tar.gz: 48e973e7699b8ead7d098afb8589b261cdf481340a757693a9e629ed4a9906fbe1c42df06349318f6d0f47c906319f5bdbbc9581e9925857a5344e38489cf4e4

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015, 2016 Christopher Aue
+Copyright (c) 2015 - 2017 Christopher Aue
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,22 +1,21 @@
 # CallbacksAttachable
 
-Attach callbacks to a class and trigger them for all its instances or just one
-particular instance. Additionally, instances can also have their own set of
-individual callbacks.
+Attach callbacks to classes to be triggered for all instances or attach them
+to an individual instance to be triggered only for this instance.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'callbacks_attachable'
+gem 'callbacks_attachable', '~> 2.0'
 ```
 
 And then execute:
 
     $ bundle
 
-Or install it yourself as:
+Or install it yourself:
 
     $ gem install callbacks_attachable
 
@@ -32,90 +31,72 @@ end
 
 ### Callbacks attached to the class
 
-Attach callbacks for an event to the class with:
+Attach callbacks for an event for all instances of a class with:
 
 ```ruby
-callback = AClass.on(:event) do |method|
-    puts self.__send__(method)
+callback = AClass.on(:event) do |instance, method|
+    puts instance.__send__(method)
 end
-```
 
-Callbacks attached to a class are executed in the context of each existing
-instance. To trigger all `:event` callbacks for all instances of `AClass`, use:
+instance0 = AClass.new(value: 0)
+instance1 = AClass.new(value: 1)
 
-```ruby
-AClass.trigger(:event, :name) # => puts 'AClass'
+AClass.trigger(:event, :value) # => 0
+                               #    1
 ```
 
-The second and other arguments given to `.trigger` are passed to the callback.
-
-Callbacks attached to a class can also be triggered for just one of its
-instances with `.trigger_for`:
-
-```ruby
-an_instance = AClass.new
-AClass.trigger_for(an_instance, :event, :__id__)
-# => puts the result of an_instance.__id__
-```
+The first argument of the callback is the instance the callback is executed
+for. The second and further arguments given to `.trigger` are passed to the
+callback as additional arguments.
 
-To detach a callback call `.off` with the event's name and the callback handle
-returned by `.on`:
+Registering a callback returns a `Callback` object. To cancel the callback use
+`#cancel` on that object.
 
 ```ruby
 callback = AClass.on(:event) { do_something }
-AClass.off(:event, callback)
+callback.cancel
 ```
 
 If you want to execute a callback just a single time attach it with `.once_on`:
 
 ```ruby
-AClass.once_on(:singularity) { puts 'callback called!' }
-AClass.trigger(:singularity) # => puts 'callback called!' and immediately
-                                      #    detaches the callback
-AClass.trigger(:singularity) # => does nothing
+AClass.once_on(:singular) { puts 'callback called!' }
+AClass.trigger(:singular) # => puts 'callback called!' and immediately
+                          #    detaches the callback
+AClass.trigger(:singular) # => does nothing
 ```
 
-To detach a callback when a condition is met use `.until_true_on`. The callback
-will be detached if it has a truthy (!) return value.
+To filter the instances to call the callback for, use the `:if` option:
 
 ```ruby
-counter = 0
-AClass.until_true_on(:count_to_two) do
-    puts counter
-    counter >= 2
+instance0 = AClass.new(value: 0)
+instance1 = AClass.new(value: 1)
+instance2 = AClass.new(value: 2)
+AClass.on(:even, if: proc{ |inst| inst.value.even? }) do |instance|
+    puts instance.value
 end
 
-AClass.trigger(:count_to_two) # => puts 0
-AClass.trigger(:count_to_two) # => puts 1
-AClass.trigger(:count_to_two) # => puts 2 and detaches the callback
-AClass.trigger(:count_to_two) # => does nothing
+AClass.trigger(:even) # => 0
+                      #    2
 ```
 
+This is especially useful in combination with `.once_on` to execute the
+callback just for the first instance meeting certain criteria.
+
 ### Callbacks attached to an instance
 
 All above mentioned methods on the class level also exist for each instance of
-the class. Callbacks for an individual instance are executed by calling
-`#trigger` on it. They are also called, when calling `.trigger` or
-`.trigger_for(instance, ...)` on its class.
+the class.
 
-Callbacks attached to individual instances are evaluated in their lexical scope.
-So, `self` inside and outside the callback is the same object.
+Callbacks for an individual instance are executed by calling `#trigger` on it.
+This also executes callbacks attached to the class.
 
 ```ruby
-an_instance1 = AClass.new
-an_instance2 = AClass.new
-
-callback1 = an_instance1.on(:event) { puts 'This is #1!' }
-callback2 = an_instance2.on(:event) { puts 'This is #2!' }
-
-an_instance1.trigger(:event) # => puts 'This is #1!'
-an_instance2.trigger(:event) # => puts 'This is #2!'
+instance = AClass.new
 
-AClass.trigger(:event) # => puts 'This is #1!' and 'This is #2!'
-
-an_instance1.off(:event, callback)
-an_instance2.off(:event, callback)
-```
+AClass.on(:event) { puts 'class callback' }
+instance.on(:event) { puts 'instance callback' }
 
-The two methods `#once_on` and `#until_true_on` are available for instances,
-too. They work as you'd expect.
+instance.trigger(:event) # => 'class callback'
+                         #    'instance callback'
+```

data/callbacks_attachable.gemspec

@@ -6,9 +6,8 @@ Gem::Specification.new do |spec|
   spec.version       = CallbacksAttachable::VERSION
   spec.summary       = %q{Attach callbacks to classes or individual instances.}
   spec.description  = <<-DESC
-Attach callbacks to a class and trigger them for all its instances or just one
-particular instance. Additionally, instances can also have their own set of
-individual callbacks.
+Attach callbacks to classes to be triggered for all instances or attach them
+to an individual instance to be triggered only for this instance.
   DESC
 
   spec.homepage      = "https://github.com/christopheraue/m-ruby-callbacks_attachable"

data/lib/callbacks_attachable.rb

@@ -1,5 +1,4 @@
 require_relative "../mrblib/callbacks_attachable"
 require_relative "../mrblib/version"
 require_relative "../mrblib/callback_registry"
-require_relative "../mrblib/instance_callback"
-require_relative "../mrblib/all_instances_callback"
+require_relative "../mrblib/callback"

data/mrbgem.rake

@@ -4,9 +4,8 @@ MRuby::Gem::Specification.new('mruby-callbacks_attachable') do |spec|
   spec.version      = CallbacksAttachable::VERSION
   spec.summary      = %q{Attach callbacks to classes or individual instances.}
   spec.description  = <<-DESC
-Attach callbacks to a class and trigger them for all its instances or just one
-particular instance. Additionally, instances can also have their own set of
-individual callbacks.
+Attach callbacks to classes to be triggered for all instances or attach them
+to an individual instance to be triggered only for this instance.
 DESC
 
   spec.homepage     = "https://github.com/christopheraue/m-ruby-callbacks_attachable"

data/mrblib/callback.rb

@@ -0,0 +1,27 @@
+module CallbacksAttachable
+  class Callback
+    def initialize(registry, event, opts = {}, callback)
+      @registry = registry
+      @event = event
+      @call_condition = opts.fetch(:if, false)
+      @cancel_condition = opts.fetch(:until, false)
+      @callback = callback
+    end
+
+    def call(instance, args)
+      return if @call_condition and not @call_condition.call instance, *args
+      @callback.call(instance, *args)
+      cancel if @cancel_condition and @cancel_condition.call instance, *args
+    end
+
+    def on_cancel(&on_cancel)
+      @on_cancel = on_cancel
+    end
+
+    def cancel
+      @registry.deregister @event, self
+      @on_cancel.call if @on_cancel
+      true
+    end
+  end
+end

data/mrblib/callback_registry.rb

@@ -1,45 +1,28 @@
 module CallbacksAttachable
   class CallbackRegistry
-    def initialize(object, callback_class)
-      @object = object
-      @callback_class = callback_class
+    def initialize(owner)
+      @owner = owner
       @callbacks = {}
     end
 
-    def on(event, opts = {}, &callback)
-      @callbacks[event] ||= []
-      @callbacks[event] << @callback_class.new(@object, opts, &callback)
-      @callbacks[event].last
+    def register(event, opts, callback)
+      @callbacks[event] ||= {}
+      callback = Callback.new(self, event, opts, callback)
+      @callbacks[event][callback] = true
+      callback
     end
 
-    def once_on(event, *opts, &callback)
-      callback_registry = self
-      registered_callback = @object.on(event, *opts) do |*args|
-        callback_registry.off(event, registered_callback)
-        yield(*args)
-      end
-    end
-
-    def until_true_on(event, *opts, &callback)
-      callback_registry = self
-      registered_callback = @object.on(event, *opts) do |*args|
-        yield(*args).tap do |result|
-          callback_registry.off(event, registered_callback) if result
-        end
-      end
+    def registered?(event)
+      @callbacks.key? event
     end
 
     def trigger(instance, event, args)
-      return true unless @callbacks[event]
-
-      # dup the callback list so that removing callbacks while iterating does
-      # still call all callbacks during map.
-      @callbacks[event].dup.all?{ |callback| callback.call(instance, args) }
+      @callbacks[event] and @callbacks[event].keys.each{ |callback| callback.call(instance, args) }
     end
 
-    def off(event, callback)
-      return unless @callbacks[event]
+    def deregister(event, callback)
       @callbacks[event].delete(callback)
+      @callbacks.delete(event) if @callbacks[event].empty?
     end
   end
 end

data/mrblib/callbacks_attachable.rb

@@ -1,67 +1,40 @@
 module CallbacksAttachable
-  def self.included(klass)
-    klass.extend ClassMethods
-  end
-
-  module ClassMethods
-    def on(*args, &block)
-      __callback_registry__.on(*args, &block)
+  module RegistryOwnable
+    def on(event, opts = {}, &callback)
+      __callbacks__.register(event, opts, callback)
     end
-    alias on_event on
 
-    def once_on(*args, &block)
-      __callback_registry__.once_on(*args, &block)
+    def once_on(event, opts = {}, &callback)
+      on(event, opts.merge(until: proc{ true }), &callback)
     end
-    alias once_on_event once_on
 
-    def until_true_on(*args, &block)
-      __callback_registry__.until_true_on(*args, &block)
-    end
-    alias until_true_on_event until_true_on
-
-    def off(*args)
-      __callback_registry__.off(*args)
-    end
-    alias off_event off
-
-    def trigger(event, *args)
-      ObjectSpace.each_object(self).all?{ |inst| inst.trigger(event, *args) }
+    def on?(event)
+      __callbacks__.registered? event
     end
-    alias trigger_event trigger
 
-    def __callback_registry__
-      @__callback_registry__ ||= CallbackRegistry.new(self, AllInstancesCallback)
+    private def __callbacks__
+      @__callbacks__ ||= CallbackRegistry.new(self)
     end
   end
 
-  def on(*args, &block)
-    __callback_registry__.on(*args, &block)
-  end
-  alias on_event on
+  include RegistryOwnable
 
-  def once_on(*args, &block)
-    __callback_registry__.once_on(*args, &block)
+  def self.included(klass)
+    klass.extend ClassMethods
   end
-  alias once_on_event once_on
 
-  def until_true_on(*args, &block)
-    __callback_registry__.until_true_on(*args, &block)
-  end
-  alias until_true_on_event until_true_on
+  module ClassMethods
+    include RegistryOwnable
 
-  def off(*args)
-    __callback_registry__.off(*args)
+    def trigger(event, *args)
+      ObjectSpace.each_object(self).all?{ |inst| inst.trigger(event, *args) }
+    end
   end
-  alias off_event off
 
   def trigger(event, *args)
-    self.class.__callback_registry__.trigger(self, event, args) and __callback_registry__.trigger(self, event, args)
-  end
-  alias trigger_event trigger
-
-  private
-
-  def __callback_registry__
-    @__callback_registry__ ||= CallbackRegistry.new(self, InstanceCallback)
+    @class_callbacks ||= self.class.__send__ :__callbacks__
+    @class_callbacks.trigger(self, event, args)
+    @__callbacks__ and @__callbacks__.trigger(self, event, args)
+    true
   end
 end

data/mrblib/version.rb

@@ -1,3 +1,3 @@
 module CallbacksAttachable
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: callbacks_attachable
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Christopher Aue
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-18 00:00:00.000000000 Z
+date: 2017-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,9 +53,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.4'
 description: |
-  Attach callbacks to a class and trigger them for all its instances or just one
-  particular instance. Additionally, instances can also have their own set of
-  individual callbacks.
+  Attach callbacks to classes to be triggered for all instances or attach them
+  to an individual instance to be triggered only for this instance.
 email:
 - rubygems@christopheraue.net
 executables: []
@@ -70,10 +69,9 @@ files:
 - callbacks_attachable.gemspec
 - lib/callbacks_attachable.rb
 - mrbgem.rake
-- mrblib/all_instances_callback.rb
+- mrblib/callback.rb
 - mrblib/callback_registry.rb
 - mrblib/callbacks_attachable.rb
-- mrblib/instance_callback.rb
 - mrblib/version.rb
 homepage: https://github.com/christopheraue/m-ruby-callbacks_attachable
 licenses:

data/mrblib/all_instances_callback.rb

@@ -1,16 +0,0 @@
-module CallbacksAttachable
-  class AllInstancesCallback
-    def initialize(klass, opts = {}, &callback)
-      @class = klass
-      @skip = opts.fetch(:skip, 0)
-      @callback = callback
-      @call_counts = {}
-    end
-
-    def call(instance, args)
-      @call_counts[instance.__id__] = @call_counts[instance.__id__].to_i + 1
-      return true if @call_counts[instance.__id__] <= @skip
-      false != instance.instance_exec(*args, &@callback)
-    end
-  end
-end

data/mrblib/instance_callback.rb

@@ -1,16 +0,0 @@
-module CallbacksAttachable
-  class InstanceCallback
-    def initialize(instance, opts = {}, &callback)
-      @instance = instance
-      @skip = opts.fetch(:skip, 0)
-      @callback = callback
-      @call_count = 0
-    end
-
-    def call(instance, args)
-      @call_count += 1
-      return true if @call_count <= @skip
-      @callback.call(*args) != false
-    end
-  end
-end