terminal_rb 0.19.0 → 1.0.3

data/lib/terminal/text.rb

@@ -1,135 +1,213 @@
 # frozen_string_literal: true
 
 require_relative 'ansi'
+require_relative 'text/formatter'
 
 module Terminal
-  # Text helper functions.
+  # Unicode-aware text processing utilities for display width calculation,
+  # word-wrapping, and formatted text output.
+  #
+  # All methods correctly handle multi-byte Unicode characters, East Asian
+  # wide characters, emoji, combining marks, and ANSI escape codes.
+  #
+  # @see Terminal::Text::Formatter
+  #
+  # @example Measure display width
+  #   Terminal::Text.width('Hello')     # => 5
+  #   Terminal::Text.width("\u{1F600}") # => 2  (emoji)
+  #
+  # @example Word-wrap text
+  #   Terminal::Text.lines('Hello World, this is a test', width: 12)
+  #   # => ["Hello World,", "this is a", "test"]
   #
   module Text
     class << self
-      # Value for {width} of letters whose display width is not precisely
-      # defined by the Unicode standard.
-      # Defaults to one (1).
+      # Display width used for East Asian ambiguous-width characters.
       #
-      # @see .width
+      # @example
+      #   Terminal::Text.ambiguous_char_width     # => 1
+      #   Terminal::Text.ambiguous_char_width = 2 # for CJK terminals
       #
-      # @return [Integer] value
+      # @return [Integer] default: +1+
       attr_accessor :ambiguous_char_width
 
-      # Calculates the display width of the text representation of a given
-      # argument.
-      # It can optionally ignore embedded BBCode.
+      # Calculate the display width of a string in terminal columns.
       #
-      # The Unicode standard defines the display width for most characters but
-      # some are ambiguous. The function uses {ambiguous_char_width} for each of
-      # these characters.
+      # @example
+      #   Terminal::Text.width('Hello')                          # => 5
+      #   Terminal::Text.width('[bold]Hi[/bold]')                # => 2
+      #   Terminal::Text.width('[bold]Hi[/bold]', bbcode: false) # => 14
       #
-      # @param str [#to_s] str to process
-      # @param bbcode [true|false] whether to interpret embedded BBCode
-      # @return [Integer] display width
-      def width(str, bbcode: true)
-        return 0 if (str = bbcode ? Ansi.unbbcode(str) : str.to_s).empty?
-        str = str.encode(@encoding) if str.encoding != @encoding
-        width = 0
-        str.scan(@scan_width) do |sp, gc|
-          next width += char_width(gc) if gc
-          width += 1 if sp
-        end
-        width
+      # @param str [#to_s] the string to measure
+      # @param bbcode (see Formatter#initialize)
+      # @param spaces (see Formatter#initialize)
+      # @return [Integer] display width in columns
+      def width(str, bbcode: true, spaces: true)
+        Formatter
+          .new(str, bbcode:, spaces:, ansi: false, eol: false)
+          .lines_with_size
+          .dig(0, -1) || 0
       end
 
-      # Iterate each line of given text.
+      # Split text into lines with their display widths.
       #
-      # @example Generate word-by-word wrapped text for a limited output width
-      #   Terminal::Text.each_line('This is a simple test 😀', limit: 6).to_a
-      #   # => ["This", "is a", "simple", "test", "😀"]
+      # @example
+      #   Terminal::Text.lines_with_size('Hello World', width: 5)
+      #   # => [["Hello", 5], ["World", 5]]
       #
-      # @param text [#to_s, ...]
-      #   text objects to process
-      # @param limit [#to_i, nil]
-      #   optionally limit line size
-      # @param bbcode [true, false]
-      #   whether to interprete embedded BBCode (see {Ansi.bbcode})
-      # @param ansi [true, false]
-      #   whether to keep embedded ANSI control codes
-      # @param ignore_newline [true, false]
-      #   wheter to ignore embedded line breaks (`"\r\n"` or `"\n"`)
-      # @yield [String] text line
-      # @return [Enumerator] when no block given
-      # @return [nil]
-      # @raise ArgumentError when a `limit` less than `1` is given
+      # @param (see Formatter#initialize)
+      # @param (see Formatter#lines_with_size)
+      # @return (see Formatter#lines_with_size)
+      def lines_with_size(
+        *str,
+        bbcode: true,
+        ansi: true,
+        spaces: true,
+        eol: true,
+        width: nil
+      )
+        Formatter.new(*str, bbcode:, ansi:, spaces:, eol:).lines_with_size(
+          width:
+        )
+      end
+
+      # Split text into lines as strings.
+      #
+      # @see Formatter#lines
+      #
+      # @example
+      #   Terminal::Text.lines('Hello World', width: 5)
+      #   # => ["Hello", "World"]
+      # @example With BBCode
+      #   Terminal::Text.lines('[bold]Hello[/] World', width: 5)
+      #   # => ["\e[1mHello\e[m", "World"]
+      #
+      # @param (see Formatter#initialize)
+      # @param (see Formatter#lines)
+      # @return (see Formatter#lines)
+      def lines(
+        *str,
+        bbcode: true,
+        ansi: true,
+        spaces: true,
+        eol: true,
+        width: nil
+      )
+        Formatter.new(*str, bbcode:, ansi:, spaces:, eol:).lines(width:)
+      end
+
+      # Format text with alignment, padding, and decorations.
+      #
+      # @see Formatter.format
+      #
+      # @param (see Formatter.format)
+      # @return (see Formatter.format)
+      # @raise (see Formatter.format)
+      def format(...) = Formatter.format(...)
+
+      # @deprecated Use {.lines} and iterate over the result.
+      #
+      # @comment @param str [Array<#to_s>] text to process
+      # @comment @param limit [Integer, nil] maximum line width
+      # @comment @param bbcode [true, false] process BBCode markup
+      # @comment @param ansi [true, false] recognize ANSI escape codes
+      # @comment @param ignore_newline [true, false] treat newlines as spaces
+      # @comment @yield [String] each line
+      # @comment @return [Enumerator, Object] enumerator or block result
       def each_line(
-        *text,
+        *str,
         limit: nil,
         bbcode: true,
         ansi: true,
         ignore_newline: false,
-        &block
+        &
       )
-        unless limit
-          snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
-          return block ? lines(snippets, &block) : to_enum(:lines, snippets)
-        end
-        limit = limit.to_i
-        raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
-        snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
-        return lim_lines(snippets, limit, &block) if block
-        to_enum(:lim_lines, snippets, limit)
+        warn(
+          '[DEPRECATED] `each_line` is deprecated – use `.lines.each` instead',
+          category: :deprecated,
+          uplevel: 1
+        )
+        lines(
+          *str,
+          bbcode:,
+          ansi:,
+          spaces: true,
+          eol: !ignore_newline,
+          width: limit
+        ).each(&)
       end
       alias each each_line
 
-      # Iterate each line and it's display width of given text.
-      #
-      # @example Generate word-by-word wrapped text for a limited output width
-      #   Terminal::Text.each_line_with_size('This is a simple test 😀', limit: 6).to_a
-      #   # => [["This", 4], ["is a", 4], ["simple", 6], ["test", 4], ["😀", 2]]
+      # @deprecated Use {.lines_with_size} and iterate over the result.
       #
-      # @param (see each_line)
-      # @yield [String, Integer] text line and it's display width
-      # @return (see each_line)
-      # @raise (see each_line)
+      # @comment @param str [Array<to_s>] text to process
+      # @comment @param limit [Integer, nil] maximum line width
+      # @comment @param bbcode [true, false] process BBCode markup
+      # @comment @param ansi [true, false] recognize ANSI escape codes
+      # @comment @param ignore_newline [true, false] treat newlines as spaces
+      # @comment @yield [String, Integer] each line and its display width
+      # @comment @return [Enumerator, Object] enumerator or block result
       def each_line_with_size(
-        *text,
+        *str,
         limit: nil,
         bbcode: true,
         ansi: true,
         ignore_newline: false,
-        &block
+        &
       )
-        unless limit
-          snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
-          return block ? pairs(snippets, &block) : to_enum(:pairs, snippets)
-        end
-        limit = limit.to_i
-        raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
-        snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
-        return lim_pairs(snippets, limit, &block) if block
-        to_enum(:lim_pairs, snippets, limit)
+        warn(
+          '[DEPRECATED] `each_line_with_size` is deprecated ' \
+            '– use `.lines_width_size.each` instead',
+          category: :deprecated,
+          uplevel: 1
+        )
+
+        lines_with_size(
+          *str,
+          bbcode:,
+          ansi:,
+          spaces: true,
+          eol: !ignore_newline,
+          width: limit
+        ).each(&)
       end
       alias each_with_size each_line_with_size
 
-      # Returns maximal width of a line of given text.
+      # Calculate the maximum display width of any line.
       #
-      # @param (see each_line)
-      # @return [Integer] width
-      def max_line_width(*text, ignore_newline: false)
-        return 0 if text.empty?
-        ret = 0
-        pairs(as_snippets(text, false, false, ignore_newline, Word)) do |_l, w|
-          ret = w if w > ret
+      # @example
+      #   Terminal::Text.max_line_width("short\na longer line")
+      #   # => 13
+      #
+      # @param (see Formatter#initialize)
+      # @return (see Formatter#max_line_width)
+      def max_line_width(
+        *str,
+        ansi: true,
+        bbcode: true,
+        spaces: true,
+        eol: true,
+        **opts
+      )
+        # backward compatibility:
+        if opts.key?(:ignore_newline)
+          eol = opts[:ignore_newline] ? false : true
+          warn(
+            "Parameter ':ignore_newline' will become obsolete - " \
+              "use 'eol: #{eol.inspect}' instead",
+            category: :deprecated
+          )
         end
-        ret
-      end
 
-      private
+        Formatter.new(*str, bbcode:, ansi:, spaces:, eol:).max_line_width
+      end
 
+      # @private
       def char_width(char)
         ord = char.ord
         return @ctrlchar_width[ord] if ord < 0x20
         if char.size == 1
-          return 1 if ord < 0xa1
-          width = CharWidth[ord]
-          return width < 0 ? @ambiguous_char_width : width
+          return ord < 0xa1 ? 1 : CharWidth[ord] || @ambiguous_char_width
         end
         sum = 0
         zwj = false
@@ -137,346 +215,13 @@ module Terminal
           next zwj = false if zwj
           ord = c.ord
           next zwj = true if ord == 0x200d # zero with joiner
-          width = CharWidth[ord]
-          sum += (width < 0 ? @ambiguous_char_width : width)
+          sum += CharWidth[ord] || @ambiguous_char_width
         end
         sum
       end
-
-      def lim_pairs(snippets, limit)
-        line = @empty.dup
-        size = 0
-        csi = nil
-        snippets.each do |snippet|
-          if snippet == :space
-            next if size == 0
-            next line << ' ' if (size += 1) <= limit
-            yield(line, size - 1)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :nl
-            line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :hard_nl
-            line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = @empty.dup
-            csi = nil
-            next size = 0
-          end
-
-          if snippet == CsiEnd
-            line << CsiEnd if csi
-            next csi = nil
-          end
-
-          next line << (csi = snippet) if Csi === snippet
-          next line << snippet if Osc === snippet
-
-          # Word:
-
-          if (ns = size + snippet.size) <= limit
-            line << snippet
-            next size = ns
-          end
-
-          if line[-1] == ' '
-            line.chop!
-            size -= 1
-          end
-          yield(line, size) if size != 0
-
-          if snippet.size <= limit
-            line = "#{csi}#{snippet}"
-            next size = snippet.size
-          end
-
-          words = snippet.split(limit)
-          if words[-1].size <= limit
-            snippet = words.pop
-            line = "#{csi}#{snippet}"
-            size = snippet.size
-          else
-            line = "#{csi}"
-            size = 0
-          end
-          words.each { yield("#{csi}#{_1}", _1.size) }
-        end
-        nil
-      end
-
-      def pairs(snippets)
-        line = @empty.dup
-        size = 0
-        csi = nil
-        snippets.each do |snippet|
-          if snippet == :space
-            next if size == 0
-            line << ' '
-            next size += 1
-          end
-
-          if snippet == :nl
-            line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :hard_nl
-            line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
-            line = @empty.dup
-            csi = nil
-            next size = 0
-          end
-
-          if snippet == CsiEnd
-            line << CsiEnd if csi
-            next csi = nil
-          end
-
-          next line << (csi = snippet) if Csi === snippet
-          next line << snippet if Osc === snippet
-
-          # Word:
-          size += snippet.size
-          line << snippet
-        end
-        nil
-      end
-
-      def lim_lines(snippets, limit)
-        line = @empty.dup
-        size = 0
-        csi = nil
-        snippets.each do |snippet|
-          if snippet == :space
-            next if size == 0
-            next line << ' ' if (size += 1) <= limit
-            yield(line)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :nl
-            yield(line[-1] == ' ' ? line.chop : line)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :hard_nl
-            yield(line[-1] == ' ' ? line.chop : line)
-            line = @empty.dup
-            csi = nil
-            next size = 0
-          end
-
-          if snippet == CsiEnd
-            line << CsiEnd if csi
-            next csi = nil
-          end
-
-          next line << (csi = snippet) if Csi === snippet
-          next line << snippet if Osc === snippet
-
-          # Word:
-
-          if (ns = size + snippet.size) <= limit
-            line << snippet
-            next size = ns
-          end
-
-          if line[-1] == ' '
-            line.chop!
-            size -= 1
-          end
-          yield(line) if size != 0
-
-          if snippet.size <= limit
-            line = "#{csi}#{snippet}"
-            next size = snippet.size
-          end
-
-          words = snippet.split(limit)
-          if words[-1].size <= limit
-            snippet = words.pop
-            line = "#{csi}#{snippet}"
-            size = snippet.size
-          else
-            line = "#{csi}"
-            size = 0
-          end
-          words.each { yield("#{csi}#{_1}") }
-        end
-        nil
-      end
-
-      def lines(snippets)
-        line = @empty.dup
-        size = 0
-        csi = nil
-        snippets.each do |snippet|
-          if snippet == :space
-            next if size == 0
-            line << ' '
-            next size += 1
-          end
-
-          if snippet == :nl
-            yield(line[-1] == ' ' ? line.chop : line)
-            line = "#{csi}"
-            next size = 0
-          end
-
-          if snippet == :hard_nl
-            yield(line[-1] == ' ' ? line.chop : line)
-            line = @empty.dup
-            csi = nil
-            next size = 0
-          end
-
-          if snippet == CsiEnd
-            line << CsiEnd if csi
-            next csi = nil
-          end
-
-          next line << (csi = snippet) if Csi === snippet
-          next line << snippet if Osc === snippet
-
-          # Word:
-          size += snippet.size
-          line << snippet
-        end
-        nil
-      end
-
-      def as_snippets(text, bbcode, ansi, ignore_newline, word_class)
-        ret = []
-        last = nil
-        to_s = bbcode ? ->(s) { Ansi.bbcode(s) } : :to_s.to_proc
-        text.each do |txt|
-          if (txt = to_s[txt]).empty?
-            next ret[-1] = last = :hard_nl if Symbol === last
-            next ret << (last = :hard_nl)
-          end
-
-          txt = txt.encode(@encoding) if txt.encoding != @encoding
-
-          txt.scan(@scan_snippet) do |nl, csi, osc, space, gc|
-            if gc
-              next last.add(gc, char_width(gc)) if word_class === last
-              next ret << (last = word_class.new(gc, char_width(gc)))
-            end
-
-            next Symbol === last ? nil : ret << (last = :space) if space
-
-            if nl
-              if ignore_newline # handle nl like space
-                next Symbol === last ? nil : ret << (last = :space)
-              end
-              next last == :space ? ret[-1] = last = :nl : ret << (last = :nl)
-            end
-
-            next unless ansi
-
-            next ret << (last = Osc.new(osc)) if osc
-
-            if csi == "\e[m" || csi == "\e[0m"
-              next last == CsiEnd ? nil : ret << (last = CsiEnd)
-            end
-
-            Csi === last ? last.add(csi) : ret << (last = Csi.new(csi))
-          end
-
-          Symbol === last ? ret[-1] = last = :hard_nl : ret << (last = :hard_nl)
-        end
-        ret
-      end
-    end
-
-    class Osc
-      attr_reader :to_str, :size
-      alias to_s to_str
-
-      def initialize(str)
-        @to_str = str
-        @size = 0
-      end
-    end
-
-    class Csi < Osc
-      def add(str) = (@to_str << str)
-    end
-
-    module CsiEnd
-      class << self
-        attr_reader :to_str, :size
-      end
-      @to_str = "\e[m"
-      @size = 0
-    end
-
-    class Word
-      attr_reader :to_str, :size
-      alias to_s to_str
-
-      def initialize(char, size)
-        @to_str = char.dup
-        @size = size
-      end
-
-      def add(char, size)
-        @to_str << char
-        @size += size
-      end
-    end
-
-    class WordEx < Word
-      attr_reader :chars
-
-      def initialize(char, size)
-        super
-        @chars = [[char, size]]
-      end
-
-      def add(char, size)
-        @chars << [char, size]
-        super
-      end
-
-      def split(limit)
-        chars = @chars.dup
-        ret = [last = Word.new(*chars.shift)]
-        chars.each do |c, s|
-          next ret << (last = Word.new(c, s)) if last.size + s > limit
-          last.add(c, s)
-        end
-        ret
-      end
     end
 
     @ambiguous_char_width = 1
-    @empty = String.new(encoding: @encoding = Encoding::UTF_8).freeze
-
-    @scan_snippet =
-      /\G(?:
-        (\r?\n)
-        | (\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
-        | (\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
-        | (\s+)
-        | (\X)
-      )/x
-
-    @scan_width =
-      /\G(?:
-        (?:\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
-        | (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
-        | (\s+)
-        | (\X)
-      )/x
 
     @ctrlchar_width =
       Hash
@@ -521,7 +266,6 @@ module Terminal
     cw_file = "#{__dir__}/text/char_width.rb"
     autoload :CharWidth, cw_file
     autoload :UNICODE_VERSION, cw_file
-
-    private_constant :Osc, :Csi, :CsiEnd, :Word, :WordEx, :CharWidth
+    private_constant :CharWidth
   end
 end

data/lib/terminal/version.rb

@@ -2,5 +2,5 @@
 
 module Terminal
   # The version number of the gem.
-  VERSION = '0.19.0'
+  VERSION = '1.0.3'
 end