strings 0.0.0 → 0.1.0

data/lib/strings/padder.rb

@@ -0,0 +1,160 @@
+# frozen_string_litera: true
+
+module Strings
+  # A class responsible for parsing padding value
+  #
+  # Used internally by {Strings::Pad}
+  #
+  # @api private
+  class Padder
+    ParseError = Class.new(ArgumentError)
+
+    # Parse padding options
+    #
+    # Turn possible values into 4 element array
+    #
+    # @example
+    #   padder = TTY::Table::Padder.parse(5)
+    #   padder.padding # => [5, 5, 5, 5]
+    #
+    # @param [Object] value
+    #
+    # @return [TTY::Padder]
+    #   the new padder with padding values
+    #
+    # @api public
+    def self.parse(value = nil)
+      return value if value.is_a?(self)
+
+      new(convert_to_ary(value))
+    end
+
+    # Convert value to 4 element array
+    #
+    # @return [Array[Integer]]
+    #   the 4 element padding array
+    #
+    # @api private
+    def self.convert_to_ary(value)
+      if value.class <= Numeric
+        [value, value, value, value]
+      elsif value.nil?
+        []
+      elsif value.size == 2
+        [value[0], value[1], value[0], value[1]]
+      elsif value.size == 4
+        value
+      else
+        raise ParseError, 'Wrong :padding parameter, must be an array'
+      end
+    end
+
+    # Padding
+    #
+    # @return [Array[Integer]]
+    attr_reader :padding
+
+    # Initialize a Padder
+    #
+    # @api public
+    def initialize(padding)
+      @padding = padding
+    end
+
+    # Top padding
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def top
+      @padding[0].to_i
+    end
+
+    # Set top padding
+    #
+    # @param [Integer] val
+    #
+    # @return [nil]
+    #
+    # @api public
+    def top=(value)
+      @padding[0] = value
+    end
+
+    # Right padding
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def right
+      @padding[1].to_i
+    end
+
+    # Set right padding
+    #
+    # @param [Integer] val
+    #
+    # @api public
+    def right=(value)
+      @padding[1] = value
+    end
+
+    # Bottom padding
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def bottom
+      @padding[2].to_i
+    end
+
+    # Set bottom padding
+    #
+    # @param [Integer] value
+    #
+    # @return [nil]
+    #
+    # @api public
+    def bottom=(value)
+      @padding[2] = value
+    end
+
+    # Left padding
+    #
+    # @return [Integer]
+    #
+    # @api public
+    def left
+      @padding[3].to_i
+    end
+
+    # Set left padding
+    #
+    # @param [Integer] value
+    #
+    # @return [nil]
+    #
+    # @api public
+    def left=(value)
+      @padding[3] = value
+    end
+
+    # Check if padding is set
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def empty?
+      padding.empty?
+    end
+
+    # String represenation of this padder with padding values
+    #
+    # @return [String]
+    #
+    # @api public
+    def to_s
+      inspect
+    end
+  end # Padder
+end

data/lib/strings/truncate.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+require 'unicode_utils/each_grapheme'
+
+require_relative 'ansi'
+
+module Strings
+  # A module responsible for text truncation
+  module Truncate
+    DEFAULT_TRAILING = '…'.freeze
+
+    DEFAULT_LENGTH = 30
+
+    # Truncate a text at a given length (defualts to 30)
+    #
+    # @param [String] text
+    #   the text to be truncated
+    #
+    # @param [Integer] truncate_at
+    #   the width at which to truncate the text
+    #
+    # @param [Hash] options
+    #   @option options [Symbol] :separator the character for splitting words
+    #   @option options [Symbol] :trailing  the character for ending sentence
+    #
+    # @example
+    #   text = "The sovereignest thing on earth is parmacetti for an inward bruise."
+    #
+    #   Strings::Truncate.truncate(text)
+    #   # => "The sovereignest thing on ear…"
+    #
+    #   Strings::Truncate.truncate(text, 20)
+    #   # => "The sovereignest th…"
+    #
+    #   Strings::Truncate.truncate(text, 20, separator: ' ' )
+    #   # => "The sovereignest…"
+    #
+    #   Strings::Truncate.truncate(40, trailing: '... (see more)' )
+    #   # => "The sovereignest thing on... (see more)"
+    #
+    # @api public
+    def truncate(text, truncate_at = DEFAULT_LENGTH, options = {})
+      if truncate_at.is_a?(Hash)
+        options = truncate_at
+        truncate_at = DEFAULT_LENGTH
+      end
+
+      if display_width(text) <= truncate_at.to_i || truncate_at.to_i.zero?
+        return text.dup
+      end
+
+      trail      = options.fetch(:trailing) { DEFAULT_TRAILING }
+      separation = options.fetch(:separator) { nil }
+      sanitized_text = Strings::ANSI.sanitize(text)
+
+      length_without_trailing = truncate_at - display_width(trail)
+      chars = to_chars(sanitized_text).to_a
+      stop  = chars[0, length_without_trailing].rindex(separation)
+      slice_length = stop || length_without_trailing
+      sliced_chars = chars[0, slice_length]
+      original_chars = to_chars(text).to_a[0, 3 * slice_length]
+      shorten(original_chars, sliced_chars, length_without_trailing).join + trail
+    end
+    module_function :truncate
+
+    # Perform actual shortening of the text
+    #
+    # @return [String]
+    #
+    # @api private
+    def shorten(original_chars, chars, length_without_trailing)
+      truncated = []
+      char_width = display_width(chars[0])
+      while length_without_trailing - char_width > 0
+        orig_char = original_chars.shift
+        char = chars.shift
+        break unless char
+        while orig_char != char # consume ansi
+          ansi = true
+          truncated << orig_char
+          orig_char = original_chars.shift
+        end
+        truncated << char
+        char_width = display_width(char)
+        length_without_trailing -= char_width
+      end
+      truncated << ["\e[0m"] if ansi
+      truncated
+    end
+    module_function :shorten
+
+    # @api private
+    def to_chars(text)
+      UnicodeUtils.each_grapheme(text)
+    end
+    module_function :to_chars
+
+    # Visible width of a string
+    #
+    # @api private
+    def display_width(string)
+      Unicode::DisplayWidth.of(Strings::ANSI.sanitize(string))
+    end
+    module_function :display_width
+  end # Truncate
+end # Strings

data/lib/strings/version.rb

@@ -1,3 +1,3 @@
 module Strings
-  VERSION = "0.0.0"
+  VERSION = '0.1.0'.freeze
 end

data/lib/strings/wrap.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'unicode/display_width'
+require 'unicode_utils/each_grapheme'
+
+require_relative 'ansi'
+require_relative 'fold'
+
+module Strings
+  module Wrap
+    DEFAULT_WIDTH = 80
+
+    NEWLINE = "\n".freeze
+
+    SPACE = ' '.freeze
+
+    LINE_BREAK = "\r\n+|\r+|\n+".freeze
+
+    # Wrap a text into lines no longer than wrap_at length.
+    # Preserves existing lines and existing word boundaries.
+    #
+    # @example
+    #   Strings::Wrap.wrap("Some longish text", 8)
+    #   # => >Some
+    #        >longish
+    #        >text
+    #
+    # @api public
+    def wrap(text, wrap_at = DEFAULT_WIDTH)
+      if text.length < wrap_at.to_i || wrap_at.to_i.zero?
+        return text
+      end
+      ansi_stack = []
+      text.split(%r{#{LINE_BREAK}}, -1).map do |paragraph|
+        format_paragraph(paragraph, wrap_at, ansi_stack)
+      end * NEWLINE
+    end
+    module_function :wrap
+
+    # Format paragraph to be maximum of wrap_at length
+    #
+    # @param [String] paragraph
+    #   the paragraph to format
+    # @param [Integer] wrap_at
+    #   the maximum length to wrap the paragraph
+    #
+    # @return [Array[String]]
+    #   the wrapped lines
+    #
+    # @api private
+    def format_paragraph(paragraph, wrap_at, ansi_stack)
+      cleared_para = Fold.fold(paragraph)
+      lines = []
+      line  = []
+      word  = []
+      ansi  = []
+      ansi_matched = false
+      word_length = 0
+      line_length = 0
+      char_length = 0 # visible char length
+      text_length = display_width(cleared_para)
+      total_length = 0
+
+      UnicodeUtils.each_grapheme(cleared_para) do |char|
+        # we found ansi let's consume
+        if char == Strings::ANSI::CSI || ansi.length > 0
+          ansi << char
+          if Strings::ANSI.only_ansi?(ansi.join)
+            ansi_matched = true
+          elsif ansi_matched
+            ansi_stack << [ansi[0...-1].join, line_length + word_length]
+            ansi_matched = false
+            ansi = []
+          end
+          next if ansi.length > 0
+        end
+
+        char_length = display_width(char)
+        total_length += char_length
+        if line_length + word_length + char_length <= wrap_at
+          if char == SPACE || total_length == text_length
+            line << word.join + char
+            line_length += word_length + char_length
+            word = []
+            word_length = 0
+          else
+            word << char
+            word_length += char_length
+          end
+          next
+        end
+
+        if char == SPACE # ends with space
+          lines << insert_ansi(ansi_stack, line.join)
+          line = []
+          line_length = 0
+          word << char
+          word_length += char_length
+        elsif word_length + char_length <= wrap_at
+          lines << insert_ansi(ansi_stack, line.join)
+          line = [word.join + char]
+          line_length = word_length + char_length
+          word = []
+          word_length = 0
+        else # hyphenate word - too long to fit a line
+          lines << insert_ansi(ansi_stack, word.join)
+          line_length = 0
+          word = [char]
+          word_length = char_length
+        end
+      end
+      lines << insert_ansi(ansi_stack, line.join) unless line.empty?
+      lines << insert_ansi(ansi_stack, word.join) unless word.empty?
+      lines
+    end
+    module_function :format_paragraph
+
+    # Insert ANSI code into string
+    #
+    # Check if there are any ANSI states, if present
+    # insert ANSI codes at given positions unwinding the stack.
+    #
+    # @param [Array[Array[String, Integer]]] ansi_stack
+    #   the ANSI codes to apply
+    #
+    # @param [String] string
+    #   the string to insert ANSI codes into
+    #
+    # @return [String]
+    #
+    # @api private
+    def insert_ansi(ansi_stack, string)
+      return string if ansi_stack.empty?
+      to_remove = 0
+      reset_index = -1
+      output = string.dup
+      resetting = false
+      ansi_stack.reverse_each do |state|
+        if state[0] =~ /#{Regexp.quote(Strings::ANSI::RESET)}/
+          resetting = true
+          reset_index = state[1]
+          to_remove += 2
+          next
+        elsif !resetting
+          reset_index = -1
+          resetting = false
+        end
+
+        color, color_index = *state
+        output.insert(reset_index, Strings::ANSI::RESET).insert(color_index, color)
+      end
+      ansi_stack.pop(to_remove) # remove used states
+      output
+    end
+    module_function :insert_ansi
+
+    # Visible width of a string
+    #
+    # @api private
+    def display_width(string)
+      Unicode::DisplayWidth.of(Strings::ANSI.sanitize(string))
+    end
+    module_function :display_width
+  end # Wrap
+end # Strings

data/strings.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Piotr Murach"]
   spec.email         = [""]
 
-  spec.summary       = %q{A module to wrap, truncate, indent, and otherwise transform strings.}
-  spec.description   = %q{A module to wrap, truncate, indent, and otherwise transofrm strings.}
+  spec.summary       = %q{A set of useful functions for transforming strings.}
+  spec.description   = %q{A set of useful functions such as fold, truncate, wrap and more for transoforming strings.}
   spec.homepage      = ""
   spec.license       = "MIT"
 
@@ -21,6 +21,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency 'unicode_utils',        '~> 1.4.0'
+  spec.add_dependency 'unicode-display_width','~> 1.3.0'
+
   spec.add_development_dependency "bundler", "~> 1.15"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"