myrrha 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# 1.0.0 / 2011-07-22
+
+* Enhancements
+
+  * Birthday!

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec :name => "myrrha"

data/Gemfile.lock

@@ -0,0 +1,41 @@
+PATH
+  remote: .
+  specs:
+    myrrha (1.0.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.11)
+    diff-lcs (1.1.2)
+    highline (1.6.2)
+    noe (1.3.0)
+      highline (~> 1.6.0)
+      quickl (~> 0.2.0)
+      wlang (~> 0.10.1)
+    quickl (0.2.2)
+    rake (0.9.2)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    wlang (0.10.2)
+    yard (0.7.2)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  bundler (~> 1.0)
+  myrrha!
+  noe (~> 1.3.0)
+  rake (~> 0.9.2)
+  rspec (~> 2.6.0)
+  wlang (~> 0.10.1)
+  yard (~> 0.7.2)

data/LICENCE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2011 - Bernard Lambeau
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,13 @@
+examples/**/*
+lib/**/*
+spec/**/*
+tasks/**/*
+Rakefile
+CHANGELOG.md
+Gemfile
+Gemfile.lock
+LICENCE.md
+Manifest.txt
+myrrha.gemspec
+myrrha.noespec
+README.md

data/README.md

@@ -0,0 +1,337 @@
+# Myrrha
+
+## Description
+
+Myrrha provides the coercion framework which is missing to Ruby, IMHO. Coercions
+are simply defined as a set of rules for converting values from source to target
+domains (in an abstract sense). As a typical and useful example, it comes bundled
+with a coerce() method providing a unique entry point for converting a string to 
+a numeric, a boolean, a date, a time, an URI, and so on.  
+
+### Install
+
+    % [sudo] gem install myrrha
+
+### Bundler & Require 
+
+    # Bug fixes (tiny) do not even add new default rules to coerce and 
+    # to\_ruby\_literal. Minor version can, which could break your code. 
+    # Therefore, please always use:
+    gem "alf", "~> 1.0.0"
+
+## Links
+
+* http://rubydoc.info/github/blambeau/myrrha/master/frames (read this file there!)
+* http://github.com/blambeau/myrrha (source code)
+* http://rubygems.org/gems/myrrha (download)
+
+## The missing <code>coerce()</code>
+
+    Myrrha.coerce(:anything, Domain)
+    coerce(:anything, Domain)                    # with core extensions
+
+### What for?
+
+Having a single entry point for coercing values from one data-type (typically
+a String) to another one is very useful. Unfortunately, Ruby does not provide
+such a unique entry point... Thanks to Myrrah, the following scenario is 
+possible and even straightforward:
+
+    require 'myrrha/with_core_ext'
+    require 'myrrha/coerce'
+    require 'date'
+    
+    values = ["12", "true", "2011-07-20"]
+    types  = [Integer, Boolean, Date]
+    values.zip(types).collect do |value,domain|
+      coerce(value, domain)
+    end
+    # => [12, true, #<Date: 2011-07-20 (...)>]
+
+### Example
+
+    require 'myrrha/with_core_ext'
+    require 'myrrha/coerce'
+    
+    # it works on numerics
+    coerce("12", Integer)             # => 12
+    coerce("12.0", Float)             # => 12.0
+    
+    # but also on regexp (through Regexp.compile)
+    coerce("[a-z]+", Regexp)          # => /[a-z]+/
+    
+    # and, yes, on Boolean (sorry Matz!)
+    coerce("true", Boolean)           # => true
+    coerce("false", Boolean)          # => false
+  
+    # and on date and time (through Date/Time.parse)  
+    require 'date'
+    require 'time'
+    coerce("2011-07-20", Date)        # => #<Date: 2011-07-20 (4911525/2,0,2299161)>  
+    coerce("2011-07-20 10:57", Time)  # => 2011-07-20 10:57:00 +0200
+    
+    # why not on URI?
+    require 'uri'
+    coerce('http://google.com', URI)  # => #<URI::HTTP:0x8281ce0 URL:http://google.com>    
+
+    # on nil, it always returns nil
+    coerce(nil, Integer)              # => nil
+
+### No core extension? no problem!
+
+    require 'myrrha/coerce'
+    
+    Myrrha.coerce("12", Integer)            # => 12
+    Myrrha.coerce("12.0", Float)            # => 12.0
+    
+    Myrrha.coerce("true", Myrrha::Boolean)  # => true
+    # [... and so on ...]
+
+### Adding your own coercions
+
+The easiest way to add additional coercions is to implement a <code>coerce</code>
+method on you class; it will be used in priority.
+
+    class Foo
+      def initialize(arg)
+        @arg = arg
+      end
+      def self.coerce(arg)
+        Foo.new(arg)
+      end
+    end
+    
+    Myrrha.coerce(:hello, Foo) 
+    # => #<Foo:0x869eee0 @arg=:hello>
+
+If <code>Foo</code> is not your code and you don't want to make core extensions
+by adding a <code>coerce</code> class method, you can simply add new rules to 
+Myrrha itself:
+
+    Myrrha::Coerce.append do |r|
+      r.coercion(Symbol, Foo) do |value, _|
+        Foo.new(value)
+      end
+    end
+    
+    Myrrha.coerce(:hello, Foo) 
+    # => #<Foo:0x8866f84 @arg=:hello>
+
+Now, doing so, the new coercion rule will be shared with all Myrrha users, which 
+might be intrusive. Why not using your own set of coercion rules?
+
+    MyRules = Myrrha::Coerce.dup.append do |r|
+      r.coercion(Symbol, Foo) do |value, _|
+        Foo.new(value)
+      end
+    end 
+    
+    # Myrrha.coerce is actually a shortcut for:
+    Myrrha::Coerce.apply(:hello, Foo)
+    # => Myrrha::Error: Unable to coerce `hello` to Foo
+    
+    MyRules.apply(:hello, Foo) 
+    # =>  #<Foo:0x8b7d254 @arg=:hello>
+
+## The missing <code>to\_ruby\_literal()</code>
+
+    Myrrha.to_ruby_literal([:anything]) 
+    [:anything].to_ruby_literal                  # with core extensions
+
+### What for?
+
+<code>Object#to\_ruby\_literal</code> has a very simple specification. Given an 
+object o that can be considered as a true _value_, the result of 
+<code>o.to\_ruby\_literal</code> must be such that the following invariant 
+holds:
+
+    Kernel.eval(o.to_ruby_literal) == o 
+
+That is, parsing & evaluating the literal yields the same value. When generating 
+(human-readable) ruby code, having a unique entry point that respects the 
+specification is very useful. 
+
+For almost all ruby classes, but not all, using o.inspect respects the 
+invariant. For example, the following is true:
+ 
+    Kernel.eval("hello".inspect)           == "hello"            # => true
+    Kernel.eval([1, 2, 3].inspect)         == [1, 2, 3]          # => true
+    Kernel.eval({:key => :value}.inspect)  == {:key => :value}   # => true
+    # => true
+
+Unfortunately, this is not always the case:
+
+    Kernel.eval(Date.today.inspect) == Date.today
+    # => false 
+    # => because Date.today.inspect yields "#<Date: 2011-07-20 ...", which is a comment
+
+### Example
+
+Myrrha implements a very simple set of rules for implementing 
+<code>Object#to\_ruby\_literal</code> that works:
+
+    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('...')]"
+
+Myrrha implements a best-effort strategy to return a human readable string. It
+simply fallbacks to <code>Marshal.load(...)</code> when the strategy fails:
+
+    (1..10).to_ruby_literal                 # => "1..10"
+    
+    today = Date.today
+    (today..today+1).to_ruby_literal        # => "Marshal.load('...')"
+
+### No core extension? no problem!
+
+    require 'date'
+    require 'myrrha/to_ruby_literal'
+    
+    Myrrha.to_ruby_literal(1)              # => 1
+    Myrrha.to_ruby_literal(Date.today)     # => Marshal.load("...")
+    # [... and so on ...]
+
+### Adding your own rules
+
+The easiest way is simply to override <code>to\_ruby\_literal</code> in your
+class
+
+    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)" 
+
+As with coerce, contributing your own rule to Myrrha is possible:
+
+    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)" 
+    
+And building your own set of rules is possible as well:
+
+    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)" 
+    
+### Limitation
+
+As the feature fallbacks to marshaling, everything which is marshalable will
+work. As usual, <code>to\_ruby\_literal(Proc)</code> won't work. 
+
+## The general coercion framework
+
+A set of coercion rules can simply be created from scratch as follows:
+
+    Rules = Myrrha.coercions do |r|
+    
+      # `upon` rules are tried in priority if PRE holds
+      r.upon(SourceDomain) do |value, requested_domain|
+     
+        # PRE: - user wants to coerce `value` to a requested_domain
+        #      - belongs_to?(value, SourceDomain)
+        
+        # implement the coercion or throw(:newrule)
+        returned_value = something(value)
+        
+        # POST: belongs_to?(returned_value, requested_domain)
+        
+      end
+      
+      # `coercion` rules are then tried in order if PRE holds
+      r.coercion(SourceDomain, TargetDomain) do |value, requested_domain|
+     
+        # PRE: - user wants to coerce `value` to a requested_domain
+        #      - belongs_to?(value, SourceDomain)
+        #      - subdomain?(TargetDomain, requested_domain)
+        
+        # implement the coercion or throw(:newrule)
+        returned_value = something(value) 
+        
+        # POST: returned_value belongs to requested_domain
+        
+      end
+      
+      # fallback rules are tried if everything else has failed
+      r.fallback(SourceDomain) do |value, requested_domain|
+      
+        # exactly the same as upon rules
+      
+      end
+    
+    end
+    
+When the user invokes <code>Rules.apply(value, domain)</code> all rules for 
+which PRE holds are executed in order, until one succeed (chain of 
+responsibility design pattern). This means that coercions always execute in 
+<code>O(number of rules)</code>.
+
+### <code>belongs\_to?</code> and <code>subdomain?</code> 
+
+The pseudo-code given above relies on two main abstractions. Suppose the user 
+makes a call to <code>coerce(value, requested_domain)</code>:
+
+* <code>belongs\_to?(value, SourceDomain)</code> is true iif
+  * <code>SourceDomain</code> is a <code>Proc</code> of arity 2, and 
+    <code>SourceDomain.call(value, requested_domain)</code> yields true
+  * <code>SourceDomain</code> is a <code>Proc</code> of arity 1, and 
+    <code>SourceDomain.call(value)</code> yields true
+  * <code>SourceDomain === value</code> yields true
+
+* <code>subdomain?(SourceDomain,TargetDomain)</code> is true iif
+  * <code>SourceDomain == TargetDomain</code> yields true
+  * SourceDomain and TargetDomain are both classes and the latter is a super 
+    class of the former 
+    
+### Advanced rule examples
+
+    Rules = Myrrha.coercions do |r|
+    
+      # A 'catch-all' upon rule, always fired
+      catch_all = lambda{|v,rd| true} 
+      r.upon(catch_all) do |value, requested_domain|
+        if you_can_coerce?(value)
+          # then do it!
+        else
+          throw(:next_rule)
+        end
+      end
+      
+      # Delegate every call to the requested domain if it responds to compile
+      compilable = lambda{|v,rd| rd.respond_to?(:compile)} 
+      r.upon(compilable) do |value, requested_domain|
+        requested_domain.compile(value)
+      end  
+      
+      # A fallback strategy if everything else fails
+      r.fallback(Object) do |value, requested_domain|
+        # always fired after everything else
+        # this is your last change, an Myrrha::Error will be raised if you fail
+      end
+      
+    end    

data/Rakefile

@@ -0,0 +1,23 @@
+begin
+  gem "bundler", "~> 1.0"
+  require "bundler/setup"
+rescue LoadError => ex
+  puts ex.message
+  abort "Bundler failed to load, (did you run 'gem install bundler' ?)"
+end
+
+# Dynamically load the gem spec
+$gemspec_file = File.expand_path('../myrrha.gemspec', __FILE__)
+$gemspec      = Kernel.eval(File.read($gemspec_file))
+
+# We run tests by default
+task :default => :test
+
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  instance_eval File.read(taskfile), taskfile
+end

data/examples/String#toXXX.rb

@@ -0,0 +1,40 @@
+require File.expand_path('../examples_helper', __FILE__)
+require 'date'
+
+# In many cases, arguments coming from the user (in console mode, in web,
+# and so on) are Strings, that must be converted to other types: numerics,
+# booleans, and so on.
+#
+# The String class could be extended with to_Integer, to_Float, to_Date, 
+# to_Time and so on, but this is not a good idea... for obvious reasons.
+#
+# With Myrrha, building a set of rules for coercing strings is easy:
+
+rules = Myrrha.coercions do |r|
+  r.coercion String, Integer, lambda{|s,t| Integer(s)    }
+  r.coercion String,   Float, lambda{|s,t| Float(s)      }
+  r.coercion String,    Date, lambda{|s,t| Date.parse(s) }
+  # ... add your own rules here ...
+end
+
+# Integers are recognized correctly
+rules.coerce("12", Integer).should be_a(Integer)
+rules.coerce("12", Integer).should eq(12)
+
+# And so are Floats
+rules.coerce("12.0", Float).should be_a(Float)
+rules.coerce("12.0", Float).should eq(12.0)
+
+#
+# Interestingly, coercion to Numeric works as well. Because
+# of the order in which the rules are defined, Integer are 
+# return in priority!
+# 
+rules.coerce("12", Numeric).should be_a(Integer) 
+rules.coerce("12.0", Numeric).should be_a(Float) 
+
+# And dates will work as well
+rules.coerce("2010-07-20", Date).should be_a(Date)
+rules.coerce("2010-07-20", Date).should eq(Date.parse("2010-07-20"))
+
+# Going further? See the set of rules in Myrrha::Ruby

data/examples/coerce.rb

@@ -0,0 +1,26 @@
+require 'myrrha/with_core_ext'
+require 'myrrha/coerce'
+
+# it works on numerics
+coerce("12", Integer)             # => 12
+coerce("12.0", Float)             # => 12.0
+
+# but also on regexp (through Regexp.compile)
+coerce("[a-z]+", Regexp)          # => /[a-z]+/
+
+# and, yes, on Boolean (sorry Matz!)
+coerce("true", Boolean)           # => true
+coerce("false", Boolean)          # => false
+
+# and on date and time (through Date/Time.parse)  
+require 'date'
+require 'time'
+coerce("2011-07-20", Date)        # => #<Date: 2011-07-20 (4911525/2,0,2299161)>  
+coerce("2011-07-20 10:57", Time)  # => 2011-07-20 10:57:00 +0200
+
+# why not on URI?
+require 'uri'
+coerce('http://google.com', URI)  # => #<URI::HTTP:0x8281ce0 URL:http://google.com>
+
+# on nil, it always returns nil
+coerce(nil, Integer)              # => nil

data/examples/coerce_foo.rb

@@ -0,0 +1,12 @@
+require 'myrrha/coerce'
+
+class Foo
+  def initialize(arg)
+    @arg = arg
+  end
+  def self.coerce(arg)
+    Foo.new(arg)
+  end
+end
+
+Myrrha.coerce(:hello, Foo) 

data/examples/coerce_foo2.rb

@@ -0,0 +1,17 @@
+require 'myrrha/coerce'
+
+class Foo
+  def initialize(arg)
+    @arg = arg
+  end
+end
+
+Myrrha::Coerce.append do |r|
+  r.coercion(Symbol, Foo) do |value, _|
+    Foo.new(value)
+  end
+end 
+
+Myrrha.coerce(:hello, Foo) 
+# => #<Foo:0x8866f84 @arg=:hello>
+

data/examples/coerce_foo3.rb

@@ -0,0 +1,23 @@
+require 'myrrha/coerce'
+
+class Foo
+  def initialize(arg)
+    @arg = arg
+  end
+end
+
+MyRules = Myrrha::Coerce.dup.append do |r|
+  r.coercion(Symbol, Foo) do |value, _|
+    Foo.new(value)
+  end
+end 
+
+begin
+  Myrrha::Coerce.apply(:hello, Foo)
+  raise "Unexpected"
+rescue Myrrha::Error
+  # => Myrrha::Error: Unable to coerce `hello` to Foo
+end
+
+MyRules.apply(:hello, Foo) 
+# =>  #<Foo:0x8b7d254 @arg=:hello>

data/examples/coerce_intro.rb

@@ -0,0 +1,10 @@
+require 'myrrha/with_core_ext'
+require 'myrrha/coerce'
+require 'date'
+
+values = ["12", "true", "2011-07-20"]
+types  = [Integer, Boolean, Date]
+values.zip(types).collect do |value,domain|
+  coerce(value, domain)
+end
+# => [12, true, #<Date: 2011-07-20 (...)>]

data/examples/coerce_noext.rb

@@ -0,0 +1,6 @@
+require 'myrrha/coerce'
+
+Myrrha.coerce("12", Integer)            # => 12
+Myrrha.coerce("12.0", Float)            # => 12.0
+
+Myrrha.coerce("true", Myrrha::Boolean)  # => true

data/examples/examples_helper.rb

@@ -0,0 +1,17 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require "myrrha"
+class Object
+  
+  def eq(x)
+    lambda{|y| raise("Expected #{x} but was #{y} ") unless x == y}
+  end
+  
+  def be_a(clazz)
+    lambda{|y| raise("Expected #{y.inspect} to be a #{clazz}") unless y.is_a?(clazz)}
+  end
+  
+  def should(matcher)
+    matcher.call(self)
+  end
+  
+end

data/examples/friendly_but_safe_api.rb

@@ -0,0 +1,73 @@
+require File.expand_path('../examples_helper', __FILE__)
+
+#
+# Sometimes building friendly public APIs requires some type flexibility 
+# at the public interface, that is coercion.
+#
+# In the example below, the API class defines a public interface. The Foo 
+# class is a pseudo-internal class: it is not intended to be instantiated 
+# by users, but can be manipulated once obtained (typically reused as an 
+# argument for a later call to the API). An array of symbol is a good kind 
+# of Foo literals. Therefore, the API should allow both Foo instance and 
+# arrays of symbols in a 'flexible but safe' way. 
+#
+class API
+
+  # Foo is an internal class, that users should not instantiate directly. 
+  # Instances of Foo can are sometimes returned by internals, are reused 
+  # later as API arguments (see below).
+  class Foo
+    
+    attr_reader :elements
+    
+    def initialize(elements)
+      @elements = elements
+    end
+    
+    def reverse
+      Foo.new(elements.reverse)
+    end
+    
+    def inspect
+      "Foo(#{elements.inspect})"
+    end
+    alias :to_s :inspect
+  
+  end
+  
+  # We define a simple rule for coercing arrays of symvols
+  # as Foo instances
+  Coercions = Myrrha.coercions do |r|
+    FriendlyFoo = lambda{|v| v.is_a?(Array) and v.all?{|s| s.is_a?(Symbol)}}
+    r.coercion FriendlyFoo, Foo, lambda{|v,t| Foo.new(v)}
+  end
+    
+  #
+  # Reverses a Foo.
+  #
+  # This method may be used with a Foo instance. It also accepts an array of 
+  # symbols as a friendly Foo literal. 
+  #
+  def self.reverse(foo)
+    Coercions.coerce(foo, Foo).reverse
+  end
+
+end # class API
+
+# An initial call with an array of symbols work
+puts(x = API.reverse([:a, :b]))
+
+# And so is a call with a Foo instance
+puts(y = API.reverse(x))
+
+# An invalid call will simply fail
+begin
+  API.reverse("hello")
+  true.should eq(false)
+rescue Myrrha::Error => ex
+  puts ex.message
+end 
+
+# this is for testing purposes
+API.reverse([:a, :b]).should be_a(API::Foo)
+API.reverse(API.reverse([:a, :b])).should be_a(API::Foo)