mr_darcy 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 200c16f28a04c2608e104d084400e44c55f84e78
+  data.tar.gz: 2c4132617b62c2713cedcc37d560c55a180e6251
+SHA512:
+  metadata.gz: baa8c75ad0f00c458e6610b389a52b29d345b705d02f71ca845a8df4297deb31c3c7c5b6b556ef3338b179a807f8e5f53121308d30eb0111f045bdbf6f1bd044
+  data.tar.gz: c73abc19ded59554f375cbf4e34a74fa946e114d2a34d90711e568f0b47179b5535675fb6448614706024108b33ef27cc41f701347a086d9943bf4476a0970e6

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,7 @@
+rvm:
+  - 2.1.1
+  - 2.1.0
+  - 2.0.0
+  - jruby-20mode
+  - rbx
+

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'pry-byebug', platforms: [:mri_20, :mri_21]
+
+# Specify your gem's dependencies in mr_darcy.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,95 @@
+PATH
+  remote: .
+  specs:
+    mr_darcy (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.5)
+    byebug (2.6.0)
+      columnize (~> 0.3)
+      debugger-linecache (~> 1.2)
+    celluloid (0.15.2)
+      timers (~> 1.1.0)
+    celluloid-io (0.15.0)
+      celluloid (>= 0.15.0)
+      nio4r (>= 0.5.0)
+    coderay (1.1.0)
+    columnize (0.3.6)
+    cookiejar (0.3.0)
+    debugger-linecache (1.2.0)
+    diff-lcs (1.2.5)
+    em-http-request (1.0.3)
+      addressable (>= 2.2.3)
+      cookiejar
+      em-socksify
+      eventmachine (>= 1.0.0.beta.4)
+      http_parser.rb (>= 0.5.3)
+    em-socksify (0.2.1)
+      eventmachine (>= 1.0.0.beta.4)
+    eventmachine (1.0.3)
+    ffi (1.9.3)
+    formatador (0.2.4)
+    guard (2.4.0)
+      formatador (>= 0.2.4)
+      listen (~> 2.1)
+      lumberjack (~> 1.0)
+      pry (>= 0.9.12)
+      thor (>= 0.18.1)
+    guard-bundler (2.0.0)
+      bundler (~> 1.0)
+      guard (~> 2.2)
+    guard-rspec (4.2.6)
+      guard (~> 2.1)
+      rspec (>= 2.14, < 4.0)
+    http_parser.rb (0.6.0)
+    listen (2.5.0)
+      celluloid (>= 0.15.2)
+      celluloid-io (>= 0.15.0)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.4)
+    method_source (0.8.2)
+    nio4r (1.0.0)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    pry-byebug (1.3.1)
+      byebug (~> 2.6)
+      pry (~> 0.9.12)
+    rake (10.1.1)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.3)
+      ffi (>= 0.5.0)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.5)
+    slop (3.4.7)
+    terminal-notifier-guard (1.5.3)
+    thor (0.18.1)
+    timers (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.5)
+  celluloid
+  em-http-request
+  eventmachine
+  guard
+  guard-bundler
+  guard-rspec
+  mr_darcy!
+  pry
+  pry-byebug
+  rake
+  rspec
+  terminal-notifier-guard

data/Guardfile

@@ -0,0 +1,14 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard :bundler do
+  watch('Gemfile')
+  watch(/^.+\.gemspec/)
+end
+
+guard :rspec do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 James Harton
+
+MIT License
+
+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,267 @@
+# MrDarcy
+
+A mashup of Async Promises and DCI in ruby.
+
+![Build Status](https://www.codeship.io/projects/baa3c520-a0e3-0131-f32f-26748b0e5360/status)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mr_darcy'
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself as:
+
+```sh
+gem install mr_darcy
+```
+
+## Usage
+
+### WARNING
+
+MrDarcy is definitely experimental, and was mostly built over the weekend of
+[RailsCamp NZ 5](http://camp.ruby.org.nz/) with the generous help of the
+amazing and sexy [@breccan](https://twitter.com/breccan) and
+[@eoinkelly](https://twitter.com/eoinkelly).
+
+#### Should I use MrDarcy in Production?
+
+No.
+
+#### How can I help make MrDarcy production ready?
+
+Run it in production. Report bugs.
+
+### Such promise. Many then.
+
+Promises are a way of structuring batches of (async) functionality into a
+pipeline, in such a way as to make them seem synchronous.
+
+Here's an example:
+
+```ruby
+# We're going to wrap an asynchronous web request using EventMachine
+# in a promise:
+data = MrDarcy.promise do
+  EM.run do
+    http = EM.HttpRequest.new('http://camp.ruby.org.nz/').get
+    http.errback do
+      reject http.error
+      EM.stop
+    end
+    http.callback do
+      resolve http.response
+      EM.stop
+    end
+  end
+end.then do |response|
+  response.body
+end.result
+
+puts data
+```
+
+What's cool about MrDarcy is that we can switch between different methods of
+doing async ruby:
+  - Naive threads, using MRI's thread implementation.
+  - Reactor pattern, using [EventMachine](http://rubyeventmachine.com/) to
+    schedule promises on the a reactor thread.
+  - Actor pattern, using [Celluloid](http://celluloid.io/) to schedule
+    promises using Celluloid futures.
+
+#### Key points to know about Promises
+
+  1. You create them with a block, which is scheduled asynchronously, and
+     inside of which you can place your long-running executable. Inside this
+     block you call either `resolve <value>` or `reject <exception>` to resolve
+     or reject the promise.
+
+     ```ruby
+     MrDarcy.promise do
+       accellerate_the_delorean
+       if speed >= 88
+         resolve :time_flux_initiated
+       else
+         reject :engage_service_brake
+       end
+     end
+     ```
+
+  2. All promises have `then` and `fail` methods, to which you pass a block to
+     be called when the promise resolves (`then`) or rejects (`fail`). These
+     methods return new promises, upon which you can chain more `then` and
+     `fail` calls.
+
+     ```ruby
+     MrDarcy.promise do
+       i = rand
+       i > 0.5 ? resolve i : reject i
+     end.then |value|
+       # success
+     end.fail |value|
+       # failure
+     end
+     ```
+
+  3. `fail` is used to catch errors asynchronously, and deal with them.
+     Therefore the result of a `fail` block will be a resolved promise.
+     If you wish to keep processing a failure then you can `raise` it
+     within the `fail` block to pass it along to the next `fail` block.
+
+     ```ruby
+     MrDarcy.promise do
+       reject 2
+     end.fail |value|
+       value * value
+     end.then |value|
+       # I am called with 4
+     end
+     ```
+
+  4. Failures cascade until they're caught:
+
+     ```ruby
+     MrDarcy.promise do
+       reject :fail
+     end.then
+       # I am skipped
+     end.then
+       # as am I
+     end.fail
+       # I am called
+     end
+     ```
+
+  5. If your block returns a new promise, then `then` or `fail` will defer
+     their resolution until the new promise is resolved:
+
+     ```ruby
+     MrDarcy.promise do
+       resolve 1
+     end.then do |value|
+       MrDarcy.promise do
+         resolve value * 2
+       end
+     end.then |value|
+       # I will be called with 2
+     end
+     ```
+
+### Sprinkle on some DCI goodness.
+
+[DCI](http://fulloo.info) is a method of specifying interactions between
+objects in a single location, by decorating or extending your data objects
+within a context, running the interaction and then (optionally) removing
+the extensions again.
+
+Other takes on DCI in Ruby:
+  - [playhouse](https://github.com/enspiral/playhouse) is an app framework
+    for building entire apps with DCI from the lovable hippies at
+    [enspiral](http://www.enspiral.com/),
+
+  - [surrounded](https://github.com/saturnflyer/surrounded) by
+    [Jim Gay](https://github.com/saturnflyer) is a gem for doing DCI in
+    a simple, repeatable fashion.
+
+MrDarcy is a little differnt to these approaches, as is builds an interesting
+DSL on top of promises to create contexts that are alive as long as they need
+to be to achieve their goal, even when code is being run asynchronously.
+
+Here's how we define a classic bank trasfer example:
+
+```ruby
+class BankTransfer < MrDarcy::Context
+  role :money_source do
+    def has_available_funds? amount
+      available_balance >= amount
+    end
+
+    def subtract_funds amount
+      self.available_balance = available_balance - amount
+    end
+  end
+
+  role :money_destination do
+    def receive_funds amount
+      self.available_balance = available_balance + amount
+    end
+  end
+
+  action :transfer do |amount|
+    if money_source.has_available_funds? amount
+      money_source.subtract_funds amount
+      money_destination.receive_funds amount
+    else
+      raise "insufficient funds"
+    end
+    amount
+  end
+end
+```
+
+  - The `role` class method defines roles, which the context will expect to be
+    passed on object creation.  They also define the extra behaviour (methods)
+    that we wish to see added to our role players at initialisation.
+
+  - The `action` class method defines our interactions. In other words, this
+    is where we define how the interaction will take place. These also define
+    instance methods on the class of the same name, which return a promise
+    when called.
+
+  - You can have as many roles and actions as needed by your context.
+
+Let's transfer some funds between two accounts:
+
+```ruby
+Account = Struct.new(:available_balance)
+marty     = Account.new(10)
+doc_brown = Account.new(15)
+
+context = BankTransfer.new money_source: marty, money_destination: doc_brown
+context.transfer(5).then do |amount|
+  puts "Successfully transferred #{amount} from #{money_source} to #{money_destination}"
+end
+
+context.transfer(50).fail do |exception|
+  puts "Failed to transfer funds: #{exception.message}"
+end
+```
+
+What's super cool, however is that because promises can return and chain other
+promises, we can come up with some pretty involved scenarios:
+
+```ruby
+marty     = Account.new(10)
+jenn      = Account.new(10)
+doc_brown = Account.new(200)
+
+context = BankTransfer.new money_source: marty, money_destination: jenn
+context.transfer(20).fail do
+  # Oh no, Marty doesn't have enough money, let's borrow some from Doc.
+  BankTransfer.new(money_source: doc_brown, money_destination: marty) \
+    .transfer(20).then
+      # Thy transferring again.
+      context.transfer(20)
+    end
+end
+```
+
+I hope that's enough to get you started.  Yup, it's a bit crazy, but it might
+just work.
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/mr_darcy/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new :spec
+
+task default: :spec

data/lib/mr_darcy/context.rb

@@ -0,0 +1,71 @@
+module MrDarcy
+  class Context
+
+    class << self
+      def role role_name, options={}, &block
+        self.roles[role_name] = Role.new(role_name, options, &block)
+      end
+
+      def action action_name, &block
+        define_method action_name do |*args|
+          self.then do |value|
+            self.instance_exec(*args, &block)
+          end
+          self
+        end
+      end
+
+      def roles
+        @roles ||= {}
+      end
+    end
+
+    def initialize role_players={}
+      @driver   = role_players.delete(:driver) || MrDarcy.driver
+      @deferred = Deferred.new(driver: driver) {}
+      deferred.resolve nil
+
+      roles = self.class.roles
+      roles.each do |role_name, role|
+        player = role_players[role_name]
+        raise ArgumentError, "No role player for #{role_name} supplied" unless player
+
+        role.pollute(player)
+
+        self.singleton_class.send :define_method, role_name do
+          player
+        end
+      end
+    end
+
+    def then &block
+      deferred.then do |value|
+        self.instance_exec(value, &block)
+      end
+      self
+    end
+
+    def fail &block
+      deferred.fail do |value|
+        self.instance_exec(value, &block)
+      end
+      self
+    end
+
+    %w| result rejected? resolved? unresolved? |.map(&:to_sym).each do |method|
+      define_method method do
+        deferred.public_send method
+      end
+    end
+
+    def final
+      deferred.final
+      self
+    end
+
+    private
+
+    attr_accessor :deferred, :driver
+
+  end
+end

data/lib/mr_darcy/deferred.rb

@@ -0,0 +1,25 @@
+module MrDarcy
+  class Deferred
+
+    attr_accessor :promise, :last_promise
+
+    %w| resolved? rejected? unresolved? resolve reject final result |.map(&:to_sym).each do |method|
+      define_method method do |*args|
+        promise.public_send method, *args
+      end
+    end
+
+    def then &block
+      self.last_promise = last_promise.then(&block)
+    end
+
+    def fail &block
+      self.last_promise = last_promise.fail(&block)
+    end
+
+    def initialize driver: MrDarcy.driver
+      self.promise = MrDarcy::Promise.new(driver: driver) {}
+      self.last_promise = promise
+    end
+  end
+end

data/lib/mr_darcy/drivers/celluloid.rb

@@ -0,0 +1,23 @@
+require 'celluloid/autostart'
+
+module MrDarcy
+  module Drivers
+    module Celluloid
+      module_function
+
+      def dispatch(&block)
+        futures << ::Celluloid::Future.new(&block)
+      end
+
+      def wait
+        futures.each do |future|
+          future.value
+        end
+      end
+
+      def futures
+        @futures ||= []
+      end
+    end
+  end
+end

data/lib/mr_darcy/drivers/synchronous.rb

@@ -0,0 +1,15 @@
+module MrDarcy
+  module Drivers
+    module Synchronous
+      module_function
+
+      def dispatch
+        yield
+      end
+
+      def wait
+        yield
+      end
+    end
+  end
+end

data/lib/mr_darcy/drivers/thread.rb

@@ -0,0 +1,22 @@
+require 'thread'
+
+module MrDarcy
+  module Drivers
+    module Thread
+      module_function
+
+      def dispatch(&block)
+        @threads ||= []
+        @threads << ::Thread.new(&block)
+      end
+
+      def wait
+        @threads ||= []
+        @threads.each do |thread|
+          thread.join unless ::Thread.current == thread
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/mr_darcy/drivers.rb

@@ -0,0 +1,13 @@
+module MrDarcy
+  module Drivers
+    autoload :Synchronous, File.expand_path('../drivers/synchronous.rb', __FILE__)
+    autoload :Thread,      File.expand_path('../drivers/thread.rb', __FILE__)
+    autoload :Celluloid,   File.expand_path('../drivers/celluloid.rb', __FILE__)
+
+    module_function
+
+    def all
+      [ Synchronous, Thread, Celluloid ]
+    end
+  end
+end