functional-ruby 0.7.7 → 1.0.0

data/lib/functional/protocol.rb

@@ -0,0 +1,157 @@
+require_relative 'protocol_info'
+
+module Functional
+
+  # An exception indicating a problem during protocol processing.
+  ProtocolError = Class.new(StandardError)
+
+  # Specify a new protocol or retrieve the specification of an existing
+  # protocol.
+  #
+  # When called without a block the global protocol registry will be searched
+  # for a protocol with the matching name. If found the corresponding
+  # {Functional::ProtocolInfo} object will be returned. If not found `nil` will
+  # be returned.
+  #
+  # When called with a block, a new protocol with the given name will be
+  # created and the block will be processed to provide the specifiction.
+  # When successful the new {Functional::ProtocolInfo} object will be returned.
+  # An exception will be raised if a protocol with the same name already
+  # exists.
+  #
+  # @example
+  #   Functional::SpecifyProtocol(:Queue) do
+  #     instance_method :push, 1
+  #     instance_method :pop, 0
+  #     instance_method :length, 0
+  #   end
+  #
+  # @param [Symbol] name The global name of the new protocol
+  # @yield The protocol definition
+  # @return [Functional::ProtocolInfo] the newly created or already existing
+  #   protocol specification
+  #
+  # @raise [Functional::ProtocolError] when attempting to specify a protocol
+  #   that has already been specified.
+  #
+  # @see Functional::Protocol
+  def SpecifyProtocol(name, &block)
+    name = name.to_sym
+    protocol_info = Protocol.class_variable_get(:@@info)[name]
+
+    return protocol_info unless block_given?
+
+    if block_given? && protocol_info
+      raise ProtocolError.new(":#{name} has already been defined")
+    end
+
+    info = ProtocolInfo.new(name, &block)
+    Protocol.class_variable_get(:@@info)[name] = info
+  end
+  module_function :SpecifyProtocol
+
+  # Protocols provide a polymorphism and method-dispatch mechanism that exchews
+  # stong typing and embraces the dynamic duck typing of Ruby. Rather than
+  # 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
+  module Protocol
+
+    # The global registry of specified protocols.
+    @@info = {}
+
+    # Does the given module/class/object fully satisfy the given protocol(s)?
+    #
+    # @param [Object] target the method/class/object to interrogate
+    # @param [Symbol] protocols one or more protocols to check against the target
+    # @return [Boolean] true if the target satisfies all given protocols else false
+    #
+    # @raise [ArgumentError] when no protocols given
+    def Satisfy?(target, *protocols)
+      raise ArgumentError.new('no protocols given') if protocols.empty?
+      protocols.all?{|protocol| Protocol.satisfies?(target, protocol.to_sym) }
+    end
+    module_function :Satisfy?
+
+    # Does the given module/class/object fully satisfy the given protocol(s)?
+    # Raises a {Functional::ProtocolError} on failure.
+    #
+    # @param [Object] target the method/class/object to interrogate
+    # @param [Symbol] protocols one or more protocols to check against the target
+    # @return [Symbol] the target
+    #
+    # @raise [Functional::ProtocolError] when one or more protocols are not satisfied
+    # @raise [ArgumentError] when no protocols given
+    def Satisfy!(target, *protocols)
+      Protocol::Satisfy?(target, *protocols) or
+        Protocol.error(target, 'does not', *protocols)
+      target
+    end
+    module_function :Satisfy!
+
+    # Have the given protocols been specified?
+    #
+    # @param [Symbol] protocols the list of protocols to check
+    # @return [Boolean] true if all given protocols have been specified else false
+    #
+    # @raise [ArgumentError] when no protocols are given
+    def Specified?(*protocols)
+      raise ArgumentError.new('no protocols given') if protocols.empty?
+      Protocol.unspecified(*protocols).empty?
+    end
+    module_function :Specified?
+
+    # Have the given protocols been specified?
+    # Raises a {Functional::ProtocolError} on failure.
+    #
+    # @param [Symbol] protocols the list of protocols to check
+    # @return [Boolean] true if all given protocols have been specified
+    #
+    # @raise [Functional::ProtocolError] if one or more of the given protocols have
+    #   not been specified
+    # @raise [ArgumentError] when no protocols are given
+    def Specified!(*protocols)
+      raise ArgumentError.new('no protocols given') if protocols.empty?
+      (unspecified = Protocol.unspecified(*protocols)).empty? or
+        raise ProtocolError.new("The following protocols are unspecified: :#{unspecified.join('; :')}.")
+    end
+    module_function :Specified!
+
+    private
+
+    # Does the target satisfy the given protocol?
+    #
+    # @param [Object] target the module/class/object to check
+    # @param [Symbol] protocol the protocol to check against the target
+    # @return [Boolean] true if the target satisfies the protocol else false
+    def self.satisfies?(target, protocol)
+      info = @@info[protocol]
+      return info && info.satisfies?(target)
+    end
+
+    # Reduces a list of protocols to a list of unspecified protocols.
+    #
+    # @param [Symbol] protocols the list of protocols to check
+    # @return [Array] zero or more unspecified protocols
+    def self.unspecified(*protocols)
+      protocols.drop_while do |protocol|
+        @@info.has_key? protocol.to_sym
+      end
+    end
+
+    # Raise a {Functional::ProtocolError} formatted with the given data.
+    #
+    # @param [Object] target the object that was being interrogated
+    # @param [String] message the message fragment to inject into the error
+    # @param [Symbol] protocols list of protocols that were being checked against the target
+    #
+    # @raise [Functional::ProtocolError] the formatted exception object
+    def self.error(target, message, *protocols)
+      target = target.class unless target.is_a?(Module)
+      raise ProtocolError,
+        "Value (#{target.class}) '#{target}' #{message} behave as all of: :#{protocols.join('; :')}."
+    end
+  end
+end

data/lib/functional/protocol_info.rb

@@ -0,0 +1,193 @@
+module Functional
+
+  # An immutable object describing a single protocol and capable of building
+  # itself from a block. Used by {Functional#SpecifyProtocol}.
+  # 
+  # @see Functional::Protocol
+  class ProtocolInfo
+
+    # The symbolic name of the protocol
+    attr_reader :name
+
+    # Process a protocol specification block and build a new object.
+    #
+    # @param [Symbol] name the symbolic name of the protocol
+    # @yield self to the given specification block
+    # @return [Functional::ProtocolInfo] the new info object, frozen
+    #
+    # @raise [ArgumentError] when name is nil or an empty string
+    # @raise [ArgumentError] when no block given
+    def initialize(name, &specification)
+      raise ArgumentError.new('no block given') unless block_given?
+      raise ArgumentError.new('no name given') if name.nil? || name.empty?
+      @name = name.to_sym
+      @info = Info.new({}, {}, [])
+      self.instance_eval(&specification)
+      @info.each_pair{|col, _| col.freeze}
+      @info.freeze
+      self.freeze
+    end
+
+    # The instance methods expected by this protocol.
+    #
+    # @return [Hash] a frozen hash of all instance method names and their
+    #   expected arity for this protocol
+    def instance_methods
+      @info.instance_methods
+    end
+
+    # The class methods expected by this protocol.
+    #
+    # @return [Hash] a frozen hash of all class method names and their
+    #   expected arity for this protocol
+    def class_methods
+      @info.class_methods
+    end
+
+    # The constants expected by this protocol.
+    #
+    # @return [Array] a frozen list of the constants expected by this protocol
+    def constants
+      @info.constants
+    end
+
+    # Does the given module/class/object satisfy this protocol?
+    #
+    # @return [Boolean] true if the target satisfies this protocol else false
+    def satisfies?(target)
+      satisfies_constants?(target) &&
+        satisfies_instance_methods?(target) &&
+        satisfies_class_methods?(target)
+    end
+
+    private
+
+    # Data structure for encapsulating the protocol info data.
+    Info = Struct.new(:instance_methods, :class_methods, :constants)
+
+    # Does the target satisfy the constants expected by this protocol?
+    #
+    # @param [target] target the module/class/object to interrogate
+    # @return [Boolean] true when satisfied else false
+    def satisfies_constants?(target)
+      clazz = target.is_a?(Module) ? target : target.class
+      @info.constants.all?{|constant| clazz.const_defined?(constant) }
+    end
+
+    # Does the target satisfy the instance methods expected by this protocol?
+    #
+    # @param [target] target the module/class/object to interrogate
+    # @return [Boolean] true when satisfied else false
+    def satisfies_instance_methods?(target)
+      @info.instance_methods.all? do |method, arity|
+        if target.is_a? Module
+          target.method_defined?(method) && check_arity?(target.instance_method(method), arity)
+        else
+          target.respond_to?(method) && check_arity?(target.method(method), arity)
+        end
+      end
+    end
+
+
+    # Does the target satisfy the class methods expected by this protocol?
+    #
+    # @param [target] target the module/class/object to interrogate
+    # @return [Boolean] true when satisfied else false
+    def satisfies_class_methods?(target)
+      clazz = target.is_a?(Module) ? target : target.class
+      @info.class_methods.all? do |method, arity|
+        break false unless clazz.respond_to? method
+        method = clazz.method(method)
+        check_arity?(method, arity)
+      end
+    end
+
+    # Does the given method have the expected arity? Returns true
+    # if the arity of the method is `-1` (variable length argument list
+    # with no required arguments), when expected is `nil` (indicating any
+    # arity is acceptable), or the arity of the method exactly matches the
+    # expected arity.
+    #
+    # @param [Method] method the method object to interrogate
+    # @param [Fixnum] expected the expected arity
+    # @return [Boolean] true when an acceptable match else false
+    #
+    # @see http://www.ruby-doc.org/core-2.1.2/Method.html#method-i-arity Method#arity
+    def check_arity?(method, expected)
+      arity = method.arity
+      expected.nil? || arity == -1 || expected == arity
+    end
+
+    #################################################################
+    # DSL methods
+
+    # Specify an instance method.
+    #
+    # @param [Symbol] name the name of the method
+    # @param [Fixnum] arity the required arity
+    def instance_method(name, arity = nil)
+      arity = arity.to_i unless arity.nil?
+      @info.instance_methods[name.to_sym] = arity
+    end
+
+    # Specify a class method.
+    #
+    # @param [Symbol] name the name of the method
+    # @param [Fixnum] arity the required arity
+    def class_method(name, arity = nil)
+      arity = arity.to_i unless arity.nil?
+      @info.class_methods[name.to_sym] = arity
+    end
+
+    # Specify an instance reader attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def attr_reader(name)
+      instance_method(name, 0)
+    end
+
+    # Specify an instance writer attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def attr_writer(name)
+      instance_method("#{name}=".to_sym, 1)
+    end
+
+    # Specify an instance accessor attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def attr_accessor(name)
+      attr_reader(name)
+      attr_writer(name)
+    end
+
+    # Specify a class reader attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def class_attr_reader(name)
+      class_method(name, 0)
+    end
+
+    # Specify a class writer attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def class_attr_writer(name)
+      class_method("#{name}=".to_sym, 1)
+    end
+
+    # Specify a class accessor attribute.
+    #
+    # @param [Symbol] name the name of the attribute
+    def class_attr_accessor(name)
+      class_attr_reader(name)
+      class_attr_writer(name)
+    end
+
+    # Specify a constant.
+    #
+    # @param [Symbol] name the name of the constant
+    def constant(name)
+      @info.constants << name.to_sym
+    end
+  end
+end

data/lib/functional/record.rb

@@ -0,0 +1,155 @@
+require_relative 'abstract_struct'
+require_relative 'type_check'
+
+module Functional
+
+  # An immutable data structure with multiple data fields. A `Record` is a
+  # convenient way to bundle a number of field attributes together,
+  # 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
+  #
+  # @!macro thread_safe_immutable_object
+  module Record
+    extend self
+
+    # Create a new record class with the given fields.
+    #
+    # @return [Functional::AbstractStruct] the new record subclass
+    # @raise [ArgumentError] no fields specified
+    def new(*fields, &block)
+      raise ArgumentError.new('no fields provided') if fields.empty?
+      build(fields, &block)
+    end
+
+    private
+
+    # @!visibility private
+    #
+    # A set of restrictions governing the creation of a new record.
+    class Restrictions
+      include TypeCheck
+
+      # Create a new restrictions object by processing the given
+      # block. The block should be the DSL for defining a record class.
+      #
+      # @param [Proc] block A DSL definition of a new record.
+      # @yield A DSL definition of a new record.
+      def initialize(&block)
+        @required = []
+        @defaults = {}
+        instance_eval(&block) if block_given?
+        @required.freeze
+        @defaults.freeze
+        self.freeze
+      end
+
+      # DSL method for declaring one or more fields to be mandatory.
+      #
+      # @param [Symbol] fields zero or more mandatory fields
+      def mandatory(*fields)
+        @required.concat(fields.collect{|field| field.to_sym})
+      end
+
+      # DSL method for declaring a default value for a field
+      #
+      # @param [Symbol] field the field to be given a default value
+      # @param [Object] value the default value of the field
+      def default(field, value)
+        @defaults[field] = value
+      end
+
+      # Clone a default value if it is cloneable. Else just return
+      # the value.
+      #
+      # @param [Symbol] field the name of the field from which the
+      #   default value is to be cloned.
+      # @return [Object] a clone of the value or the value if uncloneable
+      def clone_default(field)
+        value = @defaults[field]
+        value = value.clone unless uncloneable?(value)
+      rescue TypeError
+        # can't be cloned
+      ensure
+        return value
+      end
+
+      # 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)
+        if data.any?{|k,v| @required.include?(k) && v.nil? }
+          raise ArgumentError.new('mandatory fields must not be nil')
+        end
+      end
+
+      private
+
+      # Is the given object uncloneable?
+      #
+      # @param [Object] object the object to check
+      # @return [Boolean] true if the object cannot be cloned else false
+      def uncloneable?(object)
+        Type? object, NilClass, TrueClass, FalseClass, Fixnum, Bignum, Float
+      end
+    end
+
+    # Use the given `AbstractStruct` class and build the methods necessary
+    # to support the given data fields.
+    #
+    # @param [Array] fields the list of symbolic names for all data fields
+    # @return [Functional::AbstractStruct] the record class
+    def build(fields, &block)
+      record, fields = AbstractStruct.define_class(self, :record, fields)
+      record.class_variable_set(:@@restrictions, Restrictions.new(&block))
+      define_initializer(record)
+      fields.each do |field|
+        define_reader(record, field)
+      end
+      record
+    end
+
+    # Define an initializer method on the given record class.
+    #
+    # @param [Functional::AbstractStruct] record the new record class
+    # @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|
+          memo[field] = data.fetch(field, restrictions.clone_default(field))
+          memo
+        end
+        restrictions.check_mandatory!(data)
+        set_data_hash(data)
+        set_values_array(data.values)
+        self.freeze
+      end
+      record
+    end
+
+    # Define a reader method on the given record class for the given data field.
+    #
+    # @param [Functional::AbstractStruct] record the new record class
+    # @param [Symbol] field symbolic name of the current data field
+    # @return [Functional::AbstractStruct] the record class
+    def define_reader(record, field)
+      record.send(:define_method, field) do
+        to_h[field]
+      end
+      record
+    end
+  end
+end