functional-ruby 0.5.0 → 0.6.0

data/lib/functional/future.rb

@@ -0,0 +1,42 @@
+require 'thread'
+
+require 'functional/obligation'
+require 'functional/global_thread_pool'
+
+module Functional
+
+  class Future
+    include Obligation
+    behavior(:future)
+
+    def initialize(*args)
+
+      unless block_given?
+        @state = :fulfilled
+      else
+        @value = nil
+        @state = :pending
+        $GLOBAL_THREAD_POOL.post do
+          semaphore.synchronize do
+            Thread.pass
+            begin
+              @value = yield(*args)
+              @state = :fulfilled
+            rescue Exception => ex
+              @state = :rejected
+              @reason = ex
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+module Kernel
+
+  def future(*args, &block)
+    return Functional::Future.new(*args, &block)
+  end
+  module_function :future
+end

data/lib/functional/global_thread_pool.rb

@@ -0,0 +1,3 @@
+require 'functional/cached_thread_pool'
+
+$GLOBAL_THREAD_POOL ||= Functional::CachedThreadPool.new

data/lib/functional/obligation.rb

@@ -0,0 +1,121 @@
+require 'thread'
+require 'timeout'
+
+require 'functional/behavior'
+
+behavior_info(:future,
+              state: 0,
+              value: -1,
+              reason: 0,
+              pending?: 0,
+              fulfilled?: 0,
+              rejected?: 0)
+
+behavior_info(:promise,
+              state: 0,
+              value: -1,
+              reason: 0,
+              pending?: 0,
+              fulfilled?: 0,
+              rejected?: 0,
+              then: 0,
+              rescue: -1)
+
+module Functional
+
+  module Obligation
+
+    attr_reader :state
+    attr_reader :reason
+
+    # Has the obligation been fulfilled?
+    # @return [Boolean]
+    def fulfilled?() return(@state == :fulfilled); end
+    alias_method :realized?, :fulfilled?
+
+    # Is obligation completion still pending?
+    # @return [Boolean]
+    def pending?() return(!(fulfilled? || rejected?)); end
+
+    def value(timeout = nil)
+      if !pending? || timeout == 0
+        return @value
+      elsif timeout.nil?
+        return semaphore.synchronize { @value }
+      else
+        begin
+          return Timeout::timeout(timeout.to_f) {
+            semaphore.synchronize { @value }
+          }
+        rescue Timeout::Error => ex
+          return nil
+        end
+      end
+    end
+    alias_method :deref, :value
+
+    # Has the promise been rejected?
+    # @return [Boolean]
+    def rejected?() return(@state == :rejected); end
+
+    protected
+
+    def semaphore
+      @semaphore ||= Mutex.new
+    end
+  end
+end
+
+module Kernel
+
+  def deref(obligation, timeout = nil)
+    if obligation.respond_to?(:deref)
+      return obligation.deref(timeout)
+    elsif obligation.respond_to?(:value)
+      return obligation.deref(timeout)
+    else
+      return nil
+    end
+  end
+  module_function :deref
+
+  def pending?(obligation)
+    if obligation.respond_to?(:pending?)
+      return obligation.pending?
+    else
+      return false
+    end
+  end
+  module_function :pending?
+
+  def fulfilled?(obligation)
+    if obligation.respond_to?(:fulfilled?)
+      return obligation.fulfilled?
+    elsif obligation.respond_to?(:realized?)
+      return obligation.realized?
+    else
+      return false
+    end
+  end
+  module_function :fulfilled?
+
+  def realized?(obligation)
+    if obligation.respond_to?(:realized?)
+      return obligation.realized?
+    elsif obligation.respond_to?(:fulfilled?)
+      return obligation.fulfilled?
+    else
+      return false
+    end
+  end
+  module_function :realized?
+
+  def rejected?(obligation)
+    if obligation.respond_to?(:rejected?)
+      return obligation.rejected?
+    else
+      return false
+    end
+  end
+  module_function :rejected?
+end

data/lib/functional/promise.rb

@@ -0,0 +1,194 @@
+require 'thread'
+
+require 'functional/obligation'
+require 'functional/global_thread_pool'
+
+module Functional
+
+  class Promise
+    include Obligation
+    behavior(:future)
+    behavior(:promise)
+
+    # Creates a new promise object. "A promise represents the eventual
+    # value returned from the single completion of an operation."
+    # Promises can be chained in a tree structure where each promise
+    # has zero or more children. Promises are resolved asynchronously
+    # in the order they are added to the tree. Parents are guaranteed
+    # to be resolved before their children. The result of each promise
+    # is passed to each of its children upon resolution. When
+    # a promise is rejected all its children will be summarily rejected.
+    # A promise that is neither resolved or rejected is pending.
+    #
+    # @param args [Array] zero or more arguments for the block
+    # @param block [Proc] the block to call when attempting fulfillment
+    #
+    # @see http://wiki.commonjs.org/wiki/Promises/A
+    # @see http://promises-aplus.github.io/promises-spec/
+    def initialize(*args, &block)
+      if args.first.is_a?(Promise)
+        @parent = args.first
+      else
+        @parent = nil
+        @chain = [self]
+      end
+
+      @mutex = Mutex.new
+      @handler = block || Proc.new{|result| result }
+      @state = :pending
+      @value = nil
+      @reason = nil
+      @children = []
+      @rescuers = []
+
+      realize(*args) if root?
+    end
+
+    # Create a new child Promise. The block argument for the child will
+    # be the result of fulfilling its parent. If the child will
+    # immediately be rejected if the parent has already been rejected.
+    #
+    # @param block [Proc] the block to call when attempting fulfillment
+    #
+    # @return [Promise] the new promise
+    def then(&block)
+      child = @mutex.synchronize do
+        block = Proc.new{|result| result } unless block_given?
+        @children << Promise.new(self, &block)
+        @children.last.on_reject(@reason) if rejected?
+        push(@children.last)
+        @children.last
+      end
+      return child
+    end
+
+    # Add a rescue handler to be run if the promise is rejected (via raised
+    # exception). Multiple rescue handlers may be added to a Promise.
+    # Rescue blocks will be checked in order and the first one with a
+    # matching Exception class will be processed. The block argument
+    # will be the exception that caused the rejection.
+    #
+    # @param clazz [Class] The class of exception to rescue
+    # @param block [Proc] the block to call if the rescue is matched
+    #
+    # @return [self] so that additional chaining can occur
+    def rescue(clazz = Exception, &block)
+      @mutex.synchronize do
+        @rescuers << Rescuer.new(clazz, block) if block_given?
+      end
+      return self
+    end
+    alias_method :catch, :rescue
+    alias_method :on_error, :rescue
+
+    protected
+
+    attr_reader :parent
+    attr_reader :handler
+    attr_reader :rescuers
+
+    # @private
+    Rescuer = Struct.new(:clazz, :block)
+
+    # @private
+    def root # :nodoc:
+      current = self
+      current = current.parent until current.root?
+      return current
+    end
+
+    # @private
+    def root? # :nodoc:
+      @parent.nil?
+    end
+
+    # @private
+    def push(promise) # :nodoc:
+      if root?
+        @chain << promise
+      else
+        @parent.push(promise)
+      end
+    end
+
+    # @private
+    def on_fulfill(value) # :nodoc:
+      @mutex.synchronize do
+        if pending?
+          @value = @handler.call(value)
+          @state = :fulfilled
+          @reason = nil
+        end
+      end
+      return @value
+    end
+
+    # @private
+    def on_reject(reason) # :nodoc:
+      @mutex.synchronize do
+        if pending?
+          @state = :rejected
+          @reason = reason
+          self.try_rescue(reason)
+          @value = nil
+        end
+        @children.each{|child| child.on_reject(reason) }
+      end
+    end
+
+    # @private
+    def try_rescue(ex) # :nodoc:
+      rescuer = @rescuers.find{|r| ex.is_a?(r.clazz) }
+      rescuer.block.call(ex) if rescuer
+    rescue Exception => e
+      # supress
+    end
+
+    # @private
+    def realize(*args) # :nodoc:
+      $GLOBAL_THREAD_POOL.post(@chain, @mutex, args) do |chain, mutex, args|
+        result = args.length == 1 ? args.first : args
+        index = 0
+        loop do
+          Thread.pass
+          current = mutex.synchronize{ chain[index] }
+          unless current.rejected?
+            current.semaphore.synchronize do
+              begin
+                result = current.on_fulfill(result)
+              rescue Exception => ex
+                current.on_reject(ex)
+              end
+            end
+          end
+          index += 1
+          sleep while index >= chain.length
+        end
+      end
+    end
+  end
+end
+
+module Kernel
+
+  # Creates a new promise object. "A promise represents the eventual
+  # value returned from the single completion of an operation."
+  # Promises can be chained in a tree structure where each promise
+  # has zero or more children. Promises are resolved asynchronously
+  # in the order they are added to the tree. Parents are guaranteed
+  # to be resolved before their children. The result of each promise
+  # is passes to each of its children when the child resolves. When
+  # a promise is rejected all its children will be summarily rejected.
+  # A promise added to a rejected promise will immediately be rejected.
+  # A promise that is neither resolved or rejected is pending.
+  #
+  # @param args [Array] zero or more arguments for the block
+  # @param block [Proc] the block to call when attempting fulfillment
+  #
+  # @see Promise
+  # @see http://wiki.commonjs.org/wiki/Promises/A
+  def promise(*args, &block)
+    return Functional::Promise.new(*args, &block)
+  end
+  module_function :promise
+end

data/lib/functional/thread_pool.rb

@@ -0,0 +1,61 @@
+require 'functional/behavior'
+require 'functional/event'
+
+behavior_info(:thread_pool,
+              running?: 0,
+              shutdown?: 0,
+              killed?: 0,
+              shutdown: 0,
+              kill: 0,
+              size: 0,
+              wait_for_termination: -1,
+              post: -1,
+              :<< => 1,
+              status: 0)
+
+behavior_info(:global_thread_pool,
+              post: -1,
+              :<< => 1)
+
+module Functional
+
+  class ThreadPool
+
+    def initialize
+      @status = :running
+      @queue = Queue.new
+      @termination = Event.new
+      @pool = []
+    end
+
+    def running?
+      return @status == :running
+    end
+
+    def shutdown?
+      return ! running?
+    end
+
+    def killed?
+      return @status == :killed
+    end
+
+    def shutdown
+      @pool.size.times{ @queue << :stop }
+      @status = :shuttingdown
+    end
+
+    def wait_for_termination(timeout = nil)
+      if shutdown? || killed?
+        return true
+      else
+        return @termination.wait(timeout)
+      end
+    end
+
+    def <<(block)
+      self.post(&block)
+      return self
+    end
+  end
+end

data/lib/functional/utilities.rb

@@ -0,0 +1,114 @@
+require 'pp'
+require 'stringio'
+require 'erb'
+
+Infinity = 1/0.0 unless defined?(Infinity)
+NaN = 0/0.0 unless defined?(NaN)
+
+module Kernel
+
+  # Compute the difference (delta) between two values.
+  #
+  # When a block is given the block will be applied to both arguments.
+  # Using a block in this way allows computation against a specific field
+  # in a data set of hashes or objects.
+  #
+  # @yield iterates over each element in the data set
+  # @yieldparam item each element in the data set
+  #
+  # @param [Object] v1 the first value
+  # @param [Object] v2 the second value
+  #
+  # @return [Float] positive value representing the difference
+  #   between the two parameters
+  def delta(v1, v2)
+    if block_given?
+      v1 = yield(v1)
+      v2 = yield(v2)
+    end
+    return (v1 - v2).abs
+  end
+  module_function :delta
+
+  # Sandbox the given operation at a high $SAFE level.
+  #
+  # @param args [Array] zero or more arguments to pass to the block
+  # @param block [Proc] the block to isolate
+  #
+  # @return [Object] the result of the block operation
+  def safe(*args)
+    raise ArgumentError.new('no block given') unless block_given?
+    result = nil
+    t = Thread.new do
+      $SAFE = 3
+      result = yield(*args)
+    end
+    t.join
+    return result
+  end
+  module_function :safe
+
+  # Open a file, read it, close the file, and return its contents.
+  #
+  # @param file [String] path to and name of the file to open
+  # @return [String] file contents
+  #
+  # @see slurpee
+  def slurp(file)
+    File.open(file, 'rb') {|f| f.read }
+  end
+  module_function :slurp
+
+  # Open a file, read it, close the file, run the contents through the
+  # ERB parser, and return updated contents.
+  #
+  # @param file [String] path to and name of the file to open
+  # @param safe_level [Integer] when not nil, ERB will $SAFE set to this
+  # @return [String] file contents
+  #
+  # @see slurpee
+  def slurpee(file, safe_level = nil)
+    ERB.new(slurp(file), safe_level).result
+  end
+  module_function :slurpee
+
+  #############################################################################
+
+  # @private
+  def repl? # :nodoc:
+    return ($0 == 'irb' || $0 == 'pry' || $0 == 'script/rails' || !!($0 =~ /bin\/bundle$/))
+  end
+  module_function :repl?
+
+  # @private
+  def timestamp # :nodoc:
+    return Time.now.getutc.to_i
+  end
+
+  # @private
+  def timer(*args) # :nodoc:
+    t1 = Time.now
+    result = yield(*args)
+    t2 = Time.now
+    return (t2 - t1)
+  end
+  module_function :timer
+
+  # @private
+  def strftimer(seconds) # :nodoc:
+    Time.at(seconds).gmtime.strftime('%R:%S.%L')
+  end
+  module_function :strftimer
+
+  # @private
+  # @see http://rhaseventh.blogspot.com/2008/07/ruby-and-rails-how-to-get-pp-pretty.html
+  def pp_s(*objs) # :nodoc:
+    s = StringIO.new
+    objs.each {|obj|
+      PP.pp(obj, s)
+    }
+    s.rewind
+    s.read
+  end
+  module_function :pp_s
+end

data/lib/functional/version.rb

@@ -1,3 +1,3 @@
 module Functional
-  VERSION = '0.5.0'
+  VERSION = '0.6.0'
 end

data/lib/functional.rb

@@ -0,0 +1 @@
+require 'functional/all'

data/lib/functional_ruby.rb

@@ -0,0 +1 @@
+require 'functional/all'

data/md/behavior.md

@@ -0,0 +1,147 @@
+# For good -behavior(timeoff).
+
+One of Ruby's greatest strengths is [duck typing](http://rubylearning.com/satishtalim/duck_typing.html).
+Usually this is awesome and I'm happy to not have to deal with static typing and the compiler. Usually.
+The problem with duck typing is that is is impossible in Ruby to enforce an interface definition.
+I would never advocate turning Ruby into the cesspool complex object creation that Java has
+unfortunately become, but occasionally it would be nice to make sure a class implements a set of
+required methods. Enter Erlang's [-behavior](http://metajack.im/2008/10/29/custom-behaviors-in-erlang/)
+keyword. Basically, you define a `behavior_info` then drop a `behavior` call within a class.
+Forget to implement a required method and Ruby will let you know. See the examples below for details.
+
+## Usage
+
+The `behavior` functionality is not imported by default. It needs a separate `require` statement:
+
+```ruby
+require 'functional/behavior'
+
+# -or-
+
+require 'functional/behaviour'
+```
+
+### behavior_info
+
+Next, declare a behavior using the `behavior_info` function (this function should sit outside
+of any module/class definition, but will probably work regardless). The first parameter to
+`behavior_info` (or `behaviour_info`) is a symbol name for the behavior. The remaining parameter
+is a hash of function names and their arity:
+
+```ruby
+behaviour_info(:gen_foo, foo: 0, bar: 1, baz: 2)
+
+# -or (for the Java/C# crowd)
+
+interface(:gen_foo, foo: 0, bar: 1, baz: 2)
+
+```
+
+Each function name can be listed only once and the arity must follow the rules of the
+[Method#arity](http://ruby-doc.org/core-1.9.3/Method.html#method-i-arity) function.
+Though not explicitly documented, block arguments do not count toward a method's arity.
+methods defined using this gem's `defn` function will always have an arity of -1,
+regardless of how many overloads are defined.
+
+### behavior
+
+To enforce a behavior on a class simply call the `behavior` function within the class,
+passing the name of the desired behavior:
+
+```ruby
+class Foo
+  behavior(:gen_foo)
+  ...
+end
+
+# or use the idiomatic Erlang spelling
+class Bar
+  behaviour(:gen_foo)
+  ...
+end
+
+# or use the idiomatic Rails syntax
+class Baz
+  behaves_as :gen_foo
+  ...
+end
+```
+
+Make sure you the implement the required methods in your class. If you don't, Ruby will
+raise an exception when you try to create an object from the class:
+
+```ruby
+Baz.new #=> ArgumentError: undefined callback functions in Baz (behavior 'gen_foo')
+```
+
+### behaves_as?
+
+As an added bonus, Ruby [Object](http://ruby-doc.org/core-1.9.3/Object.html) will be
+monkey-patched with a `behaves_as?` predicate method.
+
+## Example
+
+A complete example:
+
+```ruby
+behaviour_info(:gen_foo, foo: 0, bar: 1, baz: 2, boom: -1, bam: :any)
+
+class Foo
+  behavior(:gen_foo)
+
+  def foo
+    return 'foo/0'
+  end
+
+  def bar(one, &block)
+    return 'bar/1'
+  end
+
+  def baz(one, two)
+    return 'baz/2'
+  end
+
+  def boom(*args)
+    return 'boom/-1'
+  end
+
+  def bam
+    return 'bam!'
+  end
+end
+
+foo = Foo.new
+
+foo.behaves_as? :gen_foo    #=> true
+foo.behaves_as?(:bogus)     #=> false
+'foo'.behaves_as? :gen_foo  #=> false
+```
+
+## 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.