elevate 0.3

data/.gitignore

@@ -0,0 +1,5 @@
+.repl_history
+build
+resources/*.nib
+resources/*.momd
+resources/*.storyboardc

data/.rvmrc

@@ -0,0 +1,5 @@
+rvm ruby-1.9.3-p194@rubymotion --create
+
+[[ -s "config/rvm_env.sh" ]] && . "config/rvm_env.sh"
+[[ -s ".rvm_env" ]] && . ".rvm_env"
+

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: .
+  specs:
+    elevate (0.3)
+
+GEM
+  remote: http://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/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'motion', :all_after_pass => false do
+  watch(%r{^spec/.+_spec\.rb$})
+
+  # RubyMotion gem example
+  watch(%r{^lib/[^/]+/(.+)\.rb$})     { |m| "./spec/#{m[1]}_spec.rb" }
+end

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2013 Matt Green
+
+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/README.md

@@ -0,0 +1,179 @@
+Elevate
+======
+How do we convey the intent of our application?
+
+Background
+-----------
+iOS applications employ the MVC architecture to delineate responsibilities:
+
+* Models represent the entities important to our app
+* Views display those entities
+* Controllers react to user input, adjusting the model
+
+However, iOS view controllers seem to attract complexity: not only do they coordinate models, but they also coordinate boundary objects (persistence mechanisms, backend APIs) and view-related concerns. This conflation of responsibilities shrouds the domain logic (that is, what your application does), making it harder to reason about and test. Pure model-related logic can be tested easily on its own, the difficulty arises when models interact with boundaries. Asynchronous behavior only makes it worse.
+
+Elevate posits that the essence of your system are the use cases. They constitute the unique value that your application delivers. Their correctness is too important to be mixed in with presentation-level concerns. This results in a bit more code (one class per use case), but it allows the view controller to be relentlessly focused on view-related concerns.
+
+Extracting use cases into their own class has several benefits:
+
+* Consolidates domain and boundary interactions (read: all non-UI code) to a single conceptual unit
+* Clarifies the intent of the code, both within the view controller and the use case
+* Simplifies IO within the use case, allowing it feel blocking, while remaining interruptible (see below)
+* Eases testing, allow you to employ either mock-based tests or acceptance tests
+
+Implementation
+--------------
+Use cases are executed one at a time in a single, global `NSOperationQueue`. Each use case invocation is contained within a `NSOperation` subclass called `ElevateOperation`. `ElevateOperation` sets up an execution environment enabling compliant IO libraries to use traditional blocking control flows, rather than the traditional asynchronous style employed by iOS. Calls may be interrupted by invoking `cancel` on the `ElevateOperation`, triggering a `CancelledError` to be raised within the use case.
+
+The `Elevate::HTTP` module wraps NSURLRequest to work with this control flow. (Unfortunately, most iOS HTTP libraries do not work well with this paradigm.)
+
+Example
+------------
+Synchronizing data between a remote API and a local DB:
+
+```ruby
+class SyncArtists < Action
+  def execute
+    stale_artists.each do |stale_artist|
+      artist = api.get_artist(stale_artist.name)
+      tracked_artists.add(artist)
+    end
+
+    tracked_artists.all
+  end
+
+  private
+  def stale_artists
+    stale = []
+
+    current = api.get_artists()
+    current.each do |artist|
+      if stale?(artist)
+        stale << artist
+      end
+    end
+
+    stale
+  end
+
+  def stale?(artist)
+    existing = tracked_artists.find_by_name(artist.name)
+    if existing.nil?
+      return true
+    end
+
+    existing.updated_at < artist.updated_at
+  end
+end
+```
+
+Notice the use case (`SyncArtists`) describes the algorithm at a high level. It is not concerned with the UI, and it depends on abstractions. 
+
+The view controller retains a similar focus. In fact, it is completely ignorant of how the sync algorithm operates. It only knows that it will return a list of artists to display:
+
+```ruby
+class ArtistsViewController < UITableViewController
+  include Elevate
+
+  def artists
+    @artists ||= []
+  end
+
+  def artists=(artists)
+    @artists = artists
+    view.reloadData()
+  end
+
+  def viewWillAppear(animated)
+    super
+
+    async SyncArtists.new do
+      on_completed do |operation|
+        self.artists = operation.result
+      end
+    end
+  end
+end
+```
+
+Requirements
+------------
+* **iOS 6.x and higher** (due to `setDelegateQueue` being [horribly broken](http://openradar.appspot.com/10529053) on iOS 5.x.)
+
+Installation
+------------
+Update your Gemfile:
+
+    gem "elevate", "~> 0.3.0"
+
+Bundle:
+
+    $ bundle install
+
+Usage
+-----
+
+Write a use case. Use case classes must respond to `execute`. Anything returned from `execute` is made available to the controller callbacks:
+```ruby
+class TrackArtist < Action
+  def initialize(artist_name)
+    @artist_name = artist_name
+  end
+
+  def execute
+    unless registration.completed?
+      user = api.register()
+      registration.save(user)
+    end
+
+    artist = api.track(@artist_name)
+    tracked_artists.add(artist)
+
+    artist
+  end
+end
+```
+
+Include the module in your view controller:
+
+```ruby
+class ArtistsSearchViewController < UIViewController
+  include Elevate
+```
+
+Execute a use case:
+
+```ruby
+async TrackArtist.new(artist_name) do
+  on_started do |operation|
+    SVProgressHUD.showWithStatus("Adding...", maskType:SVProgressHUDMaskTypeGradient)
+  end
+
+  # operation.result contains the return value of #execute
+  # operation.exception contains the raised exception (if any)
+  on_completed do |operation|
+    SVProgressHUD.dismiss()
+  end
+end
+```
+
+Caveats
+---------
+* **DSL is not finalized**
+* Sending CoreData entities across threads is dangerous
+* The callback DSL is clunky to try to avoid retain issues
+* 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
+-----------
+* [PoEAA: Transaction Script](http://martinfowler.com/eaaCatalog/transactionScript.html)
+* [The Clean Architecture](http://blog.8thlight.com/uncle-bob/2012/08/13/the-clean-architecture.html)
+* [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture)
+* [Architecture: The Lost Years](http://www.youtube.com/watch?v=WpkDN78P884)
+* [Android SDK's AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html)
+* Go (asynchronous IO done correctly)
+
+License
+---------
+MIT License

data/Rakefile

@@ -0,0 +1,20 @@
+$:.unshift("/Library/RubyMotion/lib")
+
+require 'motion/project'
+require "bundler/gem_tasks"
+require "bundler/setup"
+Bundler.require :default
+
+require 'webstub'
+
+$:.unshift("./lib/")
+require './lib/elevate'
+
+Motion::Project::App.setup do |app|
+  app.name = "elevate"
+
+  if ENV["DEFAULT_PROVISIONING_PROFILE"]
+    app.provisioning_profile = ENV["DEFAULT_PROVISIONING_PROFILE"]
+  end
+end
+

data/app/app_delegate.rb

@@ -0,0 +1,5 @@
+class AppDelegate
+  def application(application, didFinishLaunchingWithOptions:launchOptions)
+    true
+  end
+end

data/elevate.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/elevate/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Matt Green"]
+  gem.email         = ["mattgreenrocks@gmail.com"]
+  gem.description   = "Distill the essence of your RubyMotion app"
+  gem.summary       = "Distill the essence of your RubyMotion app"
+  gem.homepage      = "http://github.com/mattgreen/elevate"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "elevate"
+  gem.require_paths = ["lib"]
+  gem.version       = Elevate::VERSION
+
+  gem.add_development_dependency 'rake', '>= 0.9.0'
+  gem.add_development_dependency 'guard-motion', '~> 0.1.1'
+  gem.add_development_dependency 'rb-fsevent', '~> 0.9.1'
+  gem.add_development_dependency 'webstub', '~> 0.3.3'
+end

data/lib/elevate.rb

@@ -0,0 +1,11 @@
+require 'elevate/version'
+
+unless defined?(Motion::Project::Config)
+  raise "This file must be required within a RubyMotion project Rakefile."
+end
+
+Motion::Project::App.setup do |app|
+  Dir.glob(File.join(File.dirname(__FILE__), "elevate/**/*.rb")).each do |file|
+    app.files.unshift(file)
+  end
+end

data/lib/elevate/api.rb

@@ -0,0 +1,33 @@
+module Elevate
+  def async(target, &block)
+    with_operation(target, block) do |operation|
+      queue.addOperation(operation)
+    end
+  end
+
+  private
+
+  def queue
+    Dispatch.once do
+      $elevate_queue = NSOperationQueue.alloc.init
+      $elevate_queue.maxConcurrentOperationCount = 1
+    end
+
+    $elevate_queue
+  end
+
+  def with_operation(target, dsl_block, &block)
+    operation = ElevateOperation.alloc.initWithTarget(target)
+
+    if dsl_block
+      dsl = DSL.new(&dsl_block)
+
+      operation.on_started  = Callback.new(self, operation, dsl.started_callback)  if dsl.started_callback
+      operation.on_finished = Callback.new(self, operation, dsl.finished_callback) if dsl.finished_callback
+    end
+
+    yield operation
+
+    operation
+  end
+end

data/lib/elevate/callback.rb

@@ -0,0 +1,13 @@
+module Elevate
+  class Callback
+    def initialize(context, operation, block)
+      @context = context
+      @operation = operation
+      @block = block
+    end
+
+    def call
+      @context.instance_exec(@operation, &@block)
+    end
+  end
+end

data/lib/elevate/dispatcher.rb

@@ -0,0 +1,53 @@
+module Elevate
+  class Dispatcher
+    def initialize
+      @on_finished = nil
+      @on_started = nil
+    end
+
+    def dispose
+      return if @on_started.nil? && @on_finished.nil?
+
+      # Callbacks must be released on the main thread, because they may contain a strong
+      # reference to a UIKit component. See "The Deallocation Problem" for more info.
+      unless NSThread.isMainThread
+        self.performSelectorOnMainThread(:dispose, withObject: nil, waitUntilDone: true)
+        return
+      end
+
+      @on_started = nil
+      @on_finished = nil
+    end
+
+    def invoke_finished_callback
+      invoke(:@on_finished)
+    end
+
+    def on_finished=(callback)
+      @on_finished = callback
+    end
+
+    def on_started=(callback)
+      @on_started = callback
+
+      Dispatch::Queue.main.async do
+        invoke(:@on_started)
+      end
+    end
+
+    private
+
+    def invoke(callback_name)
+      unless NSThread.isMainThread
+        self.performSelectorOnMainThread(:"invoke:", withObject: callback_name, waitUntilDone: true)
+        return
+      end
+
+      if callback = instance_variable_get(callback_name)
+        callback.call()
+
+        instance_variable_set(callback_name, nil)
+      end
+    end
+  end
+end

data/lib/elevate/dsl.rb

@@ -0,0 +1,18 @@
+module Elevate
+  class DSL
+    def initialize(&block)
+      instance_eval(&block)
+    end
+
+    attr_reader :started_callback
+    attr_reader :finished_callback
+
+    def on_started(&block)
+      @started_callback = block
+    end
+
+    def on_completed(&block)
+      @finished_callback = block
+    end
+  end
+end

data/lib/elevate/http/base64.rb

@@ -0,0 +1,9 @@
+module Elevate
+module HTTP
+  module Base64
+    def self.encode(s)
+      [s].pack("m0")
+    end
+  end
+end
+end