myrrha 1.2.2 → 2.0.0

data/lib/myrrha/coercions.rb

@@ -0,0 +1,265 @@
+module Myrrha
+  # Defines a set of coercion rules
+  #
+  class Coercions
+
+    # @return [Domain] The main target domain, if any
+    attr_accessor :main_target_domain
+
+    # Creates an empty list of coercion rules
+    def initialize(&defn)
+      @definitions = []
+      @upons = []
+      @rules = []
+      @fallbacks = []
+      @appender = :<<
+      @main_target_domain = nil
+      extend_rules(:<<, defn) if defn
+    end
+
+    # Appends the list of rules with new ones.
+    #
+    # New upon, coercion and fallback rules will be put after the already
+    # existing ones, in each case.
+    #
+    # Example:
+    #
+    #   rules = Myrrha.coercions do ... end
+    #   rules.append do |r|
+    #
+    #     # [previous coercion rules would come here]
+    #
+    #     # install new rules
+    #     r.coercion String, Float, lambda{|v,t| Float(t)}
+    #   end
+    #
+    def append(&proc)
+      extend_rules(:<<, proc)
+    end
+
+    # Prepends the list of rules with new ones.
+    #
+    # New upon, coercion and fallback rules will be put before the already
+    # existing ones, in each case.
+    #
+    # Example:
+    #
+    #   rules = Myrrha.coercions do ... end
+    #   rules.prepend do |r|
+    #
+    #     # install new rules
+    #     r.coercion String, Float, lambda{|v,t| Float(t)}
+    #
+    #     # [previous coercion rules would come here]
+    #
+    #   end
+    #
+    def prepend(&proc)
+      extend_rules(:unshift, proc)
+    end
+
+    # Adds an upon rule for a source domain.
+    #
+    # Example:
+    #
+    #   Myrrha.coercions do |r|
+    #
+    #     # Don't even try something else on nil
+    #     r.upon(NilClass){|s,t| nil}
+    #     [...]
+    #
+    #   end
+    #
+    # @param source [Domain] a source domain (mimic Domain)
+    # @param converter [Converter] an optional converter (mimic Converter)
+    # @param convproc [Proc] used when converter is not specified
+    # @return self
+    #
+    def upon(source, converter = nil, &convproc)
+      @upons.send(@appender, [source, nil, converter || convproc])
+      self
+    end
+
+    # Adds an upon rule that works by delegation if the value responds to `method`.
+    #
+    # Example:
+    #
+    #     Myrrha.coercions do |r|
+    #       r.delegate(:to_foo)
+    #
+    #       # is a shortcut for
+    #       r.upon(lambda{|v,_| v.respond_to?(:to_foo)}){|v,_| v.to_foo}
+    #     end
+    #
+    def delegate(method, &convproc)
+      convproc ||= lambda{|v,t| v.send(method) }
+      upon(lambda{|v,t| v.respond_to?(method) }, convproc)
+    end
+
+    # Adds a coercion rule from a source to a target domain.
+    #
+    # The conversion can be provided through `converter` or via a block
+    # directly. See main documentation about recognized converters.
+    #
+    # Example:
+    #
+    #   Myrrha.coercions do |r|
+    #
+    #     # With an explicit proc
+    #     r.coercion String, Integer, lambda{|v,t|
+    #       Integer(v)
+    #     }
+    #
+    #     # With an implicit proc
+    #     r.coercion(String, Float) do |v,t|
+    #       Float(v)
+    #     end
+    #
+    #   end
+    #
+    # @param source [Domain] a source domain (mimicing Domain)
+    # @param target [Domain] a target domain (mimicing Domain)
+    # @param converter [Converter] an optional converter (mimic Converter)
+    # @param convproc [Proc] used when converter is not specified
+    # @return self
+    #
+    def coercion(source, target = main_target_domain, converter = nil, &convproc)
+      @rules.send(@appender, [source, target, converter || convproc])
+      self
+    end
+
+    # Adds a fallback rule for a source domain.
+    #
+    # Example:
+    #
+    #   Myrrha.coercions do |r|
+    #
+    #     # Add a 'last chance' rule for Strings
+    #     r.fallback(String) do |v,t|
+    #       # the user wants _v_ to be converted to a value of domain _t_
+    #     end
+    #
+    #   end
+    #
+    # @param source [Domain] a source domain (mimic Domain)
+    # @param converter [Converter] an optional converter (mimic Converter)
+    # @param convproc [Proc] used when converter is not specified
+    # @return self
+    #
+    def fallback(source, converter = nil, &convproc)
+      @fallbacks.send(@appender, [source, nil, converter || convproc])
+      self
+    end
+
+    # Coerces `value` to an element of `target_domain`
+    #
+    # This method tries each coercion rule, then each fallback in turn. Rules
+    # for which source and target domain match are executed until one succeeds.
+    # A Myrrha::Error is raised if no rule matches or executes successfuly.
+    #
+    # @param [Object] value any ruby value
+    # @param [Domain] target_domain a target domain to convert to (mimic Domain)
+    # @return self
+    #
+    def coerce(value, target_domain = main_target_domain)
+      return value if belongs_to?(value, target_domain)
+      error = nil
+      each_rule do |from,to,converter|
+        next unless from.nil? or belongs_to?(value, from, target_domain)
+        begin
+          catch(:nextrule) do
+            if to.nil? or subdomain?(to, target_domain)
+              got = convert(value, target_domain, converter)
+              return got
+            elsif subdomain?(target_domain, to)
+              got = convert(value, to, converter)
+              return got if belongs_to?(got, target_domain)
+            end
+          end
+        rescue => ex
+          error = ex unless error
+        end
+      end
+      raise Error.new("Unable to coerce `#{value}` to #{target_domain}", error)
+    end
+    alias :apply :coerce
+
+    # Duplicates this set of rules in such a way that the original will not
+    # be affected by any change made to the copy.
+    #
+    # @return [Coercions] a copy of this set of rules
+    #
+    def dup
+      c = Coercions.new
+      @definitions.each do |defn|
+        c.extend_rules(*defn)
+      end
+      c
+    end
+
+  protected
+
+    # Returns true if `value` can be considered as a valid element of the
+    # domain `domain`, false otherwise.
+    #
+    # @param [Object] value any ruby value
+    # @param [Domain] domain a domain (mimic Domain)
+    # @return [Boolean] true if `value` belongs to `domain`, false otherwise
+    #
+    def belongs_to?(value, domain, target_domain = domain)
+      if domain.is_a?(Proc) and domain.arity==2
+        domain.call(value, target_domain)
+      else
+        domain.respond_to?(:===) && (domain === value)
+      end
+    end
+
+    # Returns `true` if `child` can be considered a valid sub domain of
+    # `parent`, false otherwise.
+    #
+    # @param [Domain] child a domain (mimic Domain)
+    # @param [Domain] parent another domain (mimic Domain)
+    # @return [Boolean] true if `child` is a subdomain of `parent`, false
+    #         otherwise.
+    #
+    def subdomain?(child, parent)
+      if child == parent
+        true
+      elsif parent.respond_to?(:superdomain_of?)
+        parent.superdomain_of?(child)
+      elsif child.respond_to?(:superclass) && child.superclass
+        subdomain?(child.superclass, parent)
+      else
+        false
+      end
+    end
+
+    # Extends existing rules
+    def extend_rules(appender, block)
+      @definitions << [appender, block]
+      @appender = appender
+      block.call(self)
+      self
+    end
+
+    # Yields each rule in turn (upons, coercions then fallbacks)
+    def each_rule(&proc)
+      @upons.each(&proc)
+      @rules.each(&proc)
+      @fallbacks.each(&proc)
+    end
+
+    # Calls converter on a (value,target_domain) pair.
+    def convert(value, target_domain, converter)
+      if converter.respond_to?(:call)
+        converter.call(value, target_domain)
+      elsif converter.is_a?(Array)
+        path = converter + [target_domain]
+        path.inject(value){|cur,ndom| coerce(cur, ndom)}
+      else
+        raise ArgumentError, "Unable to use #{converter} for coercing"
+      end
+    end
+
+  end # class Coercions
+end # module Myrrha

data/lib/myrrha/domain.rb

@@ -0,0 +1,18 @@
+module Myrrha
+  module Domain
+
+    # Creates a domain instance by specialization by constraint
+    #
+    # @param [Class] superdom the superdomain of the created domain
+    # @param [Proc] pred the domain predicate
+    # @return [Class] the created domain
+    def self.sbyc(superdom = Object, subdoms = [], &pred)
+      Class.new(superdom).extend SByC.new(superdom, subdoms, pred)
+    end
+
+  end # module Domain
+end # module Myrrha
+require_relative 'domain/value_methods'
+require_relative 'domain/coercion_methods'
+require_relative 'domain/impl'
+require_relative 'domain/sbyc'

data/lib/myrrha/domain/coercion_methods.rb

@@ -0,0 +1,17 @@
+module Myrrha
+  module Domain
+    module CoercionMethods
+
+      def coercions(&bl)
+        @coercions ||= Coercions.new{|c| c.main_target_domain = self}
+        @coercions.append(&bl) if bl
+        @coercions
+      end
+
+      def coerce(arg)
+        coercions.coerce(arg, self)
+      end
+
+    end # module CoercionMethods
+  end # module Domain
+end # module Myrrha

data/lib/myrrha/domain/impl.rb

@@ -0,0 +1,50 @@
+module Myrrha
+  module Domain
+    class Impl < Module
+
+      def initialize(component_names)
+        @component_names = component_names.freeze
+        define_initialize
+        define_component_readers
+        include_value_methods
+      end
+
+      def included(clazz)
+        define_component_names_on(clazz)
+        define_coercion_methods_on(clazz)
+        super
+      end
+
+    private
+
+      def define_initialize
+        component_names = @component_names
+        define_method(:initialize){|*args|
+          component_names.zip(args).each do |n,arg|
+            instance_variable_set(:"@#{n}", arg)
+          end
+        }
+      end
+
+      def define_component_readers
+        @component_names.each do |n|
+          define_method(n){ instance_variable_get(:"@#{n}") }
+        end
+      end
+
+      def include_value_methods
+        module_eval{ include ValueMethods }
+      end
+
+      def define_component_names_on(clazz)
+        component_names = @component_names
+        clazz.define_singleton_method(:component_names){ component_names }
+      end
+
+      def define_coercion_methods_on(clazz)
+        clazz.extend(CoercionMethods)
+      end
+
+    end # class Impl
+  end # module Domain
+end # module Myrrha

data/lib/myrrha/domain/sbyc.rb

@@ -0,0 +1,78 @@
+module Myrrha
+  module Domain
+    class SByC < Module
+
+      def initialize(super_domain, sub_domains, predicate)
+        @super_domain = super_domain
+        @sub_domains = sub_domains
+        @predicate = predicate
+        define
+      end
+
+    private
+
+      def define
+        define_super_domain_method
+        define_sub_domains_method
+        define_predicate_method
+        include_type_methods
+        include_coercion_methods
+      end
+
+      def define_super_domain_method
+        super_domain = @super_domain
+        define_method(:super_domain){ super_domain }
+      end
+
+      def define_sub_domains_method
+        sub_domains = @sub_domains
+        define_method(:sub_domains){ sub_domains }
+      end
+
+      def define_predicate_method
+        predicate = @predicate
+        define_method(:predicate){ predicate }
+      end
+
+      def include_type_methods
+        module_eval{ include TypeMethods }
+      end
+
+      def include_coercion_methods
+        module_eval{ include CoercionMethods }
+      end
+
+      module TypeMethods
+
+        # Creates a new instance of this domain
+        def new(*args)
+          if (args.size == 1) && (superclass===args.first)
+            raise ArgumentError, "Invalid value #{args.join(' ')} for #{self}" unless self===args.first
+            args.first
+          elsif superclass.respond_to?(:new)
+            new(super(*args))
+          else
+            raise ArgumentError, "Invalid value #{args.join(' ')} for #{self}"
+          end
+        end
+
+        # (see Class.superclass)
+        def superclass
+          super_domain || super
+        end
+
+        # Returns true if clazz if an explicit sub domain of self or if it's the case in Ruby.
+        def superdomain_of?(child)
+          sub_domains.include?(child)
+        end
+
+        # Checks if `value` belongs to this domain
+        def ===(value)
+          (superclass === value) && predicate.call(value)
+        end
+
+      end # module TypeMethods
+
+    end # module SByC
+  end # module Domain
+end # module Myrrha

data/lib/myrrha/domain/value_methods.rb

@@ -0,0 +1,60 @@
+module Myrrha
+  module Domain
+    module ValueMethods
+
+      # Parts of this module have been extracted from Virtus, MIT Copyright (c) 2011-2012
+      # Piotr Solnica.
+
+      # Returns a hash code for the value
+      #
+      # @return Integer
+      #
+      # @api public
+      def hash
+        component_names.map{|key| send(key).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)
+        component_names.all?{|key| send(key).send(comparator, other.send(key)) }
+      end
+
+      def component_names
+        self.class.component_names
+      end
+
+    end # module ValueMethods
+  end # module Domain
+end # module Myrrha