gbs-signal-slot 1.0.0

data/README

@@ -0,0 +1,215 @@
+= GBS::SignalSlot v. 1.0.0
+Greenblack Software signal/slot pattern implementation for Ruby language
+
+== GBS::SignalSlot User's Guide
+
+1. Introduction
+2. Connecting slots
+3. Disconnecting slots
+4. Class signals
+5. MIT License
+
+=== Introduction
+
+GBS::SignalSlot is a signal/slot mechanism implementation done in Ruby. 
+The signal/slot pattern is a way of implementing the Observer design pattern. 
+Such implementation was introduced by Trolltech in their famous QT library. 
+Indeed the goal was achieved and resulted in code size reduction, 
+especially so called boilerplate code.
+
+With the Ruby facilities of meta-programming the whole implementation can be
+done within one single file with just a couple of lines. Such implementation was
+proposed by Niklas Frykholm and improved by Nobuyoshi Nakada on <b>comp.lang.ruby</b>
+usenet group (01-02-2002). Their work was the entry point to the Greenblack Software 
+implementation. In fact, the idea and main tricks are the same. Our improvements 
+were concerning on class methods support, better error checking, some additional 
+features and clean output.
+
+=== Connecting slots
+
+The best way to see what GBS::SignalSlot is and to get into it a bit more, is to look 
+thoroughly at the following examples.
+
+First, let we create a class, a container for a value. Of course with signals 
+our container will emit.
+
+		require "rubygems"
+		require "gbs_signal_slot"
+		
+		class ValueContainer
+		  include GBS::SignalSlot
+		  attr_reader :value
+		  signal :new_value        # signals are defined just like readers or writers
+
+		  def initialize(v)
+		    @value = v
+		  end
+
+		  def value=(v)
+		    @value = v
+		    new_value(v)           # signal activation
+		  end
+		end
+		
+As you can guess, the signals are defined just like obvious attributes and 
+emitted by calling a method named after the symbol indicating a signal. 
+Their parameters are matter of our arbitrary choice, however we should 
+stick to our once defined convention. Here, we are passing the new 
+value that our container gets.
+
+Particularly, the _new_value(v)_ method does not exist in the code. 
+It is added by the module behind the scene, as a private method.
+
+Next, we can use some mixed-in methods that will allow us to connect and 
+disconnect signals and slots. The simplest way is to connect to anonymous closures:
+
+		vc = ValueContainer.new(0)
+		vc.connect(:new_value) { |v| puts "New value is #{v}" }
+		
+Now, each use of the value writer will result in sending relevant string 
+to the output:
+
+		vc.value = 1
+		# >> New value is 1
+
+But to get more fun let's make a _Tracker_ object with both class
+and instance methods which will act as slots for our _new_value_ signal.
+
+		class Tracker
+		  def track_value(v)
+		    puts "value changed to #{v}!"
+		  end
+		  def self.track_value(v)
+		    puts "class slot method executed"
+		  end
+		end
+
+Now we may connect our signal to newly created tracker's slots.
+
+		t = Tracker.new
+ 		vc.connect(:new_value, :track_value, t)       # track_value instance method
+		vc.connect(:new_value, :track_value, Tracker) # track_value class method
+		vc.value = 2
+
+		# >> New value is 2
+		# >> value changed to 2
+		# >> class slot method excecuted
+		
+The last possibility is to connect signal to a global method. Like below:
+
+		def track_fun(v)
+		  puts "Global function"
+		end
+		
+		vc.connect(:new_value, :track_fun)            # that's all
+		vc.value = 3
+		
+		# >> New value is 3
+		# >> value changed to 3
+		# >> class slot method excecuted
+		# >> Global function
+		
+It is so easy because the _obj_ parameter is set to _Object_ by default. Every global
+method we create belongs to the _Object_ class, so we do not have to specify 
+anything else at all.
+
+=== Disconnecting slots
+
+Ok, now it is time to clean everything up. The connected slots can be disconnected 
+using a somewhat contrary method: _disconnect_. Let's get the rid of the global function:
+
+		vc.disconnect(:new_value, :track_fun)
+		vc.value = 4
+		
+		# >> New value is 4
+		# >> value changed to 4
+		# >> class slot method excecuted
+		
+As we see the global function call is removed. Similarly we may cut off other slot methods:
+
+		vc.disconnect(:new_value, :track_value, t)
+		vc.disconnect(:new_value, :track_value, Tracker)
+		vc.value = 5
+		
+		# >> New value is 5
+		
+Ok. But how can we deal with the anonymous closure? There are two ways. The first one 
+is to get the name, a reference saying precisely, to the proc object. The second way 
+is to cut off all slots at once. Here is the action:
+
+		blah_proc = vc.connect(:new_value) { |v| puts "blah" } # returns the proc object
+		vc.value = 6
+		
+		# >> New value is 6
+		# >> blah
+		
+		vc.disconnect(:new_value, &blah_proc)         # disconnecting the proc object
+		vc.value = 7
+		
+		# >> New value is 7
+		
+If we do not have the proc object, the only way is to disconnect all slots.
+
+		vc.disconnect(:new_value) # disconnects all slots connected to the :new_value
+		vc.value = 8
+		
+		# Nothing to print.
+
+=== Class signals
+
+GBS::SignalSlot module can be used with class methods as well 
+(within classes or modules). The only difference is the use of
+_class_signal_ method instead of _signal_. 
+
+		class SomeClass
+		  include GBS::SignalSlot
+		  
+		  signal :signal1
+		  class_signal :signal2
+		  
+		  def some_method
+		    signal1                     # activation
+		  end
+		  
+		  def self.some_other_method
+		    signal2                     # class signal activation
+		  end
+		end
+
+		some_instance.connect(:signal1) { puts "instance signal" }
+		SomeClass.connect(:signal2) { puts "class signal" }
+		# etc.
+
+The way we activate signals is still identical. It is even possible 
+to use the same signal symbol for both contexts (class and instance) 
+at the same time. The contexts will not be messed up and the right 
+signals will activate right slots as we had defined before.
+
+Such distinction (between _signal_ and _class_signal_) is due to readiness
+of class/module definitions. From the technical point of view it is easy to
+embed class and instance level behaviors into one method. The other reason is
+the fewer amount of code generated and inserted into classes.
+ 
+=== MIT License
+
+The MIT License
+
+Copyright (c) 2008 Greenblack Software
+
+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/lib/gbs_signal_slot.rb

@@ -0,0 +1,159 @@
+# Copyright (c) 2008 Greenblack Software. Licensed under the MIT License.
+# For more info please read the README or visit www.greenblacksoftware.com
+# ----
+# Based on Niklas Frykholm and Nobuyoshi Nakada signal/slot pattern implementations
+# posted to comp.lang.ruby usenet group on 01-02-2002
+
+# A default namespace used by Greenblack Software projects.
+module GBS
+
+  # A module providing signal/slot mechanism.
+  # ----
+  # Copyright (c) 2008 Greenblack Software. Licensed under the MIT License.
+  # For more info please read the README or visit www.greenblacksoftware.com
+  # ----
+  # Based on Niklas Frykholm and Nobuyoshi Nakada signal/slot pattern implementations
+  # posted to comp.lang.ruby usenet group on 01-02-2002
+  module SignalSlot
+
+    # Connects a signal to a slot. The slot might be either a method referenced as
+    # a symbol (often together with a class or an instance) or just an anonymous closure
+    # passed as a block.
+    #
+    # :call-seq:
+    #   sth.connect(signal) { ... }       -> proc
+    #   sth.connect(signal, slot)         -> global slot method
+    #   sth.connect(signal, slot, obj)    -> obj.slot method
+    #
+    # === Parameters
+    # [+signal+]
+    #   symbol defined in a class with the +signal+ or +class_signal+ method
+    # [+slot+]  
+    #   a method name referenced as a symbol object. If ommited the +connect+
+    #   will try to bind a block
+    # [+obj+]
+    #   an instance (for instance method), a class (for class methods)
+    #   or nothing for global methods
+    #
+    # === Returns
+    # * determined procedure (method) object or +nil+ if only the +signal+ parameter
+    #   was passed (without a block or a slot method name). It is important for
+    #   disconnecting anonymous proc objects because this is the only way to obtain
+    #   the reference. See also +GBS::SignalSlot#disconnect+
+    # ----
+    # === Examples
+    # [+sth.connect(:value_changed, :update_control, self)+]
+    #   if the signal +:value_changed+ is emitted, the +self#update_control+
+    #   will be executed
+    # [+sth.connect(:value_changed, update_status, MyClass)+]
+    #   similar example but with +MyClass.update_status+ class method instead
+    # [+sth.connect(:value_changed, :global_update)+]
+    #   now we are reffering to a global function (to something that
+    #   belongs to the +Object+ class in fact as the default value of +obj+
+    #   is set to +Object+)
+    # [+sth.connect(:value_changed) { |value| puts value }+]
+    #   passing anonymous closure
+    def connect(signal, slot = nil, obj = Object, &pr)
+      s = slot ? obj.method(slot) : pr
+      raise ArgumentError, "No slot provided" unless s
+      ((@_gbs_signals ||= {})[signal] ||= []) << s
+      s
+    end
+
+    # Disconnects a signal from a slot. The slot might be either a method referenced as
+    # a symbol together with a class or an instance or just an closure passed as a parameter
+    # (with & prefix)
+    #
+    # :call-seq:
+    #   sth.disconnect(signal)
+    #   sth.disconnect(signal, &proc)
+    #   sth.disconnect(signal, slot)
+    #   sth.disconnect(signal, slot, obj)
+    #
+    # === Parameters
+    # [+signal+]    
+    #   symbol defined in a class with the +signal+ or +class_signal+ method
+    # [+slot+]      
+    #   a method name referenced as a symbol object. If ommited the +connect+
+    #   will try to bind the +&proc+. If the +&proc+ parameter 
+    #   is also omitted, all connections to the signal will be erased. 
+    #   It disconnects all slots.
+    # [+obj+]       
+    #   an instance (for instance method), a class (for class methods)
+    #   or nothing for global methods 
+    # [+&proc+]   
+    #   a proc object appended with the & prefix. This object can be
+    #   obtained by the +GBS::SignalSlot#connect+ method with anonymous closure
+    #   passed.
+    # ----
+    # === Examples
+    # [+sth.disconnect(:value_changed, :update_control, self)+]
+    #   if the signal +:value_changed+ is emitted, 
+    #   the +self#update_control+ will not be executed anymore
+    # [+sth.disconnect(:value_changed, update_status, MyClass)+]
+    #   similar example but with +MyClass.update_status+ class method instead
+    # [+sth.disconnect(:value_changed, :global_update)+]
+    #   now we are reffering to a global function (to something that
+    #   belongs to the +Object+ class in fact as the default value of +obj+
+    #   is set to +Object+)
+    # [+sth.disconnect(:value_changed, &proc)+]
+    #   the +proc+ object will not be called anymore on 
+    #   +:value_changed+ signal activation.
+    # [+sth.disconnect(:value_changed)+]
+    #   +:value_changed+ totally disconnected from all slots
+    def disconnect(signal, slot = nil, obj = Object, &pr)
+      s = slot ? obj.method(slot) : pr
+      return unless @_gbs_signals and @_gbs_signals[signal]
+      if s
+        @_gbs_signals[signal].delete(s)
+      else
+        @_gbs_signals[signal] = []
+      end
+    end
+
+    def _gbs_activate_signal(signal, *args, &pr)
+      return unless @_gbs_signals and @_gbs_signals[signal]
+      # little support for asynchronous connection
+      # adding/removing during execution
+      slots = @_gbs_signals[signal].clone
+      slots.each { |slot| slot.call(*args, &pr) }
+    end
+
+    module Sender
+      
+      # Defines signals allowed to emit by an instance methods. 
+      # Signals should be provided as symbols and activated by calling instance methods 
+      # named after corresponding symbols. Those methods are appended dynamically.
+      def signal(*signals) # :doc:
+        signals.each { |s| module_eval method_str(s, false) }
+      end
+      
+      # Defines signals allowed to emit by class methods.
+      # Signals should be provided as symbols and activated by calling class methods
+      # named after corresponding symbols. Those methods are appended dynamically.
+      def class_signal(*signals) # :doc:
+        signals.each { |s| module_eval method_str(s, true) }
+      end
+      
+      def method_str(signal, klass)
+        %Q{
+          def #{klass ? "self." : ""}#{signal}(*args, &pr)
+            _gbs_activate_signal(:#{signal}, *args, &pr)
+          end
+          private#{klass ? "_class_method" : ""} :#{signal}
+        }
+      end
+
+      private :signal, :class_signal, :method_str
+    end
+
+    def self.append_features(klass)
+      super
+      klass.extend(Sender)
+      klass.extend(SignalSlot)    
+    end
+
+    private :_gbs_activate_signal
+    private_class_method :append_features
+  end
+end

data/test/tc_gbs_signal_slot.rb

@@ -0,0 +1,175 @@
+# Copyright (c) 2008 Greenblack Software. Licensed under the MIT License.
+# For more info please read the README or visit www.greenblacksoftware.com
+
+$:.unshift File.join(File.dirname(__FILE__),'..','lib')
+
+require "test/unit"
+require "gbs_signal_slot"
+
+$global_mock_value = nil
+
+def global_mock_method(text)
+  $global_mock_value = text
+end
+
+class TestSignalSlot < Test::Unit::TestCase
+  @@class_mock_value = nil
+
+  def setup
+    @val1 = nil
+    @val2 = nil
+    @@class_mock_value = nil
+  end
+
+  class InstanceTest
+    include GBS::SignalSlot
+
+    signal :test_signal
+
+    def fire_test_sig(t)
+      test_signal(t)
+    end
+  end
+
+  module ModuleTest
+    include GBS::SignalSlot
+    
+    class_signal :class_test_signal
+
+    def self.fire_class_test_sig(t)
+      class_test_signal(t)
+    end
+  end
+
+  class InstanceClassTest
+    include GBS::SignalSlot
+
+    signal :test_signal
+    class_signal :class_test_signal
+
+    def fire_test_sig(t)
+      test_signal(t)
+    end
+
+    def self.fire_class_test_sig(t)
+      class_test_signal(t)
+    end
+  end
+
+  def mock_slot_method(text)
+    @val1 = text
+  end
+
+  def self.class_mock_method(text)
+    @@class_mock_value = text
+  end
+
+  def test_connect_instance
+    it = InstanceTest.new
+    it.connect(:test_signal) { |text| @val2 = text }
+    it.connect(:test_signal, :mock_slot_method, self)
+    it.connect(:test_signal, :class_mock_method, TestSignalSlot)
+    it.connect(:test_signal, :global_mock_method)
+    it.fire_test_sig("a")
+    assert_equal("a", @val2)
+    assert_equal("a", @val1)
+    assert_equal("a", @@class_mock_value)
+    assert_equal("a", $global_mock_value)
+  end
+
+  def test_connect_module
+    ModuleTest.connect(:class_test_signal) { |text| @val2 = text }
+    ModuleTest.connect(:class_test_signal, :mock_slot_method, self)
+    ModuleTest.fire_class_test_sig("b")
+    assert_equal("b", @val2)
+    assert_equal("b", @val1)
+  end
+
+  def test_connect_mixed
+    obj = InstanceClassTest.new
+    obj.connect(:test_signal) { |text| @val2 = text }
+    obj.connect(:test_signal, :mock_slot_method, self)
+    obj.fire_test_sig("a")
+    assert_equal("a", @val2)
+    assert_equal("a", @val1)
+    InstanceClassTest.connect(:class_test_signal) { |text| @val2 = text }
+    InstanceClassTest.connect(:class_test_signal, :mock_slot_method, self)
+    InstanceClassTest.fire_class_test_sig("b")
+    assert_equal("b", @val2)
+    assert_equal("b", @val1)
+  end
+
+  def test_disconnect
+    it = InstanceTest.new
+    proc = it.connect(:test_signal) { |text| @val2 = text }
+    it.connect(:test_signal, :mock_slot_method, self)
+    it.fire_test_sig(1)
+    assert_equal(1, @val2)
+    assert_equal(1, @val1)
+    @val2 = @val1 = nil
+    it.disconnect(:test_signal, &proc)
+    it.fire_test_sig(1)
+    assert_nil(@val2)
+    assert_not_nil(@val1)
+    @val2 = @val1 = nil
+    it.disconnect(:test_signal, :mock_slot_method, self)
+    it.fire_test_sig(1)
+    assert_nil(@val2)
+    assert_nil(@val1)
+  end
+
+  def test_disconnect_all
+    it = InstanceTest.new
+    it.connect(:test_signal)  { |t| @val2 = t }
+    it.connect(:test_signal)  { |t| @val1 = t }
+    it.fire_test_sig(1)
+    assert_equal(1, @val2)
+    assert_equal(1, @val1)
+    it.disconnect(:test_signal)
+    it.fire_test_sig(2)
+    assert_not_equal(2, @val2)
+    assert_not_equal(2, @val1)
+  end
+
+  def test_signal_class_instance
+    ic = InstanceClassTest.new
+    ic.connect(:test_signal) { |t| @val1 = t }
+    InstanceClassTest.connect(:test_signal) { |t| @val2 = t}
+    ic.fire_test_sig(1)
+    assert_equal(1, @val1)
+    assert_nil(@val2)
+    InstanceClassTest.fire_class_test_sig(2)
+    assert_equal(1, @val1)
+    assert_nil(@val2)
+  end
+
+  class SpecialInstanceClassTest
+    include GBS::SignalSlot
+    signal :test_signal
+    class_signal :test_signal
+    
+    def self.fire_test_sig(n)
+      test_signal(n)
+    end
+    def fire_test_sig(n)
+      test_signal(n)
+    end
+  end
+  
+  def test_special_case
+    SpecialInstanceClassTest.connect(:test_signal) { |v| @val1 = v }
+    s = SpecialInstanceClassTest.new
+    s.connect(:test_signal) { |v| @val2 = v }
+    SpecialInstanceClassTest.fire_test_sig(10)
+    assert_equal(10, @val1)
+    assert_nil(@val2)
+    s.fire_test_sig(3)
+    assert_equal(10, @val1)
+    assert_equal(3, @val2)
+  end
+
+  def test_bad_use
+    it = InstanceTest.new
+    assert_raise(ArgumentError) { it.connect(:test_signal) }
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification 
+name: gbs-signal-slot
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Greenblack Software
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-04-06 00:00:00 +02:00
+default_executable: 
+dependencies: []
+
+description: 
+email: info@greenblacksoftware.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- test/tc_gbs_signal_slot.rb
+- lib/gbs_signal_slot.rb
+- README
+has_rdoc: true
+homepage: www.greenblacksoftware.com
+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: gbs-signal-slot
+rubygems_version: 1.1.0
+signing_key: 
+specification_version: 2
+summary: GBS::SignalSlot - a signal/slot mechanism in Ruby
+test_files: 
+- test/tc_gbs_signal_slot.rb