elevate 0.4.0 → 0.5.0

data/.gitignore

@@ -5,3 +5,4 @@ resources/*.nib
 resources/*.momd
 resources/*.storyboardc
 .rvmrc
+Gemfile.lock

data/README.md

@@ -1,8 +1,10 @@
-Elevate  [![Code Climate](https://codeclimate.com/github/mattgreen/elevate.png)](https://codeclimate.com/github/mattgreen/elevate)
+Elevate
 ======
 
 Stop scattering your domain logic across your view controller. Consolidate it to a single conceptual unit with Elevate.
 
+[![Code Climate](https://codeclimate.com/github/mattgreen/elevate.png)](https://codeclimate.com/github/mattgreen/elevate) [![Travis](https://api.travis-ci.org/mattgreen/elevate.png)](https://travis-ci.org/mattgreen/elevate)
+
 Example
 -------
 
@@ -19,16 +21,24 @@ Example
       UserRegistration.store(credentials.username, credentials.token)
     end
 
-    # Return value of block is passed back to on_completed
+    # Anything yielded from this block is passed to on_update
+    yield "Logged in!"
+
+    # Return value of block is passed back to on_finish
     credentials != nil
   end
 
-  on_started do
+  on_start do
     # This block runs on the UI thread after the operation has been queued.
     SVProgressHUD.showWithStatus("Logging In...")
   end
 
-  on_completed do |result, exception|
+  on_update do |status|
+    # This block runs on the UI thread with anything the task yields
+    puts status
+  end
+
+  on_finish do |result, exception|
     # This block runs on the UI thread after the task block has finished.
     SVProgressHUD.dismiss
 
@@ -71,7 +81,7 @@ Installation
 ------------
 Update your Gemfile:
 
-    gem "elevate", "~> 0.4.0"
+    gem "elevate", "~> 0.5.0"
 
 Bundle:
 
@@ -91,7 +101,12 @@ Launch an async task with the `async` method:
 
 * Pass all the data the task needs to operate (such as credentials or search terms) in to the `async` method.
 * Define a block that contains a `task` block. The `task` block should contain all of your non-UI code. It will be run on a background thread. Any data passed into the `async` method will be available as instance variables, keyed by the provided hash key.
-* Optionally, define `on_started` and `on_completed` blocks to run as the task starts and finishes. These are run in the UI thread, and should contain all of your UI code.
+* Optionally:
+    * Define an `on_start` block to be run when the task starts
+    * Define an `on_finish` block to be run when the task finishes
+    * Define an `on_update` block to be called any time the task calls yield (useful for relaying status information back during long operations)
+
+All of the `on_` blocks are called on the UI thread. `on_start` is guaranteed to precede `on_update` and `on_finish`.
 
 ```ruby
 @track_task = async artist: searchBar.text do
@@ -100,11 +115,11 @@ Launch an async task with the `async` method:
     ArtistDB.update(artist)
   end
 
-  on_started do
+  on_start do
     SVProgressHUD.showWithStatus("Adding...")
   end
 
-  on_completed do |result, exception|
+  on_finish do |result, exception|
     SVProgressHUD.dismiss
   end
 end
@@ -117,12 +132,10 @@ To cancel a task (like when the view controller is being dismissed), call `cance
 To Do
 -----
 * Need ability to set timeout for tasks
-* More thought on the semantics
 
 Caveats
 ---------
 * Must use Elevate's HTTP client instead of other iOS networking libs
-* No way to report progress (idea: `execute` could yield status information via optional block)
 
 Inspiration
 -----------

data/lib/elevate/api.rb

@@ -22,8 +22,9 @@ module Elevate
     raise "No task block specified!" unless dsl.task_callback
 
     operation = ElevateOperation.alloc.initWithTarget(dsl.task_callback, args: args)
-    operation.on_started  = Callback.new(self, dsl.started_callback)  if dsl.started_callback
-    operation.on_finished = Callback.new(self, dsl.finished_callback) if dsl.finished_callback
+    operation.on_start  = Callback.new(self, dsl.start_callback)  if dsl.start_callback
+    operation.on_finish = Callback.new(self, dsl.finish_callback) if dsl.finish_callback
+    operation.on_update = Callback.new(self, dsl.update_callback)   if dsl.update_callback
 
     yield operation
 

data/lib/elevate/dsl.rb

@@ -4,26 +4,31 @@ module Elevate
       instance_eval(&block)
     end
 
-    attr_reader :started_callback
-    attr_reader :finished_callback
+    attr_reader :finish_callback
+    attr_reader :start_callback
     attr_reader :task_callback
+    attr_reader :update_callback
 
-    def task(&block)
-      raise "task blocks must accept zero parameters" unless block.arity == 0
+    def on_finish(&block)
+      raise "on_finish blocks must accept two parameters" unless block.arity == 2
 
-      @task_callback = block
+      @finish_callback = block
     end
 
-    def on_started(&block)
-      raise "on_started blocks must accept zero parameters" unless block.arity == 0
+    def on_start(&block)
+      raise "on_start blocks must accept zero parameters" unless block.arity == 0
+
+      @start_callback = block
+    end
 
-      @started_callback = block
+    def on_update(&block)
+      @update_callback = block
     end
 
-    def on_completed(&block)
-      raise "on_completed blocks must accept two parameters" unless block.arity == 2
+    def task(&block)
+      raise "task blocks must accept zero parameters" unless block.arity == 0
 
-      @finished_callback = block
+      @task_callback = block
     end
   end
 end

data/lib/elevate/operation.rb

@@ -1,31 +1,21 @@
 module Elevate
-  class Context
-    def initialize(args, &block)
-      metaclass = class << self; self; end
-      metaclass.send(:define_method, :execute, &block)
-
-      args.each do |key, value|
-        instance_variable_set("@#{key}", value)
-      end
-    end
-  end
-
   class ElevateOperation < NSOperation
     def initWithTarget(target, args:args)
       if init()
         @coordinator = IOCoordinator.new
-        @target = target
-        @context = Context.new(args, &target)
-        @finished_callback = nil
+        @context = TaskContext.new(args, &target)
+        @update_callback = nil
+        @finish_callback = nil
 
         setCompletionBlock(lambda do
-          if @finished_callback
-            @finished_callback.call(@result, @exception) unless isCancelled
+          if @finish_callback
+            @finish_callback.call(@result, @exception) unless isCancelled
           end
 
           Dispatch::Queue.main.sync do
-            @target = nil
-            @finished_callback = nil
+            @context = nil
+            @update_callback = nil
+            @finish_callback = nil
           end
         end)
       end
@@ -42,7 +32,6 @@ module Elevate
     def inspect
       details = []
       details << "<canceled>" if @coordinator.cancelled?
-      details << "@target=#{@target.class.name}"
 
       "#<#{self.class.name}: #{details.join(" ")}>"
     end
@@ -58,7 +47,9 @@ module Elevate
 
       begin
         unless @coordinator.cancelled?
-          @result = @context.execute
+          @result = @context.execute do |*args|
+            @update_callback.call(*args) if @update_callback
+          end
         end
 
       rescue Exception => e
@@ -73,18 +64,22 @@ module Elevate
     attr_reader :exception
     attr_reader :result
 
-    def on_started=(callback)
-      started_callback = callback
-      started_callback.retain
+    def on_finish=(callback)
+      @finish_callback = callback
+    end
+
+    def on_start=(callback)
+      start_callback = callback
+      start_callback.retain
 
       Dispatch::Queue.main.async do
-        started_callback.call unless isCancelled
-        started_callback.release
+        start_callback.call unless isCancelled
+        start_callback.release
       end
     end
 
-    def on_finished=(callback)
-      @finished_callback = callback
+    def on_update=(callback)
+      @update_callback = callback
     end
   end
 end

data/lib/elevate/task_context.rb

@@ -0,0 +1,12 @@
+module Elevate
+  class TaskContext
+    def initialize(args, &block)
+      metaclass = class << self; self; end
+      metaclass.send(:define_method, :execute, &block)
+
+      args.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+  end
+end

data/lib/elevate/version.rb

@@ -1,3 +1,3 @@
 module Elevate
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/spec/api_spec.rb

@@ -12,7 +12,7 @@ describe Elevate do
           true
         end
 
-        on_completed do |result, exception|
+        on_finish do |result, exception|
           @called = result
           resume
         end
@@ -29,7 +29,7 @@ describe Elevate do
           @name
         end
 
-        on_completed do |name, exception|
+        on_finish do |name, exception|
           @result = name
           resume
         end
@@ -39,5 +39,34 @@ describe Elevate do
         @result.should == "harry"
       end
     end
+
+    it "allows tasks to report progress" do
+      @updates = []
+
+      async do
+        task do
+          sleep 0.1
+          yield 1
+          sleep 0.2
+          yield 2
+          sleep 0.3
+          yield 3
+
+          true
+        end
+
+        on_update do |count|
+          @updates << count
+        end
+
+        on_finish do |result, exception|
+          resume
+        end
+      end
+
+      wait_max 1.0 do
+        @updates.should == [1,2,3]
+      end
+    end
   end
 end

data/spec/operation_spec.rb

@@ -13,12 +13,12 @@ describe Elevate::ElevateOperation do
     @operation.class.ancestors.should.include NSOperation
   end
 
-  describe "#on_finished" do
+  describe "#on_finish=" do
     it "invokes it after #on_started" do
       @lock = NSLock.alloc.init
       @value = []
 
-      @operation.on_started = lambda do
+      @operation.on_start = lambda do
         @lock.lock()
         if @value == []
           @value << 1
@@ -26,7 +26,7 @@ describe Elevate::ElevateOperation do
         @lock.unlock()
       end
 
-      @operation.on_finished = lambda do |result, exception|
+      @operation.on_finish = lambda do |result, exception|
         @lock.lock()
         if @value == [1]
           @value << 2

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: elevate
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-07 00:00:00.000000000 Z
+date: 2013-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -85,7 +85,6 @@ files:
 - .gitignore
 - .travis.yml
 - Gemfile
-- Gemfile.lock
 - Guardfile
 - LICENSE
 - README.md
@@ -107,10 +106,10 @@ files:
 - lib/elevate/io_coordinator.rb
 - lib/elevate/operation.rb
 - lib/elevate/promise.rb
+- lib/elevate/task_context.rb
 - lib/elevate/version.rb
 - spec/api_spec.rb
 - spec/callback_spec.rb
-- spec/dsl_spec.rb
 - spec/http/activity_indicator_spec.rb
 - spec/http/http_client_spec.rb
 - spec/http/http_request_spec.rb
@@ -128,28 +127,21 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -1464207392655779665
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -1464207392655779665
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Distill the essence of your RubyMotion app
 test_files:
 - spec/api_spec.rb
 - spec/callback_spec.rb
-- spec/dsl_spec.rb
 - spec/http/activity_indicator_spec.rb
 - spec/http/http_client_spec.rb
 - spec/http/http_request_spec.rb

data/Gemfile.lock

@@ -1,41 +0,0 @@
-PATH
-  remote: .
-  specs:
-    elevate (0.4.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    coderay (1.0.8)
-    guard (1.6.2)
-      listen (>= 0.6.0)
-      lumberjack (>= 1.0.2)
-      pry (>= 0.9.10)
-      terminal-table (>= 1.4.3)
-      thor (>= 0.14.6)
-    guard-motion (0.1.1)
-      guard (>= 1.1.0)
-      rake (>= 0.9)
-    listen (0.7.2)
-    lumberjack (1.0.2)
-    method_source (0.8.1)
-    pry (0.9.11.4)
-      coderay (~> 1.0.5)
-      method_source (~> 0.8)
-      slop (~> 3.4)
-    rake (0.9.6)
-    rb-fsevent (0.9.3)
-    slop (3.4.3)
-    terminal-table (1.4.5)
-    thor (0.17.0)
-    webstub (0.3.4)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  elevate!
-  guard-motion (~> 0.1.1)
-  rake (>= 0.9.0)
-  rb-fsevent (~> 0.9.1)
-  webstub (~> 0.3.3)

data/spec/dsl_spec.rb

@@ -1,21 +0,0 @@
-describe Elevate::DSL do
-  describe "#on_started" do
-    it "stores the provided block" do
-      i = Elevate::DSL.new do
-        on_started { puts 'hi' }
-      end
-
-      i.started_callback.should.not.be.nil
-    end
-  end
-
-  describe "#on_completed" do
-    it "stores the passed block" do
-      i = Elevate::DSL.new do
-        on_completed { |result, exception| puts 'hi' }
-      end
-
-      i.finished_callback.should.not.be.nil
-    end
-  end
-end