omg-activesupport 8.0.0.alpha1

data/lib/active_support/core_ext/pathname/existence.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+class Pathname
+  # Returns the receiver if the named file exists otherwise returns +nil+.
+  # <tt>pathname.existence</tt> is equivalent to
+  #
+  #    pathname.exist? ? pathname : nil
+  #
+  # For example, something like
+  #
+  #   content = pathname.read if pathname.exist?
+  #
+  # becomes
+  #
+  #   content = pathname.existence&.read
+  #
+  # @return [Pathname]
+  def existence
+    self if exist?
+  end
+end

data/lib/active_support/core_ext/pathname.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/pathname/blank"
+require "active_support/core_ext/pathname/existence"

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  module CompareWithRange
+    # Extends the default Range#=== to support range comparisons.
+    #  (1..5) === (1..5)  # => true
+    #  (1..5) === (2..3)  # => true
+    #  (1..5) === (1...6) # => true
+    #  (1..5) === (2..6)  # => false
+    #
+    # The native Range#=== behavior is untouched.
+    #  ('a'..'f') === ('c') # => true
+    #  (5..9) === (11) # => false
+    #
+    # The given range must be fully bounded, with both start and end.
+    def ===(value)
+      if value.is_a?(::Range)
+        is_backwards_op = value.exclude_end? ? :>= : :>
+        return false if value.begin && value.end && value.begin.public_send(is_backwards_op, value.end)
+        # 1...10 includes 1..9 but it does not include 1..10.
+        # 1..10 includes 1...11 but it does not include 1...12.
+        operator = exclude_end? && !value.exclude_end? ? :< : :<=
+        value_max = !exclude_end? && value.exclude_end? ? value.max : value.last
+        super(value.first) && (self.end.nil? || value_max.public_send(operator, last))
+      else
+        super
+      end
+    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?(1...6) # => true
+    #  (1..5).include?(2..6)  # => false
+    #
+    # The native Range#include? behavior is untouched.
+    #  ('a'..'f').include?('c') # => true
+    #  (5..9).include?(11) # => false
+    #
+    # The given range must be fully bounded, with both start and end.
+    def include?(value)
+      if value.is_a?(::Range)
+        is_backwards_op = value.exclude_end? ? :>= : :>
+        return false if value.begin && value.end && value.begin.public_send(is_backwards_op, value.end)
+        # 1...10 includes 1..9 but it does not include 1..10.
+        # 1..10 includes 1...11 but it does not include 1...12.
+        operator = exclude_end? && !value.exclude_end? ? :< : :<=
+        value_max = !exclude_end? && value.exclude_end? ? value.max : value.last
+        super(value.first) && (self.end.nil? || value_max.public_send(operator, last))
+      else
+        super
+      end
+    end
+  end
+end
+
+Range.prepend(ActiveSupport::CompareWithRange)

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  # = \Range With Format
+  module RangeWithFormat
+    RANGE_FORMATS = {
+      db: -> (start, stop) do
+        if start && stop
+          case start
+          when String then "BETWEEN '#{start}' AND '#{stop}'"
+          else
+            "BETWEEN '#{start.to_fs(:db)}' AND '#{stop.to_fs(:db)}'"
+          end
+        elsif start
+          case start
+          when String then ">= '#{start}'"
+          else
+            ">= '#{start.to_fs(:db)}'"
+          end
+        elsif stop
+          case stop
+          when String then "<= '#{stop}'"
+          else
+            "<= '#{stop.to_fs(:db)}'"
+          end
+        end
+      end
+    }
+
+    # Convert range to a formatted string. See RANGE_FORMATS for predefined formats.
+    #
+    # This method is aliased to <tt>to_formatted_s</tt>.
+    #
+    #   range = (1..100)           # => 1..100
+    #
+    #   range.to_s                 # => "1..100"
+    #   range.to_fs(:db)           # => "BETWEEN '1' AND '100'"
+    #
+    #   range = (1..)              # => 1..
+    #   range.to_fs(:db)           # => ">= '1'"
+    #
+    #   range = (..100)            # => ..100
+    #   range.to_fs(:db)           # => "<= '100'"
+    #
+    # == Adding your own range formats to to_fs
+    # You can add your own formats to the Range::RANGE_FORMATS hash.
+    # Use the format name as the hash key and a Proc instance.
+    #
+    #   # config/initializers/range_formats.rb
+    #   Range::RANGE_FORMATS[:short] = ->(start, stop) { "Between #{start.to_fs(:db)} and #{stop.to_fs(:db)}" }
+    def to_fs(format = :default)
+      if formatter = RANGE_FORMATS[format]
+        formatter.call(self.begin, self.end)
+      else
+        to_s
+      end
+    end
+    alias_method :to_formatted_s, :to_fs
+  end
+end
+
+Range.prepend(ActiveSupport::RangeWithFormat)

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_support/time_with_zone"
+
+module ActiveSupport
+  module EachTimeWithZone # :nodoc:
+    def each(&block)
+      ensure_iteration_allowed
+      super
+    end
+
+    def step(n = 1, &block)
+      ensure_iteration_allowed
+      super
+    end
+
+    private
+      def ensure_iteration_allowed
+        raise TypeError, "can't iterate from #{first.class}" if first.is_a?(TimeWithZone)
+      end
+  end
+end
+
+Range.prepend(ActiveSupport::EachTimeWithZone)

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+class Range
+  # Compare two ranges and see if they overlap each other
+  #  (1..5).overlap?(4..6) # => true
+  #  (1..5).overlap?(7..9) # => false
+  unless Range.method_defined?(:overlap?) # Ruby 3.3+
+    def overlap?(other)
+      raise TypeError unless other.is_a? Range
+
+      self_begin = self.begin
+      other_end = other.end
+      other_excl = other.exclude_end?
+
+      return false if _empty_range?(self_begin, other_end, other_excl)
+
+      other_begin = other.begin
+      self_end = self.end
+      self_excl = self.exclude_end?
+
+      return false if _empty_range?(other_begin, self_end, self_excl)
+      return true if self_begin == other_begin
+
+      return false if _empty_range?(self_begin, self_end, self_excl)
+      return false if _empty_range?(other_begin, other_end, other_excl)
+
+      true
+    end
+
+    private
+    def _empty_range?(b, e, excl)
+      return false if b.nil? || e.nil?
+
+      comp = b <=> e
+      comp.nil? || comp > 0 || (comp == 0 && excl)
+    end
+  end
+
+  alias :overlaps? :overlap?
+end

data/lib/active_support/core_ext/range.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/range/conversions"
+require "active_support/core_ext/range/compare_range"
+require "active_support/core_ext/range/overlap"
+require "active_support/core_ext/range/each"

data/lib/active_support/core_ext/regexp.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Regexp
+  # Returns +true+ if the regexp has the multiline flag set.
+  #
+  #   (/./).multiline?  # => false
+  #   (/./m).multiline? # => true
+  #
+  #   Regexp.new(".").multiline?                    # => false
+  #   Regexp.new(".", Regexp::MULTILINE).multiline? # => true
+  def multiline?
+    options & MULTILINE == MULTILINE
+  end
+end

data/lib/active_support/core_ext/securerandom.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module SecureRandom
+  BASE58_ALPHABET = ("0".."9").to_a + ("A".."Z").to_a + ("a".."z").to_a - ["0", "O", "I", "l"]
+  BASE36_ALPHABET = ("0".."9").to_a + ("a".."z").to_a
+
+  # SecureRandom.base58 generates a random base58 string.
+  #
+  # The argument _n_ specifies the length of the random string to be generated.
+  #
+  # If _n_ is not specified or is +nil+, 16 is assumed. It may be larger in the future.
+  #
+  # The result may contain alphanumeric characters except 0, O, I, and l.
+  #
+  #   p SecureRandom.base58 # => "4kUgL2pdQMSCQtjE"
+  #   p SecureRandom.base58(24) # => "77TMHrHJFvFDwodq8w7Ev2m7"
+  def self.base58(n = 16)
+    SecureRandom.alphanumeric(n, chars: BASE58_ALPHABET)
+  end
+
+  # SecureRandom.base36 generates a random base36 string in lowercase.
+  #
+  # The argument _n_ specifies the length of the random string to be generated.
+  #
+  # If _n_ is not specified or is +nil+, 16 is assumed. It may be larger in the future.
+  # This method can be used over +base58+ if a deterministic case key is necessary.
+  #
+  # The result will contain alphanumeric characters in lowercase.
+  #
+  #   p SecureRandom.base36 # => "4kugl2pdqmscqtje"
+  #   p SecureRandom.base36(24) # => "77tmhrhjfvfdwodq8w7ev2m7"
+  def self.base36(n = 16)
+    SecureRandom.random_bytes(n).unpack("C*").map do |byte|
+      idx = byte % 64
+      idx = SecureRandom.random_number(36) if idx >= 36
+      BASE36_ALPHABET[idx]
+    end.join
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+class String
+  # If you pass a single integer, returns a substring of one character at that
+  # position. The first character of the string is at position 0, the next at
+  # position 1, and so on. If a range is supplied, a substring containing
+  # characters at offsets given by the range is returned. In both cases, if an
+  # offset is negative, it is counted from the end of the string. Returns +nil+
+  # if the initial offset falls outside the string. Returns an empty string if
+  # the beginning of the range is greater than the end of the string.
+  #
+  #   str = "hello"
+  #   str.at(0)      # => "h"
+  #   str.at(1..3)   # => "ell"
+  #   str.at(-2)     # => "l"
+  #   str.at(-2..-1) # => "lo"
+  #   str.at(5)      # => nil
+  #   str.at(5..-1)  # => ""
+  #
+  # If a Regexp is given, the matching portion of the string is returned.
+  # If a String is given, that given string is returned if it occurs in
+  # the string. In both cases, +nil+ is returned if there is no match.
+  #
+  #   str = "hello"
+  #   str.at(/lo/) # => "lo"
+  #   str.at(/ol/) # => nil
+  #   str.at("lo") # => "lo"
+  #   str.at("ol") # => nil
+  def at(position)
+    self[position]
+  end
+
+  # Returns a substring from the given position to the end of the string.
+  # If the position is negative, it is counted from the end of the string.
+  #
+  #   str = "hello"
+  #   str.from(0)  # => "hello"
+  #   str.from(3)  # => "lo"
+  #   str.from(-2) # => "lo"
+  #
+  # You can mix it with +to+ method and do fun things like:
+  #
+  #   str = "hello"
+  #   str.from(0).to(-1) # => "hello"
+  #   str.from(1).to(-2) # => "ell"
+  def from(position)
+    self[position, length]
+  end
+
+  # Returns a substring from the beginning of the string to the given position.
+  # If the position is negative, it is counted from the end of the string.
+  #
+  #   str = "hello"
+  #   str.to(0)  # => "h"
+  #   str.to(3)  # => "hell"
+  #   str.to(-2) # => "hell"
+  #
+  # You can mix it with +from+ method and do fun things like:
+  #
+  #   str = "hello"
+  #   str.from(0).to(-1) # => "hello"
+  #   str.from(1).to(-2) # => "ell"
+  def to(position)
+    position += size if position < 0
+    self[0, position + 1] || +""
+  end
+
+  # Returns the first character. If a limit is supplied, returns a substring
+  # from the beginning of the string until it reaches the limit value. If the
+  # given limit is greater than or equal to the string length, returns a copy of self.
+  #
+  #   str = "hello"
+  #   str.first    # => "h"
+  #   str.first(1) # => "h"
+  #   str.first(2) # => "he"
+  #   str.first(0) # => ""
+  #   str.first(6) # => "hello"
+  def first(limit = 1)
+    self[0, limit] || raise(ArgumentError, "negative limit")
+  end
+
+  # Returns the last character of the string. If a limit is supplied, returns a substring
+  # from the end of the string until it reaches the limit value (counting backwards). If
+  # the given limit is greater than or equal to the string length, returns a copy of self.
+  #
+  #   str = "hello"
+  #   str.last    # => "o"
+  #   str.last(1) # => "o"
+  #   str.last(2) # => "lo"
+  #   str.last(0) # => ""
+  #   str.last(6) # => "hello"
+  def last(limit = 1)
+    self[[length - limit, 0].max, limit] || raise(ArgumentError, "negative limit")
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class String
+  # Enables more predictable duck-typing on String-like classes. See <tt>Object#acts_like?</tt>.
+  def acts_like_string?
+    true
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "date"
+require "active_support/core_ext/time/calculations"
+
+class String
+  # Converts a string to a Time value.
+  # The +form+ can be either +:utc+ or +:local+ (default +:local+).
+  #
+  # The time is parsed using Time.parse method.
+  # If +form+ is +:local+, then the time is in the system timezone.
+  # If the date part is missing then the current date is used and if
+  # the time part is missing then it is assumed to be 00:00:00.
+  #
+  #   "13-12-2012".to_time               # => 2012-12-13 00:00:00 +0100
+  #   "06:12".to_time                    # => 2012-12-13 06:12:00 +0100
+  #   "2012-12-13 06:12".to_time         # => 2012-12-13 06:12:00 +0100
+  #   "2012-12-13T06:12".to_time         # => 2012-12-13 06:12:00 +0100
+  #   "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 06:12:00 UTC
+  #   "12/13/2012".to_time               # => ArgumentError: argument out of range
+  #   "1604326192".to_time               # => ArgumentError: argument out of range
+  def to_time(form = :local)
+    parts = Date._parse(self, false)
+    used_keys = %i(year mon mday hour min sec sec_fraction offset)
+    return if !parts.keys.intersect?(used_keys)
+
+    now = Time.now
+    time = Time.new(
+      parts.fetch(:year, now.year),
+      parts.fetch(:mon, now.month),
+      parts.fetch(:mday, now.day),
+      parts.fetch(:hour, 0),
+      parts.fetch(:min, 0),
+      parts.fetch(:sec, 0) + parts.fetch(:sec_fraction, 0),
+      parts.fetch(:offset, form == :utc ? 0 : nil)
+    )
+
+    form == :utc ? time.utc : time.to_time
+  end
+
+  # Converts a string to a Date value.
+  #
+  #   "1-1-2012".to_date   # => Sun, 01 Jan 2012
+  #   "01/01/2012".to_date # => Sun, 01 Jan 2012
+  #   "2012-12-13".to_date # => Thu, 13 Dec 2012
+  #   "12/13/2012".to_date # => ArgumentError: invalid date
+  def to_date
+    ::Date.parse(self, false) unless blank?
+  end
+
+  # Converts a string to a DateTime value.
+  #
+  #   "1-1-2012".to_datetime            # => Sun, 01 Jan 2012 00:00:00 +0000
+  #   "01/01/2012 23:59:59".to_datetime # => Sun, 01 Jan 2012 23:59:59 +0000
+  #   "2012-12-13 12:50".to_datetime    # => Thu, 13 Dec 2012 12:50:00 +0000
+  #   "12/13/2012".to_datetime          # => ArgumentError: invalid date
+  def to_datetime
+    ::DateTime.parse(self, false) unless blank?
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class String
+  # The inverse of <tt>String#include?</tt>. Returns true if the string
+  # does not include the other string.
+  #
+  #   "hello".exclude? "lo" # => false
+  #   "hello".exclude? "ol" # => true
+  #   "hello".exclude? ?h   # => false
+  def exclude?(string)
+    !include?(string)
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+class String
+  # Returns the string, first removing all whitespace on both ends of
+  # the string, and then changing remaining consecutive whitespace
+  # groups into one space each.
+  #
+  # Note that it handles both ASCII and Unicode whitespace.
+  #
+  #   %{ Multi-line
+  #      string }.squish                   # => "Multi-line string"
+  #   " foo   bar    \n   \t   boo".squish # => "foo bar boo"
+  def squish
+    dup.squish!
+  end
+
+  # Performs a destructive squish. See String#squish.
+  #   str = " foo   bar    \n   \t   boo"
+  #   str.squish!                         # => "foo bar boo"
+  #   str                                 # => "foo bar boo"
+  def squish!
+    gsub!(/[[:space:]]+/, " ")
+    strip!
+    self
+  end
+
+  # Returns a new string with all occurrences of the patterns removed.
+  #   str = "foo bar test"
+  #   str.remove(" test")                 # => "foo bar"
+  #   str.remove(" test", /bar/)          # => "foo "
+  #   str                                 # => "foo bar test"
+  def remove(*patterns)
+    dup.remove!(*patterns)
+  end
+
+  # Alters the string by removing all occurrences of the patterns.
+  #   str = "foo bar test"
+  #   str.remove!(" test", /bar/)         # => "foo "
+  #   str                                 # => "foo "
+  def remove!(*patterns)
+    patterns.each do |pattern|
+      gsub! pattern, ""
+    end
+
+    self
+  end
+
+  # Truncates a given +text+ to length <tt>truncate_to</tt> if +text+ is longer than <tt>truncate_to</tt>:
+  #
+  #   'Once upon a time in a world far far away'.truncate(27)
+  #   # => "Once upon a time in a wo..."
+  #
+  # Pass a string or regexp <tt>:separator</tt> to truncate +text+ at a natural break:
+  #
+  #   'Once upon a time in a world far far away'.truncate(27, separator: ' ')
+  #   # => "Once upon a time in a..."
+  #
+  #   'Once upon a time in a world far far away'.truncate(27, separator: /\s/)
+  #   # => "Once upon a time in a..."
+  #
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...").
+  # The total length will not exceed <tt>truncate_to</tt> unless both +text+ and <tt>:omission</tt>
+  # are longer than <tt>truncate_to</tt>:
+  #
+  #   'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')
+  #   # => "And they f... (continued)"
+  #
+  #   'And they found that many people were sleeping better.'.truncate(4, omission: '... (continued)')
+  #   # => "... (continued)"
+  def truncate(truncate_to, options = {})
+    return dup unless length > truncate_to
+
+    omission = options[:omission] || "..."
+    length_with_room_for_omission = truncate_to - omission.length
+    stop = \
+      if options[:separator]
+        rindex(options[:separator], length_with_room_for_omission) || length_with_room_for_omission
+      else
+        length_with_room_for_omission
+      end
+
+    +"#{self[0, stop]}#{omission}"
+  end
+
+  # Truncates +text+ to at most <tt>truncate_to</tt> bytes in length without
+  # breaking string encoding by splitting multibyte characters or breaking
+  # grapheme clusters ("perceptual characters") by truncating at combining
+  # characters.
+  #
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".size
+  #   => 20
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".bytesize
+  #   => 80
+  #   >> "🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪🔪".truncate_bytes(20)
+  #   => "🔪🔪🔪🔪…"
+  #
+  # The truncated text ends with the <tt>:omission</tt> string, defaulting
+  # to "…", for a total length not exceeding <tt>truncate_to</tt>.
+  #
+  # Raises +ArgumentError+ when the bytesize of <tt>:omission</tt> exceeds <tt>truncate_to</tt>.
+  def truncate_bytes(truncate_to, omission: "…")
+    omission ||= ""
+
+    case
+    when bytesize <= truncate_to
+      dup
+    when omission.bytesize > truncate_to
+      raise ArgumentError, "Omission #{omission.inspect} is #{omission.bytesize}, larger than the truncation length of #{truncate_to} bytes"
+    when omission.bytesize == truncate_to
+      omission.dup
+    else
+      self.class.new.force_encoding(encoding).tap do |cut|
+        cut_at = truncate_to - omission.bytesize
+
+        each_grapheme_cluster do |grapheme|
+          if cut.bytesize + grapheme.bytesize <= cut_at
+            cut << grapheme
+          else
+            break
+          end
+        end
+
+        cut << omission
+      end
+    end
+  end
+
+  # Truncates a given +text+ after a given number of words (<tt>words_count</tt>):
+  #
+  #   'Once upon a time in a world far far away'.truncate_words(4)
+  #   # => "Once upon a time..."
+  #
+  # Pass a string or regexp <tt>:separator</tt> to specify a different separator of words:
+  #
+  #   'Once<br>upon<br>a<br>time<br>in<br>a<br>world'.truncate_words(5, separator: '<br>')
+  #   # => "Once<br>upon<br>a<br>time<br>in..."
+  #
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "..."):
+  #
+  #   'And they found that many people were sleeping better.'.truncate_words(5, omission: '... (continued)')
+  #   # => "And they found that many... (continued)"
+  def truncate_words(words_count, options = {})
+    sep = options[:separator] || /\s+/
+    sep = Regexp.escape(sep.to_s) unless Regexp === sep
+    if self =~ /\A((?>.+?#{sep}){#{words_count - 1}}.+?)#{sep}.*/m
+      $1 + (options[:omission] || "...")
+    else
+      dup
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+class String
+  # Same as +indent+, except it indents the receiver in-place.
+  #
+  # Returns the indented string, or +nil+ if there was nothing to indent.
+  def indent!(amount, indent_string = nil, indent_empty_lines = false)
+    indent_string = indent_string || self[/^[ \t]/] || " "
+    re = indent_empty_lines ? /^/ : /^(?!$)/
+    gsub!(re, indent_string * amount)
+  end
+
+  # Indents the lines in the receiver:
+  #
+  #   <<EOS.indent(2)
+  #   def some_method
+  #     some_code
+  #   end
+  #   EOS
+  #   # =>
+  #     def some_method
+  #       some_code
+  #     end
+  #
+  # The second argument, +indent_string+, specifies which indent string to
+  # use. The default is +nil+, which tells the method to make a guess by
+  # peeking at the first indented line, and fall back to a space if there is
+  # none.
+  #
+  #   "  foo".indent(2)        # => "    foo"
+  #   "foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar"
+  #   "foo".indent(2, "\t")    # => "\t\tfoo"
+  #
+  # While +indent_string+ is typically one space or tab, it may be any string.
+  #
+  # The third argument, +indent_empty_lines+, is a flag that says whether
+  # empty lines should be indented. Default is false.
+  #
+  #   "foo\n\nbar".indent(2)            # => "  foo\n\n  bar"
+  #   "foo\n\nbar".indent(2, nil, true) # => "  foo\n  \n  bar"
+  #
+  def indent(amount, indent_string = nil, indent_empty_lines = false)
+    dup.tap { |_| _.indent!(amount, indent_string, indent_empty_lines) }
+  end
+end