From 1e145099a78688d25f2cfcafe58afbd651bf7be4 Mon Sep 17 00:00:00 2001
From: David Heinemeier Hansson <david@loudthinking.com>
Date: Sat, 3 Sep 2005 07:11:47 +0000
Subject: [PATCH] Added String#at, String#from, String#to, String#first,
 String#last in ActiveSupport::CoreExtensions::String::Access to ease access
 to individual characters and substrings in a string serving basically as
 human names for range access. Added easy extendability to the inflector
 through Inflector.inflections (using the Inflector::Inflections singleton
 class)

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@2110 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
---
 activesupport/CHANGELOG                       |  13 ++
 .../lib/active_support/core_ext/string.rb     |   4 +-
 .../active_support/core_ext/string/access.rb  |  58 +++++++
 .../lib/active_support/inflections.rb         |  50 ++++++
 activesupport/lib/active_support/inflector.rb | 158 ++++++++++--------
 .../test/core_ext/string_ext_test.rb          |  14 ++
 6 files changed, 229 insertions(+), 68 deletions(-)
 create mode 100644 activesupport/lib/active_support/core_ext/string/access.rb
 create mode 100644 activesupport/lib/active_support/inflections.rb

diff --git a/activesupport/CHANGELOG b/activesupport/CHANGELOG
index 331dff24cf..99cbafe0a6 100644
--- a/activesupport/CHANGELOG
+++ b/activesupport/CHANGELOG
@@ -1,5 +1,18 @@
 *SVN*
 
+* Added easy extendability to the inflector through Inflector.inflections (using the Inflector::Inflections singleton class). Examples:
+
+    Inflector.inflections do |inflect|
+      inflect.plural /^(ox)$/i, '\1\2en'
+      inflect.singular /^(ox)en/i, '\1'
+    
+      inflect.irregular 'octopus', 'octopi'
+    
+      inflect.uncountable "equipment"
+    end
+
+* Added String#at, String#from, String#to, String#first, String#last in ActiveSupport::CoreExtensions::String::Access to ease access to individual characters and substrings in a string serving basically as human names for range access.
+
 * Make Time#last_month work when invoked on the 31st of a month.
 
 * Add Time.days_in_month, and make Time#next_month work when invoked on the 31st of a month
diff --git a/activesupport/lib/active_support/core_ext/string.rb b/activesupport/lib/active_support/core_ext/string.rb
index 3056f74744..fce0557c64 100644
--- a/activesupport/lib/active_support/core_ext/string.rb
+++ b/activesupport/lib/active_support/core_ext/string.rb
@@ -1,7 +1,9 @@
 require File.dirname(__FILE__) + '/string/inflections'
 require File.dirname(__FILE__) + '/string/conversions'
+require File.dirname(__FILE__) + '/string/access'
 
 class String #:nodoc:
-  include ActiveSupport::CoreExtensions::String::Inflections
+  include ActiveSupport::CoreExtensions::String::Access
   include ActiveSupport::CoreExtensions::String::Conversions
+  include ActiveSupport::CoreExtensions::String::Inflections
 end
diff --git a/activesupport/lib/active_support/core_ext/string/access.rb b/activesupport/lib/active_support/core_ext/string/access.rb
new file mode 100644
index 0000000000..f59690b032
--- /dev/null
+++ b/activesupport/lib/active_support/core_ext/string/access.rb
@@ -0,0 +1,58 @@
+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)
+          self[position, 1]
+        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)
+          self[position..-1]
+        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)
+          self[0..position]
+        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)
+          self[0..(limit - 1)]
+        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)
+          self[(-limit)..-1]
+        end
+      end
+    end
+  end
+end
\ No newline at end of file
diff --git a/activesupport/lib/active_support/inflections.rb b/activesupport/lib/active_support/inflections.rb
new file mode 100644
index 0000000000..d6249731ff
--- /dev/null
+++ b/activesupport/lib/active_support/inflections.rb
@@ -0,0 +1,50 @@
+Inflector.inflections do |inflect|
+  inflect.plural /$/, 's'
+  inflect.plural /s$/i, 's'
+  inflect.plural /(ax|cri|test)is$/i, '\1es'
+  inflect.plural /(octop|vir)us$/i, '\1i'
+  inflect.plural /(alias)/i, '\1es'
+  inflect.plural /(bu)s$/i, '\1ses'
+  inflect.plural /(buffal|tomat)o$/i, '\1oes'
+  inflect.plural /([ti])um$/i, '\1a'
+  inflect.plural /sis$/i, 'ses'
+  inflect.plural /(?:([^f])fe|([lr])f)$/i, '\1\2ves'
+  inflect.plural /(hive)$/i, '\1s'
+  inflect.plural /([^aeiouy]|qu)y$/i, '\1ies'
+  inflect.plural /([^aeiouy]|qu)ies$/i, '\1y'
+  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 /^(ox)$/i, '\1en'
+
+  inflect.singular /s$/i, ''
+  inflect.singular /(n)ews$/i, '\1ews'
+  inflect.singular /(s)tatus$/i, '\1tatus'
+  inflect.singular /([ti])a$/i, '\1um'
+  inflect.singular /((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i, '\1\2sis'
+  inflect.singular /(^analy)ses$/i, '\1sis'
+  inflect.singular /([^f])ves$/i, '\1fe'
+  inflect.singular /(hive)s$/i, '\1'
+  inflect.singular /(tive)s$/i, '\1'
+  inflect.singular /([lr])ves$/i, '\1f'
+  inflect.singular /([^aeiouy]|qu)ies$/i, '\1y'
+  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 /(bus)es$/i, '\1'
+  inflect.singular /(o)es$/i, '\1'
+  inflect.singular /(shoe)s$/i, '\1'
+  inflect.singular /(cris|ax|test)es$/i, '\1is'
+  inflect.singular /([octop|vir])i$/i, '\1us'
+  inflect.singular /(alias)es$/i, '\1'
+  inflect.singular /^(ox)en/i, '\1'
+  inflect.singular /(vert|ind)ices$/i, '\1ex'
+  inflect.singular /(matr)ices$/i, '\1ix'
+
+  inflect.irregular 'person', 'people'
+  inflect.irregular 'man', 'men'
+  inflect.irregular 'child', 'children'
+
+  inflect.uncountable %w( equipment information rice money species series fish )
+end
\ No newline at end of file
diff --git a/activesupport/lib/active_support/inflector.rb b/activesupport/lib/active_support/inflector.rb
index ae1cbd213d..f5c92cf4d9 100644
--- a/activesupport/lib/active_support/inflector.rb
+++ b/activesupport/lib/active_support/inflector.rb
@@ -1,15 +1,99 @@
+require 'singleton' 
+
 # 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.
+# and class names to foreign keys. The default inflections for pluralization, singularization, and uncountable words are kept
+# in inflections.rb.
 module Inflector 
+  # A singleton instance of this class is yielded by Inflector.inflections, which can then be used to specify additional
+  # inflection rules. Examples:
+  #
+  #   Inflector.inflections do |inflect|
+  #     inflect.plural /^(ox)$/i, '\1\2en'
+  #     inflect.singular /^(ox)en/i, '\1'
+  #
+  #     inflect.irregular 'octopus', 'octopi'
+  #
+  #     inflect.uncountable "equipment"
+  #   end
+  #
+  # New rules are added at the top. So in the example above, the irregular rule for octopus will now be the first of the
+  # pluralization and singularization rules that is runs. This guarantees that your rules run before any of the rules that may
+  # already have been loaded.
+  class Inflections
+    include Singleton
+    
+    attr_reader :plurals, :singulars, :uncountables
+    
+    def initialize
+      @plurals, @singulars, @uncountables = [], [], []
+    end
+    
+    # Specifies a new pluralization rule and its replacement. The rule can either be a string or a regular expression. 
+    # The replacement should always be a string that may include references to the matched data from the rule.
+    def plural(rule, replacement)
+      @plurals.insert(0, [rule, replacement])
+    end
+    
+    # Specifies a new singularization rule and its replacement. The rule can either be a string or a regular expression. 
+    # The replacement should always be a string that may include references to the matched data from the rule.
+    def singular(rule, replacement)
+      @singulars.insert(0, [rule, replacement])
+    end
+
+    # Specifies a new irregular that applies to both pluralization and singularization at the same time. This can only be used
+    # for strings, not regular expressions. You simply pass the irregular in singular and plural form.
+    # 
+    # Examples:
+    #   irregular 'octopus', 'octopi'
+    #   irregular 'person', 'people'
+    def irregular(singular, plural)
+      plural(Regexp.new("(#{singular[0,1]})#{singular[1..-1]}$", "i"), '\1' + plural[1..-1])
+      singular(Regexp.new("(#{plural[0,1]})#{plural[1..-1]}$", "i"), '\1' + singular[1..-1])
+    end
+    
+    # Add uncountable words that shouldn't be attempted inflected.
+    # 
+    # Examples:
+    #   uncountable "money"
+    #   uncountable "money", "information"
+    #   uncountable %w( money information rice )
+    def uncountable(*words)
+      (@uncountables << words).flatten!
+    end
+    
+    # Clears the loaded inflections within a given scope (default is :all). Give the scope as a symbol of the inflection type,
+    # the options are: :plurals, :singulars, :uncountables
+    #
+    # Examples:
+    #   clear :all
+    #   clear :plurals
+    def clear(scope = :all)
+      case scope
+        when :all
+          @plurals, @singulars, @uncountables = [], [], []
+        else
+          instance_variable_set "@#{scope}", []
+      end
+    end
+  end
+
   extend self
 
+  def inflections
+    if block_given?
+      yield Inflections.instance
+    else
+      Inflections.instance
+    end
+  end
+
   def pluralize(word)
     result = word.to_s.dup
 
-    if uncountable_words.include?(result.downcase)
+    if inflections.uncountables.include?(result.downcase)
       result
     else
-      plural_rules.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
+      inflections.plurals.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
       result
     end
   end
@@ -17,10 +101,10 @@ module Inflector
   def singularize(word)
     result = word.to_s.dup
 
-    if uncountable_words.include?(result.downcase)
+    if inflections.uncountables.include?(result.downcase)
       result
     else
-      singular_rules.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
+      inflections.singulars.each { |(rule, replacement)| break if result.gsub!(rule, replacement) }
       result
     end
   end
@@ -72,66 +156,6 @@ module Inflector
       end
     end
   end
-
-  private
-    def uncountable_words #:doc
-      %w( equipment information rice money species series fish )
-    end
-  
-    def plural_rules #:doc:
-      [
-      	[/^(ox)$/i, '\1\2en'],		             # ox
-      	[/([m|l])ouse$/i, '\1ice'],	           # mouse, louse
-      	[/(matr|vert|ind)ix|ex$/i, '\1ices'],      # matrix, vertex, index
-        [/(x|ch|ss|sh)$/i, '\1es'],            # search, switch, fix, box, process, address
-        [/([^aeiouy]|qu)ies$/i, '\1y'],
-        [/([^aeiouy]|qu)y$/i, '\1ies'],        # query, ability, agency
-        [/(hive)$/i, '\1s'],                   # archive, hive
-        [/(?:([^f])fe|([lr])f)$/i, '\1\2ves'], # half, safe, wife
-        [/sis$/i, 'ses'],                      # basis, diagnosis
-        [/([ti])um$/i, '\1a'],                 # datum, medium
-        [/(p)erson$/i, '\1eople'],             # person, salesperson
-        [/(m)an$/i, '\1en'],                   # man, woman, spokesman
-        [/(c)hild$/i, '\1hildren'],            # child
-      	[/(buffal|tomat)o$/i, '\1\2oes'],		   # buffalo, tomato
-      	[/(bu)s$/i, '\1\2ses'],	               # bus
-        [/(alias)/i, '\1es'],                  # alias
-      	[/(octop|vir)us$/i, '\1i'],            # octopus, virus - virus has no defined plural (according to Latin/dictionary.com), but viri is better than viruses/viruss
-      	[/(ax|cri|test)is$/i, '\1es'],         # axis, crisis  
-        [/s$/i, 's'],                          # no change (compatibility)
-        [/$/, 's']
-      ]
-    end
-
-    def singular_rules #:doc:
-      [
-        [/(matr)ices$/i, '\1ix'],
-      	[/(vert|ind)ices$/i, '\1ex'],
-      	[/^(ox)en/i, '\1'],
-      	[/(alias)es$/i, '\1'],
-      	[/([octop|vir])i$/i, '\1us'],
-      	[/(cris|ax|test)es$/i, '\1is'],
-      	[/(shoe)s$/i, '\1'],
-      	[/(o)es$/i, '\1'],
-      	[/(bus)es$/i, '\1'],
-      	[/([m|l])ice$/i, '\1ouse'],
-        [/(x|ch|ss|sh)es$/i, '\1'],
-        [/(m)ovies$/i, '\1\2ovie'],
-        [/(s)eries$/i, '\1\2eries'],
-        [/([^aeiouy]|qu)ies$/i, '\1y'],
-        [/([lr])ves$/i, '\1f'],
-        [/(tive)s$/i, '\1'],
-        [/(hive)s$/i, '\1'],
-        [/([^f])ves$/i, '\1fe'],
-        [/(^analy)ses$/i, '\1sis'],
-        [/((a)naly|(b)a|(d)iagno|(p)arenthe|(p)rogno|(s)ynop|(t)he)ses$/i, '\1\2sis'],
-        [/([ti])a$/i, '\1um'],
-        [/(p)eople$/i, '\1\2erson'],
-        [/(m)en$/i, '\1an'],
-        [/(s)tatus$/i, '\1\2tatus'],
-        [/(c)hildren$/i, '\1\2hild'],
-        [/(n)ews$/i, '\1\2ews'],
-        [/s$/i, '']
-      ]
-    end
 end
+
+require File.dirname(__FILE__) + '/inflections'
\ No newline at end of file
diff --git a/activesupport/test/core_ext/string_ext_test.rb b/activesupport/test/core_ext/string_ext_test.rb
index f394509dd1..34d4057cf9 100644
--- a/activesupport/test/core_ext/string_ext_test.rb
+++ b/activesupport/test/core_ext/string_ext_test.rb
@@ -67,4 +67,18 @@ class StringInflectionsTest < Test::Unit::TestCase
     assert_equal Time.local(2005, 2, 27, 23, 50), "2005-02-27 23:50".to_time(:local)
     assert_equal Date.new(2005, 2, 27), "2005-02-27".to_date
   end
+  
+  def test_access
+    s = "hello"
+    assert_equal "h", s.at(0)
+    
+    assert_equal "llo", s.from(2)
+    assert_equal "hel", s.to(2)
+    
+    assert_equal "h", s.first
+    assert_equal "he", s.first(2)
+
+    assert_equal "o", s.last
+    assert_equal "llo", s.last(3)
+  end
 end