activesupport 3.1.12 → 3.2.0.rc1

data/lib/active_support/file_update_checker.rb

@@ -1,8 +1,28 @@
+require "active_support/core_ext/array/wrap"
+require "active_support/core_ext/array/extract_options"
+
 module ActiveSupport
-  # This class is responsible to track files and invoke the given block
-  # whenever one of these files are changed. For example, this class
-  # is used by Rails to reload the I18n framework whenever they are
-  # changed upon a new request.
+  # \FileUpdateChecker specifies the API used by Rails to watch files
+  # and control reloading. The API depends on four methods:
+  #
+  # * +initialize+ which expects two parameters and one block as
+  #   described below;
+  #
+  # * +updated?+ which returns a boolean if there were updates in
+  #   the filesystem or not;
+  #
+  # * +execute+ which executes the given block on initialization
+  #   and updates the counter to the latest timestamp;
+  #
+  # * +execute_if_updated+ which just executes the block if it was updated;
+  #
+  # After initialization, a call to +execute_if_updated+ must execute
+  # the block only if there was really a change in the filesystem.
+  #
+  # == Examples
+  #
+  # This class is used by Rails to reload the I18n framework whenever
+  # they are changed upon a new request.
   #
   #   i18n_reloader = ActiveSupport::FileUpdateChecker.new(paths) do
   #     I18n.reload!
@@ -13,24 +33,89 @@ module ActiveSupport
   #   end
   #
   class FileUpdateChecker
-    attr_reader :paths, :last_update_at
-
-    def initialize(paths, calculate=false, &block)
-      @paths = paths
+    # It accepts two parameters on initialization. The first is an array
+    # of files and the second is an optional hash of directories. The hash must
+    # have directories as keys and the value is an array of extensions to be
+    # watched under that directory.
+    #
+    # This method must also receive a block that will be called once a path changes.
+    #
+    # == Implementation details
+    #
+    # This particular implementation checks for added and updated files,
+    # but not removed files. Directories lookup are compiled to a glob for
+    # performance. Therefore, while someone can add new files to the +files+
+    # array after initialization (and parts of Rails do depend on this feature),
+    # adding new directories after initialization is not allowed.
+    #
+    # Notice that other objects that implements FileUpdateChecker API may
+    # not even allow new files to be added after initialization. If this
+    # is the case, we recommend freezing the +files+ after initialization to
+    # avoid changes that won't make effect.
+    def initialize(files, dirs={}, &block)
+      @files = files
+      @glob  = compile_glob(dirs)
       @block = block
-      @last_update_at = calculate ? updated_at : nil
+      @updated_at = nil
+      @last_update_at = updated_at
+    end
+
+    # Check if any of the entries were updated. If so, the updated_at
+    # value is cached until the block is executed via +execute+ or +execute_if_updated+
+    def updated?
+      current_updated_at = updated_at
+      if @last_update_at < current_updated_at
+        @updated_at = updated_at
+        true
+      else
+        false
+      end
     end
 
-    def updated_at
-      paths.map { |path| File.stat(path).mtime }.max
+    # Executes the given block and updates the counter to latest timestamp.
+    def execute
+      @last_update_at = updated_at
+      @block.call
+    ensure
+      @updated_at = nil
     end
 
+    # Execute the block given if updated.
     def execute_if_updated
-      current_update_at = self.updated_at
-      if @last_update_at != current_update_at
-        @last_update_at = current_update_at
-        @block.call
+      if updated?
+        execute
+        true
+      else
+        false
+      end
+    end
+
+    private
+
+    def updated_at #:nodoc:
+      @updated_at || begin
+        all = []
+        all.concat @files.select { |f| File.exists?(f) }
+        all.concat Dir[@glob] if @glob
+        all.map { |path| File.mtime(path) }.max || Time.at(0)
       end
     end
+
+    def compile_glob(hash) #:nodoc:
+      hash.freeze # Freeze so changes aren't accidently pushed
+      return if hash.empty?
+
+      globs = []
+      hash.each do |key, value|
+        globs << "#{key}/**/*#{compile_ext(value)}"
+      end
+      "{#{globs.join(",")}}"
+    end
+
+    def compile_ext(array) #:nodoc:
+      array = Array.wrap(array)
+      return if array.empty?
+      ".{#{array.join(",")}}"
+    end
   end
 end

data/lib/active_support/hash_with_indifferent_access.rb

@@ -16,6 +16,10 @@ module ActiveSupport
       dup
     end
 
+    def nested_under_indifferent_access
+      self
+    end
+
     def initialize(constructor = {})
       if constructor.is_a?(Hash)
         super()
@@ -112,7 +116,7 @@ module ActiveSupport
       end
     end
 
-    # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash
+    # 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)

data/lib/active_support/i18n.rb

@@ -2,7 +2,7 @@ begin
   require 'i18n'
   require 'active_support/lazy_load_hooks'
 rescue LoadError => e
-  $stderr.puts "You don't have i18n installed in your application. Please add it to your Gemfile and run bundle install"
+  $stderr.puts "The i18n gem is not available. Please add it to your Gemfile and run bundle install"
   raise e
 end
 

data/lib/active_support/i18n_railtie.rb

@@ -10,14 +10,19 @@ module I18n
     config.i18n.fallbacks = ActiveSupport::OrderedOptions.new
 
     def self.reloader
-      @reloader ||= ActiveSupport::FileUpdateChecker.new([]){ I18n.reload! }
+      @reloader ||= ActiveSupport::FileUpdateChecker.new(reloader_paths){ I18n.reload! }
+    end
+
+    def self.reloader_paths
+      @reloader_paths ||= []
     end
 
     # Add <tt>I18n::Railtie.reloader</tt> to ActionDispatch callbacks. Since, at this
     # point, no path was added to the reloader, I18n.reload! is not triggered
     # on to_prepare callbacks. This will only happen on the config.after_initialize
     # callback below.
-    initializer "i18n.callbacks" do
+    initializer "i18n.callbacks" do |app|
+      app.reloaders << I18n::Railtie.reloader
       ActionDispatch::Reloader.to_prepare do
         I18n::Railtie.reloader.execute_if_updated
       end
@@ -58,8 +63,8 @@ module I18n
 
       init_fallbacks(fallbacks) if fallbacks && validate_fallbacks(fallbacks)
 
-      reloader.paths.concat I18n.load_path
-      reloader.execute_if_updated
+      reloader_paths.concat I18n.load_path
+      reloader.execute
 
       @i18n_inited = true
     end

data/lib/active_support/inflections.rb

@@ -16,8 +16,8 @@ module ActiveSupport
     inflect.plural(/([^aeiouy]|qu)y$/i, '\1ies')
     inflect.plural(/(x|ch|ss|sh)$/i, '\1es')
     inflect.plural(/(matr|vert|ind)(?:ix|ex)$/i, '\1ices')
-    inflect.plural(/([m|l])ouse$/i, '\1ice')
-    inflect.plural(/([m|l])ice$/i, '\1ice')
+    inflect.plural(/(m|l)ouse$/i, '\1ice')
+    inflect.plural(/(m|l)ice$/i, '\1ice')
     inflect.plural(/^(ox)$/i, '\1en')
     inflect.plural(/^(oxen)$/i, '\1')
     inflect.plural(/(quiz)$/i, '\1zes')
@@ -35,7 +35,7 @@ module ActiveSupport
     inflect.singular(/(s)eries$/i, '\1eries')
     inflect.singular(/(m)ovies$/i, '\1ovie')
     inflect.singular(/(x|ch|ss|sh)es$/i, '\1')
-    inflect.singular(/([m|l])ice$/i, '\1ouse')
+    inflect.singular(/(m|l)ice$/i, '\1ouse')
     inflect.singular(/(bus)es$/i, '\1')
     inflect.singular(/(o)es$/i, '\1')
     inflect.singular(/(shoe)s$/i, '\1')

data/lib/active_support/inflector/inflections.rb

@@ -20,10 +20,61 @@ module ActiveSupport
         @__instance__ ||= new
       end
 
-      attr_reader :plurals, :singulars, :uncountables, :humans
+      attr_reader :plurals, :singulars, :uncountables, :humans, :acronyms, :acronym_regex
 
       def initialize
-        @plurals, @singulars, @uncountables, @humans = [], [], [], []
+        @plurals, @singulars, @uncountables, @humans, @acronyms, @acronym_regex = [], [], [], [], {}, /(?=a)b/
+      end
+
+      # Specifies a new acronym. An acronym must be specified as it will appear in a camelized string.  An underscore
+      # string that contains the acronym will retain the acronym when passed to `camelize`, `humanize`, or `titleize`.
+      # A camelized string that contains the acronym will maintain the acronym when titleized or humanized, and will
+      # convert the acronym into a non-delimited single lowercase word when passed to +underscore+.
+      #
+      # Examples:
+      #   acronym 'HTML'
+      #   titleize 'html' #=> 'HTML'
+      #   camelize 'html' #=> 'HTML'
+      #   underscore 'MyHTML' #=> 'my_html'
+      #
+      # The acronym, however, must occur as a delimited unit and not be part of another word for conversions to recognize it:
+      #
+      #   acronym 'HTTP'
+      #   camelize 'my_http_delimited' #=> 'MyHTTPDelimited'
+      #   camelize 'https' #=> 'Https', not 'HTTPs'
+      #   underscore 'HTTPS' #=> 'http_s', not 'https'
+      #
+      #   acronym 'HTTPS'
+      #   camelize 'https' #=> 'HTTPS'
+      #   underscore 'HTTPS' #=> 'https'
+      #
+      # Note: Acronyms that are passed to `pluralize` will no longer be recognized, since the acronym will not occur as
+      # a delimited unit in the pluralized result. To work around this, you must specify the pluralized form as an
+      # acronym as well:
+      #
+      #    acronym 'API'
+      #    camelize(pluralize('api')) #=> 'Apis'
+      #
+      #    acronym 'APIs'
+      #    camelize(pluralize('api')) #=> 'APIs'
+      #
+      # `acronym` may be used to specify any word that contains an acronym or otherwise needs to maintain a non-standard
+      # capitalization. The only restriction is that the word must begin with a capital letter.
+      #
+      # Examples:
+      #   acronym 'RESTful'
+      #   underscore 'RESTful' #=> 'restful'
+      #   underscore 'RESTfulController' #=> 'restful_controller'
+      #   titleize 'RESTfulController' #=> 'RESTful Controller'
+      #   camelize 'restful' #=> 'RESTful'
+      #   camelize 'restful_controller' #=> 'RESTfulController'
+      #
+      #   acronym 'McDonald'
+      #   underscore 'McDonald' #=> 'mcdonald'
+      #   camelize 'mcdonald' #=> 'McDonald'
+      def acronym(word)
+        @acronyms[word.downcase] = word
+        @acronym_regex = /#{@acronyms.values.join("|")}/
       end
 
       # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression.
@@ -117,95 +168,5 @@ module ActiveSupport
         Inflections.instance
       end
     end
-
-    # Returns the plural form of the word in the string.
-    #
-    # Examples:
-    #   "post".pluralize             # => "posts"
-    #   "octopus".pluralize          # => "octopi"
-    #   "sheep".pluralize            # => "sheep"
-    #   "words".pluralize            # => "words"
-    #   "CamelOctopus".pluralize     # => "CamelOctopi"
-    def pluralize(word)
-      result = word.to_s.dup
-
-      if word.empty? || inflections.uncountables.include?(result.downcase)
-        result
-      else
-        inflections.plurals.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
-        result
-      end
-    end
-
-    # The reverse of +pluralize+, returns the singular form of a word in a string.
-    #
-    # Examples:
-    #   "posts".singularize            # => "post"
-    #   "octopi".singularize           # => "octopus"
-    #   "sheep".singularize            # => "sheep"
-    #   "word".singularize             # => "word"
-    #   "CamelOctopi".singularize      # => "CamelOctopus"
-    def singularize(word)
-      result = word.to_s.dup
-
-      if inflections.uncountables.any? { |inflection| result =~ /\b(#{inflection})\Z/i }
-        result
-      else
-        inflections.singulars.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
-        result
-      end
-    end
-
-    # Capitalizes the first word and turns underscores into spaces and strips a
-    # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output.
-    #
-    # Examples:
-    #   "employee_salary" # => "Employee salary"
-    #   "author_id"       # => "Author"
-    def humanize(lower_case_and_underscored_word)
-      result = lower_case_and_underscored_word.to_s.dup
-
-      inflections.humans.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
-      result.gsub(/_id$/, "").gsub(/_/, " ").capitalize
-    end
-
-    # 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
-    # used in the Rails internals.
-    #
-    # +titleize+ is also aliased as as +titlecase+.
-    #
-    # Examples:
-    #   "man from the boondocks".titleize # => "Man From The Boondocks"
-    #   "x-men: the last stand".titleize  # => "X Men: The Last Stand"
-    def titleize(word)
-      humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize }
-    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.
-    #
-    # Examples
-    #   "RawScaledScorer".tableize # => "raw_scaled_scorers"
-    #   "egg_and_ham".tableize     # => "egg_and_hams"
-    #   "fancyCategory".tableize   # => "fancy_categories"
-    def tableize(class_name)
-      pluralize(underscore(class_name))
-    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+.)
-    #
-    # Examples:
-    #   "egg_and_hams".classify # => "EggAndHam"
-    #   "posts".classify        # => "Post"
-    #
-    # Singular names are not handled correctly:
-    #   "business".classify     # => "Busines"
-    def classify(table_name)
-      # strip out any leading schema name
-      camelize(singularize(table_name.to_s.sub(/.*\./, '')))
-    end
   end
 end

data/lib/active_support/inflector/methods.rb

@@ -1,3 +1,5 @@
+require 'active_support/inflector/inflections'
+
 module ActiveSupport
   # The Inflector transforms words from singular to plural, class names to table names, modularized class names to ones without,
   # and class names to foreign keys. The default inflections for pluralization, singularization, and uncountable words are kept
@@ -10,6 +12,30 @@ module ActiveSupport
   module Inflector
     extend self
 
+    # Returns the plural form of the word in the string.
+    #
+    # Examples:
+    #   "post".pluralize             # => "posts"
+    #   "octopus".pluralize          # => "octopi"
+    #   "sheep".pluralize            # => "sheep"
+    #   "words".pluralize            # => "words"
+    #   "CamelOctopus".pluralize     # => "CamelOctopi"
+    def pluralize(word)
+      apply_inflections(word, inflections.plurals)
+    end
+
+    # The reverse of +pluralize+, returns the singular form of a word in a string.
+    #
+    # Examples:
+    #   "posts".singularize            # => "post"
+    #   "octopi".singularize           # => "octopus"
+    #   "sheep".singularize            # => "sheep"
+    #   "word".singularize             # => "word"
+    #   "CamelOctopi".singularize      # => "CamelOctopus"
+    def singularize(word)
+      apply_inflections(word, inflections.singulars)
+    end
+
     # By default, +camelize+ converts strings to UpperCamelCase. If the argument to +camelize+
     # is set to <tt>:lower</tt> then +camelize+ produces lowerCamelCase.
     #
@@ -25,12 +51,14 @@ module ActiveSupport
     # though there are cases where that does not hold:
     #
     #   "SSLError".underscore.camelize # => "SslError"
-    def camelize(lower_case_and_underscored_word, first_letter_in_uppercase = true)
-      if first_letter_in_uppercase
-        lower_case_and_underscored_word.to_s.gsub(/\/(.?)/) { "::#{$1.upcase}" }.gsub(/(?:^|_)(.)/) { $1.upcase }
+    def camelize(term, uppercase_first_letter = true)
+      string = term.to_s
+      if uppercase_first_letter
+        string = string.sub(/^[a-z\d]*/) { inflections.acronyms[$&] || $&.capitalize }
       else
-        lower_case_and_underscored_word.to_s[0].chr.downcase + camelize(lower_case_and_underscored_word)[1..-1]
+        string = string.sub(/^(?:#{inflections.acronym_regex}(?=\b|[A-Z_])|\w)/) { $&.downcase }
       end
+      string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$1}#{inflections.acronyms[$2] || $2.capitalize}" }.gsub('/', '::')
     end
 
     # Makes an underscored, lowercase form from the expression in the string.
@@ -48,13 +76,68 @@ module ActiveSupport
     def underscore(camel_cased_word)
       word = camel_cased_word.to_s.dup
       word.gsub!(/::/, '/')
-      word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      word.gsub!(/(?:([A-Za-z\d])|^)(#{inflections.acronym_regex})(?=\b|[^a-z])/) { "#{$1}#{$1 && '_'}#{$2.downcase}" }
+      word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
       word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
       word.tr!("-", "_")
       word.downcase!
       word
     end
 
+    # Capitalizes the first word and turns underscores into spaces and strips a
+    # trailing "_id", if any. Like +titleize+, this is meant for creating pretty output.
+    #
+    # Examples:
+    #   "employee_salary" # => "Employee salary"
+    #   "author_id"       # => "Author"
+    def humanize(lower_case_and_underscored_word)
+      result = lower_case_and_underscored_word.to_s.dup
+      inflections.humans.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
+      result.gsub!(/_id$/, "")
+      result.gsub(/(_)?([a-z\d]*)/i) { "#{$1 && ' '}#{inflections.acronyms[$2] || $2.downcase}" }.gsub(/^\w/) { $&.upcase }
+    end
+
+    # 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
+    # used in the Rails internals.
+    #
+    # +titleize+ is also aliased as as +titlecase+.
+    #
+    # Examples:
+    #   "man from the boondocks".titleize   # => "Man From The Boondocks"
+    #   "x-men: the last stand".titleize    # => "X Men: The Last Stand"
+    #   "TheManWithoutAPast".titleize       # => "The Man Without A Past"
+    #   "raiders_of_the_lost_ark".titleize  # => "Raiders Of The Lost Ark"
+    def titleize(word)
+      humanize(underscore(word)).gsub(/\b('?[a-z])/) { $1.capitalize }
+    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.
+    #
+    # Examples
+    #   "RawScaledScorer".tableize # => "raw_scaled_scorers"
+    #   "egg_and_ham".tableize     # => "egg_and_hams"
+    #   "fancyCategory".tableize   # => "fancy_categories"
+    def tableize(class_name)
+      pluralize(underscore(class_name))
+    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+.)
+    #
+    # Examples:
+    #   "egg_and_hams".classify # => "EggAndHam"
+    #   "posts".classify        # => "Post"
+    #
+    # Singular names are not handled correctly:
+    #   "business".classify     # => "Busines"
+    def classify(table_name)
+      # strip out any leading schema name
+      camelize(singularize(table_name.to_s.sub(/.*\./, '')))
+    end
+
     # Replaces underscores with dashes in the string.
     #
     # Example:
@@ -63,13 +146,32 @@ module ActiveSupport
       underscored_word.gsub(/_/, '-')
     end
 
-    # Removes the module part from the expression in the string.
+    # Removes the module part from the expression in the string:
     #
-    # Examples:
     #   "ActiveRecord::CoreExtensions::String::Inflections".demodulize # => "Inflections"
     #   "Inflections".demodulize                                       # => "Inflections"
-    def demodulize(class_name_in_module)
-      class_name_in_module.to_s.gsub(/^.*::/, '')
+    #
+    # See also +deconstantize+.
+    def demodulize(path)
+      path = path.to_s
+      if i = path.rindex('::')
+        path[(i+2)..-1]
+      else
+        path
+      end
+    end
+
+    # Removes the rightmost segment from the constant expression in the string:
+    #
+    #   "Net::HTTP".deconstantize   # => "Net"
+    #   "::Net::HTTP".deconstantize # => "::Net"
+    #   "String".deconstantize      # => ""
+    #   "::String".deconstantize    # => ""
+    #   "".deconstantize            # => ""
+    #
+    # See also +demodulize+.
+    def deconstantize(path)
+      path.to_s[0...(path.rindex('::') || 0)] # implementation based on the one in facets' Module#spacename
     end
 
     # Creates a foreign key name from a class name.
@@ -127,6 +229,39 @@ module ActiveSupport
       end
     end
 
+    # Tries to find a constant with the name specified in the argument string:
+    #
+    #   "Module".safe_constantize     # => Module
+    #   "Test::Unit".safe_constantize # => Test::Unit
+    #
+    # The name is assumed to be the one of a top-level constant, no matter whether
+    # it starts with "::" or not. No lexical context is taken into account:
+    #
+    #   C = 'outside'
+    #   module M
+    #     C = 'inside'
+    #     C                    # => 'inside'
+    #     "C".safe_constantize # => 'outside', same as ::C
+    #   end
+    #
+    # nil is returned when the name is not in CamelCase or the constant (or part of it) is
+    # unknown.
+    #
+    #   "blargle".safe_constantize  # => nil
+    #   "UnknownModule".safe_constantize  # => nil
+    #   "UnknownModule::Foo::Bar".safe_constantize  # => nil
+    #
+    def safe_constantize(camel_cased_word)
+      begin
+        constantize(camel_cased_word)
+      rescue NameError => e
+        raise unless e.message =~ /uninitialized constant #{const_regexp(camel_cased_word)}$/ ||
+          e.name.to_s == camel_cased_word.to_s
+      rescue ArgumentError => e
+        raise unless e.message =~ /not missing constant #{const_regexp(camel_cased_word)}\!$/
+      end
+    end
+
     # Turns a number into an ordinal string used to denote the position in an
     # ordered sequence such as 1st, 2nd, 3rd, 4th.
     #
@@ -149,5 +284,34 @@ module ActiveSupport
         end
       end
     end
+
+    private
+
+    # Mount a regular expression that will match part by part of the constant.
+    # For instance, Foo::Bar::Baz will generate Foo(::Bar(::Baz)?)?
+    def const_regexp(camel_cased_word) #:nodoc:
+      parts = camel_cased_word.split("::")
+      last  = parts.pop
+
+      parts.reverse.inject(last) do |acc, part|
+        part.empty? ? acc : "#{part}(::#{acc})?"
+      end
+    end
+
+    # Applies inflection rules for +singularize+ and +pluralize+.
+    #
+    # Examples:
+    #  apply_inflections("post", inflections.plurals) # => "posts"
+    #  apply_inflections("posts", inflections.singulars) # => "post"
+    def apply_inflections(word, rules)
+      result = word.to_s.dup
+
+      if word.empty? || inflections.uncountables.any? { |inflection| result =~ /\b#{inflection}\Z/i }
+        result
+      else
+        rules.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
+        result
+      end
+    end
   end
 end