functional-ruby 1.0.0 → 1.1.0

data/lib/functional/final_var.rb

@@ -0,0 +1,163 @@
+require 'thread'
+
+module Functional
+
+  # An exception raised when an attempt is made to modify an
+  # immutable object or attribute.
+  FinalityError = Class.new(StandardError)
+
+  # A thread safe object that holds a single value and is "final" (meaning
+  # that the value can be set at most once after which it becomes immutable).
+  # The value can be set at instantiation which will result in the object
+  # becoming fully and immediately immutable. Attempting to set the value
+  # once it has been set is a logical error and will result in an exception
+  # being raised.
+  #
+  # @example Instanciation With No Value
+  #   f = Functional::FinalVar.new
+  #     #=> #<Functional::FinalVar unset>
+  #   f.set?       #=> false
+  #   f.value      #=> nil
+  #   f.value = 42 #=> 42
+  #   f.inspect
+  #     #=> "#<Functional::FinalVar value=42>"
+  #   f.set?       #=> true
+  #   f.value      #=> 42
+  #
+  # @example Instanciation With an Initial Value
+  #   f = Functional::FinalVar.new(42)
+  #     #=> #<Functional::FinalVar value=42>
+  #   f.set?       #=> true
+  #   f.value      #=> 42
+  #
+  # @since 1.1.0
+  #
+  # @see Functional::FinalStruct
+  # @see http://en.wikipedia.org/wiki/Final_(Java) Java `final` keyword
+  #
+  # @!macro thread_safe_final_object
+  class FinalVar
+
+    # @!visibility private 
+    NO_VALUE = Object.new.freeze
+
+    # Create a new `FinalVar` with the given value or "unset" when
+    # no value is given.
+    #
+    # @param [Object] value if given, the immutable value of the object
+    def initialize(value = NO_VALUE)
+      @mutex = Mutex.new
+      @value = value
+    end
+
+    # Get the current value or nil if unset.
+    #
+    # @return [Object] the current value or nil
+    def get
+      @mutex.synchronize {
+        has_been_set? ? @value : nil
+      }
+    end
+    alias_method :value, :get
+
+    # Set the value. Will raise an exception if already set.
+    #
+    # @param [Object] value the value to set
+    # @return [Object] the new value
+    # @raise [Functional::FinalityError] if the value has already been set
+    def set(value)
+      @mutex.synchronize {
+        if has_been_set?
+          raise FinalityError.new('value has already been set')
+        else
+          @value = value
+        end
+      }
+    end
+    alias_method :value=, :set
+
+    # Has the value been set?
+    #
+    # @return [Boolean] true when the value has been set else false
+    def set?
+      @mutex.synchronize {
+        has_been_set?
+      }
+    end
+    alias_method :value?, :set?
+
+    # Get the value if it has been set else set the value.
+    #
+    # @param [Object] value the value to set
+    # @return [Object] the current value if already set else the new value
+    def get_or_set(value)
+      @mutex.synchronize {
+        if has_been_set?
+          @value
+        else
+          @value = value
+        end
+      }
+    end
+
+    # Get the value if set else return the given default value.
+    #
+    # @param [Object] default the value to return if currently unset
+    # @return [Object] the current value when set else the given default
+    def fetch(default)
+      @mutex.synchronize {
+        has_been_set? ? @value : default
+      }
+    end
+
+    # Compares this object and other for equality. A `FinalVar` that is unset
+    # is never equal to anything else (it represents a complete absence of value).
+    # When set a `FinalVar` is equal to another `FinalVar` if they have the same
+    # value. A `FinalVar` is equal to another object if its value is equal to
+    # the other object using Ruby's normal equality rules.
+    #
+    # @param [Object] other the object to compare equality to
+    # @return [Boolean] true if equal else false
+    def eql?(other)
+      if (val = fetch(NO_VALUE)) == NO_VALUE
+        false
+      elsif other.is_a?(FinalVar)
+        val == other.value
+      else
+        val == other
+      end
+    end
+    alias_method :==, :eql?
+
+    # Describe the contents of this object in a string.
+    #
+    # @return [String] the string representation of this object
+    #
+    # @!visibility private
+    def inspect
+      if (val = fetch(NO_VALUE)) == NO_VALUE
+        val = 'unset'
+      else
+        val = "value=#{val.is_a?(String) ? ('"' + val + '"') : val }"
+      end
+      "#<#{self.class} #{val}>"
+    end
+
+    # Describe the contents of this object in a string.
+    #
+    # @return [String] the string representation of this object
+    #
+    # @!visibility private
+    def to_s
+      value.to_s
+    end
+
+    private
+
+    # Checks the set status without locking the mutex.
+    # @return [Boolean] true when set else false
+    def has_been_set?
+      @value != NO_VALUE
+    end
+  end
+end

data/lib/functional/memo.rb

@@ -15,14 +15,18 @@ module Functional
   # @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.
+  #
+  # @since 1.0.0
   module Memo
 
+    # @!visibility private
     def self.extended(base)
       base.extend(ClassMethods)
       base.send(:__method_memos__=, {})
       super(base)
     end
 
+    # @!visibility private
     def self.included(base)
       base.extend(ClassMethods)
       base.send(:__method_memos__=, {})

data/lib/functional/method_signature.rb

@@ -6,6 +6,8 @@ module Functional
     #
     # Helper functions used when pattern matching runtime arguments against
     # a method defined with the `defn` function of Functional::PatternMatching.
+    #
+    # @since 1.0.0
     module MethodSignature
       extend self
 

data/lib/functional/option.rb

@@ -17,6 +17,8 @@ module Functional
   # @see Functional::AbstractStruct
   # @see http://functionaljava.googlecode.com/svn/artifacts/3.0/javadoc/index.html Functional Java
   #
+  # @since 1.0.0
+  #
   # @!macro thread_safe_immutable_object
   class Option
     include AbstractStruct

data/lib/functional/pattern_matching.rb

@@ -75,6 +75,7 @@ module Functional
       end
     end
 
+    # @!visibility private
     def self.included(base)
       base.extend(ClassMethods)
       super(base)

data/lib/functional/protocol.rb

@@ -57,6 +57,8 @@ module Functional
   # It is a logical extension of the `respond_to?` method, but vastly more powerful.
   #   
   # @!macro protocol
+  #
+  # @since 1.0.0 (formerly "behavior")
   module Protocol
 
     # The global registry of specified protocols.

data/lib/functional/protocol_info.rb

@@ -4,6 +4,8 @@ module Functional
   # itself from a block. Used by {Functional#SpecifyProtocol}.
   # 
   # @see Functional::Protocol
+  #
+  # @since 1.0.0
   class ProtocolInfo
 
     # The symbolic name of the protocol
@@ -63,6 +65,7 @@ module Functional
     private
 
     # Data structure for encapsulating the protocol info data.
+    # @!visibility private
     Info = Struct.new(:instance_methods, :class_methods, :constants)
 
     # Does the target satisfy the constants expected by this protocol?

data/lib/functional/record.rb

@@ -19,6 +19,8 @@ module Functional
   # @see Functional::AbstractStruct
   # @see Functional::Union
   #
+  # @since 1.0.0
+  #
   # @!macro thread_safe_immutable_object
   module Record
     extend self
@@ -127,8 +129,8 @@ module Functional
     # @return [Functional::AbstractStruct] the record class
     def define_initializer(record)
       record.send(:define_method, :initialize) do |data = {}|
-        restrictions = self.class.class_variable_get(:@@restrictions)
-        data = fields.reduce({}) do |memo, field|
+        restrictions = record.class_variable_get(:@@restrictions)
+        data = record.fields.reduce({}) do |memo, field|
           memo[field] = data.fetch(field, restrictions.clone_default(field))
           memo
         end

data/lib/functional/tuple.rb

@@ -0,0 +1,247 @@
+module Functional
+
+  # A tuple is a pure functional data strcture that is similar to an array but is
+  # immutable and of fixed length. Tuples support many of the same operations as
+  # array/list/vector.
+  #
+  # @note The current implementation uses simple Ruby arrays. This is likely to be
+  #   very inefficient for all but the smallest tuples. The more items the tuple
+  #   contains, the less efficient it will become. A future version will use a fast,
+  #   immutable, persistent data structure such as a finger tree or a trie.
+  #
+  # @since 1.1.0
+  # 
+  # @see http://en.wikipedia.org/wiki/Tuple
+  # @see http://msdn.microsoft.com/en-us/library/system.tuple.aspx
+  # @see http://www.tutorialspoint.com/python/python_tuples.htm
+  # @see http://en.cppreference.com/w/cpp/utility/tuple
+  # @see http://docs.oracle.com/javaee/6/api/javax/persistence/Tuple.html
+  # @see http://www.erlang.org/doc/reference_manual/data_types.html
+  # @see http://www.erlang.org/doc/man/erlang.html#make_tuple-2
+  # @see http://en.wikibooks.org/wiki/Haskell/Lists_and_tuples#Tuples
+  #
+  # @!macro thread_safe_immutable_object
+  class Tuple
+
+    # Create a new tuple with the given data items in the given order.
+    #
+    # @param [Array] data the data items to insert into the new tuple
+    # @raise [ArgumentError] if data is not an array or does not implement `to_a`
+    def initialize(data = [])
+      raise ArgumentError.new('data is not an array') unless data.respond_to?(:to_a)
+      @data = data.to_a.dup.freeze
+      self.freeze
+    end
+
+    # Retrieve the item at the given index. Indices begin at zero and increment
+    # up, just like Ruby arrays. Negative indicies begin at -1, which represents the
+    # last item in the tuple, and decrement toward the first item. If the
+    # given index is out of range then `nil` is returned.
+    #
+    # @param [Fixnum] index the index of the item to be retrieved
+    # @return [Object] the item at the given index or nil when index is out of bounds
+    def at(index)
+      @data[index]
+    end
+    alias_method :nth, :at
+    alias_method :[], :at
+
+    # Retrieve the item at the given index or return the given default value if the
+    # index is out of bounds. The behavior of indicies follows the rules for the
+    # `at` method.
+    #
+    # @param [Fixnum] index the index of the item to be retrieved
+    # @param [Object] default the value to return when given an out of bounds index
+    # @return [Object] the item at the given index or default when index is out of bounds
+    #
+    # @see Functional::Tuple#at
+    def fetch(index, default)
+      if index >= length || -index > length
+        default
+      else
+        at(index)
+      end
+    end
+
+    # The number of items in the tuple.
+    #
+    # @return [Fixnum] the number of items in the tuple
+    def length
+      @data.length
+    end
+    alias_method :size, :length
+
+    # Returns a new tuple containing elements common to the two tuples, excluding any
+    # duplicates. The order is preserved from the original tuple.
+    #
+    # @!macro [attach] tuple_method_param_other_return_tuple
+    #   @param [Array] other the tuple or array-like object (responds to `to_a`) to operate on
+    #   @return [Functional::Tuple] a new tuple with the appropriate items
+    def intersect(other)
+      Tuple.new(@data & other.to_a)
+    end
+    alias_method :&, :intersect
+
+    # Returns a new tuple by joining self with other, excluding any duplicates and
+    # preserving the order from the original tuple.
+    #
+    # @!macro tuple_method_param_other_return_tuple
+    def union(other)
+      Tuple.new(@data | other.to_a)
+    end
+    alias_method :|, :union
+
+    # Returns a new tuple built by concatenating the two tuples
+    # together to produce a third tuple.
+    #
+    # @!macro tuple_method_param_other_return_tuple
+    def concat(other)
+      Tuple.new(@data + other.to_a)
+    end
+    alias_method :+, :concat
+
+    # Returns a new tuple that is a copy of the original tuple, removing any items that
+    # also appear in other. The order is preserved from the original tuple.
+    #
+    # @!macro tuple_method_param_other_return_tuple
+    def diff(other)
+      Tuple.new(@data - other.to_a)
+    end
+    alias_method :-, :diff
+
+    # Returns a new tuple built by concatenating the given number of copies of self.
+    # Returns an empty tuple when the multiple is zero.
+    #
+    # @param [Fixnum] multiple the number of times to concatenate self
+    # @return [Functional::Tuple] a new tuple with the appropriate items
+    # @raise [ArgumentError] when multiple is a negative number
+    def repeat(multiple)
+      multiple = multiple.to_i
+      raise ArgumentError.new('negative argument') if multiple < 0
+      Tuple.new(@data * multiple)
+    end
+    alias_method :*, :repeat
+
+    # Returns a new tuple by removing duplicate values in self.
+    # 
+    # @return [Functional::Tuple] the new tuple with only unique items
+    def uniq
+      Tuple.new(@data.uniq)
+    end
+
+    # Calls the given block once for each element in self, passing that element as a parameter.
+    # An Enumerator is returned if no block is given.
+    #
+    # @yieldparam [Object] item the current item
+    # @return [Enumerable] when no block is given
+    def each
+      return enum_for(:each) unless block_given?
+      @data.each do |item|
+        yield(item)
+      end
+    end
+
+    # Calls the given block once for each element in self, passing that element
+    # and the current index as parameters. An Enumerator is returned if no block is given.
+    #
+    # @yieldparam [Object] item the current item
+    # @yieldparam [Fixnum] index the index of the current item
+    # @return [Enumerable] when no block is given
+    def each_with_index
+      return enum_for(:each_with_index) unless block_given?
+      @data.each_with_index do |item, index|
+        yield(item, index)
+      end
+    end
+
+    # Calls the given block once for each element in self, passing that element
+    # and a tuple with all the remaining items in the tuple. When the last item
+    # is reached ab empty tuple is passed as the second parameter. This is the
+    # classic functional programming `head|tail` list processing idiom.
+    # An Enumerator is returned if no block is given.
+    #
+    # @yieldparam [Object] head the current item for this iteration
+    # @yieldparam [Tuple] tail the remaining items (tail) or an empty tuple when
+    #   processing the last item
+    # @return [Enumerable] when no block is given
+    def sequence
+      return enum_for(:sequence) unless block_given?
+      @data.length.times do |index|
+        last = @data.length - 1
+        if index == last
+          yield(@data[index], Tuple.new)
+        else
+          yield(@data[index], Tuple.new(@data.slice(index+1..last)))
+        end
+      end
+    end
+
+    # Compares this object and other for equality. A tuple is `eql?` to
+    # other when other is a tuple or an array-like object (any object that
+    # responds to `to_a`) and the two objects have identical values in the
+    # same foxed order.
+    #
+    # @param [Object] other the other tuple to compare for equality
+    # @return [Boolean] true when equal else false
+    def eql?(other)
+      @data == other.to_a
+    end
+    alias_method :==, :eql?
+
+    # Returns true if self contains no items.
+    #
+    # @return [Boolean] true when empty else false
+    def empty?
+      @data.empty?
+    end
+
+    # Returns the first element of the tuple or nil when empty.
+    #
+    # @return [Object] the first element or nil
+    def first
+      @data.first
+    end
+    alias_method :head, :first
+
+    # Returns a tuple containing all the items in self after the first
+    # item. Returns an empty tuple when empty or there is only one item.
+    #
+    # @return [Functional::Tuple] the tail of the tuple
+    def rest
+      if @data.length <= 1
+        Tuple.new
+      else
+        Tuple.new(@data.slice(1..@data.length-1))
+      end
+    end
+    alias_method :tail, :rest
+
+    # Create a standard Ruby mutable array containing the tuple items
+    # in the same order.
+    #
+    # @return [Array] the new array created from the tuple
+    def to_a
+      @data.dup
+    end
+    alias_method :to_ary, :to_a
+
+    # Describe the contents of this object in a string.
+    #
+    # @return [String] the string representation of this object
+    #
+    # @!visibility private
+    def inspect
+      "#<#{self.class}: #{@data.to_s}>"
+    end
+
+    # Describe the contents of this object in a string that exactly
+    # matches the string that would be created from an identical array.
+    #
+    # @return [String] the string representation of this object
+    #
+    # @!visibility private
+    def to_s
+      @data.to_s
+    end
+  end
+end