myrrha 1.0.0

data/myrrha.gemspec

@@ -0,0 +1,191 @@
+# We require your library, mainly to have access to the VERSION number. 
+# Feel free to set $version manually.
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require "myrrha/version"
+$version = Myrrha::Version.to_s
+
+#
+# This is your Gem specification. Default values are provided so that your library
+# should be correctly packaged given what you have described in the .noespec file.
+#
+Gem::Specification.new do |s|
+  
+  ################################################################### ABOUT YOUR GEM
+  
+  # Gem name (required) 
+  s.name = "myrrha"
+  
+  # Gem version (required)
+  s.version = $version
+  
+  # A short summary of this gem
+  #
+  # This is displayed in `gem list -d`.
+  s.summary = "Myrrha provides the coercion framework which is missing to Ruby, IMHO."
+
+  # A long description of this gem (required)
+  #
+  # The description should be more detailed than the summary.  For example,
+  # you might wish to copy the entire README into the description.
+  s.description = "Myrrha provides the coercion framework which is missing to Ruby, IMHO. Coercions\nare simply defined as a set of rules for converting values from source to target\ndomains (in an abstract sense). As a typical and useful example, it comes bundled\nwith a coerce() method providing a unique entry point for converting a string to \na numeric, a boolean, a date, a time, an URI, and so on.  "
+  
+  # The URL of this gem home page (optional)
+  s.homepage = "http://rubydoc.info/github/blambeau/myrrha/master/frames"
+
+  # Gem publication date (required but auto)
+  #
+  # Today is automatically used by default, uncomment only if
+  # you know what you do!
+  #
+  # s.date = Time.now.strftime('%Y-%m-%d')
+  
+  # The license(s) for the library.  Each license must be a short name, no
+  # more than 64 characters.
+  #
+  # s.licences = %w{}
+
+  # The rubyforge project this gem lives under (optional)
+  #
+  # s.rubyforge_project = nil
+
+  ################################################################### ABOUT THE AUTHORS
+  
+  # The list of author names who wrote this gem.
+  #
+  # If you are providing multiple authors and multiple emails they should be
+  # in the same order.
+  # 
+  s.authors = ["Bernard Lambeau"]
+  
+  # Contact emails for this gem
+  #
+  # If you are providing multiple authors and multiple emails they should be
+  # in the same order.
+  #
+  # NOTE: Somewhat strangly this attribute is always singular! 
+  #       Don't replace by s.emails = ...
+  s.email  = ["blambeau@gmail.com"]
+
+  ################################################################### PATHS, FILES, BINARIES
+  
+  # Paths in the gem to add to $LOAD_PATH when this gem is 
+  # activated (required).
+  #
+  # The default 'lib' is typically sufficient.
+  s.require_paths = ["lib"]
+  
+  # Files included in this gem.
+  #
+  # By default, we take all files included in the Manifest.txt file on root
+  # of the project. Entries of the manifest are interpreted as Dir[...] 
+  # patterns so that lazy people may use wilcards like lib/**/*
+  #
+  here = File.expand_path(File.dirname(__FILE__))
+  s.files = File.readlines(File.join(here, 'Manifest.txt')).
+                 inject([]){|files, pattern| files + Dir[File.join(here, pattern.strip)]}.
+                 collect{|x| x[(1+here.size)..-1]}
+
+  # Test files included in this gem.
+  #
+  s.test_files = Dir["test/**/*"] + Dir["spec/**/*"]
+
+  # The path in the gem for executable scripts (optional)
+  #
+  s.bindir = "bin"
+
+  # Executables included in the gem.
+  #
+  s.executables = (Dir["bin/*"]).collect{|f| File.basename(f)}
+
+  ################################################################### REQUIREMENTS & INSTALL
+  # Remember the gem version requirements operators and schemes:
+  #   =  Equals version
+  #   != Not equal to version
+  #   >  Greater than version
+  #   <  Less than version
+  #   >= Greater than or equal to
+  #   <= Less than or equal to
+  #   ~> Approximately greater than
+  #
+  # Don't forget to have a look at http://lmgtfy.com/?q=Ruby+Versioning+Policies 
+  # for setting your gem version.
+  #
+  # For your requirements to other gems, remember that
+  #   ">= 2.2.0"              (optimistic:  specify minimal version)
+  #   ">= 2.2.0", "< 3.0"     (pessimistic: not greater than the next major)
+  #   "~> 2.2"                (shortcut for ">= 2.2.0", "< 3.0")
+  #   "~> 2.2.0"              (shortcut for ">= 2.2.0", "< 2.3.0")
+  #
+
+  #
+  # One call to add_dependency('gem_name', 'gem version requirement') for each
+  # runtime dependency. These gems will be installed with your gem. 
+  # One call to add_development_dependency('gem_name', 'gem version requirement')
+  # for each development dependency. These gems are required for developers
+  #
+  s.add_development_dependency("rake", "~> 0.9.2")
+  s.add_development_dependency("bundler", "~> 1.0")
+  s.add_development_dependency("rspec", "~> 2.6.0")
+  s.add_development_dependency("yard", "~> 0.7.2")
+  s.add_development_dependency("bluecloth", "~> 2.0.9")
+  s.add_development_dependency("wlang", "~> 0.10.1")
+  s.add_development_dependency("noe", "~> 1.3.0")
+  
+
+  # The version of ruby required by this gem
+  #
+  # Uncomment and set this if your gem requires specific ruby versions.
+  #
+  # s.required_ruby_version = ">= 0"
+
+  # The RubyGems version required by this gem
+  #
+  # s.required_rubygems_version = ">= 0"
+
+  # The platform this gem runs on.  See Gem::Platform for details.
+  #
+  # s.platform = nil
+
+  # Extensions to build when installing the gem.  
+  #
+  # Valid types of extensions are extconf.rb files, configure scripts 
+  # and rakefiles or mkrf_conf files.
+  #
+  s.extensions = []
+  
+  # External (to RubyGems) requirements that must be met for this gem to work. 
+  # It’s simply information for the user.
+  #
+  s.requirements = nil
+  
+  # A message that gets displayed after the gem is installed
+  #
+  # Uncomment and set this if you want to say something to the user
+  # after gem installation
+  #
+  s.post_install_message = nil
+
+  ################################################################### SECURITY
+
+  # The key used to sign this gem.  See Gem::Security for details.
+  #
+  # s.signing_key = nil
+
+  # The certificate chain used to sign this gem.  See Gem::Security for
+  # details.
+  #
+  # s.cert_chain = []
+  
+  ################################################################### RDOC
+
+  # An ARGV style array of options to RDoc
+  #
+  # See 'rdoc --help' about this
+  #
+  s.rdoc_options = []
+
+  # Extra files to add to RDoc such as README
+  #
+  s.extra_rdoc_files = Dir["README.md"] + Dir["CHANGELOG.md"] + Dir["LICENCE.md"]
+
+end

data/myrrha.noespec

@@ -0,0 +1,37 @@
+# Noe template for ruby gem libraries (https://github.com/blambeau/noe) - short version
+# Run 'noe show-spec' and 'noe help show-spec' for additional details.
+template-info:
+  name: "ruby"
+  version: 1.3.0
+variables:
+  lower: 
+    myrrha
+  upper:
+    Myrrha
+  version:
+    1.0.0
+  summary: |-
+    Myrrha provides the coercion framework which is missing to Ruby, IMHO.
+  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.  
+  authors: 
+    - {name: Bernard Lambeau, email: blambeau@gmail.com}
+  links:
+    - http://rubydoc.info/github/blambeau/myrrha/master/frames
+    - http://github.com/blambeau/myrrha
+    - http://rubygems.org/gems/myrrha
+  dependencies: 
+    - {name: rake,         version: "~> 0.9.2",  groups: [development]}
+    - {name: bundler,      version: "~> 1.0",    groups: [development]}
+    - {name: rspec,        version: "~> 2.6.0",  groups: [development]}
+    - {name: yard,         version: "~> 0.7.2",  groups: [development]}
+    - {name: bluecloth,    version: "~> 2.0.9",  groups: [development]}
+    - {name: wlang,        version: "~> 0.10.1", groups: [development]}
+    - {name: noe,          version: "~> 1.3.0",  groups: [development]}
+  rake_tasks:
+    spec_test:
+      pattern: spec/**/test_*.rb

data/spec/coercions/test_append.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+module Myrrha
+  describe "Coercions#append" do
+    let(:rules){ Coercions.new }
+    
+    it "should return the rules" do
+      rules.append{|r| }.should eq(rules)
+    end
+      
+  end
+end

data/spec/coercions/test_belongs_to.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+module Myrrha
+  describe "Coercions#belongs_to?" do
+    let(:rules){ Coercions.new }
+    
+    specify "with a class" do
+      rules.belongs_to?(12, Integer).should be_true
+    end
+      
+    specify "with a superclass" do
+      rules.belongs_to?(12, Numeric).should be_true
+    end
+      
+    specify "with a proc or arity 1" do
+      rules.belongs_to?(12, lambda{|x| x>10}).should be_true
+      rules.belongs_to?(12, lambda{|x| x<10}).should be_false
+    end
+      
+    specify "with a proc or arity 2" do
+      got = nil
+      l = lambda{|x,t| got = t; t == l }
+      rules.belongs_to?(12, l).should be_true
+      got.should eq(l)
+      rules.belongs_to?(12, l, :nosuch).should be_false
+      got.should eq(:nosuch)
+    end
+      
+  end
+end

data/spec/coercions/test_convert.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+module Myrrha
+  describe "Coercions#convert" do
+    let(:graph){ Coercions.new }
+    
+    subject{ graph.send(:convert, "value", String, converter) }
+      
+    describe "when passed a proc of arity 2" do
+      let(:converter){ lambda{|v,t| [v,t]} }
+      it{ should eq(["value", String]) }
+    end
+      
+    describe "when passed an object that respond to call" do
+      let(:converter){ 
+        o = Object.new
+        def o.call(arg, t); [arg, t]; end
+        o
+      }
+      it{ should eq(["value", String]) }
+    end
+
+  end
+end

data/spec/coercions/test_dup.rb

@@ -0,0 +1,21 @@
+require 'spec_helper'
+module Myrrha
+  describe "Coercions#dup" do
+    let(:rules){ Coercions.new{|r|
+      r.coercion String, Integer, lambda{|s,t| Integer(s)}
+    }}
+    
+    it "should duplicate the rules" do
+      rules.dup.coerce("12", Integer).should eql(12)
+    end
+    
+    it "should not touch the original" do
+      dupped = rules.dup.append do |r|
+        r.coercion String, Float, lambda{|s,t| Float(s)}
+      end
+      dupped.coerce("12", Float).should eql(12.0)
+      lambda{ rules.coerce("12", Float) }.should raise_error(Myrrha::Error)
+    end
+      
+  end
+end

data/spec/coercions/test_subdomain.rb

@@ -0,0 +1,11 @@
+require 'spec_helper'
+module Myrrha
+  describe "Coercions#subdomain?" do
+    let(:graph){ Coercions.new }
+    
+    specify {
+      graph.subdomain?(Symbol, Object).should be_true
+    }
+      
+  end
+end

data/spec/shared/a_value.rb

@@ -0,0 +1,33 @@
+shared_examples_for "a value" do
+
+  def dup(val)
+    Kernel.eval(val.to_ruby_literal)
+  end
+  
+  it "should implement == correctly" do
+    subject.should eq(dup(subject))
+  end
+  
+  it "should implement eql? correctly" do
+    {subject => true, dup(subject) => false}.size.should eq(1)
+  end
+  
+  it "should implement class.parse / #to_s correctly" do
+    if subject.class.respond_to?(:parse) && subject.respond_to?(:to_s)
+      begin
+        subject.class.parse(subject.to_s).should eq(subject)
+      rescue
+        t1 = subject.class.parse(subject.to_s)
+        t2 = subject.class.parse(subject.to_s)
+        t1.should eq(t2)
+      end
+    end
+  end
+  
+  it "should implement Kernel.eval / to_ruby_literal correctly" do
+    if subject.respond_to?(:to_ruby_literal)
+      Kernel.eval(subject.to_ruby_literal).should eq(subject)
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'myrrha/with_core_ext'
+require 'myrrha/coerce'
+require 'myrrha/to_ruby_literal'
+require 'date'
+require 'time'
+require 'shared/a_value'
+
+unless defined?(SAFE_VALUES)
+  SAFE_VALUES = {
+    NilClass   => [ nil ],
+    TrueClass  => [ true ],
+    FalseClass => [ false ],
+    Fixnum     => [ -(2**(0.size * 8 - 2)), -1, 0, 1, 10, (2**(0.size * 8 - 2) - 1)],
+    Bignum     => [ -(2**(0.size * 8 - 2)) - 1, (2**(0.size * 8 - 2)) ],
+    Float      => [ -0.10, 0.0, 0.10 ],
+    String     => ['', 'hello'],
+    Symbol     => [ :hello, :"s-b-y-c", :"12" ],
+    Class      => [ Integer, ::Struct::Tms ],
+    Module     => [ Kernel, Myrrha ],
+    Regexp     => [ /a-z/, /^$/, /\s*/, /[a-z]{15}/ ],
+    Range      => [ 0..10, 0...10 ],
+    Array      => [ [], [nil], [1, "hello"] ],
+    Hash       => [ {}, {1 => 2, :hello => "world"} ]
+  }
+  UNSAFE_VALUES = {
+    Date  => [ Date.today ],
+    Time  => [ Time.now   ],
+    Array => [ [Date.today, Time.now] ],
+    Hash  => [ {Date.today => Time.now} ],
+    Range => [ Date.today..(Date.today+1) ]
+  }
+  VALUES = SAFE_VALUES.values.inject([], :+) + UNSAFE_VALUES.values.inject([], :+)
+end

data/spec/test_assumptions.rb

@@ -0,0 +1,18 @@
+require 'spec_helper'
+describe "Ruby assumptions" do
+  
+  describe "Proc#arity" do
+    specify{
+      lambda{|a| }.arity.should eq(1)
+      lambda{|a,b| }.arity.should eq(2)
+    }
+  end
+  
+  class Object
+    def no_such_myrrha_method
+    end
+  end if false
+  
+  specify{ Object.should_not respond_to(:no_such_myrrha_method) }
+  
+end

data/spec/test_coerce.rb

@@ -0,0 +1,119 @@
+require 'spec_helper'
+describe "::Ruby's coercion " do
+  
+  describe "from NilClass" do
+    it "should always return nil" do
+      coerce(nil, Integer).should be_nil
+      coerce(nil, Date).should be_nil
+    end
+  end
+  
+  describe "to Integer" do
+    specify "from Integer" do
+      coerce(12,     Integer).should eql(12)
+    end
+    specify "from String" do
+      coerce("12",   Integer).should eql(12)
+      coerce("-12",  Integer).should eql(-12)
+      coerce("0",    Integer).should eql(0)
+    end
+    specify "on error" do
+      lambda{coerce("abc",  Integer)}.should raise_error(Myrrha::Error)
+    end
+  end
+  
+  describe "to Float" do
+    specify "from Float" do
+      coerce(12.2,   Float).should eql(12.2)
+    end
+    specify "from Integer" do
+      coerce(0,      Float).should eql(0.0)
+      coerce(12,     Float).should eql(12.0)
+      coerce(-12,    Float).should eql(-12.0)
+    end
+    specify "from String" do
+      coerce("12.2", Float).should eql(12.2)
+      coerce("0",    Float).should eql(0.0)
+      coerce("0.0",  Float).should eql(0.0)
+      coerce("-12.2", Float).should eql(-12.2)
+    end
+    specify "on error" do
+      lambda{coerce("abc",  Float)}.should raise_error(Myrrha::Error)
+    end
+  end
+  
+  describe "to Numeric" do
+    specify "from String" do
+      coerce("12",   Numeric).should eql(12)
+      coerce("12.2", Numeric).should eql(12.2)
+    end
+  end
+  
+  describe "to Boolean" do    
+    specify "from Boolean" do
+      coerce(true,  Boolean).should eql(true)
+      coerce(false, Boolean).should eql(false)
+    end
+    specify "from String" do
+      coerce("true",  Boolean).should eql(true)
+      coerce("false", Boolean).should eql(false)
+    end
+    specify "on error" do
+      lambda{coerce("abc", Boolean)}.should raise_error(Myrrha::Error)
+    end
+  end
+
+  describe "to Date" do
+    let(:expected){ Date.parse("2011-07-20") }
+    specify "from String" do
+      coerce("2011-07-20", Date).should eql(expected)
+      coerce("2011/07/20", Date).should eql(expected)
+    end
+  end
+      
+  describe "to Time" do
+    let(:expected){ Time.parse("2011-07-20 10:53") }
+    specify "from String" do
+      coerce("2011-07-20 10:53", Time).should eql(expected)
+    end
+  end
+  
+  describe "to Symbol" do
+    specify "from Symbol" do
+      coerce(:hello, Symbol).should eql(:hello)
+    end
+    specify "from String" do
+      coerce("hello", Symbol).should eql(:hello)
+    end
+  end
+  
+  describe "to Regexp" do
+    specify "from Regexp" do
+      coerce(/[a-z]+/, Regexp).should eql(/[a-z]+/)
+    end
+    specify "from String" do
+      coerce("[a-z]+", Regexp).should eql(/[a-z]+/)
+    end
+  end
+  
+  describe "to URI" do
+    require 'uri'
+    specify "from String" do
+      coerce("http://www.google.com/", URI).should eql(URI.parse("http://www.google.com/"))
+    end
+  end
+  
+  specify "to a class that respond to coerce" do
+    class Coerceable
+      def self.coerce(val)
+        [:coerced, val]
+      end
+    end
+    coerce("hello", Coerceable).should eq([:coerced, "hello"])
+  end
+  
+  specify "otherwise" do
+    lambda{ coerce("hallo", Myrrha) }.should raise_error(Myrrha::Error)
+  end
+
+end

data/spec/test_myrrha.rb

@@ -0,0 +1,87 @@
+require File.expand_path('../spec_helper', __FILE__)
+describe Myrrha do
+  
+  it "should have a version number" do
+    Myrrha.const_defined?(:VERSION).should be_true
+  end
+  
+  it "should provide the abitity to define a coercion rules" do
+    rules = Myrrha.coercions do |g|
+      g.coercion String, Integer, lambda{|s,t| Integer(s)}
+      g.coercion String, Float,   lambda{|s,t| Float(s)  }
+    end
+    rules.coerce(12,     Integer).should eq(12)
+    rules.coerce("12",   Integer).should eq(12)
+    rules.coerce(12.2,   Float).should   eq(12.2)
+    rules.coerce("12.2", Float).should   eq(12.2) 
+    rules.coerce("12",   Numeric).should eq(12)
+    rules.coerce("12.2", Numeric).should eq(12.2)
+    lambda{ 
+      rules.coerce(true, Integer) 
+    }.should raise_error(Myrrha::Error, "Unable to coerce `true` to Integer")
+    lambda{ 
+      rules.coerce("12.2", Integer)
+    }.should raise_error(Myrrha::Error, /^Unable to coerce `12.2` to Integer \(invalid value /)
+  end
+  
+  it "should support upon rules" do
+    rules = Myrrha.coercions do |g|
+      g.coercion(Integer, Symbol){|s,t| :coercion} 
+      g.upon(lambda{|s| s<0}){|s,t| :upon}
+    end
+    rules.coerce(12, Symbol).should eq(:coercion)
+    rules.coerce(-12, Symbol).should eq(:upon)
+  end
+  
+  it "should support fallback rules" do
+    rules = Myrrha.coercions do |g|
+      g.fallback String, lambda{|s,t| :world}
+    end
+    rules.coerce("hello", Symbol).should eq(:world)
+  end
+  
+  it "should support using matchers" do
+    ArrayOfSymbols = proc{|val| val.is_a?(Array) && val.all?{|x| Symbol===x}}
+    rules = Myrrha.coercions do |g|
+      g.coercion ArrayOfSymbols, String, lambda{|x,t| x.join(', ')}
+    end
+    rules.coerce([:a, :b], ArrayOfSymbols).should eq([:a, :b])
+    rules.coerce([:a, :b], String).should eq("a, b")
+  end
+  
+  it "should support using any object that respond to call as converter" do
+    converter = Object.new
+    def converter.call(arg, t); [arg, t]; end
+    rules = Myrrha.coercions do |g|
+      g.coercion String, Symbol, converter
+    end
+    rules.coerce("hello", Symbol).should eq(["hello", Symbol])
+  end
+  
+  it "should support adding rules later" do
+    rules = Myrrha.coercions do |c|
+      c.coercion String, Symbol, lambda{|s,t| s.to_sym}
+      c.fallback Object,         lambda{|s,t| :fallback}
+    end
+    rules.coerce("hello", Symbol).should eq(:hello)
+    rules.coerce(12, Symbol).should eq(:fallback)
+    
+    rules.append do |c|
+      c.coercion Integer, Symbol, lambda{|s,t| s.to_s.to_sym} 
+    end
+    rules.coerce(12, Symbol).should eq(:"12")
+    rules.coerce(true, Symbol).should eq(:fallback)
+  end
+  
+  it "should support adding rules before" do
+    rules = Myrrha.coercions do |c|
+      c.coercion String, Symbol, lambda{|s,t| s.to_sym}
+    end
+    rules.coerce("hello", Symbol).should eq(:hello)
+    rules.prepend do |c|
+      c.coercion String, Symbol, lambda{|s,t| s.to_s.upcase.to_sym}
+    end
+    rules.coerce("hello", Symbol).should eq(:HELLO)
+  end
+  
+end

data/spec/test_to_ruby_literal.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+describe "to_ruby_literal" do
+
+  VALUES.each do |value|
+    describe "on #{value.inspect}" do
+      specify{ Kernel.eval(value.to_ruby_literal).should eq(value) }  
+    end
+  end
+  
+  it "should work on objects that implement to_ruby_literal" do
+    class ToRubyLiteralizable
+      def to_ruby_literal
+        :foo
+      end
+    end
+    Myrrha.to_ruby_literal(ToRubyLiteralizable.new).should eq(:foo)
+  end
+  
+end

data/spec/test_value.rb

@@ -0,0 +1,6 @@
+VALUES.each do |value|
+  describe "#{value} (#{value.class})" do
+    subject{ value }
+    it_should_behave_like "a value" 
+  end
+end