facets 2.9.3 → 3.0.0

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

@@ -1,9 +1,15 @@
 class String
 
-  # Indent left or right by n spaces.
-  # (This used to be called #tab and aliased as #indent.)
+  # Indent left or right by `n` spaces, or `n` number of `c` string.
   #
-  # CREDIT: Gavin Sinclair, Trans, Tyler Rick
+  # n - The number of spaces to indent. [Integer]
+  # c - Character to use, if other then space. [String]
+  #
+  # Returns a new string with the indention. [String]
+  #
+  # Credit: Gavin Sinclair
+  # Credit: Trans
+  # Credit: Tyler Rick
 
   def indent(n, c=' ')
     if n >= 0
@@ -14,30 +20,33 @@ class String
   end
 
   # Equivalent to String#indent, but modifies the receiver in place.
+  #
+  # n - The number of spaces to indent. [Integer]
+  # c - Character to use, if other then space. [String]
+  #
+  # Returns this string with the indention. [String]
 
   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
+  # Remove excessive indentation. Useful for multi-line strings
+  # embeded in already indented code.
   #
-  # Outputs ...
+  # size - The number of spaces to indent. [Integer]
   #
-  #   ohaie
-  #     wurld
+  # Examples
   #
-  # Instead of ...
+  #     <<-END.unindent
+  #         ohaie
+  #           wurld
+  #     END 
+  #     #=> "ohaie\n  wurld"
   #
-  #       ohaie
-  #         wurld
+  # Returns a new unindented string. [String]
   #
-  # CREDIT: Noah Gibbs, mynyml
+  # Credit: Noah Gibbs
+  # Credit: mynyml
 
   def unindent(size=nil)
     if size
@@ -57,11 +66,19 @@ class String
 
   # Equivalent to String#unindent, but modifies the receiver in place.
   #
-  # CREDIT: mynyml
+  # Returns this string unindented. [String]
+  #
+  # Credit: mynyml
 
   def unindent!
-    self.replace(self.unindent)
+    replace(unindent)
   end
 
-end
+  # DEPRECATED: Use String#indent instead.
+  alias :tab  :indent
+  alias :tab! :indent!
 
+  #alias :backtab  :unindent
+  #alias :backtab! :unindent!
+
+end

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

@@ -0,0 +1,7 @@
+require 'facets/indexable'
+require 'facets/string/splice'
+
+class String
+  include Indexable
+end
+

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

@@ -1,13 +1,17 @@
 class String
 
-  # Interpolate. Provides a means of extenally using Ruby string
+  # Interpolate provides a means of externally 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 this uses #eval under the hood. We do not recommend that
+  # it serve in place of a good templating system. But, it can be
+  # useful for simple cases.
+  #
+  # The block is neccessary in order to get then binding of the caller.
   #
   # CREDIT: Trans
 

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

@@ -0,0 +1,19 @@
+require 'facets/functor'
+
+class String
+
+  # TODO: Should String#linear be moved to separate functor gem?
+
+  # Like `#newlines` but returns a Functor instead.
+  #
+  #   "a \n b \n c".linear.strip   #=> "a\nb\nc"
+  #
+  def linear
+    Functor.new do |op, *a, &b|
+      lines.map { |line|
+        line.chomp.public_send(op, *a, &b)
+      }.join("\n")
+    end
+  end
+
+end

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

@@ -1,31 +1,59 @@
+require 'facets/string/indent'
+
 class String
 
-  # Provides a margin controlled string.
+  # Preserve relative tabbing such that the line with the least amount 
+  # of white space ends up with the given number of spaces before non-space
+  # and all other lines move relative to it.
+  #
+  # Because of the nature of this method, leading tab characters (`\t`) must
+  # be converted to spaces. The size of a tab can be set via the `:tab` option.
+  # The default size is 2.
+  #
+  # If the `:lead` option is set, then the relative margin is determined
+  # by the first non-blank line, instead of the minimum white-space for all
+  # lines.
+  #
+  # Arguments
+  #
+  #   num   - The size of the desired margin. [Integer]
+  #   opts  - Margin options. [Hash]
   #
-  #   x = %Q{
-  #         | This
-  #         |   is
-  #         |     margin controlled!
-  #         }.margin
+  # Options
   #
-  # NOTE: This may still need a bit of tweaking.
+  #   :tab  - Size of tab character in spaces. [Integer]
+  #   :lead - Use first non-blank line as relative marker. [Boolean] 
   #
-  # TODO: describe its limits and caveats and edge cases
+  # Returns a new String with adjusted margin. [String]
   #
-  # CREDIT: Trans
+  # Author: Gavin Sinclair
+  # Author: Trans
 
-  def margin(n=0)
-    #d = /\A.*\n\s*(.)/.match( self )[1]
-    #d = /\A\s*(.)/.match( self)[1] unless d
-    d = ((/\A.*\n\s*(.)/.match(self)) ||
-        (/\A\s*(.)/.match(self)))[1]
-    return '' unless d
-    if n == 0
-      gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, '')
+  def margin(num=nil, opts={})
+    # TODO: temporary to help people transition
+    raise ArgumentError, "String#margin has been renamed to #trim." unless num
+
+    tab = opts[:tab] || 2
+    str = gsub("\t", " " * tab)  # TODO: only leading tabs ?
+
+    if opts[:lead]
+      if self =~ /^( *)\S/
+        indent(num - $1.length)
+      else
+        self
+      end
     else
-      gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, ' ' * n)
+      min = []
+      str.each_line do |line|
+        next if line.strip.empty?
+        min << line.index(/\S/)
+      end
+      min = min.min
+      str.indent(num - min)
     end
   end
 
-end
+  # Original name of #margin.
+  alias :tabto :margin
 
+end

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

@@ -15,5 +15,8 @@ class String
     end
   end
 
+  # Alias for #mscan.
+  alias each_match mscan
+
 end
 

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

@@ -0,0 +1,14 @@
+class String
+
+  # Returns true if it's a decimal digits.
+  #
+  #   "123_456_789_123_456_789.123_456_000_111".number?  # => true
+  #   "1.23".number?  # => true
+  #   "1.23a".number? # => false
+  #
+  # CREDIT: u2
+
+  def number?
+    !!self.match(/\A[+-]?\d+?(_?\d+?)*?(\.\d+(_?\d+?)*?)?\Z/)
+  end
+end

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

@@ -1,14 +1 @@
-class String
-
-  # Removes occurances of a string or regexp.
-  #
-  #   ("HELLO HELLO" - "LL")    #=> "HEO HEO"
-  #
-  # CREDIT: Benjamin David Oakes
-
-  def -(pattern)
-    self.gsub(pattern, '')
-  end
-
-end
-
+require_relative 'remove'

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

@@ -0,0 +1,34 @@
+class String
+
+  # Create a random String of given length, using given character set
+  #
+  # Examples
+  #
+  #     String.random
+  #     => "D9DxFIaqR3dr8Ct1AfmFxHxqGsmA4Oz3"
+  #
+  #     String.random(10)
+  #     => "t8BIna341S"
+  #
+  #     String.random(10, ['a'..'z'])
+  #     => "nstpvixfri"
+  #
+  #     String.random(10, ['0'..'9'] )
+  #     => "0982541042"
+  #
+  #     String.random(10, ['0'..'9','A'..'F'] )
+  #     => "3EBF48AD3D"
+  #
+  # CREDIT: Tilo Sloboda
+  #
+  # SEE: https://gist.github.com/tilo/3ee8d94871d30416feba
+  #
+  # TODO: Move to random.rb in standard library?
+
+  def self.random(len=32, character_set = ["A".."Z", "a".."z", "0".."9"])
+    characters = character_set.map { |i| i.to_a }.flatten
+    characters_len = characters.length
+    (0...len).map{ characters[rand(characters_len)] }.join
+  end
+
+end

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

@@ -0,0 +1,30 @@
+class String
+
+  # Removes all occurrences of a pattern in a string.
+  #
+  # Returns a new [String] with all occurrences of the pattern removed.
+  def remove(pattern)
+    gsub(pattern, '')
+  end
+
+  # Removes all occurrences of a pattern in a string.
+  #
+  # Returns the [String] with all occurrences of the pattern removed.
+  def remove!(pattern)
+    gsub!(pattern, '')
+  end
+
+  # Removes occurances of a string or regexp. This is an operator
+  # form for the #remove method.
+  #
+  #   ("HELLO HELLO" - "LL")    #=> "HEO HEO"
+  #   ("HELLO PERL" - /L\S/)    #=> "HEO PERL"
+  #
+  # Returns a new [String] with all pattern matches removed.
+  #
+  # CREDIT: Benjamin David Oakes
+  def -(pattern)
+    gsub(pattern, '')
+  end
+
+end

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

@@ -0,0 +1,24 @@
+class String
+
+  # Rotate string to the left with count.
+  # Specifying negative number indicates rotation to the right.
+  #
+  #   'abcdefgh'.rotate(2)  #=> 'cdefghab'
+  #   'abcdefgh'.rotate(-2) #=> 'ghabcdef'
+  #
+  # CREDIT: T. Yamada
+  def rotate(count=1)
+    count+=self.length if count<0
+    self.slice(count,self.length-count)+self.slice(0,count)
+  end
+
+  # Destructive version of String#rotate
+  #
+  #   s='abcdefgh'
+  #   s.rotate!(2)
+  #   s.should eq 'cdefghab'
+  #
+  # CREDIT: T. Yamada
+  def rotate!(count=1) replace(rotate(count)) end
+
+end

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

@@ -36,7 +36,7 @@ class String
     # -- "graph" self
     last = self.length
     (0..last).each do |ff|
-      loc  = self.length
+      #loc = self.length
       break if ff == last - 1
       wordB = (1..(last-1)).to_a.reverse!
       if (wordB != nil)
@@ -50,7 +50,7 @@ class String
     # -- "graph" input string
     last = str_in.length
     (0..last).each{ |ff|
-      loc  = str_in.length
+      #loc = str_in.length
       break if ff == last - 1
       wordB = (1..(last-1)).to_a.reverse!
       wordB.each do |ss|

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

@@ -0,0 +1,5 @@
+class String
+  alias starts_with? start_with?
+  alias ends_with?   end_with?
+end
+

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

@@ -1,17 +1,2 @@
-require 'facets/string/tabto'
-
-class String
-
-  # Aligns each line n spaces.
-  #
-  # CREDIT: Gavin Sinclair
-  #
-  def tab(n)
-    gsub(/^ */, ' ' * n)
-  end
-
-  # NOTE: Deprecated #taballto which was an alias for #tab.
-  #alias_method :taballto, :tab
-
-end
-
+# DEPRECATED
+require 'facets/string/indent'

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

@@ -1,19 +1,2 @@
-require 'facets/string/indent'
-
-class String
-
-  # Preserves relative tabbing.
-  # The first non-empty line ends up with n spaces before nonspace.
-  #
-  # CREDIT: Gavin Sinclair
-
-  def tabto(n)
-    if self =~ /^( *)\S/
-      indent(n - $1.length)
-    else
-      self
-    end
-  end
-
-end
-
+# DEPRECATED
+require 'facets/string/margin'

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

@@ -0,0 +1 @@
+require_relative 'to_re'

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

@@ -0,0 +1,45 @@
+class String
+
+  # Control the margin of a string using a trim character.
+  #
+  # The first character of the second line of the string
+  # is used as the trim character. This method is useful
+  # when literal multi-line strings are needed in code.
+  # 
+  # num - Number of extra spaces with which to replace the
+  #       trim character. [Integer]
+  #
+  # Examples
+  #
+  #     x = %Q{
+  #           | This
+  #           |   is
+  #           |    trim!
+  #           }.trim
+  #
+  # Returns string with the margin trimed-off.
+  #
+  # Note: This this method used to be called `margin` prior to Facets 3.0.
+  #
+  # Since: 3.0.0
+  # Author: Trans
+
+  def trim(num=0)
+    #d = /\A.*\n\s*(.)/.match( self )[1]
+    #d = /\A\s*(.)/.match( self)[1] unless d
+
+    md = /\A.*\n\s*(.)/.match(self) || /\A\s*(.)/.match(self)
+
+    d = md[1]
+
+    return '' unless d
+
+    if num == 0
+      gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, '')
+    else
+      gsub(/\n\s*\Z/,'').gsub(/^\s*[#{d}]/, ' ' * num)
+    end
+  end
+
+end
+