functional-ruby 0.6.0 → 0.7.0

data/md/future.md

@@ -1,32 +0,0 @@
-# We're sending you back to the future!
-
-TBD...
-
-## 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/md/obligation.md

@@ -1,32 +0,0 @@
-# Obligation
-
-TBD...
-
-## 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/md/promise.md

@@ -1,220 +0,0 @@
-# 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/spec/functional/agent_spec.rb

@@ -1,405 +0,0 @@
-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