conversion 0.1.0

data/README

@@ -0,0 +1,3 @@
+README for conversion
+=====================
+

data/Rakefile

@@ -0,0 +1,85 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'conversion', 'version')
+
+AUTHOR = "Gwendal Roué"
+EMAIL = "gr@pierlis.com"
+DESCRIPTION = "Conversion module obviously allows object conversion and extends attr_writer/accessor"
+RUBYFORGE_PROJECT = "conversion"
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+BIN_FILES = %w(  )
+
+
+NAME = "conversion"
+REV = File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (Conversion::VERSION::STRING + (REV ? ".#{REV}" : ""))
+CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "conversion documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+desc "Packages up conversion gem."
+task :default => [:test]
+task :package => [:clean]
+
+Rake::TestTask.new("test") { |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+}
+
+spec =
+    Gem::Specification.new do |s|
+        s.name = NAME
+        s.version = VERS
+        s.platform = Gem::Platform::RUBY
+        s.has_rdoc = true
+        s.extra_rdoc_files = ["README", "CHANGELOG"]
+        s.rdoc_options += RDOC_OPTS + ['--exclude', '^(examples|extras)/']
+        s.summary = DESCRIPTION
+        s.description = DESCRIPTION
+        s.author = AUTHOR
+        s.email = EMAIL
+        s.homepage = HOMEPATH
+        s.executables = BIN_FILES
+        s.rubyforge_project = RUBYFORGE_PROJECT
+        s.bindir = "bin"
+        s.require_path = "lib"
+        s.autorequire = "conversion"
+
+        #s.add_dependency('activesupport', '>=1.3.1')
+        #s.required_ruby_version = '>= 1.8.2'
+
+        s.files = %w(README CHANGELOG Rakefile) +
+          Dir.glob("{bin,doc,test,lib,templates,generator,extras,website,script}/**/*") + 
+          Dir.glob("ext/**/*.{h,c,rb}") +
+          Dir.glob("examples/**/*.rb") +
+          Dir.glob("tools/*.rb")
+        
+        # s.extensions = FileList["ext/**/extconf.rb"].to_a
+    end
+
+Rake::GemPackageTask.new(spec) do |p|
+    p.need_tar = true
+    p.gem_spec = spec
+end
+
+task :install do
+  name = "#{NAME}-#{VERS}.gem"
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{name}}
+end
+
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/lib/conversion/accessors.rb

@@ -0,0 +1,137 @@
+unless Kernel.method_defined?(:singleton_class)
+  module Kernel
+    # Returns the singleton class of self
+    def singleton_class
+      class << self; self; end
+    end
+  end
+end
+
+module Conversion
+  # Classes that include Conversion::Accessors can manage the way they store their attributes.
+  #
+  # See Conversion::Accessors::ClassMethods
+  module Accessors
+    
+    # Options for Class.attr_writer and Class.attr_accessor reserved by Conversion module.
+    ACCESSOR_OPTIONS = [:store_as, :store_mode]
+    
+    # Append Conversion::Accessors features to base (the class that includes Conversion::Accessors)
+    def self.append_features(base) #:nodoc:
+      super
+      singleton_class.instance_eval do
+        alias_method :attr_accessor_before_conversion, :attr_accessor
+        alias_method :attr_writer_before_conversion, :attr_writer
+      end
+      base.extend(ClassMethods)
+      base.store_enumerable_attributes(false)
+    end
+
+    # This module is included in classes that includes Conversion::Accessors
+    module ClassMethods
+
+      @@attribute_conversion_mode = nil
+      
+      # Defines readers and setters for each symbol argument.
+      #
+      # Option keys may contain :store_as and :store_mode, which are used as the target argument and :mode option of the Conversion.converter method.
+      #
+      #   class A
+      #     include Conversion::Accessors
+      #     attr_accessor :attr1, :store_as => Integer
+      #     attr_accessor :attr2, :store_as => Integer, :store_mode => :strong_type_checking
+      #   end
+      #   a = A.new
+      #   a.attr1 = '1' # stores 1 in a.attr1
+      #   a.attr2 = '1' # raises ArgumentError
+      
+      def attr_accessor(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        accessor_options = ACCESSOR_OPTIONS.inject({}) { |h, accessor_option|
+          option_value = options[accessor_option]
+          h[accessor_option] = option_value if option_value
+          h
+        }
+        unless accessor_options.empty?
+          attr_reader(*args)
+          args.each { |symbol| attr_writer(symbol, accessor_options) }
+        else
+          attr_accessor_before_conversion(*args)
+        end
+        nil
+      end
+
+      # Defines setters for each symbol argument.
+      #
+      # Option keys may contain :store_as and :store_mode, which are used as the target argument and :mode option of the Conversion.converter method.
+      #
+      #   class A
+      #     include Conversion::Accessors
+      #     attr_writer :attr1, :store_as => Integer
+      #     attr_writer :attr2, :store_as => Integer, :store_mode => :strong_type_checking
+      #   end
+      #   a = A.new
+      #   a.attr1 = '1' # stores 1 in a.attr1
+      #   a.attr2 = '1' # raises ArgumentError
+      def attr_writer(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        if options
+          target = options[:store_as]
+          mode = options[:store_mode] || @@attribute_conversion_mode
+          converter = if @@convert_enumerable_attributes
+                        Conversion.entries_converter(target, :mode=>mode)
+                      else
+                        Conversion.converter(target, :mode=>mode)
+                      end
+          if converter
+            args.each { |symbol|
+              define_method("#{symbol}=") { |*value|
+                instance_variable_set("@#{symbol}", converter.call(*value))
+              }
+            }
+            return nil
+          end
+        end
+        attr_writer_before_conversion(*args)
+        nil
+      end
+
+      # Specifies whether entries should be converted when an enumerable is stored in an attribute
+      #
+      #   class A
+      #     include Conversion::Accessors
+      #     attr_accessor :attr1, :store_as => Integer
+      #
+      #     store_enumerable_attributes
+      #     attr_accessor :attr2, :store_as => Integer
+      #
+      #     store_enumerable_attributes false
+      #     attr_accessor :attr3, :store_as => Integer
+      #   end
+      #   a = A.new
+      #   a.attr1 = ['1'] # raises
+      #   a.attr2 = ['1'] # stores [1] in a.attr2
+      #   a.attr3 = ['1'] # raises
+      def store_enumerable_attributes(bool=true)
+        @@convert_enumerable_attributes = bool
+      end
+      
+      # Specifies the default storage mode for attributes defined after this method is called
+      #
+      #   class A
+      #     include Conversion::Accessors
+      #     attr_accessor :attr1, :store_as => Integer
+      #
+      #     store_attributes_with_mode :weak
+      #     attr_accessor :attr2, :store_as => Integer
+      #   end
+      #   a = A.new
+      #   a.attr1 = 'abc' # raises
+      #   a.attr2 = 'abc' # stores 'abc' in a.attr2
+      def store_attributes_with_mode(mode)
+        @@attribute_conversion_mode = mode
+      end
+      
+    end
+  end
+end

data/lib/conversion/class_decoration.rb

@@ -0,0 +1,107 @@
+class Bignum
+  class << self
+    # Returns a Proc that converts to Integer
+    #
+    #   Bignum.to_converter_proc.call('1') # => 1
+    #
+    # Note that the result may not be a Bignum.
+    #
+    # See Integer.to_converter_proc, Conversion.converter, Object#convert_to
+    def to_converter_proc
+      Integer.to_converter_proc
+    end
+  end
+end
+
+class Fixnum
+  class << self
+    # Returns a Proc that converts to Integer
+    #
+    #   Fixnum.to_converter_proc.call('1') # => 1
+    #
+    # Note that the result may not be a Fixnum.
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      Integer.to_converter_proc
+    end
+  end
+end
+
+class Float
+  class << self
+    # Returns a Proc that converts to Float
+    #
+    #   Float.to_converter_proc.call(1) # => 1.0
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      proc { |value| value.is_a?(Float) ? value : Float(value) }
+    end
+  end
+end
+
+class Integer
+  class << self
+    # Returns a Proc that converts to Integer
+    #
+    #   Integer.to_converter_proc.call(1) # => 1
+    #   Integer.to_converter_proc.call(1.9) # => 2
+    #   Integer.to_converter_proc.call('1.9') # => 2
+    #   Integer.to_converter_proc.call('abc') # ArgumentError: invalid value for Float(): "abc"
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      proc do |value|
+        if value.is_a?(Float)
+          value.round
+        else
+          begin
+            Integer(value)
+          rescue Exception
+            Float(value).round
+          end
+        end
+      end
+    end
+  end
+end
+
+class NilClass
+  class << self
+    # returns a Proc that converts to nil
+    #
+    #   NilClass.to_converter_proc.call(1) # => nil
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      proc { |value| nil }
+    end
+  end
+end
+
+class String
+  class << self
+    # returns a Proc that converts to String
+    #
+    #   String.to_converter_proc.call(1) # => '1'
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      proc { |value| value.to_s }
+    end
+  end
+end
+
+class Symbol
+  class << self
+    # returns a Proc that converts to Symbol
+    #
+    #   Symbol.to_converter_proc.call('abc') # => :abc
+    #
+    # See Conversion.converter, Object#convert_to
+    def to_converter_proc
+      proc { |value| value.to_sym }
+    end
+  end
+end

data/lib/conversion/core.rb

@@ -0,0 +1,336 @@
+# = Conversion Module
+#
+# Author::    Gwendal Roué  (mailto:gr@pierlis.com)
+# Copyright:: Copyright (c) 2006 Pierlis
+# License::   Distributes under the same terms as Ruby
+#
+# -------
+# 
+# The Conversion Module provides a framework for:
+# 
+# - <b>converting values</b> to others,
+# - helping classes define <b>attributes setters</b> that convert their input.
+#
+# -------
+# 
+# == Converting objects to others
+# 
+# === Type casting
+# 
+# For instance, Integer conversion:
+# 
+# 	Conversion.converter(Integer).call('1')    # => 1
+# 	'1'.convert_to(Integer)                    # => 1
+# 	'1.4'.convert_to(Integer)                  # => 1
+# 	1.9.convert_to(Integer)                    # => 2
+# 	
+# 	Conversion.entries_converter(Integer).call(['2','3'])
+# 	                                           # => [2, 3]
+# 	{:a=>'1', :b=>['2','3']}.convert_entries_to(Integer)
+# 	                                           # => {:a=>1, :b=>[2, 3]}
+# 
+# === Free conversion
+# 
+# Conversion is eventually based on Proc objects, so:
+# 
+# 	1.convert_to(proc { |x| x.succ })          # => 2
+# 	1.convert_to(:succ)                        # => 2
+# 
+# == Class Attributes Management
+# 
+# If your class includes the Conversion::Accessors module, its <tt>attr_accessor</tt> and <tt>attr_writer</tt> methods now accept some options:
+# 
+# 	class Money
+# 	  include Conversion::Accessors
+# 	  attr_accessor :amount, :store_as => Float
+# 	  attr_accessor :currency, :store_as => Symbol
+# 	
+# 	  def initialize(amount, currency=:euro)
+# 	    self.amount = amount
+# 	    self.currency = currency
+# 	  end
+# 	
+# 	  def inspect() "#{amount} #{currency}" end
+# 	end
+# 	
+# 	Money.new('1e2', :dollar)                  # 100.0 dollar
+# 	100.convert_to(Money)                      # 100.0 euro
+# 	
+# == Conversion Modes
+# 
+# Conversion behavior can be altered with <i>conversion modes</i>. Module comes with five of them, called <tt>human_input</tt>, <tt>nil_on_failure</tt>, <tt>stable_nil</tt>, <tt>strong_type_checking</tt>, and <tt>weak</tt>, which we'll define below.
+# 
+# Each of them alters the conversion process in a way that may be considered helpful.
+# 
+# Let's start with a strong example, a class that fills itself from data that may come from a HTML form:
+# 
+# 	class MyFormInput
+# 	  include Conversion::Accessors
+# 	  
+# 	  # alter the storage
+# 	  store_attributes_with_mode :human_input
+# 	
+# 	  # define attributes
+# 	  attr_accessor :start_date, :end_date, :store_as => Date
+# 	  attr_accessor :amount, :store_as => Float
+# 	
+# 	  # constructor
+# 	  def initialize(params)
+# 	    self.start_date = params[:start_date]
+# 	    self.end_date = params[:end_date]
+# 	    self.amount = params[:amount]
+# 	  end
+# 	end
+# 
+# Let's give some user data to our class:
+# 
+# 	# - start_date is a m/d/y string
+# 	# - end_date is a blank string
+# 	# - amount contains an unbreakable space and a comma (thank you Excel)
+# 	
+# 	params = {:start_date => '9/18/1973', :end_date => ' ', :amount=>'  1 234,5'}
+# 	f = MyFormInput.new(params)
+# 
+# And let's check the stored data:
+# 
+# 	f.start_date                               # => #<Date: ...>
+# 	f.end_date                                 # => nil
+# 	f.amount                                   # => 1234.5
+# 
+# Ouééé !
+# 
+# The <tt>human_input</tt> mode is <i>weak</i> in the way that we'll see below: when incoming data can't be converted, it is stored as is. This mimics the ActiveRecord::Base behavior, which strictly separates data storage from data validation.
+# 
+# 	f.amount = "I'm richer that you"
+# 	f.amount                                   # => "I'm richer that you"
+# 
+# Let's dig into our five modes now:
+# 
+# === <tt>human_input</tt>
+# 
+# ... was the real motivation behind the Conversion module:
+# 
+# 	'  1 234.5   '.convert_to(Integer, :mode=>:human_input) # => 1235
+# 	'09/18/1973'.convert_to(Date, :mode=>:human_input)      # => #<Date: ...>
+# 
+# === <tt>nil_on_failure</tt>
+# 
+# ... silently discards any conversion error and returns nil instead.
+# 
+# 	'abc'.convert_to(Integer, :mode=>:nil_on_failure)       # => nil
+# 	123.convert_to(Bignum, :mode=>:nil_on_failure)          # => nil
+# 	1234567890.convert_to(Fixnum, :mode=>:nil_on_failure)   # => nil
+# 	['1','2','a'].convert_entries_to(Integer, :mode=>:nil_on_failure)
+# 	                                                        # => [1, 2, nil]
+# 
+# === <tt>stable_nil</tt>
+# 
+# This mode makes sure nil is always converted to nil:
+# 
+# 	nil.convert_to(Integer)                                 # => 0
+# 	nil.convert_to(Integer, :mode=>:stable_nil)             # => nil
+# 	nil.convert_to(:succ)                                   # NoMethodError
+# 	nil.convert_to(:succ, :mode=>:stable_nil)               # => nil
+# 
+# === <tt>strong_type_checking</tt>
+# 
+# ... requires incoming data to already have the target type, except for nil:
+# 
+# 	'1'.convert_to(Integer)                                 # => 1
+# 	'1'.convert_to(Integer, :mode=>:strong_type_checking)   # ArgumentError
+# 	nil.convert_to(Integer, :mode=>:strong_type_checking)   # => nil
+# 	[1,'2'].convert_entries_to(Integer, :mode=>:strong_type_checking)
+# 	                                                        # ArgumentError
+# 	
+# === <tt>weak</tt>
+# 
+# ... silently discards any conversion error and leaves data unchanged
+# 
+# 	'abc'.convert_to(Integer, :mode=>:weak)                 # => 'abc'
+# 	1.convert_to(:upcase, :mode=>:weak)                     # => 1
+# 	['1','2','a'].convert_to(Integer, :mode=>:weak)         # => ["1", "2", "a"]
+# 	['1','2','a'].convert_entries_to(Integer, :mode=>:weak) # => [1, 2, "a"]
+# 
+# == Hook up your own conversions
+#
+# Conversion module leaves much room for your own conversions.
+#
+# Read carefully the documentation for these methods :
+# - Conversion.converter
+# - Conversion.base_converter
+#
+# You'll understand how those methods are triggered:
+# - Conversion.human_input_converter
+# - Conversion.weak_converter
+# - generally, Conversion.<mode>_converter
+#
+# And when those are:
+# - Integer.to_converter_proc
+# - Date.to_human_input_converter_proc
+# - generally, <conversion_target>.to_<mode>_converter_proc
+#
+# After that, you'll be able to write code like:
+#
+#   # human_input converts dates from 'm/d/y'.
+#   # That's a pity there's no support for the French 'd/m/y' format.
+#   # Let's add it by creating our own french_human_input conversion mode :
+#
+#   class Date
+#     class << self
+#       def to_french_human_input_converter_proc
+#         proc { |value|
+#           # clean and trim the value
+#           value = value.convert_to(Conversion::HumanInputString)
+#           if value.nil?
+#             nil
+#           else
+#             # "d/m/y" => date(y,m,d)
+#             elements = value.split(/[-\/]/).convert_entries_to(Integer)
+#             begin
+#               Date.civil(elements[2], elements[1], elements[0])
+#             rescue
+#               value
+#             end
+#           end
+#         }
+#       end
+#     end
+#   end
+#   
+#   '18/09/1973'.convert_to(Date, :mode=>french_human_input) => #<Date: ...>
+#
+# == Invariants
+#
+# Whatever the object, it is true that:
+#   object.convert_to(object.class).equal?(object)
+#   # 1 -> Integer -> 1
+#
+# For... many objects, it is true that:
+#   object.convert_to(Conversion::HumanInputString).convert_to(object.class, :mode=>:human_input) == object
+#   # 1 -> Conversion::HumanInputString -> '1' -> Integer -> 1
+#
+# On that last invariant, see Conversion::HumanInputString.to_converter_proc
+
+module Conversion
+  class << self
+    # Builds a converter Proc that converts to target, with options.
+    #
+    # Default converter is returned unless options contains a :mode (see Conversion.base_converter), and ArgumentError si raised if :mode is unsupported.
+    #
+    # Precisely, if target has a "to_#{mode}_converter_proc" method, it is used (see Integer.to_converter_proc, Date.to_human_input_converter_proc).
+    #
+    # Else, if Conversion has a "#{mode}_converter" method, it is used (see Conversion.weak_converter).
+    #
+    # See also: Object#convert_to
+    def converter(target, options={})
+      mode = options[:mode]
+      begin
+        target_mode = (mode == :base) ? nil : mode
+        target_builder = ['to', target_mode, 'converter_proc'].compact.join('_')
+        return target.send(target_builder)
+      rescue NoMethodError
+        begin
+          converter_mode = (mode.nil?) ? 'base' : mode.to_s
+          converter_builder = converter_mode+'_converter'
+          proc = send(converter_builder, target)
+        rescue NoMethodError
+          raise ArgumentError.new("#{options[:mode].inspect} is not a valid conversion mode")
+        end
+        
+        begin
+          target.singleton_class.instance_eval { define_method(target_builder) { proc } }
+        rescue TypeError
+          # target.singleton_class.instance_eval fails for some instances, like symbols
+        end
+        
+        proc
+      end
+    end
+  
+    # Builds an enumerable converter Proc that converts to target, with options.
+    #
+    # Default converter is returned unless options contains a :mode (see Conversion.base_converter), and ArgumentError is raised if :mode is unsupported.
+    #
+    # See also: Conversion.converter, Object#convert_entries_to
+    def entries_converter(target, options={})
+      converter(target, options).convert_to(Conversion::EnumerableConverter)
+    end
+    
+    # You're not supposed to call this method. Use Conversion.converter or Conversion.entries_converter instead.
+    #
+    # Returns a Proc that is the default converter to target.
+    #
+    # - If target is nil, returns nil
+    # - If target responds to :to_proc, returns target.to_proc
+    # - If target is a String, raise TypeError
+    # - If target is a Symbol, returns a Proc that send the target message to its parameter
+    # - If target is a Class, returns a Proc that creates a new object from its parameters
+    def base_converter(target)
+      converter = 
+#        if target.respond_to?(:to_converter_proc)
+#          target.to_converter_proc
+#      
+#        elsif target.nil?
+        if target.nil?
+          nil
+      
+        elsif target.respond_to?(:to_proc)
+          target.to_proc
+      
+        elsif target.is_a?(String)
+          raise TypeError.new("Strings can't be coerced into Proc")
+      
+        elsif target.is_a?(Symbol)
+          proc { |value| value.send(target) }
+      
+        elsif target.is_a?(Class) &&
+              target.respond_to?(:new) &&
+              target.method(:new).arity != 0
+          proc { |*value|
+            if value.length == 1 && value.first.is_a?(target)
+              value.first
+            else
+              target.new(*value)
+            end
+          }
+        end
+    
+      converter || raise(ArgumentError.new("#{target.inspect} can't be coerced into Proc"))
+    end
+
+  end
+  
+  module EnumerableConverter #:nodoc:
+    class << self
+      # Returns a Proc that converts a converter Proc to an enumerable converter Proc
+      
+      # See Conversion.converter, Object#convert_to
+      def to_converter_proc
+        proc { |converter|
+          converter.nil? ? nil :
+          proc { |value|
+            # challenging recursive mechanism found at http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/20469
+            proc { |builder| proc { |f| f.call(f) }.call( proc { |f| builder.call(proc { |*value| f.call(f).call(*value) }) }) }.call(proc { |recurse|
+              # the recursive proc
+              proc { |value|
+                if value.is_a?(Hash)
+                  value.inject(value.dup.clear) { |h, (key, entry)|
+                    h[key] = recurse.call(entry)
+                    h
+                  }
+                elsif value.is_a?(Enumerable) && !value.is_a?(String)
+                  value.inject(value.dup.clear) { |e, entry|
+                    e << recurse.call(entry)
+                  }
+                else
+                  converter.call(value)
+                end
+              }
+            }).call(value)
+          }
+        }
+      end
+    end
+  end
+end
+

data/lib/conversion/mode/human_input/class_decoration.rb

@@ -0,0 +1,31 @@
+require 'date'
+
+class Date
+  class << self
+    # Returns a human_input converter Proc that converts "m/d/y" dates to Date object
+    def to_human_input_converter_proc
+      proc { |value|
+        value = value.convert_to(Conversion::HumanInputString)
+        if value.nil?
+          nil
+        else
+          # "m/d/y" => date(y,m,d)
+          elements = value.split(/[-\/]/).convert_entries_to(Integer)
+          begin
+            Date.civil(elements[2], elements[0], elements[1])
+          rescue
+            value
+          end
+        end
+      }
+    end
+  end
+  
+  # Returns "m/d/y"
+  #
+  # See Conversion::HumanInputString.to_converter_proc
+  def to_human_input_string
+    # date(y,m,d) => "m/d/y"
+    "#{month}/#{day}/#{year}"
+  end
+end