promise.rb 0.3.0 → 0.4.0

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# promise.rb changelog
+
+## 0.4.0 (December 13, 2013)
+
+* Disclaiming my copyright, promise.rb is now in the Public Domain
+* on_fulfill argument to #then now takes precedence over block
+* The rejection reason now defaults to RuntimeError, so that it can be re-raised by #sync
+* `progress` and `on_progress` are now first class citizens

data/Gemfile

@@ -13,7 +13,6 @@ platform :rbx do
   gem 'rubysl', '~> 2.0'
   gem 'rubysl-json', '~> 2.0'
   gem 'rubinius', '~> 2.0'
-  gem 'racc'
 end
 
 # Added by devtools

data/Gemfile.devtools

@@ -4,6 +4,10 @@ group :development do
   gem 'rake',  '~> 10.1.0'
   gem 'rspec', '~> 2.14.1'
   gem 'yard',  '~> 0.8.7'
+
+  platform :rbx do
+    gem 'rubysl-singleton', '~> 2.0.0'
+  end
 end
 
 group :yard do
@@ -11,14 +15,13 @@ group :yard do
 end
 
 group :guard do
-  gem 'guard',         '~> 1.8.1'
-  gem 'guard-bundler', '~> 1.0.0'
-  gem 'guard-rspec',   '~> 3.0.2'
-  gem 'guard-rubocop', '~> 0.2.0'
-  gem 'guard-mutant',  '~> 0.0.1'
+  gem 'guard',         '~> 2.2.4'
+  gem 'guard-bundler', '~> 2.0.0'
+  gem 'guard-rspec',   '~> 4.0.4'
+  gem 'guard-rubocop', '~> 1.0.0'
 
   # file system change event handling
-  gem 'listen',     '~> 1.3.0'
+  gem 'listen',     '~> 2.2.0'
   gem 'rb-fchange', '~> 0.0.6', require: false
   gem 'rb-fsevent', '~> 0.9.3', require: false
   gem 'rb-inotify', '~> 0.9.0', require: false
@@ -30,18 +33,27 @@ group :guard do
 end
 
 group :metrics do
-  gem 'coveralls', '~> 0.6.7'
+  gem 'coveralls', '~> 0.7.0'
   gem 'flay',      '~> 2.4.0'
-  gem 'flog',      '~> 4.1.1'
+  gem 'flog',      '~> 4.2.0'
   gem 'reek',      '~> 1.3.2'
-  gem 'rubocop',   '~> 0.12.0'
-  gem 'simplecov', '~> 0.7.1'
+  gem 'rubocop',   '~> 0.15.0'
+  gem 'simplecov', '~> 0.8.2'
   gem 'yardstick', '~> 0.9.7', git: 'https://github.com/dkubb/yardstick.git'
 
   platforms :ruby_19, :ruby_20 do
-    gem 'mutant', git: 'https://github.com/mbj/mutant.git'
+    gem 'mutant',          '~> 0.3.0.rc3', git: 'https://github.com/mbj/mutant.git'
+    gem 'unparser',        '~> 0.1.5',     git: 'https://github.com/mbj/unparser.git'
     gem 'yard-spellcheck', '~> 0.1.5'
   end
+
+  platform :rbx do
+    gem 'json',               '~> 1.8.1'
+    gem 'racc',               '~> 1.4.10'
+    gem 'rubysl-logger',      '~> 2.0.0'
+    gem 'rubysl-open-uri',    '~> 2.0.0'
+    gem 'rubysl-prettyprint', '~> 2.0.2'
+  end
 end
 
 group :benchmarks do

data/README.md

@@ -1,7 +1,20 @@
 # promise.rb [![Build Status](https://travis-ci.org/lgierth/promise.rb.png?branch=master)](https://travis-ci.org/lgierth/promise.rb) [![Code Climate](https://codeclimate.com/github/lgierth/promise.rb.png)](https://codeclimate.com/github/lgierth/promise.rb) [![Coverage Status](https://coveralls.io/repos/lgierth/promise.rb/badge.png?branch=master)](https://coveralls.io/r/lgierth/promise.rb?branch=master)
 
 Ruby implementation of the [Promises/A+ spec](http://promisesaplus.com/).
-100% mutation coverage, tested on 1.9, 2.0, Rubinius, and JRuby.
+100% [mutation coverage](https://github.com/mbj/mutant), tested on 1.9, 2.0, Rubinius, and JRuby.
+
+Similar projects:
+
+- [concurrent-ruby](https://github.com/jdantonio/concurrent-ruby/blob/master/md/promise.md), Promises/A(+) implementation, thread based
+- [promise](https://github.com/bhuga/promising-future), a.k.a. promising-future, classic promises and futures, thread based
+- [celluloid-promise](https://github.com/cotag/celluloid-promise), inspired by Q, backed by a Celluloid actor
+- [em-promise](https://github.com/cotag/em-promise), inspired by Q, backed by an EventMachine reactor
+- [futuristic](https://github.com/seanlilmateus/futuristic), MacRuby bindings for Grand Central Dispatch
+- [methodmissing/promise](https://github.com/methodmissing/promise), thread based, abandoned
+
+## Todo
+
+- test with https://gist.github.com/joeljackson/5722487
 
 ## Installation
 
@@ -19,19 +32,11 @@ Or install it yourself as:
 
 ## Usage
 
-promise.rb doesn't come with a way of scheduling callback dispatch.
+This guide assumes that you are familiar with the [Promises/A+ spec](http://promisesaplus.com/). It's a quick read, though.
 
-```ruby
-require 'promise'
-
-class MyPromise < Promise
-  def defer(callback, arg)
-    callback.dispatch(arg)
-  end
-end
-```
-
-The above scheduling mechanism violates the following section of the spec:
+promise.rb comes with a very primitive way of scheduling callback dispatch. It
+immediately executes the callback, instead of scheduling it for execution
+*after* `Promise#fulfill` or `Promise#reject`, as demanded by the spec:
 
 > onFulfilled or onRejected must not be called until the execution context
 > stack contains only platform code.
@@ -44,8 +49,8 @@ require 'promise'
 require 'eventmachine'
 
 class MyPromise < Promise
-  def defer(callback, arg)
-    EM.next_tick { callback.dispatch(arg) }
+  def defer
+    EM.next_tick { yield }
   end
 end
 ```
@@ -76,10 +81,65 @@ end
 failing_stuff.then(proc { |value| }, proc { |reason| p reason })
 ```
 
-## License
+promise.rb also comes with the utility method `Promise#sync`, which waits for
+the promise to be fulfilled and returns the value, or for it to be rejected and
+re-raises the reason. Using `#sync` requires you to implement `#wait`. You could
+for example cooperatively schedule fibers waiting for different promises:
+
+```ruby
+require 'promise'
+require 'eventmachine'
+
+class MyPromise < Promise
+  def defer
+    EM.next_tick { yield }
+  end
+
+  def wait
+    fiber = Fiber.current
+    resume = proc do |arg|
+      defer { fiber.resume(arg) }
+    end
+
+    self.then(resume, resume)
+    Fiber.yield
+  end
+end
+
+promise = MyPromise.new
+Fiber.new { p promise.sync }.resume
+promise.fulfill
+```
+
+Or have the rejection reason re-raised from `#sync`:
+
+```ruby
+promise = MyPromise.new
+
+Fiber.new do
+  begin
+    promise.sync
+  rescue MyError
+    p $!
+  end
+end.resume
+
+promise.reject(MyError.new)
+```
+
+Very simple progress callbacks, as per Promises/A, are supported as well. They have been dropped in A+, but I found them to be a useful mechanism - if kept simple. Callback dispatch happens immediately in the call to `#progress`, in the order of definition via `#on_progress`. Also note that `#on_progress` does not return a new promise for chaining - the progress mechanism is meant to be very lightweight, and ignores many of the constraints and guarantees of `then`.
+
+```ruby
+promise = MyPromise.new
+promise.on_progress { |status| p status }
+promise.progress(:anything)
+```
+
+## Unlicense
 
-Hatetepe is licensed under the [MIT License](http://opensource.org/licenses/MIT).
-See LICENSE.txt for details.
+promise.rb is free and unencumbered public domain software. For more
+information, see [unlicense.org](http://unlicense.org/) or the accompanying
+UNLICENSE file.
 
 ## Contributing
 

data/config/flay.yml

@@ -1,3 +1,3 @@
 ---
-threshold: 14
+threshold: 10
 total_score: 49

data/config/rubocop.yml

@@ -24,15 +24,6 @@ CollectionMethods:
     find:     'detect'
     find_all: 'select'
 
-# Do not force public/protected/private keyword to be indented at the same
-# level as the def keyword. My personal preference is to outdent these keywords
-# because I think when scanning code it makes it easier to identify the
-# sections of code and visually separate them. When the keyword is at the same
-# level I think it sort of blends in with the def keywords and makes it harder
-# to scan the code and see where the sections are.
-AccessControl:
-  Enabled: false
-
 # Limit line length
 LineLength:
   Max: 79

data/lib/promise.rb

@@ -6,6 +6,8 @@ require 'promise/callback'
 require 'promise/progress'
 
 class Promise
+  include Promise::Progress
+
   attr_reader :value, :reason
 
   def initialize
@@ -27,7 +29,7 @@ class Promise
   end
 
   def then(on_fulfill = nil, on_reject = nil, &block)
-    on_fulfill = block if block
+    on_fulfill ||= block
     next_promise = add_callbacks(on_fulfill, on_reject)
 
     maybe_dispatch(@on_fulfill.last, @on_reject.last)
@@ -47,7 +49,7 @@ class Promise
     end
   end
 
-  def reject(reason = nil)
+  def reject(reason = RuntimeError)
     dispatch(@on_reject, reason) do
       @state = :rejected
       @reason = reason

data/lib/promise/progress.rb

@@ -2,18 +2,15 @@
 
 class Promise
   module Progress
-    def initialize
-      super
-      @on_progress = []
-    end
-
     def on_progress(&block)
-      @on_progress << block
+      @on_progress ||= []
+      @on_progress << block if block_given?
+      @on_progress
     end
 
     def progress(status)
       if pending?
-        @on_progress.each { |block| block.call(status) }
+        on_progress.each { |block| block.call(status) }
       end
     end
   end

data/lib/promise/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 class Promise
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/promise.rb.gemspec

@@ -10,9 +10,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Lars Gierth']
   spec.email         = ['lars.gierth@gmail.com']
   spec.description   = %q{Promises/A+ for Ruby}
-  spec.summary       = %q{Promises/A+ for Ruby}
+  spec.summary       = %q{Ruby implementation of the Promises/A+ spec}
   spec.homepage      = 'https://github.com/lgierth/promise'
-  spec.license       = 'MIT'
+  spec.license       = 'Public Domain'
 
   spec.files         = `git ls-files`.split($/)
   spec.test_files    = spec.files.grep(%r{^spec/})

data/spec/promise_spec.rb

@@ -117,6 +117,14 @@ describe Promise do
       subject.fulfill(value)
       expect(result).to eq(value)
     end
+
+    it 'takes precedence over block' do
+      result = nil
+      subject.then(proc { |_| result = :arg }) { |_| result = :block }
+
+      subject.fulfill(value)
+      expect(result).to be(:arg)
+    end
   end
 
   describe '3.2.3 on_reject' do
@@ -220,7 +228,7 @@ describe Promise do
     end
 
     it 'rejects promise2 with error raised by on_fulfill' do
-      promise2 = subject.then(proc { |_| raise error })
+      promise2 = subject.then(proc { |_| fail(error) })
       expect { subject.fulfill(value) }.to raise_error(error)
 
       expect(promise2).to be_rejected
@@ -228,7 +236,7 @@ describe Promise do
     end
 
     it 'rejects promise2 with error raised by on_reject' do
-      promise2 = subject.then(nil, proc { |_| raise error })
+      promise2 = subject.then(nil, proc { |_| fail(error) })
       expect { subject.reject(reason) }.to raise_error(error)
 
       expect(promise2).to be_rejected
@@ -305,11 +313,6 @@ describe Promise do
   end
 
   describe '#progress' do
-    let(:klass) do
-      Class.new(Promise) { include Promise::Progress }
-    end
-    let(:subject) { klass.new }
-
     let(:status) { double('status') }
 
     it 'calls the callbacks in the order of calls to #on_progress' do
@@ -355,7 +358,7 @@ describe Promise do
 
     it 'does not require a reason' do
       subject.reject
-      expect(subject.reason).to be(nil)
+      expect(subject.reason).to be(RuntimeError)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: promise.rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-07 00:00:00.000000000 Z
+date: 2013-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -37,11 +37,12 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- CHANGELOG.md
 - Gemfile
 - Gemfile.devtools
-- LICENSE
 - README.md
 - Rakefile
+- UNLICENSE
 - config/devtools.yml
 - config/flay.yml
 - config/flog.yml
@@ -58,7 +59,7 @@ files:
 - spec/spec_helper.rb
 homepage: https://github.com/lgierth/promise
 licenses:
-- MIT
+- Public Domain
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -80,7 +81,7 @@ rubyforge_project:
 rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Promises/A+ for Ruby
+summary: Ruby implementation of the Promises/A+ spec
 test_files:
 - spec/promise_spec.rb
 - spec/spec_helper.rb