facets 2.8.4 → 2.9.0.pre.1

data/lib/core/facets/string/cmp.rb

@@ -0,0 +1 @@
+require 'facets/comparable/cmp'

data/lib/core/facets/string/compress_lines.rb

@@ -2,15 +2,15 @@ class String
 
   # Matches any whitespace (including newline) and replaces with a single space
   #
-  # @example
-  #   <<-QUERY.compress_lines
+  #   string = <<-QUERY.compress_lines
   #     SELECT name
   #     FROM users
   #   QUERY
-  #   => "SELECT name FROM users"
+  #
+  #   string  #=> "SELECT name FROM users"
   #
   def compress_lines(spaced = true)
-    split($/).map { |line| line.strip }.join(spaced ? ' ' : '')
+    split($/).map{ |line| line.strip }.join(spaced ? ' ' : '')
   end
 
 end

data/lib/core/facets/string/divide.rb

@@ -5,10 +5,7 @@ class String
   #
   #   s = "<p>This<b>is</b>a test.</p>"
   #   s.divide( /\<.*?\>/ )
-  #
-  # _produces_
-  #
-  #   ["<p>This", "<b>is", "</b>a test.", "</p>"]
+  #   #=> ["<p>This", "<b>is", "</b>a test.", "</p>"]
   #
   # CREDIT: Trans
 

data/lib/core/facets/string/each_char.rb

@@ -4,26 +4,28 @@ class String
 
     require 'strscan'
 
-    # Iterates through each character. This is a little faster than
-    # using #chars b/c it does not create the intermediate array.
-    #
-    #    a = ''
-    #   "HELLO".each_character{ |c| a << #{c.downcase} }
-    #    a  #=> 'hello'
-
-    #def each_char  # :yield:
-    #  size.times do |i|
-    #    yield(self[i,1])
-    #  end
-    #end
-
     # Yields a single-character string for each character in the string.
     # When $KCODE = 'UTF8', multi-byte characters are yielded appropriately.
-    def each_char
+    #
+    #   a = ''
+    #   "HELLO".each_char{ |c| a << "#{c.downcase}" }
+    #   a  #=> 'hello'
+    #
+    def each_char # :yield:
       scanner, char = StringScanner.new(self), /./mu
-      loop { yield(scanner.scan(char) || break) }
+      loop{ yield(scanner.scan(char) || break) }
     end
 
+    #--
+    # Iterates through each character. This is a little faster than
+    # using #chars b/c it does not create the intermediate array...
+    #
+    #   def each_char  # :yield:
+    #     size.times{ |i| yield(self[i,1]) }
+    #   end
+    #++
+
   end
 
 end
+

data/lib/core/facets/string/each_word.rb

@@ -4,7 +4,11 @@ class String
 
   # Iterate through each word of a string.
   #
-  #   "a string".each_word { |word| ... }
+  #   a = []
+  #
+  #   "list of words".each_word { |word| a << word }
+  #
+  #   a  #=> ['list', 'of', 'words']
   #
   def each_word(&block)
     words.each(&block)

data/lib/core/facets/string/edit_distance.rb

@@ -22,7 +22,6 @@ class String
   # should be performed beforehand.
   #
   # CREDIT: Paul Battley
-  #
   def edit_distance(str2)
     str1 = self
     if $KCODE =~ /^U/i
@@ -30,10 +29,13 @@ class String
     else
       unpack_rule = 'C*'
     end
+
     s = str1.unpack(unpack_rule)
     t = str2.unpack(unpack_rule)
+
     n = s.length
     m = t.length
+
     return m if (0 == n)
     return n if (0 == m)
 
@@ -56,7 +58,67 @@ class String
     end
 
     return x
-  end
+  end if RUBY_VERSION < '1.9'
+
+  # Levenshtein distance algorithm implementation for Ruby, with UTF-8 support.
+  #
+  # The Levenshtein distance is a measure of how similar two strings s and t are,
+  # calculated as the number of deletions/insertions/substitutions needed to
+  # transform s into t. The greater the distance, the more the strings differ.
+  #
+  # The Levenshtein distance is also sometimes referred to as the
+  # easier-to-pronounce-and-spell 'edit distance'.
+  #
+  # Calculate the Levenshtein distance between two strings +self+ and +str2+.
+  # +self+ and +str2+ should be ASCII, UTF-8, or a one-byte-per character encoding
+  # such as ISO-8859-*.
+  #
+  # The strings will be treated as UTF-8 if $KCODE is set appropriately (i.e. 'u').
+  # Otherwise, the comparison will be performed byte-by-byte. There is no specific support
+  # for Shift-JIS or EUC strings.
+  #
+  # When using Unicode text, be aware that this algorithm does not perform normalisation.
+  # If there is a possibility of different normalised forms being used, normalisation
+  # should be performed beforehand.
+  #
+  # CREDIT: Paul Battley
+  def edit_distance(str2)
+    str1 = self
+
+    if str2.encoding != str1.encoding
+      str2 = str2.encode(str1.encoding.name)
+    end
+
+    s = str1.codepoints.to_a
+    t = str2.codepoints.to_a
+
+    n = s.length
+    m = t.length
+
+    return m if (0 == n)
+    return n if (0 == m)
+
+    d = (0..m).to_a
+    x = nil
+
+    (0...n).each do |i|
+      e = i+1
+      (0...m).each do |j|
+        cost = (s[i] == t[j]) ? 0 : 1
+        x = [
+          d[j+1] + 1, # insertion
+          e + 1,      # deletion
+          d[j] + cost # substitution
+        ].min
+        d[j] = e
+        e = x
+      end
+      d[m] = x
+    end
+
+    return x
+  end if RUBY_VERSION >= '1.9'
 
 end
 
+

data/lib/core/facets/string/file.rb

@@ -4,14 +4,30 @@ class String
 
   # Use fluent notation for making file directives.
   #
-  #    '~/trans/Desktop/notes.txt'.file.mtime
+  #    'README.rdoc'.file.mtime
   #  
   def file
-    f = self
-    Functor.new do |op, *a|
-      File.send(op, f, *a)
-    end
+    Functor.new(&method(:file_send).to_proc)
   end
 
+  private
+
+  def file_send(op, *a, &b)
+    File.send(op, self, *a, &b)
+  end
+
+  ## TODO: When no longer needing to support 1.8.6 we can use:
+  ##
+  ## # Use fluent notation for making file directives.
+  ## #
+  ## #    'README.rdoc'.file.mtime
+  ## #  
+  ## def file
+  ##   f = self
+  ##   Functor.new do |op, *a, &b|
+  ##     File.send(op, f, *a, &b)
+  ##   end
+  ## end
+
 end
 

data/lib/core/facets/string/indent.rb

@@ -13,12 +13,54 @@ class String
     end
   end
 
-  # Outdent just indents a negative number of spaces.
+  # Equivalent to String#indent, but modifies the receiver in place.
+
+  def indent!(n, c=' ')
+    replace(indent(n,c))
+  end
+
+  # Remove excessive indentation. Useful for multi-line strings embeded in
+  # already indented code.
+  #
+  #   <<-END.unindent
+  #       ohaie
+  #         wurld
+  #   END
+  #
+  # Outputs ...
+  #
+  #   ohaie
+  #     wurld
+  #
+  # Instead of ...
+  #
+  #       ohaie
+  #         wurld
+  #
+  # CREDIT: Noah Gibbs, mynyml
+
+  def unindent(size=nil)
+    if size
+      indent(-size)
+    else
+      char = ' '
+      self.scan(/^[\ \t]*\S/) do |m|
+        if size.nil? || m.size < size
+          size = m.size
+          char = m[0...-1]
+        end
+      end
+      size -= 1
+      indent(-size, char)
+    end
+  end
+
+  # Equivalent to String#unindent, but modifies the receiver in place.
   #
-  # CREDIT: Noah Gibbs
+  # CREDIT: mynyml
 
-  def outdent(n)
-    indent(-n)
+  def unindent!
+    self.replace(self.unindent)
   end
 
 end

data/lib/core/facets/string/interpolate.rb

@@ -1,14 +1,13 @@
 class String
 
-  # Interpolate. Provides a means of extenally using
-  # Ruby string interpolation mechinism.
+  # Interpolate. Provides a means of extenally using Ruby string
+  # interpolation mechinism.
   #
   #   try = "hello"
   #   str = "\#{try}!!!"
   #   String.interpolate{ str }    #=> "hello!!!"
   #
-  #   NOTE: The block neccessary in order to get
-  #         then binding of the caller.
+  # NOTE: The block neccessary in order to get then binding of the caller.
   #
   # CREDIT: Trans
 

data/lib/core/facets/string/line_wrap.rb

@@ -2,12 +2,9 @@ class String
 
   # Line wrap at width.
   #
-  #   puts "1234567890".line_wrap(5)
+  #   s = "1234567890".line_wrap(5)
   #
-  # _produces_
-  #
-  #   12345
-  #   67890
+  #   s  #=> "12345\n67890\n"
   #
   # CREDIT: Trans
 

data/lib/core/facets/string/lines.rb

@@ -4,7 +4,7 @@ class String
 
     # Returns an array of characters.
     #
-    #   "abc\n123".lines  #=> ["abc\n","123"]
+    #   "abc\n123".lines.to_a  #=> ["abc\n","123"]
     #
     def lines(&blk)
       if block_given?

data/lib/core/facets/string/methodize.rb

@@ -2,10 +2,10 @@ class String
 
   # Translate a (class or module) name to a suitable method name.
   #
-  #   My::CoolClass.name.methodize => "my__cool_class"
+  #   "My::CoolClass".methodize  #=> "my__cool_class"
   #
   #--
-  # Rails definition:
+  # Rails definition ...
   #
   #    gsub(/\//, '__').
   #    gsub(/::/, '__').
@@ -13,6 +13,7 @@ class String
   #    gsub(/([a-z\d])([A-Z])/,'\1_\2').
   #    tr("-", "_").
   #    downcase
+  #
   #++
   def methodize
     gsub(/([A-Z]+)([A-Z])/,'\1_\2').

data/lib/core/facets/string/modulize.rb

@@ -7,16 +7,18 @@ class String
   # paths to namespaces.
   #
   # Examples
+  #
   #   "method_name".modulize    #=> "MethodName"
   #   "method/name".modulize    #=> "Method::Name"
   #
   #--
-  # Rails definition:
+  # Rails definition ...
   #
   #    gsub(/__(.?)/){ "::#{$1.upcase}" }.
   #    gsub(/\/(.?)/){ "::#{$1.upcase}" }.
   #    gsub(/(?:_+)([a-z])/){ $1.upcase }.
   #    gsub(/(^|\s+)([a-z])/){ $1 + $2.upcase }
+  #
   #++
   def modulize
     gsub('__','/').

data/lib/core/facets/string/natcmp.rb

@@ -1,6 +1,34 @@
+#--
+# Adapted from:
+#
+# * http://sourcefrog.net/projects/natsort/natcmp.rb
+#
+# Based on Martin Pool's "Natural Order String Comparison" originally
+# written in C. (see http://sourcefrog.net/projects/natsort/)
+#
+# This implementation is Copyright (C) 2003 by Alan Davies
+# <cs96and_AT_yahoo_DOT_co_DOT_uk>
+#
+# This software is provided 'as-is', without any express or implied
+# warranty.  In no event will the authors be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+# claim that you wrote the original software. If you use this software
+# in a product, an acknowledgment in the product documentation would be
+# appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+# misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+#++
+
 class String
 
-  # 'Natural order' comparison of strings, e.g.
+  # 'Natural order' comparison of strings, e.g. ...
   #
   #   "my_prog_v1.1.0" < "my_prog_v1.2.0" < "my_prog_v1.10.0"
   #
@@ -8,40 +36,11 @@ class String
   # parameter, if set to _true_, makes the comparison
   # case insensitive.
   #
-  #   "Hello.10".natcmp("Hello.1")  #=> -1
+  #   "Hello.1".natcmp("Hello.10")  #=> -1
   #
-  #   TODO: Invert case flag?
+  # TODO: Invert case flag?
   #
   # CREDIT: Alan Davies, Martin Pool
-  #
-  #--
-  # Adapted from:
-  #
-  #   http://sourcefrog.net/projects/natsort/natcmp.rb
-  #
-  # Based on Martin Pool's "Natural Order String Comparison" originally
-  # written in C. (see http://sourcefrog.net/projects/natsort/)
-  #
-  # This implementation is Copyright (C) 2003 by Alan Davies
-  # <cs96and_AT_yahoo_DOT_co_DOT_uk>
-  #
-  # This software is provided 'as-is', without any express or implied
-  # warranty.  In no event will the authors be held liable for any damages
-  # arising from the use of this software.
-  #
-  # Permission is granted to anyone to use this software for any purpose,
-  # including commercial applications, and to alter it and redistribute it
-  # freely, subject to the following restrictions:
-  #
-  # 1. The origin of this software must not be misrepresented; you must not
-  #    claim that you wrote the original software. If you use this software
-  #    in a product, an acknowledgment in the product documentation would be
-  #    appreciated but is not required.
-  # 2. Altered source versions must be plainly marked as such, and must not be
-  #    misrepresented as being the original software.
-  # 3. This notice may not be removed or altered from any source distribution.
-  #
-  #++
 
   def natcmp(str2, caseInsensitive=false)
     str1 = self.dup
@@ -53,17 +52,17 @@ class String
       str2.downcase!
     end
 
-    # remove all whitespace
+    # -- remove all whitespace
     str1.gsub!(/\s*/, '')
     str2.gsub!(/\s*/, '')
 
     while (str1.length > 0) or (str2.length > 0) do
-      # Extract non-digits, digits and rest of string
+      # -- extract non-digits, digits and rest of string
       str1 =~ compareExpression
       chars1, num1, str1 = $1.dup, $2.dup, $3.dup
       str2 =~ compareExpression
       chars2, num2, str2 = $1.dup, $2.dup, $3.dup
-      # Compare the non-digits
+      # -- compare the non-digits
       case (chars1 <=> chars2)
         when 0 # Non-digits are the same, compare the digits...
           # If either number begins with a zero, then compare alphabetically,
@@ -80,7 +79,7 @@ class String
       end # case
     end # while
 
-    # strings are naturally equal.
+    # -- strings are naturally equal
     return 0
   end