unobservable 0.1.3 → 0.1.4

data/README.rdoc

@@ -1,9 +1,92 @@
 = unobservable
 
 Ruby's Observable mixin is often characterized as an Event Handler library.  In reality, it only provides basic
-support for "Property Changed" notifications.  
+support for "Property Changed" notifications.  If an object needs to raise several different types of events,
+then the Observable mixin is the wrong tool for the job.
 
-Unobservable strives to be a general-purpose Event Handler library.
+Unobservable overcomes the limitations of the Observable mixin by allowing objects to own one or more Event
+objects.
+
+== 2-Minute Tour
+
+Instead of a lengthy introduction, here's a short program that demonstrates the main concepts:
+
+
+  require 'unobservable'
+
+
+  class Button
+    # This will add basic support for Events to this class.  As a bonus, it will
+    # also make the attr_event keyword available to us.
+    include Unobservable::Support
+
+    # The attr_event keyword allows us to declare the Events that are available
+    # to the instances of the Button class.
+    attr_event :clicked, :double_clicked
+
+
+    # This method will raise the :clicked event when it is invoked.
+    def click(x, y)
+      raise_event(:clicked, x, y)
+    end
+
+
+    # This method will raise the :double_clicked event when it is invoked
+    def double_click(x, y)
+      raise_event(:double_clicked, x, y)
+    end
+  end
+
+
+  # This class does not publish any events, so it does not need to include
+  # the Unobserable::Support mixin.
+  class Textbox
+    attr_accessor :text
+  end
+
+
+  # Now let's create some instances of these classes
+  button  = Button.new
+  textbox = Textbox.new
+
+
+  # We want to automatically update the textbox's text whenever we click
+  # the button.  So, let's register an event handler:
+  button.clicked.register do |x, y|
+    textbox.text = "You just clicked: #{x} #{y}"
+  end
+
+
+  # We want to print the [x, y] coordinates to the console whenever the
+  # button is double-clicked.  So, we can register an event handler that
+  # just calls the Kernel#puts method directly.
+  button.double_clicked.register Kernel, :puts
+
+
+  # Show time!  First, let's print the textbox's text just to verify
+  # that it's currently null:
+  puts "Before Clicking: #{textbox.text}"
+
+  # Now click the button.  This should raise the :clicked event, which
+  # will invoke its event handlers:
+  button.click(2, 3)
+
+
+  # As expected, the event handler that we registered to the :clicked
+  # event updated the textbox's text.
+  puts "After Clicking: #{textbox.text}"
+
+
+  # Now double-click the button.  This should raise the :double_clicked
+  # event, which will invoke its event handlers.  As a result, the
+  # coordinates will be printed to the console.
+  button.double_click(15, 2)
+
+
+  # We did not register any event handlers that would change the textbox
+  # when the button was double-clicked.  Therefore, we should find that
+  # the textbox's text has remained unchanged.
+  puts "After Double-Clicking: #{textbox.text}"
 
 
 == Usage

data/Rakefile

@@ -49,5 +49,6 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "unobservable #{version}"
   rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('TODO*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/TODO.rdoc

@@ -0,0 +1,5 @@
+= TODO
+
+* Add support for singleton events
+* Figure out a decent way to restrict access to Unobservable::Event#call to encourage proper encapsulation.
+

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.4

data/lib/unobservable.rb

@@ -114,6 +114,7 @@ module Unobservable
 
 
 
+  # Minimalistic Event implementation
   class Event
     attr_reader :handlers
 
@@ -147,6 +148,10 @@ module Unobservable
     end
 
 
+    # Removes a single instance of the specified event handler
+    # from the list of event handlers.  Therefore, if you've
+    # registered the same event handler 3 times, then you will
+    # need to unregister it 3 times as well.
     def unregister(*args, &block)
       h = handler_for(*args, &block)
       index = @handlers.index(h)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: unobservable
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
   prerelease: 
 platform: ruby
 authors:
@@ -88,6 +88,7 @@ files:
 - LICENSE.txt
 - README.rdoc
 - Rakefile
+- TODO.rdoc
 - VERSION
 - lib/unobservable.rb
 - test/helper.rb
@@ -107,7 +108,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 2472220124637666856
+      hash: 1737406497350544853
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: