functional-ruby 0.7.7 → 1.0.0

data/lib/functional/memo.rb

@@ -0,0 +1,93 @@
+require 'thread'
+
+module Functional
+
+  # Memoization is a technique for optimizing functions that are time-consuming
+  # and/or involve expensive calculations. Every time a memoized function is
+  # called the result is caches with reference to the given parameters.
+  # Subsequent calls to the function that use the same parameters will return
+  # the cached result. As a result the response time for frequently called
+  # functions is vastly incresed (after the first call with any given set of)
+  # arguments, at the cost of increased memory usage (the cache).
+  #   
+  # @!macro memoize
+  #
+  # @note Memoized method calls are thread safe and can safely be used in concurrent systems.
+  #   Declaring memoization on a function is *not* thread safe and should only be done during
+  #   application initialization.
+  module Memo
+
+    def self.extended(base)
+      base.extend(ClassMethods)
+      base.send(:__method_memos__=, {})
+      super(base)
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.send(:__method_memos__=, {})
+      super(base)
+    end
+
+    # @!visibility private
+    module ClassMethods
+
+      # @!visibility private
+      Memo = Struct.new(:function, :mutex, :cache, :max_cache) do
+        def max_cache?
+          max_cache > 0 && cache.size >= max_cache
+        end
+      end
+
+      # @!visibility private
+      attr_accessor :__method_memos__
+
+      # Returns a memoized version of a referentially transparent function. The
+      # memoized version of the function keeps a cache of the mapping from arguments
+      # to results and, when calls with the same arguments are repeated often, has
+      # higher performance at the expense of higher memory use.
+      #
+      # @param [Symbol] func the class/module function to memoize
+      # @param [Hash] opts the options controlling memoization
+      # @option opts [Fixnum] :at_most the maximum number of memos to store in the
+      #   cache; a value of zero (the default) or `nil` indicates no limit
+      #
+      # @raise [ArgumentError] when the method has already been memoized
+      # @raise [ArgumentError] when :at_most option is a negative number
+      def memoize(func, opts = {})
+        func = func.to_sym
+        max_cache = opts[:at_most].to_i
+        raise ArgumentError.new("method :#{func} has already been memoized") if __method_memos__.has_key?(func)
+        raise ArgumentError.new(':max_cache must be > 0') if max_cache < 0
+        __method_memos__[func] = Memo.new(method(func), Mutex.new, {}, max_cache.to_i)
+        __define_memo_proxy__(func)
+        nil
+      end
+
+      # @!visibility private
+      def __define_memo_proxy__(func)
+        self.class_eval <<-RUBY
+          def self.#{func}(*args, &block)
+            self.__proxy_memoized_method__(:#{func}, *args, &block)
+          end
+        RUBY
+      end
+
+      # @!visibility private
+      def __proxy_memoized_method__(func, *args, &block)
+        memo = self.__method_memos__[func]
+        memo.mutex.lock
+        if block_given?
+          memo.function.call(*args, &block)
+        elsif memo.cache.has_key?(args)
+          memo.cache[args]
+        else
+          result = memo.function.call(*args)
+          memo.cache[args] = result unless memo.max_cache?
+        end
+      ensure
+        memo.mutex.unlock
+      end
+    end
+  end
+end

data/lib/functional/method_signature.rb

@@ -0,0 +1,72 @@
+module Functional
+
+  module PatternMatching
+
+    # @!visibility private
+    #
+    # Helper functions used when pattern matching runtime arguments against
+    # a method defined with the `defn` function of Functional::PatternMatching.
+    module MethodSignature
+      extend self
+
+      # Do the given arguments match the given function pattern?
+      #
+      # @return [Boolean] true when there is a match else false
+      def match?(pattern, args)
+        return false unless valid_pattern?(args, pattern)
+
+        pattern.length.times.all? do |index|
+          param = pattern[index]
+          arg = args[index]
+
+          all_param_and_last_arg?(pattern, param, index) ||
+            arg_is_type_of_param?(param, arg) ||
+            hash_param_with_matching_arg?(param, arg) ||
+            param_matches_arg?(param, arg)
+        end
+      end
+
+      # Is the given pattern a valid pattern with respect to the given
+      # runtime arguments?
+      #
+      # @return [Boolean] true when the pattern is valid else false
+      def valid_pattern?(args, pattern)
+        (pattern.last == PatternMatching::ALL && args.length >= pattern.length) \
+          || (args.length == pattern.length)
+      end
+
+      # Is this the last parameter and is it `ALL`?
+      #
+      # @return [Boolean] true when matching else false
+      def all_param_and_last_arg?(pattern, param, index)
+        param == PatternMatching::ALL && index+1 == pattern.length
+      end
+
+      # Is the parameter a class and is the provided argument an instance
+      # of that class?
+      #
+      # @return [Boolean] true when matching else false
+      def arg_is_type_of_param?(param, arg)
+        param.is_a?(Class) && arg.is_a?(param)
+      end
+
+      # Is the given parameter a Hash and does it match the given
+      # runtime argument?
+      #
+      # @return [Boolean] true when matching else false
+      def hash_param_with_matching_arg?(param, arg)
+        param.is_a?(Hash) && arg.is_a?(Hash) && ! param.empty? && param.all? do |key, value|
+          arg.has_key?(key) && (value == PatternMatching::UNBOUND || arg[key] == value)
+        end
+      end
+
+      # Does the given parameter exactly match the given runtime
+      # argument or is the parameter `UNBOUND`?
+      #
+      # @return [Boolean] true when matching else false
+      def param_matches_arg?(param, arg)
+        param == PatternMatching::UNBOUND || param == arg
+      end
+    end
+  end
+end

data/lib/functional/option.rb

@@ -0,0 +1,209 @@
+require_relative 'abstract_struct'
+require_relative 'either'
+require_relative 'protocol'
+
+Functional::SpecifyProtocol(:Option) do
+  instance_method :some?, 0
+  instance_method :none?, 0
+  instance_method :some, 0
+end
+
+module Functional
+
+  # An optional value that may be none (no value) or some (a value).
+  # This type is a replacement for the use of nil with better type checks. 
+  # It is an immutable data structure that extends `AbstractStruct`.
+  #
+  # @see Functional::AbstractStruct
+  # @see http://functionaljava.googlecode.com/svn/artifacts/3.0/javadoc/index.html Functional Java
+  #
+  # @!macro thread_safe_immutable_object
+  class Option
+    include AbstractStruct
+
+    # @!visibility private 
+    NO_OPTION = Object.new.freeze
+
+    self.datatype = :option
+    self.fields = [:some].freeze
+
+    private_class_method :new
+
+    # The reason for the absence of a value when none,
+    # defaults to nil
+    attr_reader :reason
+
+    class << self
+
+      # Construct an `Option` with no value.
+      #
+      # @return [Option] the new option
+      def none(reason = nil)
+        new(nil, true, reason).freeze
+      end
+
+      # Construct an `Option` with the given value.
+      #
+      # @param [Object] value the value of the option
+      # @return [Option] the new option
+      def some(value)
+        new(value, false).freeze
+      end
+    end
+
+    # Does the option have a value?
+    #
+    # @return [Boolean] true if some else false
+    def some?
+      ! none?
+    end
+    alias_method :value?, :some?
+    alias_method :fulfilled?, :some?
+
+    # Is the option absent a value?
+    #
+    # @return [Boolean] true if none else false
+    def none?
+      @none
+    end
+    alias_method :reason?, :none?
+    alias_method :rejected?, :none?
+
+    # The value of this option.
+    #
+    # @return [Object] the value when some else nil
+    def some
+      to_h[:some]
+    end
+    alias_method :value, :some
+
+    # Returns the length of this optional value;
+    # 1 if there is a value, 0 otherwise. 
+    #
+    # @return [Fixnum] The length of this optional value;
+    #   1 if there is a value, 0 otherwise.
+    def length
+      none? ? 0 : 1
+    end
+    alias_method :size, :length
+
+    # Perform a logical `and` operation against this option and the
+    # provided option or block. Returns true if this option is some and:
+    #
+    # * other is an `Option` with some value
+    # * other is a truthy value (not nil or false)
+    # * the result of the block is a truthy value
+    #
+    # If a block is given the value of the current option is passed to the
+    # block and the result of block processing will be evaluated for its
+    # truthiness. An exception will be raised if an other value and a
+    # block are both provided.
+    #
+    # @param [Object] other the value to be evaluated against this option
+    # @yieldparam [Object] value the value of this option when some
+    # @return [Boolean] true when the union succeeds else false
+    # @raise [ArgumentError] when given both other and a block
+    def and(other = NO_OPTION)
+      raise ArgumentError.new('cannot give both an option and a block') if other != NO_OPTION && block_given?
+      return false if none?
+
+      if block_given?
+        !! yield(some)
+      elsif Protocol::Satisfy? other, :Option
+        other.some?
+      else
+        !! other
+      end
+    end
+
+    # Perform a logical `or` operation against this option and the
+    # provided option or block. Returns true if this option is some.
+    # If this option is none it returns true if:
+    #
+    # * other is an `Option` with some value
+    # * other is a truthy value (not nil or false)
+    # * the result of the block is a truthy value
+    #
+    # If a block is given the value of the result of block processing
+    # will be evaluated for its truthiness. An exception will be raised
+    # if an other value and a block are both provided.
+    #
+    # @param [Object] other the value to be evaluated against this option
+    # @return [Boolean] true when the intersection succeeds else false
+    # @raise [ArgumentError] when given both other and a block
+    def or(other = NO_OPTION)
+      raise ArgumentError.new('cannot give both an option and a block') if other != NO_OPTION && block_given?
+      return true if some?
+
+      if block_given?
+        !! yield
+      elsif Protocol::Satisfy? other, :Option
+        other.some?
+      else
+        !! other
+      end
+    end
+
+    # Returns the value of this option when some else returns the
+    # value of the other option or block. When the other is also an
+    # option its some value is returned. When the other is any other
+    # value it is simply passed through. When a block is provided the
+    # block is processed and the return value of the block is returned.
+    # An exception will be raised if an other value and a block are
+    # both provided.
+    #
+    # @param [Object] other the value to be evaluated when this is none
+    # @return [Object] this value when some else the value of other
+    # @raise [ArgumentError] when given both other and a block
+    def else(other = NO_OPTION)
+      raise ArgumentError.new('cannot give both an option and a block') if other != NO_OPTION && block_given?
+      return some if some?
+
+      if block_given?
+        yield
+      elsif Protocol::Satisfy? other, :Option
+        other.some
+      else
+        other
+      end
+    end
+
+    # If the condition satisfies, return the given A in some, otherwise, none.
+    #
+    # @param [Object] value The some value to use if the condition satisfies.
+    # @param [Boolean] condition The condition to test (when no block given).
+    # @yield The condition to test (when no condition given).
+    #
+    # @return [Option] A constructed option based on the given condition.
+    #
+    # @raise [ArgumentError] When both a condition and a block are given.
+    def self.iff(value, condition = NO_OPTION)
+      raise ArgumentError.new('requires either a condition or a block, not both') if condition != NO_OPTION && block_given?
+      condition = block_given? ? yield : !! condition
+      condition ? some(value) : none
+    end
+
+    # @!macro inspect_method
+    def inspect
+      super.gsub(/ :some/, " (#{some? ? 'some' : 'none'}) :some")
+    end
+    alias_method :to_s, :inspect
+
+    private
+
+    # Create a new Option with the given value and disposition.
+    #
+    # @param [Object] value the value of this option
+    # @param [Boolean] none is this option absent a value?
+    # @param [Object] reason the reason for the absense of a value
+    #
+    # @!visibility private 
+    def initialize(value, none, reason = nil)
+      @none = none
+      @reason = none ? reason : nil
+      hsh = none ? {some: nil} : {some: value}
+      set_data_hash(hsh)
+      set_values_array(hsh.values)
+    end
+  end
+end

data/lib/functional/pattern_matching.rb

@@ -1,132 +1,149 @@
-module PatternMatching
-
-  UNBOUND = Class.new
-  ALL = Class.new
-
-  private
-
-  GUARD_CLAUSE = Class.new do # :nodoc:
-    def initialize(func, clazz, matcher) # :nodoc:
-      @func = func
-      @clazz = clazz
-      @matcher = matcher
-    end
-    def when(&block) # :nodoc:
-      unless block_given?
-        raise ArgumentError.new("block missing for `when` guard on function `#{@func}` of class #{@clazz}")
+require_relative 'method_signature'
+
+module Functional
+
+  # As much as I love Ruby I've always been a little disappointed that Ruby doesn't
+  # support function overloading. Function overloading tends to reduce branching
+  # and keep function signatures simpler. No sweat, I learned to do without. Then
+  # I started programming in Erlang. My favorite Erlang feature is, without
+  # question, pattern matching. Pattern matching is like function overloading
+  # cranked to 11. So one day I was musing on Twitter that I'd like to see
+  # Erlang-stype pattern matching in Ruby and one of my friends responded
+  # "Build it!" So I did. And here it is.
+  #
+  # @!macro pattern_matching
+  module PatternMatching
+
+    # A parameter that is required but that can take any value.
+    # @!visibility private
+    UNBOUND = Object.new.freeze
+
+    # A match for one or more parameters in the last position of the match.
+    # @!visibility private
+    ALL = Object.new.freeze
+
+    private
+
+    # A guard clause on a pattern match.
+    # @!visibility private
+    GuardClause = Class.new do
+      def initialize(function, clazz, pattern)
+        @function = function
+        @clazz = clazz
+        @pattern = pattern
       end
-      @matcher[@matcher.length-1] = block
-      return nil
-    end
-  end
-
-  def self.__match_pattern__(args, pattern) # :nodoc:
-    return unless (pattern.last == ALL && args.length >= pattern.length) \
-      || (args.length == pattern.length)
-    pattern.each_with_index do |p, i|
-      break if p == ALL && i+1 == pattern.length
-      arg = args[i]
-      next if p.is_a?(Class) && arg.is_a?(p)
-      if p.is_a?(Hash) && arg.is_a?(Hash) && ! p.empty?
-        p.each do |key, value|
-          return false unless arg.has_key?(key)
-          next if value == UNBOUND
-          return false unless arg[key] == value
+      def when(&block)
+        unless block_given?
+          raise ArgumentError.new("block missing for `when` guard on function `#{@function}` of class #{@clazz}")
         end
-        next
+        @pattern.guard = block
+        self
       end
-      return false unless p == UNBOUND || p == arg
     end
-    return true
-  end
 
-  def self.__unbound_args__(match, args) # :nodoc:
-    argv = []
-    match.first.each_with_index do |p, i|
-      if p == ALL && i == match.first.length-1
-        argv << args[(i..args.length)].reduce([]){|memo, arg| memo << arg }
-      elsif p.is_a?(Hash) && p.values.include?(UNBOUND)
-        p.each do |key, value|
-          argv << args[i][key] if value == UNBOUND
+    # @!visibility private
+    FunctionPattern = Struct.new(:function, :args, :body, :guard)
+
+    # @!visibility private
+    def __unbound_args__(match, args)
+      argv = []
+      match.args.each_with_index do |p, i|
+        if p == ALL && i == match.args.length-1
+          argv << args[(i..args.length)].reduce([]){|memo, arg| memo << arg }
+        elsif p.is_a?(Hash) && p.values.include?(UNBOUND)
+          p.each do |key, value|
+            argv << args[i][key] if value == UNBOUND
+          end
+        elsif p.is_a?(Hash) || p == UNBOUND || p.is_a?(Class)
+          argv << args[i] 
         end
-      elsif p.is_a?(Hash) || p == UNBOUND || p.is_a?(Class)
-        argv << args[i] 
       end
+      argv
     end
-    return argv
-  end
-
-  def self.__pattern_match__(clazz, func, *args, &block) # :nodoc:
-    args = args.first
 
-    matchers = clazz.__function_pattern_matches__[func]
-    return [:nodef, nil] if matchers.nil?
+    def __pass_guard__?(matcher, args)
+      matcher.guard.nil? ||
+        self.instance_exec(*__unbound_args__(matcher, args), &matcher.guard)
+    end
 
-    match = matchers.detect do |matcher|
-      if PatternMatching.__match_pattern__(args, matcher.first)
-        if matcher.last.nil?
-          true # no guard clause
-        else
-          self.instance_exec(*PatternMatching.__unbound_args__(matcher, args), &matcher.last)
-        end
+    # @!visibility private
+    def __pattern_match__(clazz, function, *args, &block)
+      args = args.first
+      matchers = clazz.__function_pattern_matches__.fetch(function, [])
+      matchers.detect do |matcher|
+        MethodSignature.match?(matcher.args, args) && __pass_guard__?(matcher, args)
       end
     end
 
-    return (match ? [:ok, match] : [:nomatch, nil])
-  end
-
-  protected
-
-  def self.included(base)
-
-    class << base
+    def self.included(base)
+      base.extend(ClassMethods)
+      super(base)
+    end
 
-      public
+    # Class methods added to a class that includes {Functional::PatternMatching}
+    # @!visibility private
+    module ClassMethods
 
-      def _() # :nodoc:
-        return UNBOUND
+      # @!visibility private
+      def _()
+        UNBOUND
       end
 
-      def defn(func, *args, &block)
+      # @!visibility private
+      def defn(function, *args, &block)
         unless block_given?
-          raise ArgumentError.new("block missing for definition of function `#{func}` on class #{self}")
+          raise ArgumentError.new("block missing for definition of function `#{function}` on class #{self}")
         end
 
-        pattern = __add_pattern_for__(func, *args, &block)
-
-        unless self.instance_methods(false).include?(func)
-
-          define_method(func) do |*args, &block|
-            result, match = PatternMatching.__pattern_match__(self.method(func).owner, func, args, block)
-            if result == :ok
-              # if a match is found call the block
-              argv = PatternMatching.__unbound_args__(match, args)
-              return self.instance_exec(*argv, &match[1])
-            else # if result == :nodef || result == :nomatch
-              begin
-                super(*args, &block)
-              rescue NoMethodError, ArgumentError
-                raise NoMethodError.new("no method `#{func}` matching #{args} found for class #{self.class}")
-              end
-            end
-          end
+        # add a new pattern for this function
+        pattern = __register_pattern__(function, *args, &block)
+
+        # define the delegator function if it doesn't exist yet
+        unless self.instance_methods(false).include?(function)
+          __define_method_with_matching__(function)
         end
 
-        return GUARD_CLAUSE.new(func, self, pattern)
+        # return a guard clause to be added to the pattern
+        GuardClause.new(function, self, pattern)
       end
 
-      public
+      # @!visibility private
+      # define an arity -1 function that dispatches to the appropriate
+      # pattern match variant or raises an exception
+      def __define_method_with_matching__(function)
+        define_method(function) do |*args, &block|
+          begin
+            # get the collection of matched patterns for this function
+            # use owner to ensure we climb the inheritance tree
+            match = __pattern_match__(self.method(function).owner, function, args, block)
+            if match
+              # call the matched function
+              argv = __unbound_args__(match, args)
+              self.instance_exec(*argv, &match.body)
+            else
+              # delegate to the superclass
+              super(*args, &block)
+            end
+          rescue NoMethodError, ArgumentError
+            # raise a custom error
+            raise NoMethodError.new("no method `#{function}` matching #{args} found for class #{self.class}")
+          end
+        end
+      end
 
-      def __function_pattern_matches__ # :nodoc:
+      # @!visibility private
+      def __function_pattern_matches__
         @__function_pattern_matches__ ||= Hash.new
       end
 
-      def __add_pattern_for__(func, *args, &block) # :nodoc:
+      # @!visibility private
+      def __register_pattern__(function, *args, &block)
         block = Proc.new{} unless block_given?
-        matchers = self.__function_pattern_matches__
-        matchers[func] = [] unless matchers.has_key?(func)
-        matchers[func] << [args, block, nil]
-        return matchers[func].last
+        pattern = FunctionPattern.new(function, args, block)
+        patterns = self.__function_pattern_matches__.fetch(function, [])
+        patterns << pattern
+        self.__function_pattern_matches__[function] = patterns
+        pattern
       end
     end
   end