activesupport 2.0.5 → 2.1.0

data/lib/active_support/core_ext/array/access.rb

@@ -3,9 +3,8 @@ module ActiveSupport #:nodoc:
     module Array #:nodoc:
       # Makes it easier to access parts of an array.
       module Access
-        # Returns the remaining of the array from the +position+.
+        # Returns the tail of the array from +position+.
         #
-        # Examples: 
         #   %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
@@ -13,9 +12,8 @@ module ActiveSupport #:nodoc:
           self[position..-1]
         end
         
-        # Returns the beginning of the array up to the +position+.
+        # Returns the beginning of the array up to +position+.
         #
-        # Examples: 
         #   %w( a b c d ).to(0)  # => %w( a )
         #   %w( a b c d ).to(2)  # => %w( a b c )
         #   %w( a b c d ).to(10) # => %w( a b c d )

data/lib/active_support/core_ext/array/conversions.rb

@@ -24,16 +24,16 @@ 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 <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
           map(&:to_param).join '/'
         end
 
-        # Converts an array into a string suitable for use as a URL query string, using the given <tt>key</tt> as the
-        # param name.
+        # 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"
+        #   ['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 +45,15 @@ module ActiveSupport #:nodoc:
           end
         end
 
+        # Converts a collection of elements into a formatted string by calling
+        # <tt>to_s</tt> on all elements and joining them:
+        #
+        #   Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post"
+        #
+        # Adding in the <tt>:db</tt> 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 +67,81 @@ module ActiveSupport #:nodoc:
           end
         end
 
+        # Returns a string that represents this array in XML by sending +to_xml+
+        # to each element. Active Record collections delegate their representation
+        # in XML to this method.
+        #
+        # 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:
+        #
+        #   customer.projects.to_xml
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <projects type="array">
+        #     <project>
+        #       <amount type="decimal">20000.0</amount>
+        #       <customer-id type="integer">1567</customer-id>
+        #       <deal-date type="date">2008-04-09</deal-date>
+        #       ...
+        #     </project>
+        #     <project>
+        #       <amount type="decimal">57230.0</amount>
+        #       <customer-id type="integer">1567</customer-id>
+        #       <deal-date type="date">2008-04-15</deal-date>
+        #       ...
+        #     </project>
+        #   </projects>
+        #
+        # Otherwise the root element is "records":
+        #
+        #   [{:foo => 1, :bar => 2}, {:baz => 3}].to_xml
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <records type="array">
+        #     <record>
+        #       <bar type="integer">2</bar>
+        #       <foo type="integer">1</foo>
+        #     </record>
+        #     <record>
+        #       <baz type="integer">3</baz>
+        #     </record>
+        #   </records>
+        #
+        # If the collection is empty the root element is "nil-classes" by default:
+        #
+        #   [].to_xml
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <nil-classes type="array"/>
+        #
+        # To ensure a meaningful root element use the <tt>:root</tt> option:
+        #
+        #   customer_with_no_projects.projects.to_xml(:root => "projects")
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <projects type="array"/>
+        #
+        # By default root children have as node name the one of the root
+        # singularized. You can change it with the <tt>:children</tt> option.
+        #
+        # The +options+ hash is passed downwards:
+        #
+        #   Message.all.to_xml(:skip_types => true)
+        #
+        #   <?xml version="1.0" encoding="UTF-8"?>
+        #   <messages>
+        #     <message>
+        #       <created-at>2008-03-07T09:58:18+01:00</created-at>
+        #       <id>1</id>
+        #       <name>1</name>
+        #       <updated-at>2008-03-07T09:58:18+01:00</updated-at>
+        #       <user-id>1</user-id>
+        #     </message>
+        #   </messages>
+        #
         def to_xml(options = {})
           raise "Not all elements respond to to_xml" unless all? { |e| e.respond_to? :to_xml }
 

data/lib/active_support/core_ext/array/extract_options.rb

@@ -2,7 +2,8 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module ExtractOptions
-        # Extract options from a set of arguments. Removes and returns the last element in the array if it's a hash, otherwise returns a blank hash.
+        # Extracts options from a set of arguments. Removes and returns the last
+        # element in the array if it's a hash, otherwise returns a blank hash.
         #
         #   def options(*args)
         #     args.extract_options!

data/lib/active_support/core_ext/array/grouping.rb

@@ -4,11 +4,8 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module Grouping
-        # Iterate over an array in groups of a certain size, padding any remaining 
-        # slots with specified value (<tt>nil</tt> by default) unless it is
-        # <tt>false</tt>.
-        # 
-        # E.g.
+        # Iterates over the array in groups of size +number+, padding any remaining 
+        # slots with +fill_with+ unless it is +false+.
         # 
         #   %w(1 2 3 4 5 6 7).in_groups_of(3) {|g| p g}
         #   ["1", "2", "3"]
@@ -42,11 +39,9 @@ module ActiveSupport #:nodoc:
           end
         end
 
-        # Divide the array into one or more subarrays based on a delimiting +value+
+        # Divides the array into one or more subarrays based on a delimiting +value+
         # or the result of an optional block.
         #
-        # ex.
-        #
         #   [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]]
         def split(value = nil, &block)

data/lib/active_support/core_ext/array/random_access.rb

@@ -2,7 +2,7 @@ module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module Array #:nodoc:
       module RandomAccess
-        # Return a random element from the array.
+        # Returns a random element from the array.
         def rand
           self[Kernel.rand(length)]
         end

data/lib/active_support/core_ext/base64.rb

@@ -0,0 +1,4 @@
+require 'active_support/base64'
+require 'active_support/core_ext/base64/encoding'
+
+ActiveSupport::Base64.extend ActiveSupport::CoreExtensions::Base64::Encoding

data/lib/active_support/core_ext/base64/encoding.rb

@@ -0,0 +1,13 @@
+module ActiveSupport #:nodoc:
+  module CoreExtensions #:nodoc:
+    module Base64 #:nodoc:
+      module Encoding
+        # Encodes the value as base64 without the newline breaks. This makes the base64 encoding readily usable as URL parameters 
+        # or memcache keys without further processing.
+        def encode64s(value)
+          encode64(value).gsub(/\n/, '')
+        end
+      end
+    end
+  end
+end

data/lib/active_support/core_ext/benchmark.rb

@@ -0,0 +1,12 @@
+require 'benchmark'
+
+class << Benchmark
+  remove_method :realtime
+
+  def realtime
+    r0 = Time.now
+    yield
+    r1 = Time.now
+    r1.to_f - r0.to_f
+  end
+end

data/lib/active_support/core_ext/bigdecimal.rb

@@ -1,2 +1,6 @@
 require 'bigdecimal'
 require 'active_support/core_ext/bigdecimal/conversions'
+
+class BigDecimal#:nodoc:
+  include ActiveSupport::CoreExtensions::BigDecimal::Conversions
+end

data/lib/active_support/core_ext/bigdecimal/conversions.rb

@@ -1,6 +1,41 @@
-class BigDecimal #:nodoc:
-  alias :_original_to_s :to_s
-  def to_s(format="F")
-    _original_to_s(format)
+require 'yaml'
+
+module ActiveSupport #:nodoc:
+  module CoreExtensions #:nodoc:
+    module BigDecimal #:nodoc:
+      module Conversions
+        def self.included(base) #:nodoc:
+          base.instance_eval do
+            alias_method :_original_to_s, :to_s
+            alias_method :to_s, :to_formatted_s
+          end
+        end
+        
+        def to_formatted_s(format="F")
+          _original_to_s(format)
+        end
+        
+        yaml_as "tag:yaml.org,2002:float"
+        def to_yaml( opts = {} )
+          YAML::quick_emit( nil, opts ) do |out|
+            # This emits the number without any scientific notation.
+            # I prefer it to using self.to_f.to_s, which would lose precision.
+            #
+            # Note that YAML allows that when reconsituting floats
+            # to native types, some precision may get lost.
+            # There is no full precision real YAML tag that I am aware of.
+            str = self.to_s
+            if str == "Infinity"
+              str = ".Inf"
+            elsif str == "-Infinity"
+              str = "-.Inf"
+            elsif str == "NaN"
+              str = ".NaN"
+            end
+            out.scalar( "tag:yaml.org,2002:float", str, :plain )
+          end
+        end
+      end
+    end
   end
 end

data/lib/active_support/core_ext/blank.rb

@@ -1,10 +1,13 @@
 class Object
-  # An object is blank if it's nil, empty, or a whitespace string.
-  # For example, "", "   ", nil, [], and {} are blank.
+  # An object is blank if it's false, empty, or a whitespace string.
+  # For example, "", "   ", +nil+, [], and {} are blank.
   #
   # This simplifies
+  #
   #   if !address.nil? && !address.empty?
+  #
   # to
+  #
   #   if !address.blank?
   def blank?
     respond_to?(:empty?) ? empty? : !self

data/lib/active_support/core_ext/class/attribute_accessors.rb

@@ -1,6 +1,12 @@
 # Extends the class object with class and instance accessors for class attributes,
 # just like the native attr* accessors for instance attributes.
-class Class # :nodoc:
+#
+#  class Person
+#    cattr_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+class Class
   def cattr_reader(*syms)
     syms.flatten.each do |sym|
       next if sym.is_a?(Hash)

data/lib/active_support/core_ext/class/delegating_attributes.rb

@@ -19,6 +19,12 @@ class Class
       def #{name}
         self.class.#{name}
       end
+      def self.#{name}?
+        !!#{name}
+      end
+      def #{name}?
+        !!#{name}
+      end
       EOS
     end
   end
@@ -37,4 +43,4 @@ class Class
     superclass_delegating_reader(*names)
     superclass_delegating_writer(*names)
   end
-end
+end

data/lib/active_support/core_ext/class/inheritable_attributes.rb

@@ -128,7 +128,7 @@ class Class # :nodoc:
         new_inheritable_attributes = EMPTY_INHERITABLE_ATTRIBUTES
       else
         new_inheritable_attributes = inheritable_attributes.inject({}) do |memo, (key, value)|
-          memo.update(key => (value.dup rescue value))
+          memo.update(key => value.duplicable? ? value.dup : value)
         end
       end
       

data/lib/active_support/core_ext/class/removal.rb

@@ -1,12 +1,38 @@
 class Class #:nodoc:
+  
+  # Unassociates the class with its subclasses and removes the subclasses
+  # themselves.
+  #
+  #   Integer.remove_subclasses # => [Bignum, Fixnum]
+  #   Fixnum                    # => NameError: uninitialized constant Fixnum
   def remove_subclasses
     Object.remove_subclasses_of(self)
   end
 
+  # Returns an array with the names of the subclasses of +self+ as strings.
+  #
+  #   Integer.subclasses # => ["Bignum", "Fixnum"]
   def subclasses
     Object.subclasses_of(self).map { |o| o.to_s }
   end
 
+  # Removes the classes in +klasses+ from their parent module.
+  #
+  # Ordinary classes belong to some module via a constant. This method computes
+  # that constant name from the class name and removes it from the module it
+  # belongs to.
+  #
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #
+  # Take into account that in general the class object could be still stored
+  # somewhere else.
+  #
+  #   i = Integer                  # => Integer
+  #   Object.remove_class(Integer) # => [Integer]
+  #   Integer                      # => NameError: uninitialized constant Integer
+  #   i.subclasses                 # => ["Bignum", "Fixnum"]
+  #   Fixnum.superclass            # => Integer
   def remove_class(*klasses)
     klasses.flatten.each do |klass|
       # Skip this class if there is nothing bound to this name

data/lib/active_support/core_ext/date/calculations.rb

@@ -16,13 +16,20 @@ module ActiveSupport #:nodoc:
         end
 
         module ClassMethods
+          # Returns a new Date representing the date 1 day ago (i.e. yesterday's date).
           def yesterday
             ::Date.today.yesterday
           end
           
+          # Returns a new Date representing the date 1 day after today (i.e. tomorrow's date).
           def tomorrow
             ::Date.today.tomorrow
           end
+          
+          # Returns Time.zone.today when config.time_zone is set, otherwise just returns Date.today.
+          def current
+            ::Time.zone_default ? ::Time.zone.today : ::Date.today
+          end
         end
         
         # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
@@ -68,7 +75,7 @@ module ActiveSupport #:nodoc:
         end
         
         # Provides precise Date calculations for years, months, and days.  The +options+ parameter takes a hash with 
-        # any of these keys: :years, :months, :weeks, :days.
+        # any of these keys: <tt>:years</tt>, <tt>:months</tt>, <tt>:weeks</tt>, <tt>:days</tt>.
         def advance(options)
           d = self
           d = d >> options.delete(:years) * 12 if options[:years]
@@ -141,6 +148,14 @@ module ActiveSupport #:nodoc:
         alias :monday :beginning_of_week
         alias :at_beginning_of_week :beginning_of_week
 
+        # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59)
+        def end_of_week
+          days_to_sunday = self.wday!=0 ? 7-self.wday : 0
+          result = self + days_to_sunday.days
+          self.acts_like?(:time) ? result.end_of_day : result
+        end
+        alias :at_end_of_week :end_of_week
+
         # Returns a new Date/DateTime representing the start of the given day in next week (default is Monday).
         def next_week(day = :monday)
           days_into_week = { :monday => 0, :tuesday => 1, :wednesday => 2, :thursday => 3, :friday => 4, :saturday => 5, :sunday => 6}
@@ -167,12 +182,24 @@ module ActiveSupport #:nodoc:
         end
         alias :at_beginning_of_quarter :beginning_of_quarter
 
+        # Returns a new Date/DateTime representing the end of the quarter (last day of march, june, september, december; DateTime objects will have time set to 23:59:59)
+        def end_of_quarter
+          change(:month => [3, 6, 9, 12].detect { |m| m >= self.month }).end_of_month
+        end
+        alias :at_end_of_quarter :end_of_quarter
+
         # Returns a new Date/DateTime representing the start of the year (1st of january; DateTime objects will have time set to 0:00)
         def beginning_of_year
           self.acts_like?(:time) ? change(:month => 1, :day => 1, :hour => 0, :min => 0, :sec => 0) : change(:month => 1, :day => 1)
         end
         alias :at_beginning_of_year :beginning_of_year
 
+        # Returns a new Time representing the end of the year (31st of december; DateTime objects will have time set to 23:59:59)
+        def end_of_year
+          self.acts_like?(:time) ? change(:month => 12,:day => 31,:hour => 23, :min => 59, :sec => 59) : change(:month => 12, :day => 31)
+        end
+        alias :at_end_of_year :end_of_year
+
         # Convenience method which returns a new Date/DateTime representing the time 1 day ago
         def yesterday
           self - 1

data/lib/active_support/core_ext/date/conversions.rb

@@ -7,6 +7,7 @@ module ActiveSupport #:nodoc:
           :short        => "%e %b",
           :long         => "%B %e, %Y",
           :db           => "%Y-%m-%d",
+          :number       => "%Y%m%d",
           :long_ordinal => lambda { |date| date.strftime("%B #{date.day.ordinalize}, %Y") }, # => "April 25th, 2007"
           :rfc822       => "%e %b %Y"
         }