functional-ruby 0.5.0 → 0.6.0

data/md/promise.md

@@ -0,0 +1,220 @@
+# Promises, promises...
+
+> A promise represents the eventual value returned from the single completion of an operation.
+
+Promises have become an extremely important async technique in JavaScript. A promise is an
+an operation that is performed asynchronously and is guaranteed to either succeed and return
+a value or fail with a reason. What makes promises distinctly different from futures is
+that promises can be chained such that the result of onw promise is passed to zero or
+more children. Order of execution is guaranteed based on the order the promises are
+created and parent promises are guaranteed to be complete before their children. Once a
+promise has been fulfilled or rejected the corresponding value/reason can be retrieved.
+
+## The shoulders of giants
+
+Inspiration for this implementation came from the CommonJS
+[Promises/A](http://wiki.commonjs.org/wiki/Promises/A) proposal and the
+[Promises/A+](http://promises-aplus.github.io/promises-spec/) specification.
+This implementation is specifically tailored to the idioms and practices of
+Ruby. It is not 100% compliant with either of the aforementioned specifications.
+
+## Usage
+
+
+Start by requiring promises
+
+```ruby
+require 'functional/promise'
+```
+
+Then create one
+
+```ruby
+p = Promise.new("Jerry", "D'Antonio") do |first, last|
+      "#{last}, #{first}"
+    end
+
+# -or-
+
+p = promise(10){|x| x * x * x }
+```
+
+Promises can be chained using the `then` method. The `then` method
+accepts a block but no arguments. The result of the each promise is
+passed as the block argument to chained promises
+
+
+```ruby
+p = promise(10){|x| x * 2}.then{|result| result - 10 }
+```
+
+And so on, and so on, and so on...
+
+```ruby
+p = promise(10){|x| x * 2}.
+    then{|result| result - 10 }.
+    then{|result| result * 3 }.
+    then{|result| result % 5 }
+```
+
+Promises are executed asynchronously so a newly-created promise
+*should* always be in the pending state
+
+
+```ruby
+p = promise{ "Hello, world!" }
+p.state   #=> :pending
+p.pending? #=> true
+```
+
+Wait a little bit, and the promise will resolve and provide a value
+
+
+```ruby
+p = promise{ "Hello, world!" }
+sleep(0.1)
+
+p.state      #=> :fulfilled
+p.fulfilled? #=> true
+
+p.value      #=> "Hello, world!"
+
+```
+
+If an exception occurs, the promise will be rejected and will provide
+a reason for the rejection
+
+
+```ruby
+p = promise{ raise StandardError.new("Here comes the Boom!") }
+sleep(0.1)
+
+p.state     #=> :rejected
+p.rejected? #=> true
+
+p.reason=>  #=> "#<StandardError: Here comes the Boom!>"
+```
+
+### Rejection
+
+Much like the economy, rejection exhibits a trickle-down effect. When
+a promise is rejected all its children will be rejected
+
+```ruby
+p = [ promise{ Thread.pass; raise StandardError } ]
+
+10.times{|i| p << p.first.then{ i } }
+sleep(0.1)
+
+p.length      #=> 11
+p.first.state #=> :rejected
+p.last.state  #=> :rejected
+```
+
+Once a promise is rejected it will not accept any children. Calls
+to `then` will continually return `self`
+
+```ruby
+p = promise{ raise StandardError }
+sleep(0.1)
+
+p.object_id        #=> 32960556
+p.then{}.object_id #=> 32960556
+p.then{}.object_id #=> 32960556
+```
+
+### Error Handling
+
+Promises support error handling callbacks is a style mimicing Ruby's
+own exception handling mechanism, namely `rescue`
+
+
+```ruby
+promise{ "dangerous operation..." }.rescue{|ex| puts "Bam!" }
+
+# -or- (for the Java/C# crowd)
+promise{ "dangerous operation..." }.catch{|ex| puts "Boom!" }
+
+# -or- (for the hipsters)
+promise{ "dangerous operation..." }.on_error{|ex| puts "Pow!" }
+```
+
+As with Ruby's `rescue` mechanism, a promise's `rescue` method can
+accept an optional Exception class argument (defaults to `Exception`
+when not specified)
+
+
+```ruby
+promise{ "dangerous operation..." }.rescue(ArgumentError){|ex| puts "Bam!" }
+```
+
+Calls to `rescue` can also be chained
+
+```ruby
+promise{ "dangerous operation..." }.
+  rescue(ArgumentError){|ex| puts "Bam!" }.
+  rescue(NoMethodError){|ex| puts "Boom!" }.
+  rescue(StandardError){|ex| puts "Pow!" }
+```
+
+When there are multiple `rescue` handlers the first one to match the thrown
+exception will be triggered
+
+```ruby
+promise{ raise NoMethodError }.
+  rescue(ArgumentError){|ex| puts "Bam!" }.
+  rescue(NoMethodError){|ex| puts "Boom!" }.
+  rescue(StandardError){|ex| puts "Pow!" }
+
+sleep(0.1)
+
+#=> Boom!
+```
+
+Trickle-down rejection also applies to rescue handlers. When a promise is rejected,
+for any reason, its rescue handlers will be triggered. Rejection of the parent counts.
+
+```ruby
+promise{ Thread.pass; raise StandardError }.
+  then{ true }.rescue{ puts 'Boom!' }.
+  then{ true }.rescue{ puts 'Boom!' }.
+  then{ true }.rescue{ puts 'Boom!' }.
+  then{ true }.rescue{ puts 'Boom!' }.
+  then{ true }.rescue{ puts 'Boom!' }
+sleep(0.1)
+
+#=> Boom!
+#=> Boom!
+#=> Boom!
+#=> Boom!
+#=> Boom!
+```
+
+## Copyright
+
+*Functional Ruby* is Copyright &copy; 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
+It is free software and may be redistributed under the terms specified in the LICENSE file.
+
+## License
+
+Released under the MIT license.
+
+http://www.opensource.org/licenses/mit-license.php  
+
+> 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/md/utilities.md

@@ -0,0 +1,53 @@
+# Utility Functions
+
+Convenience functions are not imported by default. They need a separate `require` statement:
+
+```ruby
+require 'functional/utilities'
+```
+
+This gives you access to a few constants and functions:
+
+```ruby
+Infinity #=> Infinity
+NaN #=> NaN
+
+repl? #=> true when called under irb, pry, bundle console, or rails console
+
+safe(1, 2){|a, b| a + b} #=> 3
+safe{ eval 'puts "Hello World!"' } #=> SecurityError: Insecure operation
+
+pp_s [1,2,3,4] #=> "[1, 2, 3, 4]\n" props to Rha7
+
+delta(-1, 1) #=> 2
+delta({count: -1}, {count: 1}){|item| item[:count]} #=> 2
+```
+
+## Copyright
+
+*Functional Ruby* is Copyright © 2013 [Jerry D'Antonio](https://twitter.com/jerrydantonio).
+It is free software and may be redistributed under the terms specified in the LICENSE file.
+
+## License
+
+Released under the MIT license.
+
+http://www.opensource.org/licenses/mit-license.php  
+
+> 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/spec/functional/agent_spec.rb

@@ -0,0 +1,405 @@
+require 'spec_helper'
+
+module Functional
+
+  describe Agent do
+
+    subject { Agent.new(0) }
+
+    let(:observer) do
+      Class.new do
+        attr_reader :value
+        define_method(:update) do |time, value|
+          @value = value
+        end
+      end.new
+    end
+
+    before(:each) do
+      $GLOBAL_THREAD_POOL = CachedThreadPool.new
+    end
+
+    context '#initialize' do
+
+      it 'sets the value to the given initial state' do
+        Agent.new(10).value.should eq 10
+      end
+
+      it 'sets the timeout to the given value' do
+        Agent.new(0, 5).timeout.should eq 5
+      end
+
+      it 'sets the timeout to the default when nil' do
+        Agent.new(0).timeout.should eq Agent::TIMEOUT
+      end
+
+      it 'sets the length to zero' do
+        Agent.new(10).length.should eq 0
+      end
+
+      it 'spawns the worker thread' do
+        $GLOBAL_THREAD_POOL.should_receive(:post).once.with(any_args())
+        Agent.new(0)
+      end
+    end
+
+    context '#rescue' do
+
+      it 'returns self when a block is given' do
+        a1 = subject
+        a2 = a1.rescue{}
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'returns self when no block is given' do
+        a1 = subject
+        a2 = a1.rescue
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'accepts an exception class as the first parameter' do
+        lambda {
+          subject.rescue(StandardError){}
+        }.should_not raise_error(ArgumentError)
+      end
+
+      it 'ignores rescuers without a block' do
+        subject.rescue
+        subject.instance_variable_get(:@rescuers).should be_empty
+      end
+    end
+
+    context '#validate' do
+
+      it 'returns self when a block is given' do
+        a1 = subject
+        a2 = a1.validate{}
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'returns self when no block is given' do
+        a1 = subject
+        a2 = a1.validate
+        a1.object_id.should eq a2.object_id
+      end
+
+      it 'ignores validators without a block' do
+        subject.validate
+        subject.instance_variable_get(:@validator).should be_nil
+      end
+    end
+
+    context '#post' do
+      
+      it 'adds the given block to the queue' do
+        before = subject.length
+        subject.post{ nil }
+        subject.post{ nil }
+        subject.length.should eq before+2
+      end
+
+      it 'does not add to the queue when no block is given' do
+        before = subject.length
+        subject.post
+        subject.post{ nil }
+        subject.length.should eq before+1
+      end
+    end
+
+    context '#length' do
+
+      it 'should be zero for a new agent' do
+        subject.length.should eq 0
+      end
+
+      it 'should increase by one for each #post' do
+        subject.post{ sleep }
+        subject.post{ sleep }
+        subject.post{ sleep }
+        subject.length.should eq 3
+      end
+
+      it 'should decrease by one each time a handler is run' do
+        subject.post{ nil }
+        subject.post{ sleep }
+        subject.post{ sleep }
+        sleep(0.1)
+        subject.length.should eq 1
+      end
+    end
+
+    context 'fulfillment' do
+
+      it 'process each block in the queue' do
+        @expected = []
+        subject.post{ @expected << 1 }
+        subject.post{ @expected << 2 }
+        subject.post{ @expected << 3 }
+        sleep(0.1)
+        @expected.should eq [1,2,3]
+      end
+
+      it 'passes the current value to the handler' do
+        @expected = nil
+        Agent.new(10).post{|i| @expected = i }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'sets the value to the handler return value on success' do
+        subject.post{ 100 }
+        sleep(0.1)
+        subject.value.should eq 100
+      end
+
+      it 'rejects the handler after timeout reached' do
+        agent = Agent.new(0, 0.1)
+        agent.post{ sleep(1); 10 }
+        agent.value.should eq 0
+      end
+    end
+
+    context 'validation' do
+
+      it 'processes the validator when present' do
+        @expected = nil
+        subject.validate{ @expected = 10; true }
+        subject.post{ nil }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'passes the new value to the validator' do
+        @expected = nil
+        subject.validate{|v| @expected = v; true }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'sets the new value when the validator returns true' do
+        agent = Agent.new(0).validate{ true }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 10
+      end
+
+      it 'does not change the value when the validator returns false' do
+        agent = Agent.new(0).validate{ false }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 0
+      end
+
+      it 'does not change the value when the validator raises an exception' do
+        agent = Agent.new(0).validate{ raise StandardError }
+        agent.post{ 10 }
+        sleep(0.1)
+        agent.value.should eq 0
+      end
+    end
+
+    context 'rejection' do
+
+      it 'calls the first exception block with a matching class' do
+        @expected = nil
+        subject.
+          rescue(StandardError){|ex| @expected = 1 }.
+          rescue(StandardError){|ex| @expected = 2 }.
+          rescue(StandardError){|ex| @expected = 3 }
+        subject.post{ raise StandardError }
+          sleep(0.1)
+        @expected.should eq 1
+      end
+
+      it 'matches all with a rescue with no class given' do
+        @expected = nil
+        subject.
+          rescue(LoadError){|ex| @expected = 1 }.
+          rescue{|ex| @expected = 2 }.
+          rescue(StandardError){|ex| @expected = 3 }
+        subject.post{ raise NoMethodError }
+        sleep(0.1)
+        @expected.should eq 2
+      end
+
+      it 'searches associated rescue handlers in order' do
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise ArgumentError }
+        sleep(0.1)
+        @expected.should eq 1
+
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise LoadError }
+        sleep(0.1)
+        @expected.should eq 2
+
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = 1 }.
+          rescue(LoadError){|ex| @expected = 2 }.
+          rescue(Exception){|ex| @expected = 3 }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should eq 3
+      end
+
+      it 'passes the exception object to the matched block' do
+        @expected = nil
+        subject.
+          rescue(ArgumentError){|ex| @expected = ex }.
+          rescue(LoadError){|ex| @expected = ex }.
+          rescue(Exception){|ex| @expected = ex }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_a(StandardError)
+      end
+
+      it 'ignores rescuers without a block' do
+        @expected = nil
+        subject.
+          rescue(StandardError).
+          rescue(StandardError){|ex| @expected = ex }.
+          rescue(Exception){|ex| @expected = ex }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_a(StandardError)
+      end
+
+      it 'supresses the exception if no rescue matches' do
+        lambda {
+          subject.
+            rescue(ArgumentError){|ex| @expected = ex }.
+            rescue(StandardError){|ex| @expected = ex }.
+            rescue(Exception){|ex| @expected = ex }
+          subject.post{ raise StandardError }
+          sleep(0.1)
+        }.should_not raise_error
+      end
+
+      it 'supresses exceptions thrown from rescue handlers' do
+        lambda {
+          subject.rescue(Exception){ raise StandardError }
+          subject.post{ raise ArgumentError }
+          sleep(0.1)
+        }.should_not raise_error(StandardError)
+      end
+    end
+
+    context 'observation' do
+
+      it 'notifies all observers when the value changes' do
+        agent = Agent.new(0)
+        agent.add_observer(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should eq 10
+      end
+
+      it 'does not notify observers when validation fails' do
+        agent = Agent.new(0)
+        agent.validate{ false }
+        agent.add_observer(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should be_nil
+      end
+
+      it 'does not notify observers when the handler raises an exception' do
+        agent = Agent.new(0)
+        agent.add_observer(observer)
+        agent.post{ raise StandardError }
+        sleep(0.1)
+        observer.value.should be_nil
+      end
+    end
+
+    context 'aliases' do
+
+      it 'aliases #deref for #value' do
+        Agent.new(10).deref.should eq 10
+      end
+
+      it 'aliases #validates for :validate' do
+        @expected = nil
+        subject.validates{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+        
+      it 'aliases #validate_with for :validate' do
+        @expected = nil
+        subject.validate_with{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'aliases #validates_with for :validate' do
+        @expected = nil
+        subject.validates_with{|v| @expected = v }
+        subject.post{ 10 }
+        sleep(0.1)
+        @expected.should eq 10
+      end
+
+      it 'aliases #catch for #rescue' do
+        @expected = nil
+        subject.catch{ @expected = true }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_true
+      end
+
+      it 'aliases #on_error for #rescue' do
+        @expected = nil
+        subject.on_error{ @expected = true }
+        subject.post{ raise StandardError }
+        sleep(0.1)
+        @expected.should be_true
+      end
+
+      it 'aliases #add_watch for #add_observer' do
+        agent = Agent.new(0)
+        agent.add_watch(observer)
+        agent.post{ 10 }
+        sleep(0.1)
+        observer.value.should eq 10
+      end
+
+      it 'aliases #<< for Agent#post' do
+        subject << proc{ 100 }
+        sleep(0.1)
+        subject.value.should eq 100
+
+        subject << lambda{ 100 }
+        sleep(0.1)
+        subject.value.should eq 100
+      end
+
+      it 'aliases Kernel#agent for Agent.new' do
+        agent(10).should be_a(Agent)
+      end
+
+      it 'aliases Kernel#deref for #deref' do
+        deref(Agent.new(10)).should eq 10
+        deref(Agent.new(10), 10).should eq 10
+      end
+
+      it 'aliases Kernel:post for Agent#post' do
+        post(subject){ 100 }
+        sleep(0.1)
+        subject.value.should eq 100
+      end
+    end
+  end
+end