From ca9413674ea70dc67ab517734af2e40dac21beef Mon Sep 17 00:00:00 2001 From: Pratik Naik Date: Wed, 26 Mar 2008 12:27:52 +0000 Subject: Improve documentation. git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@9093 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- activesupport/lib/active_support/basic_object.rb | 11 +- .../active_support/core_ext/array/conversions.rb | 59 +++++++++- .../lib/active_support/core_ext/array/grouping.rb | 4 +- activesupport/lib/active_support/core_ext/blank.rb | 2 +- .../lib/active_support/core_ext/class/removal.rb | 9 ++ .../active_support/core_ext/date/calculations.rb | 2 + .../lib/active_support/core_ext/enumerable.rb | 13 ++- activesupport/lib/active_support/core_ext/file.rb | 12 +-- .../core_ext/hash/indifferent_access.rb | 36 +++++++ .../active_support/core_ext/hash/reverse_merge.rb | 3 + .../active_support/core_ext/integer/even_odd.rb | 13 ++- .../active_support/core_ext/integer/inflections.rb | 3 +- .../active_support/core_ext/kernel/reporting.rb | 8 ++ .../core_ext/module/attr_internal.rb | 3 +- .../active_support/core_ext/module/inclusion.rb | 19 ++++ .../core_ext/module/introspection.rb | 35 +++++- .../lib/active_support/core_ext/module/loading.rb | 10 ++ .../core_ext/object/instance_variables.rb | 44 ++++++++ .../active_support/core_ext/range/conversions.rb | 7 +- .../active_support/core_ext/string/inflections.rb | 120 ++++++++++----------- .../lib/active_support/core_ext/string/unicode.rb | 2 +- .../lib/active_support/core_ext/time/zones.rb | 10 +- activesupport/lib/active_support/gzip.rb | 3 + activesupport/lib/active_support/inflector.rb | 2 +- .../lib/active_support/json/encoders/date.rb | 7 +- .../lib/active_support/json/encoders/date_time.rb | 7 +- .../lib/active_support/json/encoders/enumerable.rb | 4 +- .../lib/active_support/json/encoders/hash.rb | 9 +- .../lib/active_support/json/encoders/object.rb | 2 +- .../lib/active_support/json/encoders/time.rb | 7 +- activesupport/lib/active_support/whiny_nil.rb | 2 + 31 files changed, 352 insertions(+), 116 deletions(-) (limited to 'activesupport/lib/active_support') diff --git a/activesupport/lib/active_support/basic_object.rb b/activesupport/lib/active_support/basic_object.rb index bb01a47508..e06da79d26 100644 --- a/activesupport/lib/active_support/basic_object.rb +++ b/activesupport/lib/active_support/basic_object.rb @@ -1,6 +1,11 @@ -# Ruby 1.9 introduces BasicObject which differs slighly from Builder's BlankSlate -# that had been used so far ActiveSupport::BasicObject provides a barebones object with -# the same method on both versions. +# A base class with no predefined methods that tries to behave like Builder's +# BlankSlate in Ruby 1.9. In Ruby pre-1.9, this is actually the +# Builder::BlankSlate class. +# +# Ruby 1.9 introduces BasicObject which differs slightly from Builder's +# BlankSlate that has been used so far. ActiveSupport::BasicObject provides a +# barebones base class that emulates Builder::BlankSlate while still relying on +# Ruby 1.9's BasicObject in Ruby 1.9. module ActiveSupport if RUBY_VERSION >= '1.9' class BasicObject < ::BasicObject diff --git a/activesupport/lib/active_support/core_ext/array/conversions.rb b/activesupport/lib/active_support/core_ext/array/conversions.rb index 7574dc13cd..e46d7c1884 100644 --- a/activesupport/lib/active_support/core_ext/array/conversions.rb +++ b/activesupport/lib/active_support/core_ext/array/conversions.rb @@ -24,7 +24,8 @@ module ActiveSupport #:nodoc: end end - # Calls to_param on all its elements and joins the result with slashes. This is used by url_for in Action Pack. + # Calls to_param on all its elements and joins the result with + # slashes. This is used by url_for in Action Pack. def to_param map(&:to_param).join '/' end @@ -32,8 +33,9 @@ module ActiveSupport #:nodoc: # Converts an array into a string suitable for use as a URL query string, using the given key as the # param name. # - # ==== Example: - # ['Rails', 'coding'].to_query('hobbies') => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" + # Example: + # + # ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding" def to_query(key) collect { |value| value.to_query("#{key}[]") } * '&' end @@ -45,6 +47,15 @@ module ActiveSupport #:nodoc: end end + # Converts a collection of elements into a formatted string by calling + # to_s on all elements and joining them: + # + # Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post" + # + # Adding in the :db argument as the format yields a prettier + # output: + # + # Blog.find(:all).to_formatted_s(:db) # => "First Post,Second Post,Third Post" def to_formatted_s(format = :default) case format when :db @@ -58,6 +69,48 @@ module ActiveSupport #:nodoc: end end + # Returns a string that represents this array in XML by sending + # to_xml to each element. + # + # All elements are expected to respond to to_xml, if any of + # them does not an exception is raised. + # + # The root node reflects the class name of the first element in plural + # if all elements belong to the same type and that's not Hash. + # Otherwise the root element is "records". + # + # Root children have as node name the one of the root singularized. + # + # Example: + # + # [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml + # + # + # + # + # 2 + # 1 + # + # + # 3 + # + # + # + # The +options+ hash is passed downwards: + # + # [Message.find(:first)].to_xml(:skip_types => true) + # + # + # + # + # 2008-03-07T09:58:18+01:00 + # 1 + # 1 + # 2008-03-07T09:58:18+01:00 + # 1 + # + # + # def to_xml(options = {}) raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml } diff --git a/activesupport/lib/active_support/core_ext/array/grouping.rb b/activesupport/lib/active_support/core_ext/array/grouping.rb index 52ed61d3dc..ed5ec72daf 100644 --- a/activesupport/lib/active_support/core_ext/array/grouping.rb +++ b/activesupport/lib/active_support/core_ext/array/grouping.rb @@ -8,7 +8,7 @@ module ActiveSupport #:nodoc: # slots with specified value (nil by default) unless it is # false. # - # E.g. + # Examples: # # %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g} # ["1", "2", "3"] @@ -45,7 +45,7 @@ module ActiveSupport #:nodoc: # Divide the array into one or more subarrays based on a delimiting +value+ # or the result of an optional block. # - # ex. + # Examples: # # [1, 2, 3, 4, 5].split(3) # => [[1, 2], [4, 5]] # (1..10).to_a.split { |i| i % 3 == 0 } # => [[1, 2], [4, 5], [7, 8], [10]] diff --git a/activesupport/lib/active_support/core_ext/blank.rb b/activesupport/lib/active_support/core_ext/blank.rb index c4695816e2..f4def18ae9 100644 --- a/activesupport/lib/active_support/core_ext/blank.rb +++ b/activesupport/lib/active_support/core_ext/blank.rb @@ -1,5 +1,5 @@ class Object - # An object is blank if it's nil, empty, or a whitespace string. + # An object is blank if it's false, empty, or a whitespace string. # For example, "", " ", nil, [], and {} are blank. # # This simplifies diff --git a/activesupport/lib/active_support/core_ext/class/removal.rb b/activesupport/lib/active_support/core_ext/class/removal.rb index 0c70e7181a..f768313abe 100644 --- a/activesupport/lib/active_support/core_ext/class/removal.rb +++ b/activesupport/lib/active_support/core_ext/class/removal.rb @@ -1,12 +1,21 @@ class Class #:nodoc: + + # Will unassociate the class with its subclasses as well as uninitializing the subclasses themselves. + # >> Integer.remove_subclasses + # => [Bignum, Fixnum] + # >> Fixnum + # NameError: uninitialized constant Fixnum def remove_subclasses Object.remove_subclasses_of(self) end + # Returns a list of classes that inherit from this class in an array. + # Example: Integer.subclasses => ["Bignum", "Fixnum"] def subclasses Object.subclasses_of(self).map { |o| o.to_s } end + # Allows you to remove individual subclasses or a selection of subclasses from a class without removing all of them. def remove_class(*klasses) klasses.flatten.each do |klass| # Skip this class if there is nothing bound to this name diff --git a/activesupport/lib/active_support/core_ext/date/calculations.rb b/activesupport/lib/active_support/core_ext/date/calculations.rb index ab3b5e38f0..d1a30c3f73 100644 --- a/activesupport/lib/active_support/core_ext/date/calculations.rb +++ b/activesupport/lib/active_support/core_ext/date/calculations.rb @@ -16,10 +16,12 @@ module ActiveSupport #:nodoc: end module ClassMethods + # Finds yesterday's date, in the format similar to: Mon, 17 Mar 2008 def yesterday ::Date.today.yesterday end + # Finds tommorrow's date, in the format similar to: Tue, 18 Mar 2008 def tomorrow ::Date.today.tomorrow end diff --git a/activesupport/lib/active_support/core_ext/enumerable.rb b/activesupport/lib/active_support/core_ext/enumerable.rb index c448d0454d..1b96eb166a 100644 --- a/activesupport/lib/active_support/core_ext/enumerable.rb +++ b/activesupport/lib/active_support/core_ext/enumerable.rb @@ -2,7 +2,7 @@ module Enumerable # Collect an enumerable into sets, grouped by the result of a block. Useful, # for example, for grouping records by date. # - # e.g. + # Example: # # latest_transcripts.group_by(&:day).each do |day, transcripts| # p "#{day} -> #{transcripts.map(&:class) * ', '}" @@ -23,18 +23,21 @@ module Enumerable # Calculates a sum from the elements. Examples: # - # payments.sum { |p| p.price * p.tax_rate } - # payments.sum(&:price) + # payments.sum { |p| p.price * p.tax_rate } + # payments.sum(&:price) # - # This is instead of payments.inject { |sum, p| sum + p.price } + # This is instead of + # + # payments.inject { |sum, p| sum + p.price } # # Also calculates sums without the use of a block: + # # [5, 15, 10].sum # => 30 # # The default identity (sum of an empty list) is zero. # However, you can override this default: # - # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) + # [].sum(Payment.new(0)) { |i| i.amount } # => Payment.new(0) # def sum(identity = 0, &block) return identity unless size > 0 diff --git a/activesupport/lib/active_support/core_ext/file.rb b/activesupport/lib/active_support/core_ext/file.rb index cd43be37e3..45d93b220f 100644 --- a/activesupport/lib/active_support/core_ext/file.rb +++ b/activesupport/lib/active_support/core_ext/file.rb @@ -3,16 +3,16 @@ require 'tempfile' # Write to a file atomically. Useful for situations where you don't # want other processes or threads to see half-written files. # -# File.atomic_write("important.file") do |file| -# file.write("hello") -# end +# File.atomic_write("important.file") do |file| +# file.write("hello") +# end # # If your temp directory is not on the same filesystem as the file you're # trying to write, you can provide a different temporary directory. # -# File.atomic_write("/data/something.imporant", "/data/tmp") do |f| -# file.write("hello") -# end +# File.atomic_write("/data/something.important", "/data/tmp") do |f| +# file.write("hello") +# end def File.atomic_write(file_name, temp_dir = Dir.tmpdir) temp_file = Tempfile.new(File.basename(file_name), temp_dir) yield temp_file 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 fda0489e76..2213b09144 100644 --- a/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb +++ b/activesupport/lib/active_support/core_ext/hash/indifferent_access.rb @@ -1,5 +1,6 @@ # This class has dubious semantics and we only have it so that # people can write params[:key] instead of params['key'] +# and they get the same value for both keys. class HashWithIndifferentAccess < Hash def initialize(constructor = {}) @@ -22,10 +23,38 @@ class HashWithIndifferentAccess < Hash alias_method :regular_writer, :[]= unless method_defined?(:regular_writer) alias_method :regular_update, :update unless method_defined?(:regular_update) + # + # Assigns a new value to the hash. + # + # Example: + # + # hash = HashWithIndifferentAccess.new + # hash[:key] = "value" + # def []=(key, value) regular_writer(convert_key(key), convert_value(value)) end + # + # Updates the instantized hash with values from the second. + # + # Example: + # + # >> hash_1 = HashWithIndifferentAccess.new + # => {} + # + # >> hash_1[:key] = "value" + # => "value" + # + # >> hash_2 = HashWithIndifferentAccess.new + # => {} + # + # >> hash_2[:key] = "New Value!" + # => "New Value!" + # + # >> hash_1.update(hash_2) + # => {"key"=>"New Value!"} + # def update(other_hash) other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) } self @@ -33,6 +62,7 @@ class HashWithIndifferentAccess < Hash alias_method :merge!, :update + # Checks the hash for a key matching the argument passed in def key?(key) super(convert_key(key)) end @@ -41,22 +71,28 @@ class HashWithIndifferentAccess < Hash alias_method :has_key?, :key? alias_method :member?, :key? + # Fetches the value for the specified key, same as doing hash[key] def fetch(key, *extras) super(convert_key(key), *extras) end + # Returns an array of the values at the specified indicies. def values_at(*indices) indices.collect {|key| self[convert_key(key)]} end + # Returns an exact copy of the hash. def dup HashWithIndifferentAccess.new(self) end + # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash + # Does not overwrite the existing hash. def merge(hash) self.dup.update(hash) end + # Removes a specified key from the hash. def delete(key) super(convert_key(key)) end diff --git a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb index 3c4908ac9e..0ec0538024 100644 --- a/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb +++ b/activesupport/lib/active_support/core_ext/hash/reverse_merge.rb @@ -10,10 +10,13 @@ module ActiveSupport #:nodoc: # # The default :size and :velocity is only set if the +options+ passed in doesn't already have those keys set. module ReverseMerge + # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. def reverse_merge(other_hash) other_hash.merge(self) end + # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second. + # Modifies the receiver in place. def reverse_merge!(other_hash) replace(reverse_merge(other_hash)) end diff --git a/activesupport/lib/active_support/core_ext/integer/even_odd.rb b/activesupport/lib/active_support/core_ext/integer/even_odd.rb index 7ea4cbf2ba..b53bcd066c 100644 --- a/activesupport/lib/active_support/core_ext/integer/even_odd.rb +++ b/activesupport/lib/active_support/core_ext/integer/even_odd.rb @@ -1,11 +1,14 @@ module ActiveSupport #:nodoc: module CoreExtensions #:nodoc: module Integer #:nodoc: - # For checking if a fixnum is even or odd. - # * 1.even? # => false - # * 1.odd? # => true - # * 2.even? # => true - # * 2.odd? # => false + # For checking if a fixnum is even or odd. + # + # Examples: + # + # 1.even? # => false + # 1.odd? # => true + # 2.even? # => true + # 2.odd? # => false module EvenOdd def multiple_of?(number) self % number == 0 diff --git a/activesupport/lib/active_support/core_ext/integer/inflections.rb b/activesupport/lib/active_support/core_ext/integer/inflections.rb index 87b57e3adf..252b2c5593 100644 --- a/activesupport/lib/active_support/core_ext/integer/inflections.rb +++ b/activesupport/lib/active_support/core_ext/integer/inflections.rb @@ -7,7 +7,8 @@ module ActiveSupport #:nodoc: # Ordinalize turns a number into an ordinal string used to denote the # position in an ordered sequence such as 1st, 2nd, 3rd, 4th. # - # Examples + # Examples: + # # 1.ordinalize # => "1st" # 2.ordinalize # => "2nd" # 1002.ordinalize # => "1002nd" diff --git a/activesupport/lib/active_support/core_ext/kernel/reporting.rb b/activesupport/lib/active_support/core_ext/kernel/reporting.rb index a5cec50245..0f101e8fa4 100644 --- a/activesupport/lib/active_support/core_ext/kernel/reporting.rb +++ b/activesupport/lib/active_support/core_ext/kernel/reporting.rb @@ -42,6 +42,14 @@ module Kernel stream.reopen(old_stream) end + # Blocks and ignores any exception passed as argument if raised within the block. + # + # suppress(ZeroDivisionError) do + # 1/0 + # puts "This code is NOT reached" + # end + # + # puts "This code gets executed and nothing related to ZeroDivisionError was seen" def suppress(*exception_classes) begin yield rescue Exception => e diff --git a/activesupport/lib/active_support/core_ext/module/attr_internal.rb b/activesupport/lib/active_support/core_ext/module/attr_internal.rb index 7f2fb9641b..e0be31090c 100644 --- a/activesupport/lib/active_support/core_ext/module/attr_internal.rb +++ b/activesupport/lib/active_support/core_ext/module/attr_internal.rb @@ -13,7 +13,8 @@ class Module end end - # Declare attributes backed by 'internal' instance variables names. + # Declare an attribute reader and writer backed by an internally-named instance + # variable. def attr_internal_accessor(*attrs) attr_internal_reader(*attrs) attr_internal_writer(*attrs) diff --git a/activesupport/lib/active_support/core_ext/module/inclusion.rb b/activesupport/lib/active_support/core_ext/module/inclusion.rb index efc00d6f28..4f23841645 100644 --- a/activesupport/lib/active_support/core_ext/module/inclusion.rb +++ b/activesupport/lib/active_support/core_ext/module/inclusion.rb @@ -1,4 +1,23 @@ class Module + # Returns the classes in the current ObjectSpace where this module has been + # mixed in according to Module#included_modules. + # + # module M + # end + # + # module N + # include M + # end + # + # class C + # include M + # end + # + # class D < C + # end + # + # p M.included_in_classes # => [C, D] + # def included_in_classes classes = [] ObjectSpace.each_object(Class) { |k| classes << k if k.included_modules.include?(self) } diff --git a/activesupport/lib/active_support/core_ext/module/introspection.rb b/activesupport/lib/active_support/core_ext/module/introspection.rb index ddc9297b95..40bbebb7c4 100644 --- a/activesupport/lib/active_support/core_ext/module/introspection.rb +++ b/activesupport/lib/active_support/core_ext/module/introspection.rb @@ -1,13 +1,38 @@ class Module - # Return the module which contains this one; if this is a root module, such as - # +::MyModule+, then Object is returned. + # Returns the module which contains this one according to its name. + # + # module M + # module N + # end + # end + # X = M::N + # + # p M::N.parent # => M + # p X.parent # => M + # + # The parent of top-level and anonymous modules is Object. + # + # p M.parent # => Object + # p Module.new.parent # => Object + # def parent parent_name = name.split('::')[0..-2] * '::' parent_name.empty? ? Object : parent_name.constantize end - # Return all the parents of this module, ordered from nested outwards. The - # receiver is not contained within the result. + # Returns all the parents of this module according to its name, ordered from + # nested outwards. The receiver is not contained within the result. + # + # module M + # module N + # end + # end + # X = M::N + # + # p M.parents # => [Object] + # p M::N.parents # => [M, Object] + # p X.parents # => [M, Object] + # def parents parents = [] parts = name.split('::')[0..-2] @@ -20,7 +45,7 @@ class Module end if RUBY_VERSION < '1.9' - # Return the constants that have been defined locally by this object and + # Returns the constants that have been defined locally by this object and # not in an ancestor. This method is exact if running under Ruby 1.9. In # previous versions it may miss some constants if their definition in some # ancestor is identical to their definition in the receiver. diff --git a/activesupport/lib/active_support/core_ext/module/loading.rb b/activesupport/lib/active_support/core_ext/module/loading.rb index 36c0c61405..4b4b110b25 100644 --- a/activesupport/lib/active_support/core_ext/module/loading.rb +++ b/activesupport/lib/active_support/core_ext/module/loading.rb @@ -1,4 +1,14 @@ class Module + # Returns String#underscore applied to the module name minus trailing classes. + # + # ActiveRecord.as_load_path # => "active_record" + # ActiveRecord::Associations.as_load_path # => "active_record/associations" + # ActiveRecord::Base.as_load_path # => "active_record" (Base is a class) + # + # The Kernel module gives an empty string by definition. + # + # Kernel.as_load_path # => "" + # Math.as_load_path # => "math" def as_load_path if self == Object || self == Kernel '' diff --git a/activesupport/lib/active_support/core_ext/object/instance_variables.rb b/activesupport/lib/active_support/core_ext/object/instance_variables.rb index 57276135c4..f091acb969 100644 --- a/activesupport/lib/active_support/core_ext/object/instance_variables.rb +++ b/activesupport/lib/active_support/core_ext/object/instance_variables.rb @@ -6,6 +6,16 @@ class Object end end + # Returns a hash that maps instance variable names without "@" to their + # corresponding values. Keys are strings both in Ruby 1.8 and 1.9. + # + # class C + # def initialize(x, y) + # @x, @y = x, y + # end + # end + # + # C.new(0, 1).instance_values # => {"x" => 0, "y" => 1} def instance_values #:nodoc: instance_variables.inject({}) do |values, name| values[name.to_s[1..-1]] = instance_variable_get(name) @@ -13,10 +23,44 @@ class Object end end + # Returns an array of instance variable names including "@". They are strings + # both in Ruby 1.8 and 1.9. + # + # class C + # def initialize(x, y) + # @x, @y = x, y + # end + # end + # + # C.new(0, 1).instance_variable_names # => ["@y", "@x"] def instance_variable_names instance_variables.map(&:to_s) end + # Copies the instance variables of +object+ into self. + # + # Instance variable names in the +exclude+ array are ignored. If +object+ + # responds to protected_instance_variables the ones returned are + # also ignored. For example, Rails controllers implement that method. + # + # In both cases strings and symbols are understood, and they have to include + # the at sign. + # + # class C + # def initialize(x, y, z) + # @x, @y, @z = x, y, z + # end + # + # def protected_instance_variables + # %w(@z) + # end + # end + # + # a = C.new(0, 1, 2) + # b = C.new(3, 4, 5) + # + # a.copy_instance_variables_from(b, [:@y]) + # # a is now: @x = 3, @y = 1, @z = 2 def copy_instance_variables_from(object, exclude = []) #:nodoc: exclude += object.protected_instance_variables if object.respond_to? :protected_instance_variables diff --git a/activesupport/lib/active_support/core_ext/range/conversions.rb b/activesupport/lib/active_support/core_ext/range/conversions.rb index 3d12605f4d..8d757646d3 100644 --- a/activesupport/lib/active_support/core_ext/range/conversions.rb +++ b/activesupport/lib/active_support/core_ext/range/conversions.rb @@ -13,7 +13,12 @@ module ActiveSupport #:nodoc: alias_method :to_s, :to_formatted_s end end - + # Gives a human readable format of the range. + # + # Example: + # + # >> [1..100].to_formatted_s + # => "1..100" def to_formatted_s(format = :default) RANGE_FORMATS[format] ? RANGE_FORMATS[format].call(first, last) : to_default_s end diff --git a/activesupport/lib/active_support/core_ext/string/inflections.rb b/activesupport/lib/active_support/core_ext/string/inflections.rb index 72a93c217f..a009d7c085 100644 --- a/activesupport/lib/active_support/core_ext/string/inflections.rb +++ b/activesupport/lib/active_support/core_ext/string/inflections.rb @@ -5,44 +5,42 @@ module ActiveSupport #:nodoc: module String #:nodoc: # String inflections define new methods on the String class to transform names for different purposes. # For instance, you can figure out the name of a database from the name of a class. - # "ScaleScore".tableize => "scale_scores" + # + # "ScaleScore".tableize # => "scale_scores" module Inflections # Returns the plural form of the word in the string. # - # Examples - # "post".pluralize #=> "posts" - # "octopus".pluralize #=> "octopi" - # "sheep".pluralize #=> "sheep" - # "words".pluralize #=> "words" - # "the blue mailman".pluralize #=> "the blue mailmen" - # "CamelOctopus".pluralize #=> "CamelOctopi" + # "post".pluralize # => "posts" + # "octopus".pluralize # => "octopi" + # "sheep".pluralize # => "sheep" + # "words".pluralize # => "words" + # "the blue mailman".pluralize # => "the blue mailmen" + # "CamelOctopus".pluralize # => "CamelOctopi" def pluralize Inflector.pluralize(self) end - # The reverse of pluralize, returns the singular form of a word in a string. + # The reverse of +pluralize+, returns the singular form of a word in a string. # - # Examples - # "posts".singularize #=> "post" - # "octopi".singularize #=> "octopus" - # "sheep".singluarize #=> "sheep" - # "word".singluarize #=> "word" - # "the blue mailmen".singularize #=> "the blue mailman" - # "CamelOctopi".singularize #=> "CamelOctopus" + # "posts".singularize # => "post" + # "octopi".singularize # => "octopus" + # "sheep".singluarize # => "sheep" + # "word".singluarize # => "word" + # "the blue mailmen".singularize # => "the blue mailman" + # "CamelOctopi".singularize # => "CamelOctopus" def singularize Inflector.singularize(self) end - # By default, camelize converts strings to UpperCamelCase. If the argument to camelize - # is set to ":lower" then camelize produces lowerCamelCase. + # By default, +camelize+ converts strings to UpperCamelCase. If the argument to camelize + # is set to :lower then camelize produces lowerCamelCase. # - # camelize will also convert '/' to '::' which is useful for converting paths to namespaces + # +camelize+ will also convert '/' to '::' which is useful for converting paths to namespaces. # - # Examples - # "active_record".camelize #=> "ActiveRecord" - # "active_record".camelize(:lower) #=> "activeRecord" - # "active_record/errors".camelize #=> "ActiveRecord::Errors" - # "active_record/errors".camelize(:lower) #=> "activeRecord::Errors" + # "active_record".camelize # => "ActiveRecord" + # "active_record".camelize(:lower) # => "activeRecord" + # "active_record/errors".camelize # => "ActiveRecord::Errors" + # "active_record/errors".camelize(:lower) # => "activeRecord::Errors" def camelize(first_letter = :upper) case first_letter when :upper then Inflector.camelize(self, true) @@ -52,78 +50,72 @@ module ActiveSupport #:nodoc: alias_method :camelcase, :camelize # Capitalizes all the words and replaces some characters in the string to create - # a nicer looking title. Titleize is meant for creating pretty output. It is not + # a nicer looking title. +titleize+ is meant for creating pretty output. It is not # used in the Rails internals. # - # titleize is also aliased as as titlecase + # +titleize+ is also aliased as +titlecase+. # - # Examples - # "man from the boondocks".titleize #=> "Man From The Boondocks" - # "x-men: the last stand".titleize #=> "X Men: The Last Stand" + # "man from the boondocks".titleize # => "Man From The Boondocks" + # "x-men: the last stand".titleize # => "X Men: The Last Stand" def titleize Inflector.titleize(self) end alias_method :titlecase, :titleize - # The reverse of +camelize+. Makes an underscored form from the expression in the string. + # The reverse of +camelize+. Makes an underscored, lowercase form from the expression in the string. # - # Changes '::' to '/' to convert namespaces to paths. + # +underscore+ will also change '::' to '/' to convert namespaces to paths. # - # Examples - # "ActiveRecord".underscore #=> "active_record" - # "ActiveRecord::Errors".underscore #=> active_record/errors + # "ActiveRecord".underscore # => "active_record" + # "ActiveRecord::Errors".underscore # => active_record/errors def underscore Inflector.underscore(self) end # Replaces underscores with dashes in the string. # - # Example - # "puni_puni" #=> "puni-puni" + # "puni_puni" # => "puni-puni" def dasherize Inflector.dasherize(self) end - # Removes the module part from the expression in the string + # Removes the module part from the constant expression in the string. # - # Examples - # "ActiveRecord::CoreExtensions::String::Inflections".demodulize #=> "Inflections" - # "Inflections".demodulize #=> "Inflections" + # "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections" + # "Inflections".demodulize # => "Inflections" def demodulize Inflector.demodulize(self) end - # Create the name of a table like Rails does for models to table names. This method - # uses the pluralize method on the last word in the string. + # Creates the name of a table like Rails does for models to table names. This method + # uses the +pluralize+ method on the last word in the string. # - # Examples - # "RawScaledScorer".tableize #=> "raw_scaled_scorers" - # "egg_and_ham".tableize #=> "egg_and_hams" - # "fancyCategory".tableize #=> "fancy_categories" + # "RawScaledScorer".tableize # => "raw_scaled_scorers" + # "egg_and_ham".tableize # => "egg_and_hams" + # "fancyCategory".tableize # => "fancy_categories" def tableize Inflector.tableize(self) end # Create a class name from a plural table name like Rails does for table names to models. - # Note that this returns a string and not a Class. (To convert to an actual class - # follow classify with constantize.) + # Note that this returns a string and not a class. (To convert to an actual class + # follow +classify+ with +constantize+.) # - # Examples - # "egg_and_hams".classify #=> "EggAndHam" - # "posts".classify #=> "Post" + # "egg_and_hams".classify # => "EggAndHam" + # "posts".classify # => "Post" # - # Singular names are not handled correctly - # "business".classify #=> "Busines" + # Singular names are not handled correctly. + # + # "business".classify # => "Busines" def classify Inflector.classify(self) end - # Capitalizes the first word and turns underscores into spaces and strips _id. - # Like titleize, this is meant for creating pretty output. + # Capitalizes the first word, turns underscores into spaces, and strips '_id'. + # Like +titleize+, this is meant for creating pretty output. # - # Examples - # "employee_salary" #=> "Employee salary" - # "author_id" #=> "Author" + # "employee_salary" # => "Employee salary" + # "author_id" # => "Author" def humanize Inflector.humanize(self) end @@ -133,20 +125,20 @@ module ActiveSupport #:nodoc: # the method should put '_' between the name and 'id'. # # Examples - # "Message".foreign_key #=> "message_id" - # "Message".foreign_key(false) #=> "messageid" - # "Admin::Post".foreign_key #=> "post_id" + # "Message".foreign_key # => "message_id" + # "Message".foreign_key(false) # => "messageid" + # "Admin::Post".foreign_key # => "post_id" def foreign_key(separate_class_name_and_id_with_underscore = true) Inflector.foreign_key(self, separate_class_name_and_id_with_underscore) end - # Constantize tries to find a declared constant with the name specified + # +constantize+ tries to find a declared constant with the name specified # in the string. It raises a NameError when the name is not in CamelCase # or is not initialized. # # Examples - # "Module".constantize #=> Module - # "Class".constantize #=> Class + # "Module".constantize # => Module + # "Class".constantize # => Class def constantize Inflector.constantize(self) end diff --git a/activesupport/lib/active_support/core_ext/string/unicode.rb b/activesupport/lib/active_support/core_ext/string/unicode.rb index eab1c1d246..0e00b32194 100644 --- a/activesupport/lib/active_support/core_ext/string/unicode.rb +++ b/activesupport/lib/active_support/core_ext/string/unicode.rb @@ -27,7 +27,7 @@ module ActiveSupport #:nodoc: # object. Interoperability problems can be resolved easily with a +to_s+ call. # # For more information about the methods defined on the Chars proxy see ActiveSupport::Multibyte::Chars and - # ActiveSupport::Multibyte::Handlers::UTF8Handler + # ActiveSupport::Multibyte::Handlers::UTF8Handler. def chars ActiveSupport::Multibyte::Chars.new(self) end diff --git a/activesupport/lib/active_support/core_ext/time/zones.rb b/activesupport/lib/active_support/core_ext/time/zones.rb index ee1d33fbc8..e7610d144f 100644 --- a/activesupport/lib/active_support/core_ext/time/zones.rb +++ b/activesupport/lib/active_support/core_ext/time/zones.rb @@ -43,18 +43,18 @@ module ActiveSupport #:nodoc: end end - # Returns the simultaneous time in Time.zone. Example: + # Returns the simultaneous time in Time.zone. # - # Time.zone = 'Hawaii' # => 'Hawaii' - # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 + # Time.zone = 'Hawaii' # => 'Hawaii' + # Time.utc(2000).in_time_zone # => Fri, 31 Dec 1999 14:00:00 HST -10:00 # # This method is similar to Time#localtime, except that it uses Time.zone as the local zone # instead of the operating system's time zone. # # You can also pass in a TimeZone instance or string that identifies a TimeZone as an argument, - # and the conversion will be based on that zone instead of Time.zone. Example: + # and the conversion will be based on that zone instead of Time.zone. # - # Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 + # Time.utc(2000).in_time_zone('Alaska') # => Fri, 31 Dec 1999 15:00:00 AKST -09:00 def in_time_zone(zone = ::Time.zone) ActiveSupport::TimeWithZone.new(utc? ? self : getutc, ::Time.send!(:get_zone, zone)) end diff --git a/activesupport/lib/active_support/gzip.rb b/activesupport/lib/active_support/gzip.rb index c65944dacd..35a50e9a77 100644 --- a/activesupport/lib/active_support/gzip.rb +++ b/activesupport/lib/active_support/gzip.rb @@ -2,15 +2,18 @@ require 'zlib' require 'stringio' module ActiveSupport + # A convenient wrapper for the zlib standard library that allows compression/decompression of strings with gzip. module Gzip class Stream < StringIO def close; rewind; end end + # Decompresses a gzipped string. def self.decompress(source) Zlib::GzipReader.new(StringIO.new(source)).read end + # Compresses a string using gzip. def self.compress(source) output = Stream.new gz = Zlib::GzipWriter.new(output) diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb index 9d3976da20..9f724619e9 100644 --- a/activesupport/lib/active_support/inflector.rb +++ b/activesupport/lib/active_support/inflector.rb @@ -165,7 +165,7 @@ module Inflector humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize } end - # The reverse of +camelize+. Makes an underscored form from the expression in the string. + # The reverse of +camelize+. Makes an underscored, lowercase form from the expression in the string. # # Changes '::' to '/' to convert namespaces to paths. # diff --git a/activesupport/lib/active_support/json/encoders/date.rb b/activesupport/lib/active_support/json/encoders/date.rb index 853d9b868c..d55f17962b 100644 --- a/activesupport/lib/active_support/json/encoders/date.rb +++ b/activesupport/lib/active_support/json/encoders/date.rb @@ -1,5 +1,10 @@ class Date - def to_json(options = nil) #:nodoc: + # Returns a JSON string representing the date. + # + # ==== Example: + # Date.new(2005,2,1).to_json + # # => "2005/02/01" + def to_json(options = nil) %("#{strftime("%Y/%m/%d")}") end end diff --git a/activesupport/lib/active_support/json/encoders/date_time.rb b/activesupport/lib/active_support/json/encoders/date_time.rb index f0b0434412..380361c360 100644 --- a/activesupport/lib/active_support/json/encoders/date_time.rb +++ b/activesupport/lib/active_support/json/encoders/date_time.rb @@ -1,5 +1,10 @@ class DateTime - def to_json(options = nil) #:nodoc: + # Returns a JSON string representing the datetime. + # + # ==== Example: + # DateTime.civil(2005,2,1,15,15,10).to_json + # # => "2005/02/01 15:15:10 +0000" + def to_json(options = nil) %("#{strftime("%Y/%m/%d %H:%M:%S %z")}") end end diff --git a/activesupport/lib/active_support/json/encoders/enumerable.rb b/activesupport/lib/active_support/json/encoders/enumerable.rb index 720fd88f90..881b1d62c1 100644 --- a/activesupport/lib/active_support/json/encoders/enumerable.rb +++ b/activesupport/lib/active_support/json/encoders/enumerable.rb @@ -2,8 +2,8 @@ module Enumerable # Returns a JSON string representing the enumerable. Any +options+ # given will be passed on to its elements. For example: # - # users = User.find(:all) - # users.to_json(:only => :name) + # users = User.find(:all) + # # => users.to_json(:only => :name) # # will pass the :only => :name option to each user. def to_json(options = {}) #:nodoc: diff --git a/activesupport/lib/active_support/json/encoders/hash.rb b/activesupport/lib/active_support/json/encoders/hash.rb index 774803d64f..b9bdd55fa5 100644 --- a/activesupport/lib/active_support/json/encoders/hash.rb +++ b/activesupport/lib/active_support/json/encoders/hash.rb @@ -5,8 +5,7 @@ class Hash # the hash keys. For example: # # { :name => "Konata Izumi", 'age' => 16, 1 => 2 }.to_json - # - # {"name": "Konata Izumi", 1: 2, "age": 16} + # # => {"name": "Konata Izumi", 1: 2, "age": 16} # # The keys in the JSON string are unordered due to the nature of hashes. # @@ -14,12 +13,10 @@ class Hash # attributes included, and will accept 1 or more hash keys to include/exclude. # # { :name => "Konata Izumi", 'age' => 16, 1 => 2 }.to_json(:only => [:name, 'age']) - # - # {"name": "Konata Izumi", "age": 16} + # # => {"name": "Konata Izumi", "age": 16} # # { :name => "Konata Izumi", 'age' => 16, 1 => 2 }.to_json(:except => 1) - # - # {"name": "Konata Izumi", "age": 16} + # # => {"name": "Konata Izumi", "age": 16} # # The +options+ also filter down to any hash values. This is particularly # useful for converting hashes containing ActiveRecord objects or any object diff --git a/activesupport/lib/active_support/json/encoders/object.rb b/activesupport/lib/active_support/json/encoders/object.rb index 6da0d1d1c1..ca215d4964 100644 --- a/activesupport/lib/active_support/json/encoders/object.rb +++ b/activesupport/lib/active_support/json/encoders/object.rb @@ -1,5 +1,5 @@ class Object - # Dumps object in JSON (JavaScript Object Notation). See www.json.org for more info. + # Dumps object in JSON (JavaScript Object Notation). See www.json.org for more info. def to_json(options = {}) ActiveSupport::JSON.encode(instance_values, options) end diff --git a/activesupport/lib/active_support/json/encoders/time.rb b/activesupport/lib/active_support/json/encoders/time.rb index 4f964a92e0..b0c9189c78 100644 --- a/activesupport/lib/active_support/json/encoders/time.rb +++ b/activesupport/lib/active_support/json/encoders/time.rb @@ -1,5 +1,10 @@ class Time - def to_json(options = nil) #:nodoc: + # Returns a JSON string representing the time. + # + # ==== Example: + # Time.utc(2005,2,1,15,15,10).to_json + # # => 2005/02/01 15:15:10 +0000" + def to_json(options = nil) %("#{strftime("%Y/%m/%d %H:%M:%S")} #{formatted_offset(false)}") end end diff --git a/activesupport/lib/active_support/whiny_nil.rb b/activesupport/lib/active_support/whiny_nil.rb index f614b41fc7..983a14fd42 100644 --- a/activesupport/lib/active_support/whiny_nil.rb +++ b/activesupport/lib/active_support/whiny_nil.rb @@ -18,6 +18,7 @@ class NilClass methods.each { |method| @@method_class_map[method.to_sym] = class_name } end + # Raises a RuntimeError when you attempt to call id on nil or a nil object. def id raise RuntimeError, "Called id for nil, which would mistakenly be 4 -- if you really wanted the id of nil, use object_id", caller end @@ -27,6 +28,7 @@ class NilClass raise_nil_warning_for @@method_class_map[method], method, caller end + # Raises a NoMethodError when you attempt to call a method on nil, or a nil object. def raise_nil_warning_for(class_name = nil, selector = nil, with_caller = nil) message = "You have a nil object when you didn't expect it!" message << "\nYou might have expected an instance of #{class_name}." if class_name -- cgit v1.2.3