functional-ruby 0.7.7 → 1.0.0

data/lib/functional/abstract_struct.rb

@@ -0,0 +1,161 @@
+require_relative 'protocol'
+
+Functional::SpecifyProtocol(:Struct) do
+  instance_method :fields
+  instance_method :values
+  instance_method :length
+  instance_method :each
+  instance_method :each_pair
+end
+
+module Functional
+
+  # An abstract base class for immutable struct classes.
+  module AbstractStruct
+
+    # @return [Array] the values of all record fields in order, frozen
+    attr_reader :values
+
+    # Yields the value of each record field in order.
+    # If no block is given an enumerator is returned.
+    #
+    # @yieldparam [Object] value the value of the given field
+    #
+    # @return [Enumerable] when no block is given
+    def each
+      return enum_for(:each) unless block_given?
+      fields.each do |field|
+        yield(self.send(field))
+      end
+    end
+
+    # Yields the name and value of each record field in order.
+    # If no block is given an enumerator is returned.
+    #
+    # @yieldparam [Symbol] field the record field for the current iteration
+    # @yieldparam [Object] value the value of the current field
+    #
+    # @return [Enumerable] when no block is given
+    def each_pair
+      return enum_for(:each_pair) unless block_given?
+      fields.each do |field|
+        yield(field, self.send(field))
+      end
+    end
+
+    # Equality--Returns `true` if `other` has the same record subclass and has equal
+    # field values (according to `Object#==`).
+    #
+    # @param [Object] other the other record to compare for equality
+    # @return [Booleab] true when equal else false
+    def eql?(other)
+      self.class == other.class && self.to_h == other.to_h
+    end
+    alias_method :==, :eql?
+
+    # @!macro [attach] inspect_method
+    #
+    #   Describe the contents of this record in a string. Will include the name of the
+    #   record class, all fields, and all values.
+    #
+    #   @return [String] the class and contents of this record
+    def inspect
+      state = to_h.to_s.gsub(/^{/, '').gsub(/}$/, '')
+      "#<#{self.class.datatype} #{self.class} #{state}>"
+    end
+    alias_method :to_s, :inspect
+
+    # Returns the number of record fields.
+    #
+    # @return [Fixnum] the number of record fields
+    def length
+      fields.length
+    end
+    alias_method :size, :length
+
+    # A frozen array of all record fields.
+    #
+    # @return [Array] all record fields in order, frozen
+    def fields
+      self.class.fields
+    end
+
+    # Returns a Hash containing the names and values for the record’s fields.
+    #
+    # @return [Hash] collection of all fields and their associated values
+    def to_h
+      @data
+    end
+
+    protected
+
+    # Set the internal data hash to a copy of the given hash and freeze it.
+    # @param [Hash] data the data hash
+    #
+    # @!visibility private 
+    def set_data_hash(data)
+      @data = data.dup.freeze
+    end
+
+    # Set the internal values array to a copy of the given array and freeze it.
+    # @param [Array] values the values array
+    #
+    # @!visibility private 
+    def set_values_array(values)
+      @values = values.dup.freeze
+    end
+
+    # Define a new struct class and, if necessary, register it with
+    # the calling class/module. Will also set the datatype and fields
+    # class attributes on the new struct class.
+    #
+    # @param [Module] parent the class/module that is defining the new struct
+    # @param [Symbol] datatype the datatype value for the new struct class
+    # @param [Array] fields the list of symbolic names for all data fields
+    # @return [Functional::AbstractStruct, Array] the new class and the
+    #   (possibly) updated fields array
+    #
+    # @!visibility private 
+    def self.define_class(parent, datatype, fields)
+      struct = Class.new{ include AbstractStruct }
+      if fields.first.is_a? String
+        parent.const_set(fields.first, struct)
+        fields = fields[1, fields.length-1]
+      end
+      fields = fields.collect{|field| field.to_sym }.freeze
+      struct.send(:datatype=, datatype.to_sym)
+      struct.send(:fields=, fields)
+      [struct, fields]
+    end
+
+    private
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      super(base)
+    end
+
+    # Class methods added to a class that includes {Functional::PatternMatching}
+    #
+    # @!visibility private
+    module ClassMethods
+
+      # A frozen Array of all record fields in order
+      attr_reader :fields
+
+      # A symbol describing the object's datatype
+      attr_reader :datatype
+
+      private
+
+      # A frozen Array of all record fields in order
+      attr_writer :fields
+
+      # A symbol describing the object's datatype
+      attr_writer :datatype
+
+      fields = [].freeze
+      datatype = :struct 
+    end
+  end
+end

data/lib/functional/delay.rb

@@ -0,0 +1,117 @@
+require 'thread'
+
+module Functional
+
+  # Lazy evaluation of a block yielding an immutable result. Useful for expensive
+  # operations that may never be needed.
+  # 
+  # When a `Delay` is created its state is set to `pending`. The value and
+  # reason are both `nil`. The first time the `#value` method is called the
+  # enclosed opration will be run and the calling thread will block. Other
+  # threads attempting to call `#value` will block as well. Once the operation
+  # is complete the *value* will be set to the result of the operation or the
+  # *reason* will be set to the raised exception, as appropriate. All threads
+  # blocked on `#value` will return. Subsequent calls to `#value` will immediately
+  # return the cached value. The operation will only be run once. This means that
+  # any side effects created by the operation will only happen once as well.
+  #
+  # @see http://clojuredocs.org/clojure_core/clojure.core/delay Clojure delay
+  #
+  # @!macro thread_safe_immutable_object
+  class Delay
+
+    # Create a new `Delay` in the `:pending` state.
+    #
+    # @yield the delayed operation to perform
+    #
+    # @raise [ArgumentError] if no block is given
+    def initialize(&block)
+      raise ArgumentError.new('no block given') unless block_given?
+      @mutex = Mutex.new
+      @state = :pending
+      @task  = block
+    end
+
+    # Current state of block processing.
+    #
+    # @return [Symbol] the current state of block processing
+    def state
+      @mutex.lock
+      @state
+    ensure
+      @mutex.unlock
+    end
+
+    # The exception raised when processing the block. Returns `nil` if the
+    # operation is still `:pending` or has been `:fulfilled`.
+    #
+    # @return [StandardError] the exception raised when processing the block else nil
+    def reason
+      @mutex.lock
+      @reason
+    ensure
+      @mutex.unlock
+    end
+
+    # Return the (possibly memoized) value of the delayed operation.
+    # 
+    # If the state is `:pending` then the calling thread will block while the
+    # operation is performed. All other threads simultaneously calling `#value`
+    # will block as well. Once the operation is complete (either `:fulfilled` or
+    # `:rejected`) all waiting threads will unblock and the new value will be
+    # returned.
+    #
+    # If the state is not `:pending` when `#value` is called the (possibly memoized)
+    # value will be returned without blocking and without performing the operation
+    # again.
+    #
+    # @return [Object] the (possibly memoized) result of the block operation
+    def value
+      @mutex.lock
+      execute_task_once
+      @value
+    ensure
+      @mutex.unlock
+    end
+
+    # Has the delay been fulfilled?
+    # @return [Boolean]
+    def fulfilled?
+      state == :fulfilled
+    end
+    alias_method :value?, :fulfilled?
+
+    # Has the delay been rejected?
+    # @return [Boolean]
+    def rejected?
+      state == :rejected
+    end
+    alias_method :reason?, :rejected?
+
+    # Is delay completion still pending?
+    # @return [Boolean]
+    def pending?
+      state == :pending
+    end
+
+    protected
+
+    # @!visibility private
+    #
+    # Execute the enclosed task then cache and return the result if
+    # the current state is pending. Otherwise, return the cached result.
+    #
+    # @return [Object] the result of the block operation
+    def execute_task_once
+      if @state == :pending
+        begin
+          @value = @task.call
+          @state = :fulfilled
+        rescue => ex
+          @reason = ex
+          @state  = :rejected
+        end
+      end
+    end
+  end
+end

data/lib/functional/either.rb

@@ -0,0 +1,222 @@
+require_relative 'abstract_struct'
+require_relative 'protocol'
+
+Functional::SpecifyProtocol(:Either) do
+  instance_method :left, 0
+  instance_method :left?, 0
+  instance_method :right, 0
+  instance_method :right?, 0
+end
+
+module Functional
+
+  # The `Either` type represents a value of one of two possible types (a disjoint union).
+  # It is an immutable structure that contains one and only one value. That value can
+  # be stored in one of two virtual position, `left` or `right`. The position provides
+  # context for the encapsulated data.
+  #
+  # One of the main uses of `Either` is as a return value that can indicate either
+  # success or failure. Object oriented programs generally report errors through
+  # either state or exception handling, neither of which work well in functional
+  # programming. In the former case, a method is called on an object and when an
+  # error occurs the state of the object is updated to reflect the error. This does
+  # not translate well to functional programming because they eschew state and
+  # mutable objects. In the latter, an exception handling block provides branching
+  # logic when an exception is thrown. This does not translate well to functional
+  # programming because it eschews side effects like structured exception handling
+  # (and structured exception handling tends to be very expensive). `Either` provides
+  # a powerful and easy-to-use alternative.
+  #
+  # A function that may generate an error can choose to return an immutable `Either`
+  # object in which the position of the value (left or right) indicates the nature
+  # of the data. By convention, a `left` value indicates an error and a `right` value
+  # indicates success. This leaves the caller with no ambiguity regarding success or
+  # failure, requires no persistent state, and does not require expensive exception
+  # handling facilities.
+  #
+  # `Either` provides several aliases and convenience functions to facilitate these
+  # failure/success conventions. The `left` and `right` functions, including their
+  # derivatives, are mirrored by `reason` and `value`. Failure is indicated by the
+  # presence of a `reason` and success is indicated by the presence of a `value`.
+  # When an operation has failed the either is in a `rejected` state, and when an
+  # operation has successed the either is in a `fulfilled` state. A common convention
+  # is to use a Ruby `Exception` as the `reason`. The factory method `error` facilitates
+  # this. The semantics and conventions of `reason`, `value`, and their derivatives
+  # follow the conventions of the Concurrent Ruby gem.
+  #
+  # The `left`/`right` and `reason`/`value` methods are not mutually exclusive. They
+  # can be commingled and still result in functionally correct code. This practice
+  # should be avoided, however. Consistent use of either `left`/`right` or
+  # `reason`/`value` against each `Either` instance will result in more expressive,
+  # intent-revealing code.
+  #
+  # @example
+  #
+  #   require 'uri'
+  #
+  #   def web_host(url)
+  #     uri = URI(url)
+  #     if uri.scheme == 'http'
+  #       Functional::Either.left(uri.host)
+  #     else
+  #       Functional::Either.right('Invalid HTTP URL')
+  #     end
+  #   end
+  #
+  #   good = web_host('http://www.concurrent-ruby.com')
+  #   good.left? #=> true
+  #   good.left  #=> "www.concurrent-ruby"
+  #   good.right #=> nil
+  #
+  #   good = web_host('bogus')
+  #   good.left? #=> false
+  #   good.left  #=> nil
+  #   good.right #=> "Invalid HTTP URL"
+  #
+  # @see http://functionaljava.googlecode.com/svn/artifacts/3.0/javadoc/fj/data/Either.html Functional Java
+  # @see https://hackage.haskell.org/package/base-4.2.0.1/docs/Data-Either.html Haskell Data.Either
+  # @see http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/Obligation.html Concurrent Ruby
+  #
+  # @!macro thread_safe_immutable_object
+  class Either
+    include AbstractStruct
+
+    self.datatype = :either
+    self.fields = [:left, :right].freeze
+
+    # @!visibility private 
+    NO_VALUE = Object.new.freeze
+
+    private_class_method :new
+
+    class << self
+
+      # Construct a left value of either.
+      #
+      # @param [Object] value The value underlying the either.
+      # @return [Either] A new either with the given left value.
+      def left(value)
+        new(value, true).freeze
+      end
+      alias_method :reason, :left
+
+      # Construct a right value of either.
+      #
+      # @param [Object] value The value underlying the either.
+      # @return [Either] A new either with the given right value.
+      def right(value)
+        new(value, false).freeze
+      end
+      alias_method :value, :right
+
+      # Create an `Either` with the left value set to an `Exception` object
+      # complete with message and backtrace. This is a convenience method for
+      # supporting the reason/value convention with the reason always being
+      # an `Exception` object. When no exception class is given `StandardError`
+      # will be used. When no message is given the default message for the
+      # given error class will be used.
+      #
+      # @example
+      # 
+      #   either = Functional::Either.error("You're a bad monkey, Mojo Jojo")
+      #   either.fulfilled? #=> false
+      #   either.rejected?  #=> true
+      #   either.value      #=> nil
+      #   either.reason     #=> #<StandardError: You're a bad monkey, Mojo Jojo>
+      #
+      # @param [String] message The message for the new error object.
+      # @param [Exception] clazz The class for the new error object.
+      # @return [Either] A new either with an error object as the left value.
+      def error(message = nil, clazz = StandardError)
+        ex = clazz.new(message)
+        ex.set_backtrace(caller)
+        left(ex)
+      end
+    end
+
+    # Projects this either as a left.
+    # 
+    # @return [Object] The left value or `nil` when `right`.
+    def left
+      left? ? to_h[:left] : nil
+    end
+    alias_method :reason, :left
+
+    # Projects this either as a right.
+    # 
+    # @return [Object] The right value or `nil` when `left`.
+    def right
+      right? ? to_h[:right] : nil
+    end
+    alias_method :value, :right
+
+    # Returns true if this either is a left, false otherwise.
+    #
+    # @return [Boolean] `true` if this either is a left, `false` otherwise.
+    def left?
+      @is_left
+    end
+    alias_method :reason?, :left?
+    alias_method :rejected?, :left?
+
+    # Returns true if this either is a right, false otherwise.
+    #
+    # @return [Boolean] `true` if this either is a right, `false` otherwise.
+    def right?
+      ! left?
+    end
+    alias_method :value?, :right?
+    alias_method :fulfilled?, :right?
+
+    # If this is a left, then return the left value in right, or vice versa.
+    #
+    # @return [Either] The value of this either swapped to the opposing side.
+    def swap
+      if left?
+        self.class.send(:new, left, false)
+      else
+        self.class.send(:new, right, true)
+      end
+    end
+
+    # The catamorphism for either. Folds over this either breaking into left or right.
+    #
+    # @param [Proc] lproc The function to call if this is left.
+    # @param [Proc] rproc The function to call if this is right.
+    # @return [Object] The reduced value.
+    def either(lproc, rproc)
+      left? ? lproc.call(left) : rproc.call(right)
+    end
+
+    # If the condition satisfies, return the given A in left, otherwise, return the given B in right.
+    #
+    # @param [Object] lvalue The left value to use if the condition satisfies.
+    # @param [Object] rvalue The right value to use if the condition does not satisfy.
+    # @param [Boolean] condition The condition to test (when no block given).
+    # @yield The condition to test (when no condition given).
+    #
+    # @return [Either] A constructed either based on the given condition.
+    #
+    # @raise [ArgumentError] When both a condition and a block are given.
+    def self.iff(lvalue, rvalue, condition = NO_VALUE)
+      raise ArgumentError.new('requires either a condition or a block, not both') if condition != NO_VALUE && block_given?
+      condition = block_given? ? yield : !! condition
+      condition ? left(lvalue) : right(rvalue)
+    end
+
+    private
+
+    # Create a new Either wil the given value and disposition.
+    #
+    # @param [Object] value the value of this either
+    # @param [Boolean] is_left is this a left either or right?
+    #
+    # @!visibility private 
+    def initialize(value, is_left)
+      @is_left = is_left
+      hsh = is_left ? {left: value, right: nil} : {left: nil, right: value}
+      set_data_hash(hsh)
+      set_values_array(hsh.values)
+    end
+  end
+end