terminal_rb 0.20.0 → 1.0.3

data/lib/terminal/text/formatter.rb

@@ -0,0 +1,619 @@
+# frozen_string_literal: true
+
+module Terminal
+  module Text
+    # Processes text with BBCode markup and ANSI escape codes into
+    # display-width-aware lines. Supports Unicode-aware word-wrapping,
+    # alignment, padding, and prefix/suffix decorations.
+    #
+    # @see Terminal::Text
+    #
+    # @example Basic word-wrapping
+    #   fmt = Terminal::Text::Formatter.new('Hello World, this is a test')
+    #   fmt.lines(width: 12)
+    #   # => ["Hello World,", "this is a", "test"]
+    #
+    # @example Formatted output with alignment
+    #   Terminal::Text::Formatter.format(
+    #     'Hello', align: :center, width: 20
+    #   )
+    #   # => ["       Hello        "]
+    class Formatter
+      # Parse text into lines, optionally with display widths.
+      #
+      # @see #lines
+      # @see #lines_with_size
+      #
+      # @example
+      #   Terminal::Text::Formatter['Hello World', width: 5]
+      #   # => ["Hello", "World"]
+      # @example With size information
+      #   Terminal::Text::Formatter['Hello', with_size: true]
+      #   # => [["Hello", 5]]
+      #
+      # @param (see #initialize)
+      # @param with_size [true, false] when +true+,
+      #   return +[line, width]+ pairs instead of plain strings
+      # @param (see #lines_with_size)
+      # @return (see #lines_with_size)
+      def self.[](
+        *str,
+        with_size: false,
+        ansi: true,
+        bbcode: true,
+        spaces: true,
+        eol: true,
+        width: nil
+      )
+        ret = new(*str, ansi:, bbcode:, spaces:, eol:).lines_with_size(width:)
+        with_size ? ret : ret.map(&:first)
+      end
+
+      # Format text with alignment, padding, and decorations.
+      #
+      # @see #format
+      #
+      # @param (see #initialize)
+      # @param (see #format)
+      # @result (see #format)
+      # @raise (see #format)
+      def self.format(
+        *str,
+        ansi: true,
+        bbcode: true,
+        spaces: true,
+        eol: true,
+        align: nil,
+        width: nil,
+        height: nil,
+        padding: nil,
+        prefix: nil,
+        suffix: nil
+      )
+        new(*str, ansi:, bbcode:, spaces:, eol:).format(
+          align:,
+          width:,
+          height:,
+          padding:,
+          prefix:,
+          suffix:
+        )
+      end
+
+      # Create a new formatter by tokenizing the given text.
+      #
+      # @param str [Array<#to_s>] text to process
+      # @param ansi [true, false] recognize ANSI escape codes
+      # @param bbcode [true, false] process BBCode markup
+      # @param spaces [true, false] preserve whitespace;
+      #   when +false+ leading/trailing spaces and multiple spaces are
+      #   collapsed
+      # @param eol [true, false] preserve line endings;
+      #   when +false+ newlines are treated as spaces
+      def initialize(*str, ansi: true, bbcode: true, spaces: true, eol: true)
+        @lex = []
+        return if str.empty?
+        ansi ? _generate_ansi(str, bbcode) : _generate(str, bbcode)
+        return if @lex.empty?
+        @lex = _ignore_whitespace unless spaces
+        @lex = _ignore_newline unless eol
+      end
+
+      # Word-wrap and return lines with their display widths.
+      #
+      # @example
+      #   fmt = Terminal::Text::Formatter.new('Hello World')
+      #   fmt.lines_with_size(width: 5)
+      #   # => [["Hello", 5], ["World", 5]]
+      #
+      # @param width [Integer, nil] maximum line width in columns;
+      #   +nil+ returns unwrapped lines
+      # @return [Array<String, Integer>] pairs of
+      #   +[line_text, display_width]+
+      # @raise (see #format)
+      def lines_with_size(width: nil)
+        return [] if @lex.empty?
+        return @unlimited || _unlimited unless width
+        (w = width.to_i) > 0 and return _limited(w)
+        raise(ArgumentError, "invalid width - #{width.inspect}")
+      end
+
+      # Word-wrap and return lines as strings.
+      #
+      # @example
+      #   fmt = Terminal::Text::Formatter.new('Hello World')
+      #   fmt.lines(width: 5)
+      #   # => ["Hello", "World"]
+      #
+      # @param width [Integer, nil] maximum line width in columns
+      # @return [Array<String>]
+      # @raise [ArgumentError] if +width+ is zero or negative
+      def lines(width: nil) = lines_with_size(width:).map(&:first)
+
+      # Format lines with alignment, padding, and decorations.
+      #
+      # @example Centered text with padding
+      #   fmt = Terminal::Text::Formatter.new('Hi')
+      #   fmt.format(align: :center, width: 10, padding: [0, 1])
+      #   # => [" Hi         "]
+      #
+      # @param align [Symbol, nil] text alignment:
+      #   +:left+, +:right+, +:center+, or +nil+ (no fill)
+      # @param width [Integer, nil] output line width in columns
+      # @param height [Integer, nil] number of output lines;
+      #   negative values take lines from the end
+      # @param padding [Integer, Array, nil] CSS-style padding
+      #    - 1 value: all sides;
+      #    - 2 values: [vertical, horizontal];
+      #    - 3 values: [top, horizontal, bottom];
+      #    - 4 values: [top, right, bottom, left]
+      # @param prefix [#to_s, nil] string prepended to each line
+      # @param suffix [#to_s, nil] string appended to each line
+      # @return [Array<String>] formatted output lines
+      # @raise [ArgumentError] if +width+ is zero or negative
+      def format(
+        align: nil,
+        width: nil,
+        height: nil,
+        padding: nil,
+        prefix: nil,
+        suffix: nil
+      )
+        top, right, bottom, left = _padding(padding)
+
+        if height
+          return [] if (height = height.to_i) == 0
+          if height < 0
+            tail = true
+            height = -height
+          end
+          height -= top
+          height -= -bottom
+          return [] if height < 1
+        end
+
+        if width
+          w = (width = width.to_i) - left - right
+          raise(ArgumentError, "invalid width - #{width.inspect}") if w < 1
+          lws = _limited(w)
+          lws = tail ? lws.last(height) : lws.take(height) if height
+          empty = "#{prefix}#{' ' * width}#{suffix}" if top + bottom > 0
+        else
+          lws = @unlimited || _unlimited
+          lws = tail ? lws.last(height) : lws.take(height) if height
+          w = lws.empty? ? 0 : lws.max_by(&:last)[-1]
+          if top + bottom > 0
+            empty = "#{prefix}#{' ' * (w + left + right)}#{suffix}"
+          end
+        end
+
+        ret = []
+        ret.fill(empty, 0, top) if top > 0
+        left = left < 1 ? prefix.to_s : "#{prefix}#{' ' * left}"
+        right = right < 1 ? suffix.to_s : "#{' ' * right}#{suffix}"
+
+        space = SPACE_CACHE.dup
+
+        case align
+        when :left
+          lws.each { |l, s| ret << "#{left}#{l}#{space[w - s]}#{right}" }
+        when :right
+          lws.each { |l, s| ret << "#{left}#{space[w - s]}#{l}#{right}" }
+        when :center
+          lws.each do |l, s|
+            ls = (s = w - s) / 2
+            next ret << "#{left}#{l}#{right}" if ls < 1
+            ret << "#{left}#{space[ls]}#{l}#{space[s - ls]}#{right}"
+          end
+        else
+          lws.each { |l, _| ret << "#{left}#{l}#{right}" }
+        end
+
+        return ret.fill(empty, ret.size, bottom) if bottom > 0
+        ret.empty? ? ret << '' : ret
+      end
+
+      # Whether the formatter has any content.
+      #
+      # @return [true, false]
+      def empty? = @lex.empty?
+
+      # Maximum display width of any line.
+      #
+      # @example
+      #   fmt = Terminal::Text::Formatter.new("short\na longer line")
+      #   fmt.max_line_width # => 13
+      #
+      # @return [Integer] widest line in columns, +0+ when empty
+      def max_line_width
+        @max_line_width ||=
+          (@lex.empty? ? 0 : (@unlimited || _unlimited).max_by(&:last)[-1])
+      end
+
+      # @private
+      # Convert to a single string with lines joined by newlines.
+      #
+      # @example
+      #   Terminal::Text::Formatter.new('Hello World').to_s(width: 5)
+      #   # => "Hello\nWorld"
+      #
+      # @param width [Integer, nil] maximum line width in columns
+      # @return [String]
+      def to_s(width: nil) = lines(width:).join("\n")
+
+      private
+
+      def _padding(value)
+        return Array.new(4, [0, value.to_i].max) unless value.respond_to?(:to_a)
+        value = value.to_a.take(4).map! { [0, it.to_i].max }
+        case value.size
+        when 0
+          value.fill(0, 0, 4)
+        when 1
+          value.fill(value[0], 0, 4)
+        when 2
+          value * 2
+        when 3
+          value << value[1]
+        else
+          value
+        end
+      end
+
+      def _limited(width)
+        ret = []
+        line = []
+        csi = []
+        size = 0
+
+        add_line = -> do
+          if size == 0 # Osc, Csi, CsiEnd only
+            ret << [+'', 0]
+            next line = [], size = 0
+          end
+
+          if csi.empty?
+            ret << [line.join, size]
+            next line = [], size = 0
+          end
+
+          if csi.size == 1 && line[-1].is_a?(Csi) # Csi at end
+            line.pop
+            ret << [line.join, size]
+            next line = [], size = 0
+          end
+
+          line << CsiEnd if line[-1] != CsiEnd
+          ret << [line.join, size]
+          line = csi.dup
+          size = 0
+        end
+
+        @lex.each do |current|
+          if current.is_a?(NewLine)
+            if (last = line[-1]).is_a?(Space) # ignore trailing space
+              line.pop
+              size -= last.size
+            end
+            add_line.call # if size > 0
+            next
+          end
+
+          # ignore leading space:
+          next if line.empty? && current.is_a?(Space) && current.size == 1
+
+          ns = size + current.size
+
+          # fits in width:
+          if ns < width
+            if current == CsiEnd
+              next if csi.empty? # useless
+
+              if csi.size == 1 && line[-1].is_a?(Csi) # Csi at end
+                line.pop
+              else
+                line << CsiEnd
+              end
+
+              next csi = []
+            end
+
+            csi << current if current.is_a?(Csi)
+            next line << current, size = ns
+          end
+
+          # fill-up the line:
+          if ns == width
+            # ignore trailing space:
+            next add_line.call if current.is_a?(Space)
+            line << current
+            size = width
+            next add_line.call
+          end
+
+          # exceeding the width:
+
+          # force flush:
+          if (last = line[-1]).is_a?(Space) # ignore trailing space
+            line.pop
+            size -= last.size
+          end
+          add_line.call if size > 0
+
+          next if current.is_a?(Space) # ignore trailing space
+
+          # handle Word...
+          splitted = current.split(width)
+          last = splitted.pop
+
+          if csi.empty?
+            splitted.each { ret << [it.to_str, it.size] }
+          else
+            csi_str = csi.join
+            splitted.each { ret << ["#{csi_str}#{it.to_str}\e[m", it.size] }
+          end
+
+          line = csi.dup
+          next size = 0 unless last
+          line << last
+          size = last.size
+        end
+
+        ret.pop if ret[-1] == ['', 0]
+        ret
+      end
+
+      def _unlimited
+        @unlimited = []
+        line = []
+        @lex.each do |current|
+          next line << current unless current.is_a?(NewLine)
+          @unlimited << [line.join.freeze, line.sum(&:size)]
+          line = []
+        end
+        @unlimited << [line.join.freeze, line.sum(&:size)] unless line.empty?
+        @unlimited.freeze
+      end
+
+      def _generate(text, bbcode)
+        bbcode = bbcode ? ->(s) { Ansi.unbbcode(s) } : :to_s.to_proc
+
+        text.each do |line|
+          next @lex << EOP if (line = bbcode[line]).empty?
+
+          line.encode!(ENCODING) if line.encoding != ENCODING
+
+          line.scan(SCAN_REGEX) do |newline, space, _, _, char|
+            if char
+              (last = @lex[-1]).is_a?(Word) and next last.add(char)
+              next @lex << Word.new(char)
+            end
+
+            if space
+              (last = @lex[-1]).is_a?(Space) and next last.inc
+              next @lex << Space.new
+            end
+
+            next @lex << EOL if newline
+          end
+
+          @lex[-1] == EOL ? @lex[-1] = EOP : @lex << EOP
+        end
+
+        nil
+      end
+
+      def _generate_ansi(text, bbcode)
+        bbcode = bbcode ? ->(s) { Ansi.bbcode(s) } : :to_s.to_proc
+
+        text.each do |line|
+          next @lex << EOP if (line = bbcode[line]).empty?
+
+          line.encode!(ENCODING) if line.encoding != ENCODING
+          csis = 0
+
+          line.scan(SCAN_REGEX) do |newline, space, csi, osc, char|
+            if char
+              (last = @lex[-1]).is_a?(Word) and next last.add(char)
+              next @lex << Word.new(char)
+            end
+
+            if space
+              (last = @lex[-1]).is_a?(Space) and next last.inc
+              next @lex << Space.new
+            end
+
+            next @lex << EOL if newline
+
+            next @lex << Osc.new(osc) if osc
+
+            # Handle csi...
+            if csi == "\e[m" || csi == "\e[0m"
+              next if csis == 0
+
+              if @lex[-1].is_a?(Csi)
+                @lex.pop
+                next csis = 0 if csis == 1
+              end
+
+              csis = 0
+              next @lex << CsiEnd
+            end
+
+            (last = @lex[-1]).is_a?(Csi) and next last.add(csi)
+
+            csis += 1
+            @lex << Csi.new(csi)
+          end
+
+          if (last = @lex[-1]) == EOL
+            @lex.pop
+            @lex << CsiEnd if csis != 0
+            next @lex << EOP
+          end
+
+          next @lex << EOP if csis == 0
+
+          if last.is_a?(Csi)
+            @lex.pop
+            @lex << CsiEnd if csis > 1
+          else
+            @lex << CsiEnd
+          end
+          @lex << EOP
+        end
+
+        nil
+      end
+
+      def _ignore_whitespace
+        ret = []
+        last = nil
+        space = Space.new.freeze
+
+        @lex.each do |current|
+          if current.is_a?(Space)
+            next if last.nil? || last.is_a?(NewLine) # skip leading space
+            next ret << (last = space)
+          end
+
+          if current.is_a?(NewLine) # remove trailing space
+            if last == space
+              ret.pop
+            elsif last == CsiEnd && ret[-2] == space
+              ret.delete_at(-2)
+            end
+          end
+
+          ret << (last = current)
+        end
+
+        ret
+      end
+
+      def _ignore_newline
+        last = nil
+
+        @lex.filter_map do |current|
+          if current == EOL
+            next if last.nil? || last == EOP || last.is_a?(Space)
+            next last = Space.new
+          end
+
+          if current.is_a?(Space) && last.is_a?(Space)
+            last.size = last.size == 1 ? current.size : last.size + current.size
+            next
+          end
+
+          last = current
+        end
+      end
+
+      # @private
+      class Space
+        attr_accessor :size
+        def to_str = (' ' * @size)
+        def initialize = (@size = 1)
+        def inc = (@size += 1)
+        def inspect = @size == 1 ? '<Space>' : "<Space #{@size}>"
+      end
+
+      # @private
+      class Word
+        def to_str = (@to_str ||= @chars.join)
+        def size = (@size ||= @sizes.sum)
+        def inspect = "<Word #{@sizes.sum}:#{@chars.join.inspect}>"
+
+        def initialize(char, size = Text.char_width(char))
+          @chars = [char]
+          @sizes = [size]
+        end
+
+        def add(char, size = Text.char_width(char))
+          @chars << char
+          @sizes << size
+          nil
+        end
+
+        def split(width)
+          return [self] if @chars.size == 1
+          ret = last = size = nil
+          @chars.each_with_index do |char, idx|
+            csize = @sizes[idx]
+            next ret = [last = Word.new(char, size = csize)] unless ret
+            next last.add(char, csize) if (size += csize) <= width
+            ret << (last = Word.new(char, size = csize))
+          end
+          ret
+        end
+      end
+
+      # @private
+      class Osc
+        attr_reader :to_str
+        def size = 0
+        def initialize(str) = (@to_str = str)
+        def inspect = "<Osc #{@to_str.inspect}>"
+      end
+
+      # @private
+      class Csi
+        attr_reader :to_str
+        def size = 0
+        def initialize(str) = (@to_str = str)
+        def add(str) = (@to_str << str unless @to_str.include?(str))
+        def inspect = "<Csi #{@to_str.inspect}>"
+      end
+
+      # @private
+      module CsiEnd
+        class << self
+          attr_reader :to_str, :size, :inspect
+        end
+        @to_str = "\e[m"
+        @size = 0
+        @inspect = '<CsiEnd>'
+      end
+
+      # @private
+      class NewLine
+        attr_reader :inspect
+        def initialize(inspect) = (@inspect = inspect)
+      end
+
+      EOL = NewLine.new '<EOL>'
+      EOP = NewLine.new '<EOP>'
+
+      ENCODING = Encoding::UTF_8
+
+      SPACE_CACHE =
+        Hash
+          .new { |h, s| h[s] = s < 1 ? '' : ' ' * s }
+          .compare_by_identity
+          .freeze
+
+      SCAN_REGEX =
+        /\G(?:
+         (\r?\n)
+        | (\s)
+        | (\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
+        | (\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
+        | (\X)
+      )/x
+
+      private_constant(
+        :Space,
+        :Word,
+        :Osc,
+        :Csi,
+        :CsiEnd,
+        :NewLine,
+        :EOL,
+        :EOP,
+        :ENCODING,
+        :SPACE_CACHE,
+        :SCAN_REGEX
+      )
+    end
+  end
+end