Merge branch 'master' of git://github.com/rails/rails into rails

18 files changed, 153 insertions, 137 deletions

diff --git a/activesupport/lib/active_support/backtrace_cleaner.rb b/activesupport/lib/active_support/backtrace_cleaner.rb
index 0e262c003e..6fab565646 100644
--- a/activesupport/lib/active_support/backtrace_cleaner.rb
+++ b/activesupport/lib/active_support/backtrace_cleaner.rb
@@ -9,7 +9,7 @@ module ActiveSupport
   # Example:
   #
   #   bc = BacktraceCleaner.new
-  #   bc.add_filter   { |line| line.gsub(Rails.root, '') } 
+  #   bc.add_filter   { |line| line.gsub(Rails.root, '') }
   #   bc.add_silencer { |line| line =~ /mongrel|rubygems/ }
   #   bc.clean(exception.backtrace) # will strip the Rails.root prefix and skip any lines from mongrel or rubygems
   #
@@ -18,10 +18,19 @@ module ActiveSupport
     def initialize
       @filters, @silencers = [], []
     end
-    
+
     # Returns the backtrace after all filters and silencers has been run against it. Filters run first, then silencers.
-    def clean(backtrace)
-      silence(filter(backtrace))
+    def clean(backtrace, kind = :silent)
+      filtered = filter(backtrace)
+
+      case kind
+      when :silent
+        silence(filtered)
+      when :noise
+        noise(filtered)
+      else
+        filtered
+      end
     end
 
     # Adds a filter from the block provided. Each line in the backtrace will be mapped against this filter.
@@ -51,21 +60,28 @@ module ActiveSupport
       @silencers = []
     end
 
-    
     private
       def filter(backtrace)
         @filters.each do |f|
           backtrace = backtrace.map { |line| f.call(line) }
         end
-        
+
         backtrace
       end
-      
+
       def silence(backtrace)
         @silencers.each do |s|
           backtrace = backtrace.reject { |line| s.call(line) }
         end
-        
+
+        backtrace
+      end
+
+      def noise(backtrace)
+        @silencers.each do |s|
+          backtrace = backtrace.select { |line| s.call(line) }
+        end
+
         backtrace
       end
   end
diff --git a/activesupport/lib/active_support/cache.rb b/activesupport/lib/active_support/cache.rb
index 6360a4614e..7213b24f2d 100644
--- a/activesupport/lib/active_support/cache.rb
+++ b/activesupport/lib/active_support/cache.rb
@@ -30,7 +30,7 @@ module ActiveSupport
     #
     #   ActiveSupport::Cache.lookup_store(:memory_store)
     #   # => returns a new ActiveSupport::Cache::MemoryStore object
-    #   
+    #
     #   ActiveSupport::Cache.lookup_store(:mem_cache_store)
     #   # => returns a new ActiveSupport::Cache::MemCacheStore object
     #
@@ -97,7 +97,7 @@ module ActiveSupport
     # Ruby objects, but don't count on every cache store to be able to do that.
     #
     #   cache = ActiveSupport::Cache::MemoryStore.new
-    #   
+    #
     #   cache.read("city")   # => nil
     #   cache.write("city", "Duckburgh")
     #   cache.read("city")   # => "Duckburgh"
@@ -139,7 +139,7 @@ module ActiveSupport
       #
       #   cache.write("today", "Monday")
       #   cache.fetch("today")  # => "Monday"
-      #   
+      #
       #   cache.fetch("city")   # => nil
       #   cache.fetch("city") do
       #     "Duckburgh"
@@ -198,7 +198,7 @@ module ActiveSupport
       # You may also specify additional options via the +options+ argument.
       # The specific cache store implementation will decide what to do with
       # +options+.
-      # 
+      #
       # For example, MemCacheStore supports the +:expires_in+ option, which
       # tells the memcached server to automatically expire the cache item after
       # a certain period:
diff --git a/activesupport/lib/active_support/callbacks.rb b/activesupport/lib/active_support/callbacks.rb
index 8719dc0e3f..6727eda811 100644
--- a/activesupport/lib/active_support/callbacks.rb
+++ b/activesupport/lib/active_support/callbacks.rb
@@ -531,7 +531,7 @@ module ActiveSupport
       # to change this behavior.
       #
       # * <tt>:scope</tt> - Show which methods should be executed when a class
-      # is giben as callback:
+      # is given as callback:
       #
       #   define_callbacks :filters, :scope => [ :kind ]
       #
diff --git a/activesupport/lib/active_support/core_ext/array/access.rb b/activesupport/lib/active_support/core_ext/array/access.rb
index d7606bb9b0..c69a015f12 100644
--- a/activesupport/lib/active_support/core_ext/array/access.rb
+++ b/activesupport/lib/active_support/core_ext/array/access.rb
@@ -4,7 +4,7 @@ class Array
   #   %w( a b c d ).from(0)  # => %w( a b c d )
   #   %w( a b c d ).from(2)  # => %w( c d )
   #   %w( a b c d ).from(10) # => nil
-  #   %w().from(0)           # => nil
+  #   %w().from(0)           # => %w()
   def from(position)
     self[position..-1]
   end
diff --git a/activesupport/lib/active_support/core_ext/array/wrap.rb b/activesupport/lib/active_support/core_ext/array/wrap.rb
index f48d5ce500..e211bdeeca 100644
--- a/activesupport/lib/active_support/core_ext/array/wrap.rb
+++ b/activesupport/lib/active_support/core_ext/array/wrap.rb
@@ -1,6 +1,15 @@
 class Array
   # Wraps the object in an Array unless it's an Array.  Converts the
   # object to an Array using #to_ary if it implements that.
+  #
+  # It differs with Array() in that it does not call +to_a+ on
+  # the argument:
+  #
+  #   Array(:foo => :bar)      # => [[:foo, :bar]]
+  #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
+  #
+  #   Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
+  #   Array.wrap("foo\nbar")   # => ["foo\nbar"]
   def self.wrap(object)
     if object.nil?
       []
diff --git a/activesupport/lib/active_support/core_ext/exception.rb b/activesupport/lib/active_support/core_ext/exception.rb
index b594fbae8e..ef801e713d 100644
--- a/activesupport/lib/active_support/core_ext/exception.rb
+++ b/activesupport/lib/active_support/core_ext/exception.rb
@@ -1,50 +1,3 @@
 module ActiveSupport
   FrozenObjectError = RUBY_VERSION < '1.9' ? TypeError : RuntimeError
 end
-
-# TODO: Turn all this into using the BacktraceCleaner.
-class Exception # :nodoc:
-  # Clean the paths contained in the message.
-  def self.clean_paths(string)
-    require 'pathname' unless defined? Pathname
-    string.gsub(%r{[\w. ]+(/[\w. ]+)+(\.rb)?(\b|$)}) do |path|
-      Pathname.new(path).cleanpath
-    end
-  end
-
-  def clean_message
-    Exception.clean_paths(message)
-  end
-
-  TraceSubstitutions = []
-  FrameworkStart = /action_controller\/dispatcher\.rb/.freeze
-  FrameworkRegexp = /generated|vendor|dispatch|ruby|script\/\w+/.freeze
-
-  def clean_backtrace
-    backtrace.collect do |line|
-      substituted = TraceSubstitutions.inject(line) do |result, (regexp, sub)|
-        result.gsub regexp, sub
-      end
-      Exception.clean_paths(substituted)
-    end
-  end
-
-  def application_backtrace
-    before_framework_frame = nil
-    before_application_frame = true
-
-    trace = clean_backtrace.reject do |line|
-      before_framework_frame ||= (line =~ FrameworkStart)
-      non_app_frame = (line =~ FrameworkRegexp)
-      before_application_frame = false unless non_app_frame
-      before_framework_frame || (non_app_frame && !before_application_frame)
-    end
-
-    # If we didn't find any application frames, return an empty app trace.
-    before_application_frame ? [] : trace
-  end
-
-  def framework_backtrace
-    clean_backtrace.grep FrameworkRegexp
-  end
-end
diff --git a/activesupport/lib/active_support/core_ext/hash/conversions.rb b/activesupport/lib/active_support/core_ext/hash/conversions.rb
index cfd840fb93..48b185d05e 100644
--- a/activesupport/lib/active_support/core_ext/hash/conversions.rb
+++ b/activesupport/lib/active_support/core_ext/hash/conversions.rb
@@ -69,6 +69,54 @@ class Hash
     )
   end
 
+  # Returns a string containing an XML representation of its receiver:
+  # 
+  #   {"foo" => 1, "bar" => 2}.to_xml
+  #   # =>
+  #   # <?xml version="1.0" encoding="UTF-8"?>
+  #   # <hash>
+  #   #   <foo type="integer">1</foo>
+  #   #   <bar type="integer">2</bar>
+  #   # </hash>
+  # 
+  # To do so, the method loops over the pairs and builds nodes that depend on
+  # the _values_. Given a pair +key+, +value+:
+  # 
+  # * If +value+ is a hash there's a recursive call with +key+ as <tt>:root</tt>.
+  # 
+  # * If +value+ is an array there's a recursive call with +key+ as <tt>:root</tt>,
+  #   and +key+ singularized as <tt>:children</tt>.
+  # 
+  # * If +value+ is a callable object it must expect one or two arguments. Depending
+  #   on the arity, the callable is invoked with the +options+ hash as first argument
+  #   with +key+ as <tt>:root</tt>, and +key+ singularized as second argument. Its
+  #   return value becomes a new node.
+  # 
+  # * If +value+ responds to +to_xml+ the method is invoked with +key+ as <tt>:root</tt>.
+  # 
+  # * Otherwise, a node with +key+ as tag is created with a string representation of
+  #   +value+ as text node. If +value+ is +nil+ an attribute "nil" set to "true" is added.
+  #   Unless the option <tt>:skip_types</tt> exists and is true, an attribute "type" is
+  #   added as well according to the following mapping:
+  #
+  #     XML_TYPE_NAMES = {
+  #       "Symbol"     => "symbol",
+  #       "Fixnum"     => "integer",
+  #       "Bignum"     => "integer",
+  #       "BigDecimal" => "decimal",
+  #       "Float"      => "float",
+  #       "TrueClass"  => "boolean",
+  #       "FalseClass" => "boolean",
+  #       "Date"       => "date",
+  #       "DateTime"   => "datetime",
+  #       "Time"       => "datetime"
+  #     }
+  # 
+  # By default the root node is "hash", but that's configurable via the <tt>:root</tt> option.
+  # 
+  # The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can
+  # configure your own builder with the <tt>:builder</tt> option. The method also accepts
+  # options like <tt>:dasherize</tt> and friends, they are forwarded to the builder.
   def to_xml(options = {})
     require 'builder' unless defined?(Builder)
 
diff --git a/activesupport/lib/active_support/core_ext/hash/except.rb b/activesupport/lib/active_support/core_ext/hash/except.rb
index 6d04cb5621..207801d3a7 100644
--- a/activesupport/lib/active_support/core_ext/hash/except.rb
+++ b/activesupport/lib/active_support/core_ext/hash/except.rb
@@ -3,6 +3,14 @@ class Hash
   # limiting a set of parameters to everything but a few known toggles:
   #
   #   @person.update_attributes(params[:person].except(:admin))
+  #
+  # If the receiver responds to +convert_key+, the method is called on each of the
+  # arguments. This allows +except+ to play nice with hashes with indifferent access
+  # for instance:
+  #
+  #   {:a => 1}.with_indifferent_access.except(:a)  # => {}
+  #   {:a => 1}.with_indifferent_access.except("a") # => {}
+  #
   def except(*keys)
     dup.except!(*keys)
   end
diff --git a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
index b30e1602b6..0420e206af 100644
--- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
+++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb
@@ -1,6 +1,11 @@
 require 'active_support/hash_with_indifferent_access'
 
 class Hash
+
+  # Returns an +ActiveSupport::HashWithIndifferentAccess+ out of its receiver:
+  #
+  #   {:a => 1}.with_indifferent_access["a"] # => 1
+  #
   def with_indifferent_access
     hash = ActiveSupport::HashWithIndifferentAccess.new(self)
     hash.default = self.default
diff --git a/activesupport/lib/active_support/core_ext/hash/keys.rb b/activesupport/lib/active_support/core_ext/hash/keys.rb
index ffaa69570f..ecd63293b4 100644
--- a/activesupport/lib/active_support/core_ext/hash/keys.rb
+++ b/activesupport/lib/active_support/core_ext/hash/keys.rb
@@ -15,7 +15,8 @@ class Hash
     self
   end
 
-  # Return a new hash with all keys converted to symbols.
+  # Return a new hash with all keys converted to symbols, as long as
+  # they respond to +to_sym+.
   def symbolize_keys
     inject({}) do |options, (key, value)|
       options[(key.to_sym rescue key) || key] = value
@@ -23,7 +24,8 @@ class Hash
     end
   end
 
-  # Destructively convert all keys to symbols.
+  # Destructively convert all keys to symbols, as long as they respond
+  # to +to_sym+.
   def symbolize_keys!
     self.replace(self.symbolize_keys)
   end
diff --git a/activesupport/lib/active_support/core_ext/object/duplicable.rb b/activesupport/lib/active_support/core_ext/object/duplicable.rb
index a2d4d50076..b05325790c 100644
--- a/activesupport/lib/active_support/core_ext/object/duplicable.rb
+++ b/activesupport/lib/active_support/core_ext/object/duplicable.rb
@@ -1,3 +1,19 @@
+# Most objects are cloneable, but not all. For example you can't dup +nil+:
+#
+#   nil.dup # => TypeError: can't dup NilClass
+#
+# Classes may signal their instances are not duplicable removing +dup+/+clone+
+# or raising exceptions from them. So, to dup an arbitrary object you normally
+# use an optimistic approach and are ready to catch an exception, say:
+#
+#   arbitrary_object.dup rescue object
+#
+# Rails dups objects in a few critical spots where they are not that arbitrary.
+# That rescue is very expensive (like 40 times slower than a predicate), and it
+# is often triggered.
+#
+# That's why we hardcode the following cases and check duplicable? instead of
+# using that rescue idiom.
 class Object
   # Can you safely .dup this object?
   # False for nil, false, true, symbols, numbers, class and module objects; true otherwise.
diff --git a/activesupport/lib/active_support/core_ext/rexml.rb b/activesupport/lib/active_support/core_ext/rexml.rb
index 5288b639a6..0419ebc84b 100644
--- a/activesupport/lib/active_support/core_ext/rexml.rb
+++ b/activesupport/lib/active_support/core_ext/rexml.rb
@@ -2,7 +2,10 @@ require 'active_support/core_ext/kernel/reporting'
 
 # Fixes the rexml vulnerability disclosed at:
 # http://www.ruby-lang.org/en/news/2008/08/23/dos-vulnerability-in-rexml/
-# This fix is identical to rexml-expansion-fix version 1.0.1
+# This fix is identical to rexml-expansion-fix version 1.0.1.
+#
+# We still need to distribute this fix because albeit the REXML
+# in recent 1.8.7s is patched, it wasn't in early patchlevels.
 require 'rexml/rexml'
 
 # Earlier versions of rexml defined REXML::Version, newer ones REXML::VERSION
diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb
index 182b3e745d..64bc8f6cea 100644
--- a/activesupport/lib/active_support/core_ext/string/access.rb
+++ b/activesupport/lib/active_support/core_ext/string/access.rb
@@ -7,7 +7,7 @@ class String
     # Examples: 
     #   "hello".at(0)  # => "h"
     #   "hello".at(4)  # => "o"
-    #   "hello".at(10) # => nil
+    #   "hello".at(10) # => ERROR if < 1.9, nil in 1.9
     def at(position)
       mb_chars[position, 1].to_s
     end
@@ -17,7 +17,7 @@ class String
     # Examples: 
     #   "hello".from(0)  # => "hello"
     #   "hello".from(2)  # => "llo"
-    #   "hello".from(10) # => nil
+    #   "hello".from(10) # => "" if < 1.9, nil in 1.9
     def from(position)
       mb_chars[position..-1].to_s
     end
diff --git a/activesupport/lib/active_support/multibyte/chars.rb b/activesupport/lib/active_support/multibyte/chars.rb
index c7225fec06..3eb0bf31f8 100644
--- a/activesupport/lib/active_support/multibyte/chars.rb
+++ b/activesupport/lib/active_support/multibyte/chars.rb
@@ -385,7 +385,7 @@ module ActiveSupport #:nodoc:
       # Convert characters in the string to uppercase.
       #
       # Example:
-      #   'Laurent, òu sont les tests?'.mb_chars.upcase.to_s #=> "LAURENT, ÒU SONT LES TESTS?"
+      #   'Laurent, où sont les tests ?'.mb_chars.upcase.to_s #=> "LAURENT, OÙ SONT LES TESTS ?"
       def upcase
         apply_mapping :uppercase_mapping
       end
diff --git a/activesupport/lib/active_support/notifications.rb b/activesupport/lib/active_support/notifications.rb
index 3e96decb8c..a1383bb478 100644
--- a/activesupport/lib/active_support/notifications.rb
+++ b/activesupport/lib/active_support/notifications.rb
@@ -45,7 +45,7 @@ module ActiveSupport
     class << self
       attr_writer :notifier
       delegate :publish, :subscribe, :to => :notifier
-      delegate :instrument, :to => :instrumenter
+      delegate :instrument, :instrument!, :to => :instrumenter
 
       def notifier
         @notifier ||= Notifier.new
diff --git a/activesupport/lib/active_support/notifications/instrumenter.rb b/activesupport/lib/active_support/notifications/instrumenter.rb
index f3d877efe7..7c5b118ee3 100644
--- a/activesupport/lib/active_support/notifications/instrumenter.rb
+++ b/activesupport/lib/active_support/notifications/instrumenter.rb
@@ -20,6 +20,15 @@ module ActiveSupport
         result
       end
 
+      # The same as instrument, but sends the notification even if the yielded
+      # block raises an error.
+      def instrument!(name, payload={})
+        time = Time.now
+        yield(payload) if block_given?
+      ensure
+        @notifier.publish(name, time, Time.now, @id, payload)
+      end
+
       private
         def unique_id
           SecureRandom.hex(10)
diff --git a/activesupport/test/core_ext/exception_test.rb b/activesupport/test/core_ext/exception_test.rb
deleted file mode 100644
index e63842c0bd..0000000000
--- a/activesupport/test/core_ext/exception_test.rb
+++ /dev/null
@@ -1,69 +0,0 @@
-require 'abstract_unit'
-require 'active_support/core_ext/exception'
-
-class ExceptionExtTests < Test::Unit::TestCase
-
-  def get_exception(cls = RuntimeError, msg = nil, trace = nil)
-    begin raise cls, msg, (trace || caller)
-    rescue Exception => e  # passed Exception
-      return e
-    end
-  end
-
-  def setup
-    Exception::TraceSubstitutions.clear
-  end
-
-  def test_clean_backtrace
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['bhal.rb', 'rawh hid den stuff is not here', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal ['bhal.rb', 'rawh hid den stuff is not here', 'almost all'], e.clean_backtrace
-  end
-
-  def test_app_backtrace
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['bhal.rb', ' vendor/file.rb some stuff', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal ['bhal.rb', 'almost all'], e.application_backtrace
-  end
-
-  def test_app_backtrace_with_before
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['vendor/file.rb some stuff', 'bhal.rb', ' vendor/file.rb some stuff', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal ['vendor/file.rb some stuff', 'bhal.rb', 'almost all'], e.application_backtrace
-  end
-
-  def test_framework_backtrace_with_before
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['vendor/file.rb some stuff', 'bhal.rb', ' vendor/file.rb some stuff', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal ['vendor/file.rb some stuff', ' vendor/file.rb some stuff'], e.framework_backtrace
-  end
-
-  def test_backtrace_should_clean_paths
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['a/b/c/../d/../../../bhal.rb', 'rawh hid den stuff is not here', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal ['bhal.rb', 'rawh hid den stuff is not here', 'almost all'], e.clean_backtrace
-  end
-
-  def test_clean_message_should_clean_paths
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, "I dislike a/z/x/../../b/y/../c", ['a/b/c/../d/../../../bhal.rb', 'rawh hid den stuff is not here', 'almost all']
-    assert_kind_of Exception, e
-    assert_equal "I dislike a/b/c", e.clean_message
-  end
-
-  def test_app_trace_should_be_empty_when_no_app_frames
-    Exception::TraceSubstitutions << [/\s*hidden.*/, '']
-    e = get_exception RuntimeError, 'RAWR', ['vendor/file.rb some stuff', 'generated/bhal.rb', ' vendor/file.rb some stuff', 'generated/almost all']
-    assert_kind_of Exception, e
-    assert_equal [], e.application_backtrace
-  end
-
-  def test_frozen_error
-    assert_raise(ActiveSupport::FrozenObjectError) { "foo".freeze.gsub!(/oo/,'aa') }
-  end
-end
diff --git a/activesupport/test/notifications_test.rb b/activesupport/test/notifications_test.rb
index c3eb1a4eb5..c41d81fe7e 100644
--- a/activesupport/test/notifications_test.rb
+++ b/activesupport/test/notifications_test.rb
@@ -90,6 +90,22 @@ module Notifications
       drain
     end
 
+    def test_instrument_with_bang_returns_result_even_on_failure
+      begin
+        instrument!(:awesome, :payload => "notifications") do
+          raise "OMG"
+        end
+        flunk
+      rescue
+      end
+
+      drain
+
+      assert_equal 1, @events.size
+      assert_equal :awesome, @events.last.name
+      assert_equal Hash[:payload => "notifications"], @events.last.payload
+    end
+
     def test_instrument_yields_the_paylod_for_further_modification
       assert_equal 2, instrument(:awesome) { |p| p[:result] = 1 + 1 }
       drain