domain 0.0.1 → 1.0.0.rc1

data/README.md

@@ -1,7 +1,80 @@
-# Domain
+# Domain - Build data-types the easy way
 
-Provide tools for implementing domains (aka data types)
+This gem provides modules (module factories in fact) for creating domains, aka data-types, in a various common ways.
 
 ## Links
 
 https://github.com/blambeau/domain
+
+## Scalar domains
+
+A scalar domain has visible components that define the scalar structure of its values. For example a Point domain might have `x` and `y` components.
+
+    # Immediately create a Point class, that is, an implementation of the Point domain
+    # This is similar to `Struct.new(:x, :y)`
+    Point = Domain.scalar(:x, :y)
+
+    # Another way, if you want to define operators for the Point domain
+    class Point
+      extend Domain::Scalar.new(:x, :y)
+
+      def distance
+        Math.sqrt(x*x + y*y)
+      end
+    end
+
+    # in either case, `==`, `eql?` and `hash` are implemented in a consistent way
+    Point.new(1, 2) == Point.new(1, 2)
+
+## Reuse domains
+
+A domain can also be built by reuse (the current implementation only support reusing a single value) For instance, a List domain could simply be implemented by reusing an Array.
+
+    class List
+      extend Domain::Reuse.new(Array)
+
+      def head
+        # the reused instance is accessible under `reused_instance` (protected)
+        reused_instance.first
+      end
+
+      # reuse through delegation to `reused_instance`
+      delegate :each, :size, :empty?
+
+      # similar to `delegate` but redecorate the resulting value (will yield Lists)
+      reuse :map, :reject, :select
+    end
+
+    # The reused instance is expected to be passed at construction time
+    List.new [1, 2, 3]
+
+    # `==`, `eql?` and `hash` are already implemented in a consistent way
+    List.new([1, 2]) == List.new([1, 2])
+
+## Union domains
+
+A union domain is simply a domain whose values are the union of other domains. The missing Boolean domain can simply be defined as follows:
+
+    # Factors a Boolean domain immediately
+    Boolean = Domain.union(TrueClass, FalseClass)
+
+    # or use the module factory in your own class
+    class Boolean
+      extend Domain::Union.new(TrueClass, FalseClass)
+    end
+
+    # in either case, `===` is implemented in a consistent way
+    Boolean === true
+    Boolean === false
+
+## Specialization by constraints
+
+A domain can also be built through specialization by constraint, that is specifying a predicate that will filter the values of a super domain. For instance:
+
+    # Factors the set of positive integers
+    PosInt = Domain.sbyc(Integer){|i| i > 0}
+
+    # or use the module factory (you'll have to extend Integer yourself for consistency)
+    class PosInt < Integer
+      extend Domain::SByC.new(Integer){|i| i > 0}
+    end

data/domain.noespec

@@ -7,7 +7,7 @@ variables:
   upper:
     Domain
   version:
-    0.0.1
+    1.0.0.rc1
   summary: |-
     Provide tools for implementing domains (aka data types)
   description: |-

data/lib/domain.rb

@@ -1,8 +1,13 @@
+require_relative 'domain/version'
+require_relative 'domain/loader'
+require_relative 'domain/support'
+require_relative 'domain/api'
+require_relative 'domain/factory'
 #
 # Provide tools for implementing domains (aka data types)
 #
 module Domain
+  include API
+  extend  Factory
 
 end # module Domain
-require "domain/version"
-require "domain/loader"

data/lib/domain/api.rb

@@ -0,0 +1,48 @@
+module Domain
+  module API
+
+    # Returns the domain predicate, nil if no such predicate
+    #
+    # @return [Proc]
+    #   the domain predicate (possibly nil)
+    #
+    # @api public
+    def predicate
+      nil
+    end
+
+    # Returns the super domain of `self`.
+    #
+    # @return [Class]
+    #   the super domain of `self` as a ruby class
+    #
+    # @api public
+    def super_domain
+      superclass
+    end
+
+    # Returns the sub domains of `self`.
+    #
+    # @return [Array]
+    #   an array of sub domains (possibly empty)
+    #
+    # @api public
+    def sub_domains
+      []
+    end
+
+    # Returns true if this domain is a super domain of `dom`.
+    #
+    # @param [Class] dom
+    #   a domain
+    #
+    # @return [Boolean]
+    #   true if self is a super domain of `dom`, false otherwise
+    #
+    # @api public
+    def super_domain_of?(dom)
+      sub_domains.include?(dom)
+    end
+
+  end # module API
+end # module Domain

data/lib/domain/factory.rb

@@ -0,0 +1,52 @@
+require_relative 'factory/union'
+require_relative 'factory/sbyc'
+require_relative 'factory/scalar'
+require_relative 'factory/reuse'
+module Domain
+  module Factory
+    
+    # Creates a domain through specialization by constraint
+    #
+    # @param [Class] super_domain
+    #   the super_domain of the factored domain
+    # @param [Proc] pred
+    #   the domain predicate
+    #
+    # @return [Class]
+    #   the created domain as a ruby Class
+    #
+    # @api public
+    def sbyc(super_domain = Object, &pred)
+      Class.new(super_domain){ extend SByC.new(super_domain, pred) }
+    end
+
+    # Factors a union domain
+    #
+    # @param [Class] super_domain
+    #   the super_domain of the factored domain
+    # @param [Array] sub_domains
+    #   an array of sub domains for the factored domain
+    #
+    # @return [Class]
+    #   the created domain as a ruby Class
+    #
+    # @api public
+    def union(*sub_domains)
+      Class.new{ extend Union.new(*sub_domains) }
+    end
+
+    # Factors a scalar domain
+    #
+    # @param [Array] component_names
+    #   the component names as an array of symbols
+    #
+    # @return [Class]
+    #   the created domain as a ruby Class
+    #
+    # @api public
+    def scalar(*component_names)
+      Class.new{ extend Scalar.new(*component_names) }
+    end
+
+  end # module Factory
+end # module Domain

data/lib/domain/factory/reuse.rb

@@ -0,0 +1,53 @@
+module Domain
+  module Reuse
+
+    def self.new(reuse_domain, predicate = nil, &bl)
+      ImplDomain.new [ Methods, class_module(predicate || bl) ],
+                     [ instance_module(reuse_domain) ]
+    end
+
+    def self.class_module(predicate)
+      Module.new{ define_method(:predicate){ predicate } }
+    end
+
+    def self.instance_module(reuse_domain)
+      Module.new{
+        define_method(:initialize) do |arg|
+          unless reuse_domain===arg
+            raise ArgumentError, "#{reuse_domain} expected, got `#{arg.inspect}`"
+          end
+          if self.class.predicate && !self.class.predicate.call(arg)
+            raise ArgumentError, "Invalid value `#{arg.inspect}` for `#{self}`"
+          end
+          @reused_instance = arg
+        end
+        define_method(:reused_instance) do
+          @reused_instance
+        end
+        protected :reused_instance
+        include Equalizer.new(:reused_instance)
+      }
+    end
+
+    module Methods
+
+      def reuse(*methods)
+        methods.each do |m|
+          define_method(m) do |*args, &bl|
+            reused_instance.send(m, *args, &bl)
+          end
+        end
+      end
+
+      def recoat(*methods)
+        methods.each do |m|
+          define_method(m) do |*args, &bl|
+            self.class.new reused_instance.send(m, *args, &bl)
+          end
+        end
+      end
+
+    end # module Methods
+
+  end # module Reuse
+end # module Domain

data/lib/domain/factory/sbyc.rb

@@ -0,0 +1,9 @@
+module Domain
+  module SByC
+
+    def self.new(super_domain = Object, predicate = nil, &bl)
+      FakeDomain.new(super_domain, [], predicate || bl)
+    end
+
+  end # module SByC
+end # module Domain

data/lib/domain/factory/scalar.rb

@@ -0,0 +1,30 @@
+module Domain
+  module Scalar
+
+    def self.new(*component_names)
+      ImplDomain.new [], instance_module(component_names)
+    end
+
+    def self.instance_module(component_names)
+      Module.new{
+        define_method(:initialize) do |*args|
+          component_names.zip(args).each do |n,arg|
+            instance_variable_set(:"@#{n}", arg)
+          end
+        end
+        component_names.each do |n|
+          define_method(n) do
+            instance_variable_get(:"@#{n}")
+          end
+        end
+        define_method(:to_hash) do
+          component_names.each_with_object({}) do |n,h|
+            h[n] = instance_variable_get(:"@#{n}")
+          end
+        end
+        include Equalizer.new(component_names)
+      }
+    end
+
+  end # class Scalar
+end # module Domain

data/lib/domain/factory/union.rb

@@ -0,0 +1,11 @@
+module Domain
+  module Union
+
+    def self.new(*sub_domains)
+      FakeDomain.new(Object, sub_domains, lambda{|t| sub_domains.any?{|d| d===t } })
+    end
+
+  end # class Union
+end # module Domain
+
+    

data/lib/domain/support.rb

@@ -0,0 +1,3 @@
+require_relative 'support/equalizer'
+require_relative 'support/fake_domain'
+require_relative 'support/impl_domain'

data/lib/domain/support/equalizer.rb

@@ -0,0 +1,74 @@
+module Domain
+  class Equalizer < Module
+
+    # Parts of this module have been extracted from Virtus, MIT Copyright (c) 2011-2012
+    # Piotr Solnica.
+
+    # Creates an Equalizer instance.
+    #
+    # @param [Proc] bl
+    #   the proc to use to extract components that participate to equality
+    #
+    # @api private
+    def initialize(components = nil, &bl)
+      extractor = case components
+                  when NilClass then bl
+                  when Symbol   then proc{ [ send(components) ] }
+                  when Array    then proc{ components.map{|n| send(n)} }
+                  end
+      define_method(:equality_components, &extractor)
+      module_eval{ include(Methods) }
+    end
+
+    module Methods
+
+      # Returns a hash code for the value
+      #
+      # @return Integer
+      #
+      # @api public
+      def hash
+        equality_components.map{|c| c.hash }.reduce(self.class.hash, :^)
+      end
+
+      # Compare the object with other object for equality
+      #
+      # @example
+      #   object.eql?(other)  # => true or false
+      #
+      # @param [Object] other
+      #   the other object to compare with
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def eql?(other)
+        instance_of?(other.class) and cmp?(__method__, other)
+      end
+
+      # Compare the object with other object for equivalency
+      #
+      # @example
+      #   object == other  # => true or false
+      #
+      # @param [Object] other
+      #   the other object to compare with
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def ==(other)
+        return false unless self.class <=> other.class
+        cmp?(__method__, other)
+      end
+
+    private
+
+      def cmp?(comparator, other)
+        equality_components.zip(other.equality_components).
+                            all?{|l,r| l.send(comparator, r) }
+      end
+
+    end # module Methods
+  end # class Equalizer
+end # module Domain

data/lib/domain/support/fake_domain.rb

@@ -0,0 +1,38 @@
+module Domain
+  module FakeDomain
+
+    def self.new(super_domain, sub_domains, predicate)
+      Module.new{
+        include Domain, Methods
+        define_method(:super_domain){ super_domain }
+        define_method(:sub_domains) { sub_domains  }
+        define_method(:predicate)   { predicate    }
+      }
+    end
+
+    module Methods
+
+      # Creates a new instance of this domain
+      def new(*args)
+        if (args.size == 1) && self===args.first
+          return args.first
+        elsif superclass.respond_to?(:new) && (superclass != Object)
+          return new super(*args)
+        end
+        args_error_on_new(args)
+      end
+
+      # Checks if `value` belongs to this domain
+      def ===(value)
+        value.is_a?(superclass) && predicate && predicate.call(value)
+      end
+
+    private
+
+      def args_error_on_new(args)
+        raise ArgumentError, "Invalid value #{args.join(' ')} for #{self}", caller
+      end
+
+    end # module Methods
+  end # module FakeDomain
+end # module Domain

data/lib/domain/support/impl_domain.rb

@@ -0,0 +1,17 @@
+module Domain
+  module ImplDomain
+
+    def self.new(c_methods = [], i_methods = [])
+      i_methods = Array(i_methods)
+      c_methods = Array(c_methods).unshift(Domain)
+      Module.new{
+        c_methods.each{|c_m| include(c_m)}
+        define_singleton_method(:extend_object) do |obj|
+          obj.module_eval{ i_methods.each{|i_m| include(i_m)} } if obj.is_a?(Class)
+          super(obj)
+        end
+      }
+    end
+
+  end # module ImplDomain
+end # module Domain