terminal_rb 0.6.0

data/lib/terminal/text.rb

@@ -0,0 +1,542 @@
+# frozen_string_literal: true
+
+require_relative 'ansi'
+
+module Terminal
+  module Text
+    class << self
+      # Value for {width} of letters whose display width is not precisely
+      # defined by the Unicode standard.
+      # Defaults to one (1).
+      #
+      # @see .width
+      #
+      # @return [Integer] value
+      attr_accessor :ambiguous_char_width
+
+      # Calculates the display width of the text representation of a given
+      # argument.
+      # It can optionally ignore embedded BBCode.
+      #
+      # 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.
+      #
+      # @param [#to_s] str object to process
+      # @param [true|false] bbcode whether to interpret embedded BBCode
+      # @return [Integer] display width
+      def width(str, bbcode: true)
+        str = bbcode ? Ansi.unbbcode(str) : str.to_s
+        return 0 if str.empty?
+        str = str.encode(ENC) if str.encoding != ENC
+        width = 0
+        str.scan(WIDTH_SCANNER) do |sp, gc|
+          next width += __char_width(gc) if gc
+          width += 1 if sp
+        end
+        width
+      end
+
+      # Report each line of the text.
+      #
+      # @param (see Wrap#initialize)
+      # @param (see Wrap#each_line)
+      # @yield (see Wrap#each_line)
+      # @return (see Wrap#each_line)
+      # @raise (see Wrap#each_line)
+      def each_line(
+        *text,
+        bbcode: true,
+        ansi: true,
+        ignore_newline: false,
+        limit: nil,
+        with_size: false,
+        &block
+      )
+        Wrap.new(
+          *text,
+          bbcode: bbcode,
+          ansi: ansi,
+          ignore_newline: ignore_newline
+        ).each_line(limit: limit, with_size: with_size, &block)
+      end
+
+      # @!visibility private
+      # works for UTF-8 chars only!
+      def __char_width(char)
+        ord = char.ord
+        return CONTROL_CHAR_WIDTH[ord] || 2 if ord < 0x20
+        return 1 if ord < 0xa1
+        return @ambiguous_char_width if (size = CharWidth[ord]) == -1
+        return size if size != 1 || char.size < 2
+        sco = char[1].ord
+        # Halfwidth Dakuten Handakuten
+        sco == 0xff9e || sco == 0xff9f ? 2 : 1
+      end
+    end
+
+    # Helper class to calculate word-wise text wrapping in various conditions.
+    # Internally used by {Text.each_line}.
+    class Wrap
+      # Create a new instance which may support different conditions.
+      #
+      # @param [#to_s, ...] text
+      #   text objects to process
+      # @param [true, false] bbcode
+      #   whether to interprete embedded BBCode (see {Ansi.bbcode})
+      # @param [true, false] ansi
+      #   whether to keep embedded ANSI control codes
+      # @param [true, false] ignore_newline
+      #   wheter to ignore embedded line breaks (`"\r\n"` or `"\n"`)
+      def initialize(*text, bbcode: true, ansi: true, ignore_newline: false)
+        @parts = []
+        newline = ignore_newline ? :space : :nl
+        text.each do |txt|
+          txt = bbcode ? Ansi.bbcode(txt) : txt.to_s
+          next @parts << :hard_nl if txt.empty?
+          txt = txt.encode(ENC) if txt.encoding != ENC
+          word = nil
+          txt.scan(REGEXP) do |nl, csi, osc, space, gc|
+            next word ? word << gc : @parts << (word = Word.new(gc)) if gc
+            word = nil
+            next @parts << :space if space
+            next @parts << newline if nl
+            next unless ansi
+            next @parts << [:seq, osc] if osc
+            next @parts << :seq_end if csi == "\e[m" || csi == "\e[0m"
+            @parts << [:seq, csi]
+          end
+          @parts << :hard_nl
+        end
+      end
+
+      # Report each line of the text.
+      #
+      # @param [#to_i, nil] limit
+      #   optionally limit line size
+      # @param [true, false] with_size
+      #   whether to yield each line with it's display width
+      # @yield [String] line when `with_size` is false
+      # @yield [<String, Integer>] line and it's display width
+      #   when `with_size` is true
+      # @return [Enumerator] when no block is given
+      # @return [nil] when block is given
+      # @raise ArgumentError when a `limit` less than `1` is given
+      def each_line(limit: nil, with_size: false, &block)
+        unless limit
+          return with_size ? pairs(&block) : lines(&block) if block_given?
+          return to_enum(with_size ? :pairs : :lines)
+        end
+        limit = limit.to_i
+        raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
+        if block_given?
+          return with_size ? pairs_in(limit, &block) : lines_in(limit, &block)
+        end
+        to_enum(with_size ? :pairs_in : :lines_in, limit)
+      end
+      alias each each_line
+
+      # @!visibility private
+      def each_word(with_size: false, &block)
+        return with_size ? word_pairs(&block) : words(&block) if block_given?
+        to_enum(with_size ? :word_pairs : :words)
+      end
+
+      # @!visibility private
+      def to_str
+        str = EMPTY.dup
+        seq = EMPTY.dup
+        @parts.each do |part, opt|
+          next str << part if part.is_a?(Word)
+          next str << ' ' if part == :space
+
+          if part == :nl
+            str << "\n"
+            next str << seq.dup
+          end
+
+          if part == :seq
+            str << opt
+            next seq << opt
+          end
+
+          # :seq_end
+          next if seq.empty?
+          str << "\e[m"
+          seq.clear
+        end
+        str
+      end
+      alias to_s to_str
+
+      # @!visibility private
+      def to_a(limit: nil, with_size: false)
+        each_line(limit: limit, with_size: with_size).to_a
+      end
+
+      # @!visibility private
+      def to_ary = each_line.to_a
+
+      private
+
+      def words
+        @parts.each { yield(_1.to_s) if _1.is_a?(Word) }
+        nil
+      end
+
+      def word_pairs
+        @parts.each { yield(_1.to_s, _1.size) if _1.is_a?(Word) }
+        nil
+      end
+
+      def lines
+        current = EMPTY.dup
+        seq = EMPTY.dup
+        lws = nil
+        @parts.each do |part, opt|
+          if part == :space
+            next if lws
+            current << ' '
+            next lws = true
+          end
+
+          if part.is_a?(Word)
+            current << part
+            next lws = false
+          end
+
+          if part == :nl
+            yield(lws ? current.chop : current)
+            current = seq.dup
+            next lws = false
+          end
+
+          if part == :hard_nl
+            yield(lws ? current.chop : current)
+            seq.clear
+            current = EMPTY.dup
+            next lws = false
+          end
+
+          lws = false
+
+          if part == :seq
+            current << opt
+            next seq << opt
+          end
+
+          # :seq_end
+          current << "\e[m"
+          seq.clear
+        end
+        nil
+      end
+
+      def lines_in(limit)
+        current = EMPTY.dup
+        seq = EMPTY.dup
+        width = 0
+        lws = nil
+        @parts.each do |part, opt|
+          if part == :space
+            next if lws
+            if width.succ < limit
+              current << ' '
+              width += 1
+              next lws = true
+            end
+            yield(current)
+            current = seq.dup
+            width = 0
+            next lws = false
+          end
+
+          if part.is_a?(Word)
+            if (nw = width + part.size) <= limit
+              current << part
+              width = nw
+              next lws = false
+            end
+
+            yield(lws ? current.chop : current) if width > 0
+            current = seq.dup
+
+            if part.size < limit
+              current << part
+              width = part.size
+              next lws = false
+            end
+
+            if part.size == limit
+              yield(current + part)
+              current = seq.dup
+              width = 0
+              next lws = false
+            end
+
+            width = 0
+            part.chars.each do |c, w|
+              next current << c if (width += w) <= limit
+              yield(current)
+              current = seq.dup << c
+              width = w
+            end
+
+            next lws = false
+          end
+
+          if part == :nl
+            yield(lws ? current.chop : current)
+            current = seq.dup
+            width = 0
+            next lws = false
+          end
+
+          if part == :hard_nl
+            yield(lws ? current.chop : current) if width > 0
+            seq.clear
+            current = EMPTY.dup
+            width = 0
+            next lws = false
+          end
+
+          lws = false
+
+          if part == :seq
+            current << opt
+            next seq << opt
+          end
+
+          # :seq_end
+          next if seq.empty?
+          current << "\e[m"
+          seq.clear
+        end
+        nil
+      end
+
+      def pairs
+        current = EMPTY.dup
+        seq = EMPTY.dup
+        width = 0
+        lws = nil
+        @parts.each do |part, opt|
+          if part == :space
+            next if lws
+            current << ' '
+            width += 1
+            next lws = true
+          end
+
+          if part.is_a?(Word)
+            current << part
+            width += part.size
+            next lws = false
+          end
+
+          if part == :nl
+            lws ? yield(current.chop, width - 1) : yield(current, width)
+            current = seq.dup
+            width = 0
+            next lws = false
+          end
+
+          if part == :hard_nl
+            lws ? yield(current.chop, width - 1) : yield(current, width)
+            seq.clear
+            current = EMPTY.dup
+            width = 0
+            next lws = false
+          end
+
+          lws = false
+
+          if part == :seq
+            current << opt
+            next seq << opt
+          end
+
+          # :seq_end
+          next if seq.empty?
+          current << "\e[m"
+          seq.clear
+        end
+        nil
+      end
+
+      def pairs_in(limit)
+        current = EMPTY.dup
+        seq = EMPTY.dup
+        width = 0
+        lws = nil
+        @parts.each do |part, opt|
+          if part == :space
+            next if lws
+            if width.succ < limit
+              current << ' '
+              width += 1
+              next lws = true
+            end
+            yield(current, width)
+            current = seq.dup
+            width = 0
+            next lws = false
+          end
+
+          if part.is_a?(Word)
+            if (nw = width + part.size) <= limit
+              current << part
+              width = nw
+              next lws = false
+            end
+
+            if width > 0
+              lws ? yield(current.chop, width - 1) : yield(current, width)
+            end
+            current = seq.dup
+
+            if part.size < limit
+              current << part
+              width = part.size
+              next lws = false
+            end
+
+            if part.size == limit
+              yield(current + part, limit)
+              current = seq.dup
+              width = 0
+              next lws = false
+            end
+
+            width = 0
+            part.chars.each do |c, w|
+              next current << c if (width += w) <= limit
+              yield(current, width - w)
+              current = seq.dup << c
+              width = w
+            end
+
+            next lws = false
+          end
+
+          if part == :nl
+            lws ? yield(current.chop, width - 1) : yield(current, width)
+            current = seq.dup
+            width = 0
+            next lws = false
+          end
+
+          if part == :hard_nl
+            if width > 0
+              lws ? yield(current.chop, width - 1) : yield(current, width)
+            end
+            seq.clear
+            current = EMPTY.dup
+            width = 0
+            next lws = false
+          end
+
+          lws = false
+
+          if part == :seq
+            current << opt
+            next seq << opt
+          end
+
+          # :seq_end
+          next if seq.empty?
+          current << "\e[m"
+          seq.clear
+        end
+        nil
+      end
+
+      class Word
+        attr_reader :to_str, :size, :chars
+
+        def initialize(char)
+          @to_str = char.dup
+          @size = Text.__char_width(char)
+          @chars = [[char, @size]]
+        end
+
+        def <<(char)
+          @to_str << char
+          @chars << [char, cw = Text.__char_width(char)]
+          @size += cw
+          self
+        end
+      end
+      private_constant :Word
+
+      REGEXP =
+        /\G(?:
+          (\r?\n)
+          | (\e\[[\d;:\?]*[ABCDEFGHJKSTfminsuhl])
+          | (\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
+          | (\s+)
+          | (\X)
+        )/x
+      private_constant :REGEXP
+
+      ENC = Encoding::UTF_8
+      private_constant :ENC
+
+      EMPTY = String.new(encoding: ENC).freeze
+      private_constant :EMPTY
+    end
+
+    ENC = Encoding::UTF_8
+    private_constant :ENC
+
+    @ambiguous_char_width = 1
+
+    WIDTH_SCANNER =
+      /\G(?:
+        (?:\e\[[\d;:\?]*[ABCDEFGHJKSTfminsuhl])
+        | (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
+        | (\s+)
+        | (\X)
+      )/x
+    private_constant :WIDTH_SCANNER
+
+    CONTROL_CHAR_WIDTH = {
+      0x00 => 0,
+      0x01 => 1,
+      0x02 => 1,
+      0x03 => 1,
+      0x04 => 1,
+      0x05 => 0,
+      0x06 => 1,
+      0x07 => 0,
+      0x08 => 0,
+      0x09 => 8,
+      0x0a => 0,
+      0x0b => 0,
+      0x0c => 0,
+      0x0d => 0,
+      0x0e => 0,
+      0x0f => 0,
+      0x10 => 1,
+      0x11 => 1,
+      0x12 => 1,
+      0x13 => 1,
+      0x14 => 1,
+      0x15 => 1,
+      0x16 => 1,
+      0x17 => 1,
+      0x18 => 1,
+      0x19 => 1,
+      0x1a => 1,
+      0x1b => 1,
+      0x1c => 1,
+      0x1d => 1,
+      0x1e => 1,
+      0x1f => 1
+    }.compare_by_identity.freeze
+    private_constant :CONTROL_CHAR_WIDTH
+
+    autoload :CharWidth, "#{__dir__}/text/char_width.rb"
+    private_constant :CharWidth
+  end
+end

data/lib/terminal/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Terminal
+  # The version number of the gem.
+  VERSION = '0.6.0'
+end