activesupport 2.0.5 → 2.1.0

data/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

data/lib/active_support/core_ext/module/attr_internal.rb

@@ -1,19 +1,20 @@
 class Module
-  # Declare an attribute reader backed by an internally-named instance variable.
+  # Declares an attribute reader backed by an internally-named instance variable.
   def attr_internal_reader(*attrs)
     attrs.each do |attr|
       module_eval "def #{attr}() #{attr_internal_ivar_name(attr)} end"
     end
   end
 
-  # Declare an attribute writer backed by an internally-named instance variable.
+  # Declares an attribute writer backed by an internally-named instance variable.
   def attr_internal_writer(*attrs)
     attrs.each do |attr|
       module_eval "def #{attr}=(v) #{attr_internal_ivar_name(attr)} = v end"
     end
   end
 
-  # Declare attributes backed by 'internal' instance variables names.
+  # Declares 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)

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

@@ -1,6 +1,16 @@
 # Extends the module object with module and instance accessors for class attributes, 
 # just like the native attr* accessors for instance attributes.
-class Module # :nodoc:
+#
+#  module AppConfiguration
+#    mattr_accessor :google_api_key
+#    self.google_api_key = "123456789"
+#
+#    mattr_accessor :paypal_url
+#    self.paypal_url = "www.sandbox.paypal.com"
+#  end
+#
+#  AppConfiguration.google_api_key = "overriding the api key!"
+class Module
   def mattr_reader(*syms)
     syms.each do |sym|
       next if sym.is_a?(Hash)

data/lib/active_support/core_ext/module/delegation.rb

@@ -1,8 +1,8 @@
 class Module
   # Provides a delegate class method to easily expose contained objects' methods
   # as your own. Pass one or more methods (specified as symbols or strings)
-  # and the name of the target object as the final :to option (also a symbol
-  # or string).  At least one method and the :to option are required.
+  # and the name of the target object as the final <tt>:to</tt> option (also a symbol
+  # or string).  At least one method and the <tt>:to</tt> option are required.
   #
   # Delegation is particularly useful with Active Record associations:
   #
@@ -20,6 +20,7 @@ class Module
   #   Foo.new.goodbye # => NoMethodError: undefined method `goodbye' for #<Foo:0x1af30c>
   #
   # Multiple delegates to the same target are allowed:
+  #
   #   class Foo < ActiveRecord::Base
   #     belongs_to :greeter
   #     delegate :hello, :goodbye, :to => :greeter
@@ -28,7 +29,8 @@ class Module
   #   Foo.new.goodbye # => "goodbye"
   #
   # Methods can be delegated to instance variables, class variables, or constants
-  # by providing the variable as a symbol:
+  # by providing them as a symbols:
+  #
   #   class Foo
   #     CONSTANT_ARRAY = [0,1,2,3]
   #     @@class_array  = [4,5,6,7]

data/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) }

data/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]
@@ -18,18 +43,27 @@ class Module
     parents << Object unless parents.include? Object
     parents
   end
-  
-  # Return the constants that have been defined locally by this object and not
-  # in an ancestor. This method may miss some constants if their definition in
-  # the ancestor is identical to their definition in the receiver.
-  def local_constants
-    inherited = {}
-    ancestors.each do |anc|
-      next if anc == self
-      anc.constants.each { |const| inherited[const] = anc.const_get(const) }
+
+  if RUBY_VERSION < '1.9'
+    # 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.
+    def local_constants
+      inherited = {}
+
+      ancestors.each do |anc|
+        next if anc == self
+        anc.constants.each { |const| inherited[const] = anc.const_get(const) }
+      end
+
+      constants.select do |const|
+        !inherited.key?(const) || inherited[const].object_id != const_get(const).object_id
+      end
     end
-    constants.select do |const|
-      ! inherited.key?(const) || inherited[const].object_id != const_get(const).object_id
+  else
+    def local_constants #:nodoc:
+      constants(false)
     end
   end
 

data/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
       ''

data/lib/active_support/core_ext/numeric.rb

@@ -1,7 +1,9 @@
 require 'active_support/core_ext/numeric/time'
 require 'active_support/core_ext/numeric/bytes'
+require 'active_support/core_ext/numeric/conversions'
 
 class Numeric #:nodoc:
   include ActiveSupport::CoreExtensions::Numeric::Time 
-  include ActiveSupport::CoreExtensions::Numeric::Bytes 
+  include ActiveSupport::CoreExtensions::Numeric::Bytes
+  include ActiveSupport::CoreExtensions::Numeric::Conversions 
 end

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

@@ -0,0 +1,19 @@
+module ActiveSupport #:nodoc:
+  module CoreExtensions #:nodoc:
+    module Numeric #:nodoc:
+      module Conversions
+        # Assumes self represents an offset from UTC in seconds (as returned from Time#utc_offset)
+        # and turns this into an +HH:MM formatted string. Example:
+        #
+        #   -21_600.to_utc_offset_s   # => "-06:00"
+        def to_utc_offset_s(colon=true)
+          seconds = self
+          sign = (seconds < 0 ? -1 : 1)
+          hours = seconds.abs / 3600
+          minutes = (seconds.abs % 3600) / 60
+          "%+03d%s%02d" % [ hours * sign, colon ? ":" : "", minutes ]
+        end
+      end
+    end
+  end
+end

data/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,6 +23,48 @@ 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"]
+  if RUBY_VERSION >= '1.9'
+    def instance_variable_names
+      instance_variables.map(&:to_s)
+    end
+  else
+    alias_method :instance_variable_names, :instance_variables
+  end
+
+  # Copies the instance variables of +object+ into +self+.
+  #
+  # Instance variable names in the +exclude+ array are ignored. If +object+
+  # responds to <tt>protected_instance_variables</tt> 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
 

data/lib/active_support/core_ext/object/misc.rb

@@ -48,7 +48,7 @@ class Object
     yield ActiveSupport::OptionMerger.new(self, options)
   end
   
-  # A duck-type assistant method. For example, ActiveSupport extends Date
+  # A duck-type assistant method. For example, Active Support extends Date
   # to define an acts_like_date? method, and extends Time to define
   # acts_like_time?. As a result, we can do "x.acts_like?(:time)" and
   # "x.acts_like?(:date)" to do duck-type-safe comparisons, since classes that

data/lib/active_support/core_ext/process.rb

@@ -0,0 +1 @@
+require 'active_support/core_ext/process/daemon'

data/lib/active_support/core_ext/process/daemon.rb

@@ -0,0 +1,25 @@
+if RUBY_VERSION < "1.9"
+  module Process
+    def self.daemon(nochdir = nil, noclose = nil)
+      exit if fork                     # Parent exits, child continues.
+      Process.setsid                   # Become session leader.
+      exit if fork                     # Zap session leader. See [1].
+
+      unless nochdir
+        Dir.chdir "/"                  # Release old working directory.
+      end
+
+      File.umask 0000                  # Ensure sensible umask. Adjust as needed.
+
+      unless noclose
+        STDIN.reopen "/dev/null"       # Free file descriptors and
+        STDOUT.reopen "/dev/null", "a" # point them somewhere sensible.
+        STDERR.reopen '/dev/null', 'a'
+      end
+
+      trap("TERM") { exit }
+
+      return 0
+    end
+  end
+end

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

@@ -13,7 +13,11 @@ 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

data/lib/active_support/core_ext/range/include_range.rb

@@ -7,6 +7,14 @@ module ActiveSupport #:nodoc:
           base.alias_method_chain :include?, :range
         end
 
+        # Extends the default Range#include? to support range comparisons.
+        #  (1..5).include?(1..5) # => true
+        #  (1..5).include?(2..3) # => true
+        #  (1..5).include?(2..6) # => false
+        #
+        # The native Range#include? behavior is untouched.
+        #  ("a".."f").include?("c") # => true
+        #  (5..9).include?(11) # => false
         def include_with_range?(value)
           if value.is_a?(::Range)
             operator = exclude_end? ? :< : :<=

data/lib/active_support/core_ext/range/overlaps.rb

@@ -3,6 +3,9 @@ module ActiveSupport #:nodoc:
     module Range #:nodoc:
       # Check if Ranges overlap.
       module Overlaps
+        # Compare two ranges and see if they overlap eachother
+        #  (1..5).overlaps?(4..6) # => true
+        #  (1..5).overlaps?(7..9) # => false
         def overlaps?(other)
           include?(other.first) || other.include?(first)
         end

data/lib/active_support/core_ext/string.rb

@@ -2,22 +2,17 @@ require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/string/conversions'
 require 'active_support/core_ext/string/access'
 require 'active_support/core_ext/string/starts_ends_with'
-require 'active_support/core_ext/string/iterators' unless 'test'.respond_to?(:each_char)
+require 'active_support/core_ext/string/iterators'
 require 'active_support/core_ext/string/unicode'
 require 'active_support/core_ext/string/xchar'
+require 'active_support/core_ext/string/filters'
 
 class String #:nodoc:
   include ActiveSupport::CoreExtensions::String::Access
   include ActiveSupport::CoreExtensions::String::Conversions
+  include ActiveSupport::CoreExtensions::String::Filters
   include ActiveSupport::CoreExtensions::String::Inflections
-  if RUBY_VERSION < '1.9'
-    include ActiveSupport::CoreExtensions::String::StartsEndsWith
-  else
-    alias starts_with? start_with?
-    alias ends_with? end_with?
-  end
-  if defined? ActiveSupport::CoreExtensions::String::Iterators
-    include ActiveSupport::CoreExtensions::String::Iterators
-  end
+  include ActiveSupport::CoreExtensions::String::StartsEndsWith
+  include ActiveSupport::CoreExtensions::String::Iterators
   include ActiveSupport::CoreExtensions::String::Unicode
 end

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

@@ -1,56 +1,80 @@
 module ActiveSupport #:nodoc:
   module CoreExtensions #:nodoc:
     module String #:nodoc:
-      # Makes it easier to access parts of a string, such as specific characters and substrings.
-      module Access
-        # Returns the character at the +position+ treating the string as an array (where 0 is the first character).
-        #
-        # Examples: 
-        #   "hello".at(0)  # => "h"
-        #   "hello".at(4)  # => "o"
-        #   "hello".at(10) # => nil
-        def at(position)
-          chars[position, 1].to_s
-        end
-        
-        # Returns the remaining of the string from the +position+ treating the string as an array (where 0 is the first character).
-        #
-        # Examples: 
-        #   "hello".from(0)  # => "hello"
-        #   "hello".from(2)  # => "llo"
-        #   "hello".from(10) # => nil
-        def from(position)
-          chars[position..-1].to_s
-        end
-        
-        # Returns the beginning of the string up to the +position+ treating the string as an array (where 0 is the first character).
-        #
-        # Examples: 
-        #   "hello".to(0)  # => "h"
-        #   "hello".to(2)  # => "hel"
-        #   "hello".to(10) # => "hello"
-        def to(position)
-          chars[0..position].to_s
-        end
+      unless '1.9'.respond_to?(:force_encoding)
+        # Makes it easier to access parts of a string, such as specific characters and substrings.
+        module Access
+          # Returns the character at the +position+ treating the string as an array (where 0 is the first character).
+          #
+          # Examples: 
+          #   "hello".at(0)  # => "h"
+          #   "hello".at(4)  # => "o"
+          #   "hello".at(10) # => nil
+          def at(position)
+            chars[position, 1].to_s
+          end
+          
+          # Returns the remaining of the string from the +position+ treating the string as an array (where 0 is the first character).
+          #
+          # Examples: 
+          #   "hello".from(0)  # => "hello"
+          #   "hello".from(2)  # => "llo"
+          #   "hello".from(10) # => nil
+          def from(position)
+            chars[position..-1].to_s
+          end
+          
+          # Returns the beginning of the string up to the +position+ treating the string as an array (where 0 is the first character).
+          #
+          # Examples: 
+          #   "hello".to(0)  # => "h"
+          #   "hello".to(2)  # => "hel"
+          #   "hello".to(10) # => "hello"
+          def to(position)
+            chars[0..position].to_s
+          end
 
-        # Returns the first character of the string or the first +limit+ characters.
-        #
-        # Examples: 
-        #   "hello".first     # => "h"
-        #   "hello".first(2)  # => "he"
-        #   "hello".first(10) # => "hello"
-        def first(limit = 1)
-          chars[0..(limit - 1)].to_s
+          # Returns the first character of the string or the first +limit+ characters.
+          #
+          # Examples: 
+          #   "hello".first     # => "h"
+          #   "hello".first(2)  # => "he"
+          #   "hello".first(10) # => "hello"
+          def first(limit = 1)
+            chars[0..(limit - 1)].to_s
+          end
+          
+          # Returns the last character of the string or the last +limit+ characters.
+          #
+          # Examples: 
+          #   "hello".last     # => "o"
+          #   "hello".last(2)  # => "lo"
+          #   "hello".last(10) # => "hello"
+          def last(limit = 1)
+            (chars[(-limit)..-1] || self).to_s
+          end
         end
-        
-        # Returns the last character of the string or the last +limit+ characters.
-        #
-        # Examples: 
-        #   "hello".last     # => "o"
-        #   "hello".last(2)  # => "lo"
-        #   "hello".last(10) # => "hello"
-        def last(limit = 1)
-          (chars[(-limit)..-1] || self).to_s
+      else
+        module Access #:nodoc:
+          def at(position)
+            self[position]
+          end
+
+          def from(position)
+            self[position..-1]
+          end
+
+          def to(position)
+            self[0..position]
+          end
+
+          def first(limit = 1)
+            self[0..(limit - 1)]
+          end
+
+          def last(limit = 1)
+            from(-limit) || self
+          end
         end
       end
     end