motion-wiretap 0.1.0 → 0.2.0

data/README.md

@@ -1,16 +1,156 @@
-MotionWiretap
+Wiretap
 -------
 
 An iOS / OS X wrapper heavily inspired by ReactiveCocoa.
 
-gem coming soon, just need to write the gemspec
+    gem install motion-wiretap
 
-run the OSX specs using `rake spec platform=osx`
+Run the OSX specs using `rake spec platform=osx`
+
+First things first
+------------------
+
+You **MUST** call `cancel!` on any wiretaps you create, otherwise they will live
+in memory forever.  The upside is that you can create 
 
 Showdown
--------
+--------
 
 Open these side by side to see the comparison:
 
 [reactive.rb](https://gist.github.com/colinta/d0a273f8d858a8f61c73)
 [reactive.mm](https://gist.github.com/colinta/5cfa588fed7b929193ae)
+
+Usage
+-----
+
+These are taken from the specs.
+
+### Key-Value Observation
+
+```ruby
+class Person
+  attr_accessor :name
+  attr_accessor :email
+  attr_accessor :address
+end
+
+# listen for changes
+person = Person.new
+person.wiretap(:name) do |name|
+  puts "name is now #{name}"
+end
+person.name = 'Joe'
+# puts => "name is now Joe"
+
+# bind the property of one object to the value of another
+person_1 = Person.new
+person_2 = Person.new
+wiretap = person_1.wiretap(:name).bind_to(person_2.wiretap(:name))
+person_2.name = 'Bob'
+person_1.name # => "Bob"
+
+# cancel a wiretap
+wiretap.cancel!
+person_2.name = 'Jane'
+person_1.name
+# => "BOB"
+
+# bind the property of one object to the value of another, but change it using `map`
+wiretap = person_1.wiretap(:name).bind_to(person_2.wiretap(:name).map { |value| value.upcase })
+person_2.name = 'Bob'
+person_1.name # => "BOB"
+```
+
+### Working with arrays
+
+```
+# combine the values `name` and `email`
+person = Person.new
+[
+  person.wiretap(:name),
+  person.wiretap(:email),
+].wiretap.combine do |name, email|
+  puts "#{name} <#{email}>"
+end
+
+person.name = 'Kazuo'
+# puts => "Kazuo <>"
+person.email = 'kaz@example.com'
+# puts => "Kazuo <kaz@example.com>"
+
+# reduce/inject
+person_1 = Person.new
+person_2 = Person.new
+[
+  person_1.wiretap(:name),
+  person_2.wiretap(:name),
+].wiretap.reduce do |memo, name|
+  memo ||= []
+  memo + [name]
+end
+person_1.name = 'Mr. White'
+person_1.name = 'Mr. Blue'
+# => ['Mr. White', 'Mr. Blue']
+
+# you can provide an initial 'memo' (default: nil)
+[
+  person_1.wiretap(:name),
+  person_2.wiretap(:name),
+].wiretap.reduce([]) do |memo, name|
+  memo + [name]  # you should not change memo in place, the same one will be used on every change event
+end
+```
+
+### Monitoring jobs
+
+```ruby
+# monitor for background job completion
+-> {
+  this_will_take_forever!
+}.wiretap(Dispatch::Queue.concurrent) do
+  puts "done!"
+end
+
+# Note: this is convenient shorthand for calling `queue`, `and_then`, and `start`
+-> {}.wiretap.queue(...).and_then do ... end.start
+
+# send a stream of values.  a lambda is passed in that will forward change
+# events to the `listen` block
+-> (on_change) do
+  5.times do |count|
+    on_change.call count
+  end
+end.wiretap.queue(Dispatch::Queue.concurrent).listen do |index|
+  puts "...#{index}"
+end.and_then do
+  puts "done!"
+end.start
+# => puts "...0", "...1", "...2", "...3", "...4", "done!"
+```
+
+### Let's do something practical!
+
+```ruby
+# bind the `enabled` property to the Wiretap object to a check on whether
+# `username_field.text` and `password_field.text` are blank
+@login_button.wiretap(:enabled).bind_to(
+  [
+    @username_field.wiretap(:text),
+    @password_field.wiretap(:text),
+  ].wiretap.combine do |username, password|
+    username && username.length > 0 && password && password.length > 0
+  end
+  )
+```
+
+### Notifications
+
+```ruby
+notification = "NotificationName".wiretap do
+  puts "notification received!"
+end
+
+# rememder: it's *important* to cancel all wiretaps!
+notification.cancel!
+```

data/lib/motion-wiretap/all/wiretap.rb

@@ -1,11 +1,10 @@
-$motion_wiretaps = []
 
 module MotionWiretap
 
   class Wiretap
 
     def initialize(&block)
-      $motion_wiretaps << self  # signal will be removed when it is completed
+      # MotionWiretap.wiretaps << self  # signal will be removed when it is completed
 
       @is_torn_down = false
       @is_completed = false
@@ -19,16 +18,16 @@ module MotionWiretap
       listen &block if block
     end
 
-    def dealloc
+    # this is the preferred way to turn off a wiretap; child classes override
+    # `teardown`, which is only ever called once.
+    def cancel!
+      return if @is_torn_down
+      @is_torn_down = true
       teardown
-      super
     end
 
+    # for internal use
     def teardown
-      return if @is_torn_down
-
-      @is_torn_down = true
-      $motion_wiretaps.remove(self)
     end
 
     # specify the GCD queue that the listeners should be run on
@@ -97,7 +96,7 @@ module MotionWiretap
         trigger_completed_on(block_or_wiretap)
       end
 
-      teardown
+      cancel!
       return self
     end
 
@@ -131,7 +130,7 @@ module MotionWiretap
         trigger_error_on(block_or_wiretap, error)
       end
 
-      teardown
+      cancel!
       return self
     end
 
@@ -242,18 +241,18 @@ module MotionWiretap
 
   end
 
-  class WiretapArray < WiretapTarget
+  class WiretapArray < Wiretap
     attr :targets
 
     def initialize(targets, &block)
       raise "Not only is listening to an empty array pointless, it will also cause errors" if targets.length == 0
 
-      # the complete trigger isn't called until all the wiretaps are complete
+      # the complete trigger isn't called until all the wiretap are complete
       @uncompleted = targets.length
 
       # targets can be an array of Wiretap objects (they will be monitored), or
       # plain objects (they'll just be included in the sequence)
-      super(targets, &block)
+      super(&block)
 
       # gets assigned to the wiretap value if it's a Wiretap, or the object
       # itself if it is anything else.
@@ -293,9 +292,16 @@ module MotionWiretap
       end
     end
 
-    def teardown
+    def cancel!
+      @wiretaps.each do |wiretap,index|
+        wiretap.cancel!
+      end
       super
+    end
+
+    def teardown
       @wiretaps = nil
+      super
     end
 
     def trigger_changed(*values)
@@ -325,8 +331,8 @@ module MotionWiretap
     end
 
     def teardown
-      super
       @parent = nil
+      super
     end
 
   end
@@ -349,8 +355,8 @@ module MotionWiretap
     end
 
     def teardown
-      super
       @parent = nil
+      super
     end
 
   end
@@ -374,8 +380,8 @@ module MotionWiretap
     end
 
     def teardown
-      super
       @parent = nil
+      super
     end
 
   end
@@ -398,23 +404,21 @@ module MotionWiretap
     end
 
     def teardown
-      super
       @parent = nil
+      super
     end
 
   end
 
   class WiretapProc < WiretapTarget
 
-    def initialize(target, queue=nil, &block)
+    def initialize(target, queue, block)
       @started = false
-      super(target, &block)
+      super(target)
+      and_then(&block) if block
       queue(queue) if queue
-    end
 
-    def queue(queue)
-      super
-      start
+      start if block
     end
 
     def start
@@ -422,7 +426,11 @@ module MotionWiretap
         @started = true
         enqueue do
           begin
-            trigger_changed(@target.call)
+            if @target.arity == 0
+              @target.call
+            else
+              @target.call(-> (value) { self.trigger_changed(value) })
+            end
           rescue Exception => error
             trigger_error(error)
           else
@@ -432,16 +440,33 @@ module MotionWiretap
       end
     end
 
+  end
 
-    def listen(wiretap=nil, &block)
-      raise "WiretapProc does not support listeners (only the `completed` event is triggered)"
+  class WiretapNotification < Wiretap
+
+    def initialize(notification, object, block)
+      @notification = notification
+      @object = object
+
+      NSNotificationCenter.defaultCenter.addObserver(self, selector: 'notify:', name:@notification, object:@object)
+      listen(&block) if block
     end
 
-    def and_then(wiretap=nil, &block)
+    def notify(notification)
+      trigger_changed(notification.object, notification.userInfo)
+    end
+
+    def teardown
+      NSNotificationCenter.defaultCenter.removeObserver(self, name:@notification, object:@object)
       super
-      start
     end
 
   end
 
+  module_function
+
+  def wiretaps
+    @wiretaps ||= []
+  end
+
 end

data/lib/motion-wiretap/all/wiretap_exts.rb

@@ -10,11 +10,7 @@ end
 
 class NSArray
 
-  def wiretap(property=nil, &block)
-    raise "`wiretap` is not supported on Arrays (arrays are not observable).  You probably meant to use `wiretaps`."
-  end
-
-  def wiretaps(&block)
+  def wiretap(&block)
     MotionWiretap::WiretapArray.new(self, &block)
   end
 
@@ -24,7 +20,16 @@ end
 class Proc
 
   def wiretap(queue=nil, &block)
-    MotionWiretap::WiretapProc(queue, &block)
+    MotionWiretap::WiretapProc.new(self, queue, block)
+  end
+
+end
+
+
+class NSString
+
+  def wiretap(object=nil, &block)
+    MotionWiretap::WiretapNotification(self, object, block)
   end
 
 end

data/lib/motion-wiretap/ios/wiretap_control_events.rb

@@ -76,7 +76,7 @@ module MotionWiretap
       when :all
         return UIControlEventAllEvents
       else
-        raise ControlEventNotFound.new
+        raise ControlEventNotFound.new(control_events.to_s)
       end
     end
 

data/lib/motion-wiretap/ios/wiretap_ios.rb

@@ -1,25 +1,33 @@
 module MotionWiretap
+  class GestureNotFound < Exception
+  end
 
-  class WiretapView < WiretapTarget
+  class WiretapView < Wiretap
 
     def on(recognizer, options=nil, &block)
-      case recognizer
-      when :tap
-        recognizer = MotionWiretap::Gestures.tap(self, options)
-      when :pinch
-        recognizer = MotionWiretap::Gestures.pinch(self, options)
-      when :rotate
-        recognizer = MotionWiretap::Gestures.rotate(self, options)
-      when :swipe
-        recognizer = MotionWiretap::Gestures.swipe(self, options)
-      when :pan
-        recognizer = MotionWiretap::Gestures.pan(self, options)
-      when :press
-        recognizer = MotionWiretap::Gestures.press(self, options)
+      if recognizer
+        case recognizer
+        when :tap
+          recognizer = Gestures.tap(self, options)
+        when :pinch
+          recognizer = Gestures.pinch(self, options)
+        when :rotate
+          recognizer = Gestures.rotate(self, options)
+        when :swipe
+          recognizer = Gestures.swipe(self, options)
+        when :pan
+          recognizer = Gestures.pan(self, options)
+        when :press
+          recognizer = Gestures.press(self, options)
+        else
+          raise GestureNotFound.new(recognizer.to_s)
+        end
+
+        self.target.addGestureRecognizer(recognizer)
       end
 
-      self.target.addGestureRecognizer(recognizer)
-      listen(&block) if block
+      super(&block)
+
       return self
     end
 
@@ -31,16 +39,18 @@ module MotionWiretap
 
   class WiretapControl < WiretapView
 
-    # control_event can be any UIControlEventconstant, or any symbol found in
-    # wiretap_control_events.rb, or an array of UIControlEvent constants or
-    # symbols.
+    # control_event can be any UIControlEventConstant, or any symbol found in
+    # wiretap_control_events.rb, or an array of UIControlEventConstants or
+    # symbols.  Since UIView implements `on` to accept a gesture, this method
+    # calls `super` when the symbol isn't a control
     def on(control_event, options={}, &block)
       begin
         control_event = ControlEvents.convert(control_event)
         self.target.addTarget(self, action:'handle_event:', forControlEvents:control_event)
-        listen(&block) if block
       rescue ControlEventNotFound
         super(control_event, options, &block)
+      else
+        super(nil, options, &block)
       end
 
       return self

data/lib/motion-wiretap/version.rb

@@ -1,3 +1,3 @@
 module MotionWiretap
-  Version = '0.1.0'
+  Version = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: motion-wiretap
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-16 00:00:00.000000000 Z
+date: 2013-09-24 00:00:00.000000000 Z
 dependencies: []
 description: ! 'ReactiveCocoa is an amazing system, and RubyMotion could benefit from
   the