myrrha 1.0.0

data/examples/to_ruby_literal.rb

@@ -0,0 +1,16 @@
+require 'date'
+require 'myrrha/with_core_ext'
+require 'myrrha/to_ruby_literal'
+
+require 'date'
+require 'myrrha/with_core_ext'
+require 'myrrha/to_ruby_literal'
+
+1.to_ruby_literal                       # => "1"      
+Date.today.to_ruby_literal              # => "Marshal.load('...')"
+["hello", Date.today].to_ruby_literal   # => "['hello', Marshal.load('...')]"
+
+(1..10).to_ruby_literal                 # => "1..10"
+
+today = Date.today
+(today..today+1).to_ruby_literal        # => "Marshal.load('...')"

data/examples/to_ruby_literal_foo.rb

@@ -0,0 +1,14 @@
+require "myrrha/to_ruby_literal"
+
+class Foo
+  attr_reader :arg
+  def initialize(arg)
+    @arg = arg
+  end
+  def to_ruby_literal
+    "Foo.new(#{arg.inspect})"
+  end
+end
+
+Myrrha.to_ruby_literal(Foo.new(:hello))
+# => "Foo.new(:hello)" 

data/examples/to_ruby_literal_foo2.rb

@@ -0,0 +1,17 @@
+require "myrrha/to_ruby_literal"
+
+class Foo
+  attr_reader :arg
+  def initialize(arg)
+    @arg = arg
+  end
+end
+
+Myrrha::ToRubyLiteral.append do |r|
+  r.coercion(Foo) do |foo, _|
+    "Foo.new(#{foo.arg.inspect})"
+  end
+end
+
+Myrrha.to_ruby_literal(Foo.new(:hello))
+# => "Foo.new(:hello)" 

data/examples/to_ruby_literal_foo3.rb

@@ -0,0 +1,21 @@
+require "myrrha/to_ruby_literal"
+
+class Foo
+  attr_reader :arg
+  def initialize(arg)
+    @arg = arg
+  end
+end
+
+MyRules = Myrrha::ToRubyLiteral.dup.append do |r|
+  r.coercion(Foo) do |foo, _|
+    "Foo.new(#{foo.arg.inspect})"
+  end
+end
+
+# Myrrha.to_ruby_literal is actually a shortcut for:
+Myrrha::ToRubyLiteral.apply(Foo.new(:hello))
+# => "Marshal.load('...')"
+
+MyRules.apply(Foo.new(:hello))
+# => "Foo.new(:hello)" 

data/examples/to_ruby_literal_noext.rb

@@ -0,0 +1,5 @@
+require 'date'
+require 'myrrha/to_ruby_literal'
+
+Myrrha.to_ruby_literal(1)              # => 1
+Myrrha.to_ruby_literal(Date.today)     # => Marshal.load("...")

data/lib/myrrha/coerce.rb

@@ -0,0 +1,93 @@
+require 'myrrha'
+module Myrrha
+  
+  #
+  # Defines the missing Boolean type.
+  #
+  # This module mimics a Ruby missing Boolean type. 
+  #
+  module Boolean
+
+    #
+    # Returns Object, as the superclass of Boolean
+    #
+    # @return [Class] Object
+    #
+    def self.superclass; Object; end
+      
+    #
+    # Returns true if `val` is <code>true</code> or <code>false</code>, false 
+    # otherwise.
+    #
+    def self.===(val)
+      (val == true) || (val == false)
+    end
+    
+  end # module Boolean
+  
+  #
+  # Coerces _s_ to a Boolean
+  #
+  # This method mimics Ruby's Integer(), Float(), etc. for Boolean values.
+  #
+  # @param [Object] s a Boolean or a String 
+  # @return [Boolean] true if `s` is already true of the string 'true',
+  #                   false if `s` is already false of the string 'false'.
+  # @raise [ArgumentError] if `s` cannot be coerced to a boolean. 
+  #
+  def self.Boolean(s)
+    if (s==true || s.to_str.strip == "true")
+      true
+    elsif (s==false || s.to_str.strip == "false")
+      false
+    else
+      raise ArgumentError, "invalid value for Boolean: \"#{s}\""
+    end
+  end
+  
+  # Defines basic coercions for Ruby, mostly from String 
+  Coerce = coercions do |g|
+    
+    # NilClass should return immediately
+    g.upon(NilClass) do |s,t| 
+      nil
+    end
+    
+    # Use t.coerce if it exists
+    g.upon(lambda{|s,t| t.respond_to?(:coerce)}) do |s,t|
+      t.coerce(s)
+    end
+    
+    # Specific basic rules
+    g.coercion String, Integer, lambda{|s,t| Integer(s)        }
+    g.coercion String,   Float, lambda{|s,t| Float(s)          }
+    g.coercion String, Boolean, lambda{|s,t| Boolean(s)        }
+    g.coercion Integer,  Float, lambda{|s,t| Float(s)          }
+    g.coercion String,  Symbol, lambda{|s,t| s.to_sym          }
+    g.coercion String,  Regexp, lambda{|s,t| Regexp.compile(s) }
+      
+    # By default, we try to invoke :parse on the class 
+    g.fallback(String) do |s,t| 
+      t.respond_to?(:parse) ? t.parse(s.to_str) : throw(:nextrule) 
+    end
+    
+  end # Coerce
+
+  def self.coerce(value, domain)
+    Coerce.apply(value, domain)
+  end
+    
+end # module Myrrha
+
+if Myrrha.core_ext?
+  Boolean = Myrrha::Boolean
+  def Boolean(s)
+    Myrrha::Boolean(s)
+  end
+  class Object
+    private
+    def coerce(value, domain)
+      Myrrha.coerce(value, domain)
+    end 
+  end
+end

data/lib/myrrha/to_ruby_literal.rb

@@ -0,0 +1,76 @@
+require 'myrrha'
+module Myrrha
+
+  # These are all classes for which using inspect is safe for to_ruby_literal
+  TO_RUBY_THROUGH_INSPECT = [ NilClass, TrueClass, FalseClass, 
+                              Fixnum, Bignum, Float, 
+                              String, Symbol, Class, Module, Regexp ]
+  
+  # Defines basic coercions for implementing to_ruby_literal
+  ToRubyLiteral = coercions do |r|
+    r.main_target_domain = :to_ruby_literal
+    
+    r.upon(Object) do |s,t|
+      s.to_ruby_literal{ throw :nextrule }
+    end
+    
+    # On safe .inspect 
+    safe = lambda{|x| TO_RUBY_THROUGH_INSPECT.include?(x.class)}
+    r.coercion(safe) do |s,t| 
+      s.inspect
+    end
+    
+    # Best-effort on Range or let it be marshalled
+    r.coercion(Range) do |s,t|
+      (TO_RUBY_THROUGH_INSPECT.include?(s.first.class) &&
+       TO_RUBY_THROUGH_INSPECT.include?(s.last.class)) ?
+        s.inspect : throw(:nextrule)
+    end
+    
+    # Be friendly on array
+    r.coercion(Array) do |s,t|
+      "[" + s.collect{|v| r.apply(v)}.join(', ') + "]"
+    end
+    
+    # As well as on Hash
+    r.coercion(Hash) do |s,t|
+      "{" + s.collect{|k,v| 
+        r.apply(k) + " => " + r.apply(v) 
+      }.join(', ') + "}"
+    end
+    
+    # Use Marshal by default
+    r.fallback(Object) do |s,t| 
+      "Marshal.load(#{Marshal.dump(s).inspect})"
+    end
+    
+  end
+  
+  #
+  # Converts `value` to a ruby literal
+  #
+  # @param [Object] value any ruby value
+  # @return [String] a representation `s` of `value` such that 
+  #         <code>Kernel.eval(s) == value</code> is true
+  #
+  def self.to_ruby_literal(value = self)
+    block_given? ? 
+      yield : 
+      ToRubyLiteral.apply(value)
+  end
+  
+end # module Myrrha
+
+class Object
+
+  #
+  # Converts self to a ruby literal
+  #
+  # @return [String] a representation `s` of self such that 
+  #         <code>Kernel.eval(s) == value</code> is true
+  #
+  def to_ruby_literal
+    block_given? ? yield : Myrrha.to_ruby_literal(self)
+  end
+
+end if Myrrha.core_ext?

data/lib/myrrha/version.rb

@@ -0,0 +1,14 @@
+module Myrrha
+  module Version
+  
+    MAJOR = 1
+    MINOR = 0
+    TINY  = 0
+  
+    def self.to_s
+      [ MAJOR, MINOR, TINY ].join('.')
+    end
+  
+  end 
+  VERSION = Version.to_s
+end

data/lib/myrrha/with_core_ext.rb

@@ -0,0 +1,2 @@
+require 'myrrha'
+Myrrha::OPTIONS[:core_ext] = true

data/lib/myrrha.rb

@@ -0,0 +1,295 @@
+#
+# Myrrha -- the missing coercion framework for Ruby
+#
+module Myrrha
+  
+  #
+  # Raised when a coercion fails
+  #
+  class Error < StandardError; end
+  
+  #
+  # Builds a set of coercions rules. 
+  #
+  # Example:
+  #
+  #   rules = Myrrha.coercions do |c|
+  #     c.coercion String, Integer, lambda{|s,t| Integer(s)}
+  #     #
+  #     # [...]
+  #     #
+  #     c.fallback String, lambda{|s,t| ... }
+  #   end
+  #
+  def self.coercions(&block)
+    Coercions.new(&block)
+  end
+    
+  # 
+  # 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(upons = [], rules = [], fallbacks = [])
+      @upons = upons
+      @rules = rules
+      @fallbacks = fallbacks
+      @appender = :<<
+      yield(self) if block_given?
+    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 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)
+        next unless to.nil?   or subdomain?(to, target_domain)
+        begin
+          catch(:nextrule){
+            return convert(value, target_domain, converter)
+          }
+        rescue => ex
+          error = ex.message unless error
+        end
+      end
+      msg = "Unable to coerce `#{value}` to #{target_domain}"
+      msg += " (#{error})" if error
+      raise Error, msg
+    end
+    alias :apply :coerce
+    
+    #
+    # 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)
+      case domain
+      when Proc
+        if domain.arity == 2
+          domain.call(value, target_domain)
+        elsif RUBY_VERSION < "1.9"
+          domain.call(value)
+        elsif domain
+          domain === value
+        end
+      else 
+        domain.respond_to?(:===) ? 
+          domain === value :
+          false
+      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)
+      return true if child == parent
+      (child.respond_to?(:superclass) && child.superclass) ? 
+        subdomain?(child.superclass, parent) :
+        false
+    end
+    
+    #
+    # 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
+      Coercions.new(@upons.dup, @rules.dup, @fallbacks.dup)
+    end
+    
+    private
+    
+    # Extends existing rules
+    def extend_rules(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)
+      else
+        raise ArgumentError, "Unable to use #{converter} for coercing"
+      end
+    end
+    
+  end # class Coercions
+    
+  # Myrrha main options
+  OPTIONS = {
+    :core_ext => false
+  }
+  
+  # Install core extensions?
+  def self.core_ext?
+    OPTIONS[:core_ext]
+  end
+  
+end # module Myrrha
+require "myrrha/version"
+require "myrrha/loader"