core_ext 0.0.1

data/lib/core_ext/object/to_query.rb

@@ -0,0 +1,84 @@
+require 'cgi'
+
+class Object
+  # Alias of <tt>to_s</tt>.
+  def to_param
+    to_s
+  end
+
+  # Converts an object into a string suitable for use as a URL query string,
+  # using the given <tt>key</tt> as the param name.
+  def to_query(key)
+    "#{CGI.escape(key.to_param)}=#{CGI.escape(to_param.to_s)}"
+  end
+end
+
+class NilClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class TrueClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class FalseClass
+  # Returns +self+.
+  def to_param
+    self
+  end
+end
+
+class Array
+  # Calls <tt>to_param</tt> on all its elements and joins the result with
+  # slashes. This is used by <tt>url_for</tt> in Action Pack.
+  def to_param
+    collect(&:to_param).join '/'
+  end
+
+  # Converts an array into a string suitable for use as a URL query string,
+  # using the given +key+ as the param name.
+  #
+  #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
+  def to_query(key)
+    prefix = "#{key}[]"
+
+    if empty?
+      nil.to_query(prefix)
+    else
+      collect { |value| value.to_query(prefix) }.join '&'
+    end
+  end
+end
+
+class Hash
+  # Returns a string representation of the receiver suitable for use as a URL
+  # query string:
+  #
+  #   {name: 'David', nationality: 'Danish'}.to_query
+  #   # => "name=David&nationality=Danish"
+  #
+  # An optional namespace can be passed to enclose key names:
+  #
+  #   {name: 'David', nationality: 'Danish'}.to_query('user')
+  #   # => "user%5Bname%5D=David&user%5Bnationality%5D=Danish"
+  #
+  # The string pairs "key=value" that conform the query string
+  # are sorted lexicographically in ascending order.
+  #
+  # This method is also aliased as +to_param+.
+  def to_query(namespace = nil)
+    collect do |key, value|
+      unless (value.is_a?(Hash) || value.is_a?(Array)) && value.empty?
+        value.to_query(namespace ? "#{namespace}[#{key}]" : key)
+      end
+    end.compact.sort! * '&'
+  end
+
+  alias_method :to_param, :to_query
+end

data/lib/core_ext/object/try.rb

@@ -0,0 +1,146 @@
+require 'delegate'
+
+module CoreExt
+  module Tryable #:nodoc:
+    def try(*a, &b)
+      try!(*a, &b) if a.empty? || respond_to?(a.first)
+    end
+
+    def try!(*a, &b)
+      if a.empty? && block_given?
+        if b.arity == 0
+          instance_eval(&b)
+        else
+          yield self
+        end
+      else
+        public_send(*a, &b)
+      end
+    end
+  end
+end
+
+class Object
+  include CoreExt::Tryable
+
+  ##
+  # :method: try
+  #
+  # :call-seq:
+  #   try(*a, &b)
+  #
+  # Invokes the public method whose name goes as first argument just like
+  # +public_send+ does, except that if the receiver does not respond to it the
+  # call returns +nil+ rather than raising an exception.
+  #
+  # This method is defined to be able to write
+  #
+  #   @person.try(:name)
+  #
+  # instead of
+  #
+  #   @person.name if @person
+  #
+  # +try+ calls can be chained:
+  #
+  #   @person.try(:spouse).try(:name)
+  #
+  # instead of
+  #
+  #   @person.spouse.name if @person && @person.spouse
+  #
+  # +try+ will also return +nil+ if the receiver does not respond to the method:
+  #
+  #   @person.try(:non_existing_method) # => nil
+  #
+  # instead of
+  #
+  #   @person.non_existing_method if @person.respond_to?(:non_existing_method) # => nil
+  #
+  # +try+ returns +nil+ when called on +nil+ regardless of whether it responds
+  # to the method:
+  #
+  #   nil.try(:to_i) # => nil, rather than 0
+  #
+  # Arguments and blocks are forwarded to the method if invoked:
+  #
+  #   @posts.try(:each_slice, 2) do |a, b|
+  #     ...
+  #   end
+  #
+  # The number of arguments in the signature must match. If the object responds
+  # to the method the call is attempted and +ArgumentError+ is still raised
+  # in case of argument mismatch.
+  #
+  # If +try+ is called without arguments it yields the receiver to a given
+  # block unless it is +nil+:
+  #
+  #   @person.try do |p|
+  #     ...
+  #   end
+  #
+  # You can also call try with a block without accepting an argument, and the block
+  # will be instance_eval'ed instead:
+  #
+  #   @person.try { upcase.truncate(50) }
+  #
+  # Please also note that +try+ is defined on +Object+. Therefore, it won't work
+  # with instances of classes that do not have +Object+ among their ancestors,
+  # like direct subclasses of +BasicObject+.
+
+  ##
+  # :method: try!
+  #
+  # :call-seq:
+  #   try!(*a, &b)
+  #
+  # Same as #try, but raises a +NoMethodError+ exception if the receiver is
+  # not +nil+ and does not implement the tried method.
+  #
+  #   "a".try!(:upcase) # => "A"
+  #   nil.try!(:upcase) # => nil
+  #   123.try!(:upcase) # => NoMethodError: undefined method `upcase' for 123:Fixnum
+end
+
+class Delegator
+  include CoreExt::Tryable
+
+  ##
+  # :method: try
+  #
+  # :call-seq:
+  #   try(a*, &b)
+  #
+  # See Object#try
+
+  ##
+  # :method: try!
+  #
+  # :call-seq:
+  #   try!(a*, &b)
+  #
+  # See Object#try!
+end
+
+class NilClass
+  # Calling +try+ on +nil+ always returns +nil+.
+  # It becomes especially helpful when navigating through associations that may return +nil+.
+  #
+  #   nil.try(:name) # => nil
+  #
+  # Without +try+
+  #   @person && @person.children.any? && @person.children.first.name
+  #
+  # With +try+
+  #   @person.try(:children).try(:first).try(:name)
+  def try(*args)
+    nil
+  end
+
+  # Calling +try!+ on +nil+ always returns +nil+.
+  #
+  #   nil.try!(:name) # => nil
+  def try!(*args)
+    nil
+  end
+end

data/lib/core_ext/object/with_options.rb

@@ -0,0 +1,69 @@
+require 'core_ext/option_merger'
+
+class Object
+  # An elegant way to factor duplication out of options passed to a series of
+  # method calls. Each method called in the block, with the block variable as
+  # the receiver, will have its options merged with the default +options+ hash
+  # provided. Each method called on the block variable must take an options
+  # hash as its final argument.
+  #
+  # Without <tt>with_options</tt>, this code contains duplication:
+  #
+  #   class Account < ActiveRecord::Base
+  #     has_many :customers, dependent: :destroy
+  #     has_many :products,  dependent: :destroy
+  #     has_many :invoices,  dependent: :destroy
+  #     has_many :expenses,  dependent: :destroy
+  #   end
+  #
+  # Using <tt>with_options</tt>, we can remove the duplication:
+  #
+  #   class Account < ActiveRecord::Base
+  #     with_options dependent: :destroy do |assoc|
+  #       assoc.has_many :customers
+  #       assoc.has_many :products
+  #       assoc.has_many :invoices
+  #       assoc.has_many :expenses
+  #     end
+  #   end
+  #
+  # It can also be used with an explicit receiver:
+  #
+  #   I18n.with_options locale: user.locale, scope: 'newsletter' do |i18n|
+  #     subject i18n.t :subject
+  #     body    i18n.t :body, user_name: user.name
+  #   end
+  #
+  # When you don't pass an explicit receiver, it executes the whole block
+  # in merging options context:
+  #
+  #   class Account < ActiveRecord::Base
+  #     with_options dependent: :destroy do
+  #       has_many :customers
+  #       has_many :products
+  #       has_many :invoices
+  #       has_many :expenses
+  #     end
+  #   end
+  #
+  # <tt>with_options</tt> can also be nested since the call is forwarded to its receiver.
+  #
+  # NOTE: Each nesting level will merge inherited defaults in addition to their own.
+  #
+  #   class Post < ActiveRecord::Base
+  #     with_options if: :persisted?, length: { minimum: 50 } do
+  #       validates :content, if: -> { content.present? }
+  #     end
+  #   end
+  #
+  # The code is equivalent to:
+  #
+  #   validates :content, length: { minimum: 50 }, if: -> { content.present? }
+  #
+  # Hence the inherited default for `if` key is ignored.
+  #
+  def with_options(options, &block)
+    option_merger = CoreExt::OptionMerger.new(self, options)
+    block.arity.zero? ? option_merger.instance_eval(&block) : block.call(option_merger)
+  end
+end

data/lib/core_ext/object.rb

@@ -0,0 +1,14 @@
+require 'core_ext/object/acts_like'
+require 'core_ext/object/blank'
+require 'core_ext/object/duplicable'
+require 'core_ext/object/deep_dup'
+require 'core_ext/object/try'
+require 'core_ext/object/inclusion'
+
+require 'core_ext/object/conversions'
+require 'core_ext/object/instance_variables'
+
+require 'core_ext/object/json'
+require 'core_ext/object/to_param'
+require 'core_ext/object/to_query'
+require 'core_ext/object/with_options'

data/lib/core_ext/option_merger.rb

@@ -0,0 +1,25 @@
+require 'core_ext/hash/deep_merge'
+
+module CoreExt
+  class OptionMerger #:nodoc:
+    instance_methods.each do |method|
+      undef_method(method) if method !~ /^(__|instance_eval|class|object_id)/
+    end
+
+    def initialize(context, options)
+      @context, @options = context, options
+    end
+
+    private
+      def method_missing(method, *arguments, &block)
+        if arguments.first.is_a?(Proc)
+          proc = arguments.pop
+          arguments << lambda { |*args| @options.deep_merge(proc.call(*args)) }
+        else
+          arguments << (arguments.last.respond_to?(:to_hash) ? @options.deep_merge(arguments.pop) : @options.dup)
+        end
+
+        @context.__send__(method, *arguments, &block)
+      end
+  end
+end

data/lib/core_ext/ordered_hash.rb

@@ -0,0 +1,48 @@
+require 'yaml'
+
+YAML.add_builtin_type("omap") do |type, val|
+  CoreExt::OrderedHash[val.map{ |v| v.to_a.first }]
+end
+
+module CoreExt
+  # <tt>CoreExt::OrderedHash</tt> implements a hash that preserves
+  # insertion order.
+  #
+  #   oh = CoreExt::OrderedHash.new
+  #   oh[:a] = 1
+  #   oh[:b] = 2
+  #   oh.keys # => [:a, :b], this order is guaranteed
+  #
+  # Also, maps the +omap+ feature for YAML files
+  # (See http://yaml.org/type/omap.html) to support ordered items
+  # when loading from yaml.
+  #
+  # <tt>CoreExt::OrderedHash</tt> is namespaced to prevent conflicts
+  # with other implementations.
+  class OrderedHash < ::Hash
+    def to_yaml_type
+      "!tag:yaml.org,2002:omap"
+    end
+
+    def encode_with(coder)
+      coder.represent_seq '!omap', map { |k,v| { k => v } }
+    end
+
+    def select(*args, &block)
+      dup.tap { |hash| hash.select!(*args, &block) }
+    end
+
+    def reject(*args, &block)
+      dup.tap { |hash| hash.reject!(*args, &block) }
+    end
+
+    def nested_under_indifferent_access
+      self
+    end
+
+    # Returns true to make sure that this hash is extractable via <tt>Array#extract_options!</tt>
+    def extractable_options?
+      true
+    end
+  end
+end

data/lib/core_ext/ordered_options.rb

@@ -0,0 +1,81 @@
+module CoreExt
+  # Usually key value pairs are handled something like this:
+  #
+  #   h = {}
+  #   h[:boy] = 'John'
+  #   h[:girl] = 'Mary'
+  #   h[:boy]  # => 'John'
+  #   h[:girl] # => 'Mary'
+  #   h[:dog]  # => nil
+  #
+  # Using +OrderedOptions+, the above code could be reduced to:
+  #
+  #   h = CoreExt::OrderedOptions.new
+  #   h.boy = 'John'
+  #   h.girl = 'Mary'
+  #   h.boy  # => 'John'
+  #   h.girl # => 'Mary'
+  #   h.dog  # => nil
+  #
+  # To raise an exception when the value is blank, append a
+  # bang to the key name, like:
+  #
+  #   h.dog! # => raises KeyError: key not found: :dog
+  #
+  class OrderedOptions < Hash
+    alias_method :_get, :[] # preserve the original #[] method
+    protected :_get # make it protected
+
+    def []=(key, value)
+      super(key.to_sym, value)
+    end
+
+    def [](key)
+      super(key.to_sym)
+    end
+
+    def method_missing(name, *args)
+      name_string = name.to_s
+      if name_string.chomp!('=')
+        self[name_string] = args.first
+      else
+        bangs = name_string.chomp!('!')
+
+        if bangs
+          fetch(name_string.to_sym).presence || raise(KeyError.new("#{name_string} is blank."))
+        else
+          self[name_string]
+        end
+      end
+    end
+
+    def respond_to_missing?(name, include_private)
+      true
+    end
+  end
+
+  # +InheritableOptions+ provides a constructor to build an +OrderedOptions+
+  # hash inherited from another hash.
+  #
+  # Use this if you already have some hash and you want to create a new one based on it.
+  #
+  #   h = CoreExt::InheritableOptions.new({ girl: 'Mary', boy: 'John' })
+  #   h.girl # => 'Mary'
+  #   h.boy  # => 'John'
+  class InheritableOptions < OrderedOptions
+    def initialize(parent = nil)
+      if parent.kind_of?(OrderedOptions)
+        # use the faster _get when dealing with OrderedOptions
+        super() { |h,k| parent._get(k) }
+      elsif parent
+        super() { |h,k| parent[k] }
+      else
+        super()
+      end
+    end
+
+    def inheritable_copy
+      self.class.new(self)
+    end
+  end
+end

data/lib/core_ext/range/conversions.rb

@@ -0,0 +1,34 @@
+class Range
+  RANGE_FORMATS = {
+    :db => Proc.new { |start, stop| "BETWEEN '#{start.to_s(:db)}' AND '#{stop.to_s(:db)}'" }
+  }
+
+  # Convert range to a formatted string. See RANGE_FORMATS for predefined formats.
+  #
+  # This method is aliased to <tt>to_s</tt>.
+  #
+  #   range = (1..100)           # => 1..100
+  #
+  #   range.to_formatted_s       # => "1..100"
+  #   range.to_s                 # => "1..100"
+  #
+  #   range.to_formatted_s(:db)  # => "BETWEEN '1' AND '100'"
+  #   range.to_s(:db)            # => "BETWEEN '1' AND '100'"
+  #
+  # == Adding your own range formats to to_formatted_s
+  # You can add your own formats to the Range::RANGE_FORMATS hash.
+  # Use the format name as the hash key and a Proc instance.
+  #
+  #   # config/initializers/range_formats.rb
+  #   Range::RANGE_FORMATS[:short] = ->(start, stop) { "Between #{start.to_s(:db)} and #{stop.to_s(:db)}" }
+  def to_formatted_s(format = :default)
+    if formatter = RANGE_FORMATS[format]
+      formatter.call(first, last)
+    else
+      to_default_s
+    end
+  end
+
+  alias_method :to_default_s, :to_s
+  alias_method :to_s, :to_formatted_s
+end

data/lib/core_ext/range/each.rb

@@ -0,0 +1,21 @@
+module CoreExt
+  module EachTimeWithZone #:nodoc:
+    def each(&block)
+      ensure_iteration_allowed
+      super
+    end
+
+    def step(n = 1, &block)
+      ensure_iteration_allowed
+      super
+    end
+
+    private
+
+      def ensure_iteration_allowed
+        raise TypeError, "can't iterate from #{first.class}" if first.is_a?(Time)
+      end
+  end
+end
+
+Range.prepend(CoreExt::EachTimeWithZone)

data/lib/core_ext/range/include_range.rb

@@ -0,0 +1,23 @@
+module CoreExt
+  module IncludeWithRange #:nodoc:
+    # Extends the default Range#include? to support range comparisons.
+    #  (1..5).include?(1..5) # => true
+    #  (1..5).include?(2..3) # => true
+    #  (1..5).include?(2..6) # => false
+    #
+    # The native Range#include? behavior is untouched.
+    #  ('a'..'f').include?('c') # => true
+    #  (5..9).include?(11) # => false
+    def include?(value)
+      if value.is_a?(::Range)
+        # 1...10 includes 1..9 but it does not include 1..10.
+        operator = exclude_end? && !value.exclude_end? ? :< : :<=
+        super(value.first) && value.last.send(operator, last)
+      else
+        super
+      end
+    end
+  end
+end
+
+Range.prepend(CoreExt::IncludeWithRange)

data/lib/core_ext/range/overlaps.rb

@@ -0,0 +1,8 @@
+class Range
+  # Compare two ranges and see if they overlap each other
+  #  (1..5).overlaps?(4..6) # => true
+  #  (1..5).overlaps?(7..9) # => false
+  def overlaps?(other)
+    cover?(other.first) || other.cover?(first)
+  end
+end

data/lib/core_ext/range.rb

@@ -0,0 +1,4 @@
+require 'core_ext/range/conversions'
+require 'core_ext/range/include_range'
+require 'core_ext/range/overlaps'
+require 'core_ext/range/each'

data/lib/core_ext/regexp.rb

@@ -0,0 +1,5 @@
+class Regexp #:nodoc:
+  def multiline?
+    options & MULTILINE == MULTILINE
+  end
+end

data/lib/core_ext/rescuable.rb

@@ -0,0 +1,119 @@
+require 'core_ext/concern'
+require 'core_ext/class/attribute'
+require 'core_ext/string/inflections'
+require 'core_ext/array/extract_options'
+
+module CoreExt
+  # Rescuable module adds support for easier exception handling.
+  module Rescuable
+    extend Concern
+
+    included do
+      class_attribute :rescue_handlers
+      self.rescue_handlers = []
+    end
+
+    module ClassMethods
+      # Rescue exceptions raised in controller actions.
+      #
+      # <tt>rescue_from</tt> receives a series of exception classes or class
+      # names, and a trailing <tt>:with</tt> option with the name of a method
+      # or a Proc object to be called to handle them. Alternatively a block can
+      # be given.
+      #
+      # Handlers that take one argument will be called with the exception, so
+      # that the exception can be inspected when dealing with it.
+      #
+      # Handlers are inherited. They are searched from right to left, from
+      # bottom to top, and up the hierarchy. The handler of the first class for
+      # which <tt>exception.is_a?(klass)</tt> holds true is the one invoked, if
+      # any.
+      #
+      #   class ApplicationController < ActionController::Base
+      #     rescue_from User::NotAuthorized, with: :deny_access # self defined exception
+      #     rescue_from ActiveRecord::RecordInvalid, with: :show_errors
+      #
+      #     rescue_from 'MyAppError::Base' do |exception|
+      #       render xml: exception, status: 500
+      #     end
+      #
+      #     protected
+      #       def deny_access
+      #         ...
+      #       end
+      #
+      #       def show_errors(exception)
+      #         exception.record.new_record? ? ...
+      #       end
+      #   end
+      #
+      # Exceptions raised inside exception handlers are not propagated up.
+      def rescue_from(*klasses, &block)
+        options = klasses.extract_options!
+
+        unless options.has_key?(:with)
+          if block_given?
+            options[:with] = block
+          else
+            raise ArgumentError, "Need a handler. Supply an options hash that has a :with key as the last argument."
+          end
+        end
+
+        klasses.each do |klass|
+          key = if klass.is_a?(Module) && klass.respond_to?(:===)
+            klass.name
+          elsif klass.is_a?(String)
+            klass
+          else
+            raise ArgumentError, "#{klass} is neither an Exception nor a String"
+          end
+
+          # Put the new handler at the end because the list is read in reverse.
+          self.rescue_handlers += [[key, options[:with]]]
+        end
+      end
+    end
+
+    # Tries to rescue the exception by looking up and calling a registered handler.
+    def rescue_with_handler(exception)
+      if handler = handler_for_rescue(exception)
+        handler.arity != 0 ? handler.call(exception) : handler.call
+        true # don't rely on the return value of the handler
+      end
+    end
+
+    def handler_for_rescue(exception)
+      # We go from right to left because pairs are pushed onto rescue_handlers
+      # as rescue_from declarations are found.
+      _, rescuer = self.class.rescue_handlers.reverse.detect do |klass_name, handler|
+        # The purpose of allowing strings in rescue_from is to support the
+        # declaration of handler associations for exception classes whose
+        # definition is yet unknown.
+        #
+        # Since this loop needs the constants it would be inconsistent to
+        # assume they should exist at this point. An early raised exception
+        # could trigger some other handler and the array could include
+        # precisely a string whose corresponding constant has not yet been
+        # seen. This is why we are tolerant to unknown constants.
+        #
+        # Note that this tolerance only matters if the exception was given as
+        # a string, otherwise a NameError will be raised by the interpreter
+        # itself when rescue_from CONSTANT is executed.
+        klass = self.class.const_get(klass_name) rescue nil
+        klass ||= (klass_name.constantize rescue nil)
+        klass === exception if klass
+      end
+
+      case rescuer
+      when Symbol
+        method(rescuer)
+      when Proc
+        if rescuer.arity == 0
+          Proc.new { instance_exec(&rescuer) }
+        else
+          Proc.new { |_exception| instance_exec(_exception, &rescuer) }
+        end
+      end
+    end
+  end
+end