functional-ruby 1.1.0 → 1.2.0

data/lib/functional/final_var.rb

@@ -1,4 +1,4 @@
-require 'thread'
+require 'functional/synchronization'
 
 module Functional
 
@@ -30,15 +30,20 @@ module Functional
   #   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
+  # @!macro [new] thread_safe_final_object
+  #
+  #   @note This is a write-once, read-many, thread safe object that can
+  #     be used in concurrent systems. Thread safety guarantees *cannot* be made
+  #     about objects contained *within* this object, however. Ruby variables are
+  #     mutable references to mutable objects. This cannot be changed. The best
+  #     practice it to only encapsulate immutable, frozen, or thread safe objects.
+  #     Ultimately, thread safety is the responsibility of the programmer.
+  class FinalVar < Synchronization::Object
 
-    # @!visibility private 
+    # @!visibility private
     NO_VALUE = Object.new.freeze
 
     # Create a new `FinalVar` with the given value or "unset" when
@@ -46,17 +51,15 @@ module Functional
     #
     # @param [Object] value if given, the immutable value of the object
     def initialize(value = NO_VALUE)
-      @mutex = Mutex.new
-      @value = value
+      super
+      synchronize{ @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
-      }
+      synchronize { has_been_set? ? @value : nil }
     end
     alias_method :value, :get
 
@@ -66,13 +69,13 @@ module Functional
     # @return [Object] the new value
     # @raise [Functional::FinalityError] if the value has already been set
     def set(value)
-      @mutex.synchronize {
+      synchronize do
         if has_been_set?
           raise FinalityError.new('value has already been set')
         else
           @value = value
         end
-      }
+      end
     end
     alias_method :value=, :set
 
@@ -80,9 +83,7 @@ module Functional
     #
     # @return [Boolean] true when the value has been set else false
     def set?
-      @mutex.synchronize {
-        has_been_set?
-      }
+      synchronize { has_been_set? }
     end
     alias_method :value?, :set?
 
@@ -91,13 +92,13 @@ module Functional
     # @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 {
+      synchronize do
         if has_been_set?
           @value
         else
           @value = value
         end
-      }
+      end
     end
 
     # Get the value if set else return the given default value.
@@ -105,9 +106,7 @@ module Functional
     # @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
-      }
+      synchronize { has_been_set? ? @value : default }
     end
 
     # Compares this object and other for equality. A `FinalVar` that is unset

data/lib/functional/memo.rb

@@ -1,4 +1,4 @@
-require 'thread'
+require 'functional/synchronization'
 
 module Functional
 
@@ -9,14 +9,12 @@ module Functional
   # 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.
+  # {include:file:doc/memo.md}
   #
-  # @since 1.0.0
+  # @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
 
     # @!visibility private
@@ -37,24 +35,36 @@ module Functional
     module ClassMethods
 
       # @!visibility private
-      Memo = Struct.new(:function, :mutex, :cache, :max_cache) do
+      class Memoizer < Synchronization::Object
+        attr_reader :function, :cache, :max_cache
+        def initialize(function, max_cache)
+          super
+          synchronize do
+            @function = function
+            @max_cache = max_cache
+            @cache = {}
+          end
+        end
         def max_cache?
           max_cache > 0 && cache.size >= max_cache
         end
+        public :synchronize
       end
+      private_constant :Memoizer
 
       # @!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.
+      # 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
+      # @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
@@ -63,7 +73,7 @@ module Functional
         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)
+        __method_memos__[func] = Memoizer.new(method(func), max_cache.to_i)
         __define_memo_proxy__(func)
         nil
       end
@@ -80,17 +90,16 @@ module Functional
       # @!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?
+        memo.synchronize do
+          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
         end
-      ensure
-        memo.mutex.unlock
       end
     end
   end

data/lib/functional/method_signature.rb

@@ -6,8 +6,6 @@ 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
 
@@ -70,5 +68,6 @@ module Functional
         param == PatternMatching::UNBOUND || param == arg
       end
     end
+    private_constant :MethodSignature
   end
 end

data/lib/functional/option.rb

@@ -1,6 +1,7 @@
-require_relative 'abstract_struct'
-require_relative 'either'
-require_relative 'protocol'
+require 'functional/abstract_struct'
+require 'functional/either'
+require 'functional/protocol'
+require 'functional/synchronization'
 
 Functional::SpecifyProtocol(:Option) do
   instance_method :some?, 0
@@ -14,13 +15,10 @@ module Functional
   # 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
   #
-  # @since 1.0.0
-  #
   # @!macro thread_safe_immutable_object
-  class Option
+  class Option < Synchronization::Object
     include AbstractStruct
 
     # @!visibility private 
@@ -201,11 +199,13 @@ module Functional
     #
     # @!visibility private 
     def initialize(value, none, reason = nil)
+      super
       @none = none
       @reason = none ? reason : nil
       hsh = none ? {some: nil} : {some: value}
       set_data_hash(hsh)
       set_values_array(hsh.values)
+      ensure_ivar_visibility!
     end
   end
 end

data/lib/functional/pattern_matching.rb

@@ -1,17 +1,17 @@
-require_relative 'method_signature'
+require 'functional/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
+  # 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
+  # {include:file:doc/pattern_matching.md}
   module PatternMatching
 
     # A parameter that is required but that can take any value.
@@ -40,9 +40,11 @@ module Functional
         self
       end
     end
+    private_constant :GuardClause
 
     # @!visibility private
     FunctionPattern = Struct.new(:function, :args, :body, :guard)
+    private_constant :FunctionPattern
 
     # @!visibility private
     def __unbound_args__(match, args)
@@ -55,7 +57,7 @@ module Functional
             argv << args[i][key] if value == UNBOUND
           end
         elsif p.is_a?(Hash) || p == UNBOUND || p.is_a?(Class)
-          argv << args[i] 
+          argv << args[i]
         end
       end
       argv

data/lib/functional/protocol.rb

@@ -1,4 +1,4 @@
-require_relative 'protocol_info'
+require 'functional/protocol_info'
 
 module Functional
 
@@ -55,10 +55,8 @@ module Functional
   # interrogate a module, class, or object for its type and ancestry, protocols
   # allow modules, classes, and methods to be interrogated based on their behavior.
   # It is a logical extension of the `respond_to?` method, but vastly more powerful.
-  #   
-  # @!macro protocol
   #
-  # @since 1.0.0 (formerly "behavior")
+  # {include:file:doc/protocol.md}
   module Protocol
 
     # The global registry of specified protocols.

data/lib/functional/protocol_info.rb

@@ -1,12 +1,12 @@
+require 'functional/synchronization'
+
 module Functional
 
   # An immutable object describing a single protocol and capable of building
   # itself from a block. Used by {Functional#SpecifyProtocol}.
   # 
   # @see Functional::Protocol
-  #
-  # @since 1.0.0
-  class ProtocolInfo
+  class ProtocolInfo < Synchronization::Object
 
     # The symbolic name of the protocol
     attr_reader :name
@@ -22,11 +22,13 @@ module Functional
     def initialize(name, &specification)
       raise ArgumentError.new('no block given') unless block_given?
       raise ArgumentError.new('no name given') if name.nil? || name.empty?
+      super
       @name = name.to_sym
       @info = Info.new({}, {}, [])
       self.instance_eval(&specification)
       @info.each_pair{|col, _| col.freeze}
       @info.freeze
+      ensure_ivar_visibility!
       self.freeze
     end
 

data/lib/functional/record.rb

@@ -1,5 +1,6 @@
-require_relative 'abstract_struct'
-require_relative 'type_check'
+require 'functional/abstract_struct'
+require 'functional/protocol'
+require 'functional/type_check'
 
 module Functional
 
@@ -8,18 +9,17 @@ module Functional
   # using accessor methods, without having to write an explicit class.
   # The `Record` module generates new `AbstractStruct` subclasses that hold a
   # set of fields with a reader method for each field.
-  #   
+  #
   # A `Record` is very similar to a Ruby `Struct` and shares many of its behaviors
   # and attributes. Unlike a # Ruby `Struct`, a `Record` is immutable: its values
   # are set at construction and can never be changed. Divergence between the two
   # classes derive from this core difference.
-  #   
-  # @!macro record
   #
-  # @see Functional::AbstractStruct
-  # @see Functional::Union
+  # {include:file:doc/record.md}
   #
-  # @since 1.0.0
+  # @see Functional::Union
+  # @see Functional::Protocol
+  # @see Functional::TypeCheck
   #
   # @!macro thread_safe_immutable_object
   module Record
@@ -28,10 +28,30 @@ module Functional
     # Create a new record class with the given fields.
     #
     # @return [Functional::AbstractStruct] the new record subclass
-    # @raise [ArgumentError] no fields specified
+    # @raise [ArgumentError] no fields specified or an invalid type
+    #   specification is given
     def new(*fields, &block)
       raise ArgumentError.new('no fields provided') if fields.empty?
-      build(fields, &block)
+
+      name = nil
+      types = nil
+
+      # check if a name for registration is given
+      if fields.first.is_a?(String)
+        name = fields.first
+        fields = fields[1..fields.length-1]
+      end
+
+      # check for a set of type/protocol specifications
+      if fields.size == 1 && fields.first.respond_to?(:to_h)
+        types = fields.first
+        fields = fields.first.keys
+        check_types!(types)
+      end
+
+      build(name, fields, types, &block)
+    rescue
+      raise ArgumentError.new('invalid specification')
     end
 
     private
@@ -40,14 +60,18 @@ module Functional
     #
     # A set of restrictions governing the creation of a new record.
     class Restrictions
+      include Protocol
       include TypeCheck
 
       # Create a new restrictions object by processing the given
       # block. The block should be the DSL for defining a record class.
       #
+      # @param [Hash] types a hash of fields and the associated type/protocol
+      #   when type/protocol checking is among the restrictions
       # @param [Proc] block A DSL definition of a new record.
       # @yield A DSL definition of a new record.
-      def initialize(&block)
+      def initialize(types = nil, &block)
+        @types = types
         @required = []
         @defaults = {}
         instance_eval(&block) if block_given?
@@ -86,18 +110,44 @@ module Functional
         return value
       end
 
+      # Validate the record data against this set of restrictions.
+      #
+      # @param [Hash] data the data hash
+      # @raise [ArgumentError] when the data does not match the restrictions
+      def validate!(data)
+        validate_mandatory!(data)
+        validate_types!(data)
+      end
+
+      private
+
       # Check the given data hash to see if it contains non-nil values for
       # all mandatory fields.
       #
       # @param [Hash] data the data hash
       # @raise [ArgumentError] if any mandatory fields are missing
-      def check_mandatory!(data)
+      def validate_mandatory!(data)
         if data.any?{|k,v| @required.include?(k) && v.nil? }
           raise ArgumentError.new('mandatory fields must not be nil')
         end
       end
 
-      private
+      # Validate the record data against a type/protocol specification.
+      #
+      # @param [Hash] data the data hash
+      # @raise [ArgumentError] when the data does not match the specification
+      def validate_types!(data)
+        return if @types.nil?
+        @types.each do |field, type|
+          value = data[field]
+          next if value.nil?
+          if type.is_a? Module
+            raise ArgumentError.new("'#{field}' must be of type #{type}") unless Type?(value, type)
+          else
+            raise ArgumentError.new("'#{field}' must stasify the protocol :#{type}") unless Satisfy?(value, type)
+          end
+        end
+      end
 
       # Is the given object uncloneable?
       #
@@ -107,15 +157,29 @@ module Functional
         Type? object, NilClass, TrueClass, FalseClass, Fixnum, Bignum, Float
       end
     end
+    private_constant :Restrictions
+
+    # Validate the given type/protocol specification.
+    #
+    # @param [Hash] types the type specification
+    # @raise [ArgumentError] when the specification is not valid
+    def check_types!(types)
+      return if types.nil?
+      unless types.all?{|k,v| v.is_a?(Module) || v.is_a?(Symbol) }
+        raise ArgumentError.new('invalid specification')
+      end
+    end
 
     # Use the given `AbstractStruct` class and build the methods necessary
     # to support the given data fields.
     #
+    # @param [String] name the name under which to register the record when given
     # @param [Array] fields the list of symbolic names for all data fields
     # @return [Functional::AbstractStruct] the record class
-    def build(fields, &block)
+    def build(name, fields, types, &block)
+      fields = [name].concat(fields) unless name.nil?
       record, fields = AbstractStruct.define_class(self, :record, fields)
-      record.class_variable_set(:@@restrictions, Restrictions.new(&block))
+      record.class_variable_set(:@@restrictions, Restrictions.new(types, &block))
       define_initializer(record)
       fields.each do |field|
         define_reader(record, field)
@@ -129,14 +193,16 @@ module Functional
     # @return [Functional::AbstractStruct] the record class
     def define_initializer(record)
       record.send(:define_method, :initialize) do |data = {}|
+        super()
         restrictions = record.class_variable_get(:@@restrictions)
         data = record.fields.reduce({}) do |memo, field|
           memo[field] = data.fetch(field, restrictions.clone_default(field))
           memo
         end
-        restrictions.check_mandatory!(data)
+        restrictions.validate!(data)
         set_data_hash(data)
         set_values_array(data.values)
+        ensure_ivar_visibility!
         self.freeze
       end
       record