From dba196cb7f8d34b93f6872e4a43737bb52019065 Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Sun, 17 Jan 2010 03:26:20 +0530 Subject: Merge docrails --- activesupport/lib/active_support/callbacks.rb | 2 +- .../lib/active_support/core_ext/array/access.rb | 2 +- .../lib/active_support/core_ext/array/wrap.rb | 9 ++++ .../active_support/core_ext/hash/conversions.rb | 48 ++++++++++++++++++++++ .../lib/active_support/core_ext/hash/except.rb | 8 ++++ .../core_ext/hash/indifferent_access.rb | 5 +++ .../lib/active_support/core_ext/hash/keys.rb | 6 ++- .../active_support/core_ext/object/duplicable.rb | 16 ++++++++ activesupport/lib/active_support/core_ext/rexml.rb | 5 ++- .../lib/active_support/core_ext/string/access.rb | 4 +- .../lib/active_support/multibyte/chars.rb | 2 +- 11 files changed, 99 insertions(+), 8 deletions(-) (limited to 'activesupport/lib/active_support') 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. # # * :scope - 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/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 + # # => + # # + # # + # # 1 + # # 2 + # # + # + # 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 :root. + # + # * If +value+ is an array there's a recursive call with +key+ as :root, + # and +key+ singularized as :children. + # + # * 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 :root, 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 :root. + # + # * 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 :skip_types 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 :root option. + # + # The default XML builder is a fresh instance of Builder::XmlMarkup. You can + # configure your own builder with the :builder option. The method also accepts + # options like :dasherize 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 -- cgit v1.2.3