1  require 'active_support/deprecation'
   2 
   3  class Object
   4    # Returns +value+ after yielding +value+ to the block. This simplifies the
   5    # process of constructing an object, performing work on the object, and then
   6    # returning the object from a method. It is a Ruby-ized realization of the K
   7    # combinator, courtesy of Mikael Brockman.
   8    #
   9    # ==== Examples
  10    #
  11    #  # Without returning
  12    #  def foo
  13    #    values = []
  14    #    values << "bar"
  15    #    values << "baz"
  16    #    return values
  17    #  end
  18    #
  19    #  foo # => ['bar', 'baz']
  20    #
  21    #  # returning with a local variable
  22    #  def foo
  23    #    returning values = [] do
  24    #      values << 'bar'
  25    #      values << 'baz'
  26    #    end
  27    #  end
  28    #
  29    #  foo # => ['bar', 'baz']
  30    #  
  31    #  # returning with a block argument
  32    #  def foo
  33    #    returning [] do |values|
  34    #      values << 'bar'
  35    #      values << 'baz'
  36    #    end
  37    #  end
  38    #  
  39    #  foo # => ['bar', 'baz']
  40    def returning(value)
  41      ActiveSupport::Deprecation.warn('Kernel#returning has been deprecated in favor of Object#tap.', caller)
  42      yield(value)
  43      value
  44    end
  45 
  46    # Yields <code>x</code> to the block, and then returns <code>x</code>.
  47    # The primary purpose of this method is to "tap into" a method chain,
  48    # in order to perform operations on intermediate results within the chain.
  49    #
  50    #   (1..10).tap { |x| puts "original: #{x.inspect}" }.to_a.
  51    #     tap    { |x| puts "array: #{x.inspect}" }.
  52    #     select { |x| x%2 == 0 }.
  53    #     tap    { |x| puts "evens: #{x.inspect}" }.
  54    #     map    { |x| x*x }.
  55    #     tap    { |x| puts "squares: #{x.inspect}" }
  56    def tap
  57      yield self
  58      self
  59    end unless Object.respond_to?(:tap)
  60 
  61    # An elegant way to factor duplication out of options passed to a series of
  62    # method calls. Each method called in the block, with the block variable as
  63    # the receiver, will have its options merged with the default +options+ hash
  64    # provided. Each method called on the block variable must take an options
  65    # hash as its final argument.
  66    # 
  67    #   with_options :order => 'created_at', :class_name => 'Comment' do |post|
  68    #     post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all
  69    #     post.has_many :unapproved_comments, :conditions => ['approved = ?', false]
  70    #     post.has_many :all_comments
  71    #   end
  72    #
  73    # Can also be used with an explicit receiver:
  74    #
  75    #   map.with_options :controller => "people" do |people|
  76    #     people.connect "/people",     :action => "index"
  77    #     people.connect "/people/:id", :action => "show"
  78    #   end
  79    #
  80    def with_options(options)
  81      yield ActiveSupport::OptionMerger.new(self, options)
  82    end
  83    
  84    # A duck-type assistant method. For example, Active Support extends Date
  85    # to define an acts_like_date? method, and extends Time to define
  86    # acts_like_time?. As a result, we can do "x.acts_like?(:time)" and
  87    # "x.acts_like?(:date)" to do duck-type-safe comparisons, since classes that
  88    # we want to act like Time simply need to define an acts_like_time? method.
  89    def acts_like?(duck)
  90      respond_to? "acts_like_#{duck}?"
  91    end
  92 
  93  end