terminal_rb 1.0.5 → 1.0.8

data/lib/terminal/text/formatter.rb

@@ -32,8 +32,8 @@ module Terminal
       #   # => [["Hello", 5]]
       #
       # @param (see #initialize)
-      # @param with_size [true, false] when +true+,
-      #   return +[line, width]+ pairs instead of plain strings
+      # @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.[](
@@ -86,17 +86,23 @@ module Terminal
       # @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
+      #   when `false` leading/trailing spaces and multiple spaces are
       #   collapsed
       # @param eol [true, false] preserve line endings;
-      #   when +false+ newlines are treated as spaces
+      #   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?
+        @keep_paragraph = true
         @lex = _ignore_whitespace unless spaces
-        @lex = _ignore_newline unless eol
+        case eol
+        when false, nil
+          @lex = _ignore_newline
+        when :no_paragraph
+          @keep_paragraph = false
+        end
       end
 
       # Word-wrap and return lines with their display widths.
@@ -106,10 +112,10 @@ module Terminal
       #   fmt.lines_with_size(width: 5)
       #   # => [["Hello", 5], ["World", 5]]
       #
-      # @param width [Integer, nil] maximum line width in columns;
-      #   +nil+ returns unwrapped lines
+      # @param width [#to_i, nil] maximum line width in columns;
+      #   `nil` returns unwrapped lines
       # @return [Array<String, Integer>] pairs of
-      #   +[line_text, display_width]+
+      #   `[line_text, display_width]`
       # @raise (see #format)
       def lines_with_size(width: nil)
         return [] if @lex.empty?
@@ -125,9 +131,9 @@ module Terminal
       #   fmt.lines(width: 5)
       #   # => ["Hello", "World"]
       #
-      # @param width [Integer, nil] maximum line width in columns
+      # @param width [#to_i, nil] maximum line width in columns
       # @return [Array<String>]
-      # @raise [ArgumentError] if +width+ is zero or negative
+      # @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.
@@ -138,11 +144,11 @@ module Terminal
       #   # => [" 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;
+      #   `:left`, `:right`, `:center`, or `nil` (no fill)
+      # @param width [#to_i, nil] output line width in columns
+      # @param height [#to_i, nil] number of output lines;
       #   negative values take lines from the end
-      # @param padding [Integer, Array, nil] CSS-style padding
+      # @param padding [#to_i, Array, nil] CSS-style padding
       #    - 1 value: all sides;
       #    - 2 values: [vertical, horizontal];
       #    - 3 values: [top, horizontal, bottom];
@@ -150,7 +156,7 @@ module Terminal
       # @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
+      # @raise [ArgumentError] if `width` is zero or negative
       def format(
         align: nil,
         width: nil,
@@ -226,7 +232,7 @@ module Terminal
       #   fmt = Terminal::Text::Formatter.new("short\na longer line")
       #   fmt.max_line_width # => 13
       #
-      # @return [Integer] widest line in columns, +0+ when empty
+      # @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])
@@ -239,7 +245,7 @@ module Terminal
       #   Terminal::Text::Formatter.new('Hello World').to_s(width: 5)
       #   # => "Hello\nWorld"
       #
-      # @param width [Integer, nil] maximum line width in columns
+      # @param width [#to_i, nil] maximum line width in columns
       # @return [String]
       def to_s(width: nil) = lines(width:).join("\n")
 
@@ -298,7 +304,7 @@ module Terminal
               size -= last.size
               next add_line.call
             end
-            add_line.call if size > 0
+            add_line.call if (current != EOP) || (@keep_paragraph || size > 0)
             next
           end
 
@@ -386,18 +392,41 @@ module Terminal
 
           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)
+          line.scan(SCAN_REGEX) do |token|
+            b = token.getbyte(0)
+
+            if b > 0x20 # word chunk: an ASCII run or a single grapheme
+              # a single-byte token is printable ASCII: one character, one
+              # column - no need to ask for its width
+              size = token.bytesize
+              if size == 1
+                (last = @lex[-1]).is_a?(Word) and next last.add(token, 1)
+                next @lex << Word.new(token, 1)
+              end
+              # an ASCII run is the only multi-byte token which cannot be a
+              # grapheme cluster - there its width is simply its byte count
+              size = nil unless b < 0x80 && token.ascii_only?
+              if (last = @lex[-1]).is_a?(Word)
+                next size ? last.add(token, size, true) : last.add(token)
+              end
+              next @lex << Word.new(token, size, true) if size
+              next @lex << Word.new(token)
             end
 
-            if space
-              (last = @lex[-1]).is_a?(Space) and next last.inc
-              next @lex << Space.new
+            if SPACE_BYTE[b] && !(b == 0x0d && token.bytesize == 2)
+              size = token.bytesize
+              (last = @lex[-1]).is_a?(Space) and next last.size += size
+              next @lex << Space.new(size)
             end
 
-            next @lex << EOL if newline
+            next @lex << EOL if b == 0x0a || b == 0x0d
+
+            # escape sequences are dropped without `ansi`, any other control
+            # character is text
+            next if b == 0x1b && ((c = token.getbyte(1)) == 0x5b || c == 0x5d)
+
+            (last = @lex[-1]).is_a?(Word) and next last.add(token)
+            @lex << Word.new(token)
           end
 
           @lex[-1] == EOL ? @lex[-1] = EOP : @lex << EOP
@@ -415,23 +444,46 @@ module Terminal
           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)
+          line.scan(SCAN_REGEX) do |token|
+            b = token.getbyte(0)
+
+            if b > 0x20 # word chunk: an ASCII run or a single grapheme
+              # a single-byte token is printable ASCII: one character, one
+              # column - no need to ask for its width
+              size = token.bytesize
+              if size == 1
+                (last = @lex[-1]).is_a?(Word) and next last.add(token, 1)
+                next @lex << Word.new(token, 1)
+              end
+              # an ASCII run is the only multi-byte token which cannot be a
+              # grapheme cluster - there its width is simply its byte count
+              size = nil unless b < 0x80 && token.ascii_only?
+              if (last = @lex[-1]).is_a?(Word)
+                next size ? last.add(token, size, true) : last.add(token)
+              end
+              next @lex << Word.new(token, size, true) if size
+              next @lex << Word.new(token)
             end
 
-            if space
-              (last = @lex[-1]).is_a?(Space) and next last.inc
-              next @lex << Space.new
+            if SPACE_BYTE[b] && !(b == 0x0d && token.bytesize == 2)
+              size = token.bytesize
+              (last = @lex[-1]).is_a?(Space) and next last.size += size
+              next @lex << Space.new(size)
             end
 
-            next @lex << EOL if newline
+            next @lex << EOL if b == 0x0a || b == 0x0d
 
-            next @lex << Osc.new(osc) if osc
+            if (c = token.getbyte(1)) == 0x5d # Osc
+              next @lex << Osc.new(token)
+            end
+            if c != 0x5b # Csi
+              # a bare escape is just text
+              (last = @lex[-1]).is_a?(Word) and next last.add(token)
+              next @lex << Word.new(token)
+            end
 
-            # Handle csi...
-            if csi == "\e[m" || csi == "\e[0m"
+            # Handle Csi...
+            if token == "\e[m" || token == "\e[0m"
               next if csis == 0
 
               if @lex[-1].is_a?(Csi)
@@ -443,21 +495,17 @@ module Terminal
               next @lex << CsiEnd
             end
 
-            (last = @lex[-1]).is_a?(Csi) and next last.add(csi)
+            (last = @lex[-1]).is_a?(Csi) and next last.add(token)
 
             csis += 1
-            @lex << Csi.new(csi)
+            @lex << Csi.new(token)
           end
 
           @lex.pop if (last = @lex[-1]) == EOL
 
           next @lex << EOP if csis == 0
 
-          if last.is_a?(Csi) && csis == 1
-            @lex.pop
-          else
-            @lex << CsiEnd
-          end
+          last.is_a?(Csi) && csis == 1 ? @lex.pop : @lex << CsiEnd
           @lex << EOP
         end
 
@@ -510,34 +558,58 @@ module Terminal
       # @private
       class Space
         attr_accessor :size
-        def to_str = (' ' * @size)
-        def initialize = (@size = 1)
+        def to_str = (@size == 1 ? ' ' : ' ' * @size)
+        def initialize(size = 1) = (@size = size)
         def inc = (@size += 1)
         def inspect = @size == 1 ? '<Space>' : "<Space #{@size}>"
       end
 
       # @private
+      # A chunk is either a single grapheme cluster or a run of printable
+      # ASCII, for which the display width equals the character count.
       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]
+        def to_str = (@to_str ||= @chunks.size == 1 ? @chunks[0] : @chunks.join)
+        def size = (@size ||= @sizes.size == 1 ? @sizes[0] : @sizes.sum)
+        def inspect = "<Word #{@sizes.sum}:#{@chunks.join.inspect}>"
+
+        # `run` marks a chunk holding more than one character; only the lexer
+        # creates those and it knows without having to inspect the chunk again
+        def initialize(chunk, size = Text.char_width(chunk), run = false)
+          @chunks = [chunk]
           @sizes = [size]
+          @runs = run
         end
 
-        def add(char, size = Text.char_width(char))
-          @chars << char
+        def add(chunk, size = Text.char_width(chunk), run = false)
+          @chunks << chunk
           @sizes << size
+          @runs ||= run
           nil
         end
 
         def split(width)
-          return [self] if @chars.size == 1
+          if @runs
+            # ASCII runs have to become single characters again to be split -
+            # a multi-character grapheme cluster must stay untouched
+            chars = []
+            sizes = []
+            @chunks.each_with_index do |chunk, idx|
+              if chunk.bytesize > 1 && chunk.getbyte(0) < 0x80 &&
+                   chunk.ascii_only?
+                chunk.each_char { chars << it and sizes << 1 }
+              else
+                chars << chunk
+                sizes << @sizes[idx]
+              end
+            end
+          else
+            chars = @chunks
+            sizes = @sizes
+          end
+          return [self] if chars.size == 1
           ret = last = size = nil
-          @chars.each_with_index do |char, idx|
-            csize = @sizes[idx]
+          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))
@@ -568,7 +640,7 @@ module Terminal
         class << self
           attr_reader :to_str, :size, :inspect
         end
-        @to_str = "\e[m"
+        @to_str = Ansi::RESET
         @size = 0
         @inspect = '<CsiEnd>'
       end
@@ -584,22 +656,43 @@ module Terminal
 
       ENCODING = Encoding::UTF_8
 
-      SPACE_CACHE =
+      space_cache =
+        Hash.new { |h, s| h[s] = s < 1 ? '' : ' ' * s }.compare_by_identity
+      space_cache[0]
+      space_cache[1]
+      space_cache[2]
+      SPACE_CACHE = space_cache.freeze
+
+      # A run of printable ASCII is only taken when the following character is
+      # ASCII too: everything which can extend a grapheme cluster (combining
+      # marks, ZWJ, variation selectors, ...) is non-ASCII, so a run can never
+      # swallow the base of a cluster `\X` would have kept together.
+      SCAN_REGEX =
+        /
+          [\x21-\x7e]+(?=[\x00-\x7f]|\z)
+        | \x20+
+        | \r?\n
+        | \e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z]
+        | \e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\)
+        | \s
+        | \X
+      /x
+
+      SPACE_BYTE =
         Hash
-          .new { |h, s| h[s] = s < 1 ? '' : ' ' * s }
+          .new(false)
           .compare_by_identity
+          .merge!(
+            0x20 => true,
+            0x09 => true,
+            0x0b => true,
+            0x0c => true,
+            0x0d => true
+          )
           .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_BYTE,
         :Space,
         :Word,
         :Osc,

data/lib/terminal/text.rb

@@ -28,8 +28,14 @@ module Terminal
       #   Terminal::Text.ambiguous_char_width     # => 1
       #   Terminal::Text.ambiguous_char_width = 2 # for CJK terminals
       #
-      # @return [Integer] default: +1+
-      attr_accessor :ambiguous_char_width
+      # @return [Integer] default: `1`
+      attr_reader :ambiguous_char_width
+
+      # @attribute [w] ambiguous_char_width
+      def ambiguous_char_width=(value)
+        autoload?(:CharWidth) or CharWidth.clear
+        @ambiguous_char_width = value
+      end
 
       # Calculate the display width of a string in terminal columns.
       #
@@ -206,66 +212,66 @@ module Terminal
       def char_width(char)
         ord = char.ord
         return @ctrlchar_width[ord] if ord < 0x20
-        if char.size == 1
-          return ord < 0xa1 ? 1 : CharWidth[ord] || @ambiguous_char_width
-        end
+        # CharWidth knows this rule too - a comparison just beats a memo hit
+        return ord < 0xa1 ? 1 : CharWidth[ord] if char.bytesize == 1
+        return 2 if ord == 0x1f3f3 && @very_special_flags.include?(char)
         sum = 0
-        zwj = false
-        char.each_char do |c|
-          next zwj = false if zwj
-          ord = c.ord
-          next zwj = true if ord == 0x200d # zero with joiner
-          sum += CharWidth[ord] || @ambiguous_char_width
+        skip = false
+        char.each_codepoint do |cp|
+          next skip = false if skip
+          next skip = true if cp == 0x200d # zero width joiner
+          sum += CharWidth[cp]
         end
         sum
       end
     end
 
-    @ambiguous_char_width = 1
+    @very_special_flags = [
+      "🏳\u{FE0F}\u{200D}🌈", # rainbow flag
+      "🏳\u{FE0F}\u{200D}⚧\u{FE0F}" # transgender flag
+    ].freeze
 
-    @ctrlchar_width =
-      Hash
-        .new(2)
-        .compare_by_identity
-        .merge!(
-          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
-        )
-        .freeze
+    # indexed by ordinal, only ever asked for control characters
+    @ctrlchar_width = [
+      0,
+      1,
+      1,
+      1,
+      1,
+      0,
+      1,
+      0,
+      0,
+      1,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1,
+      1
+    ].freeze
+
+    @ambiguous_char_width = 1
 
-    cw_file = "#{__dir__}/text/char_width.rb"
-    autoload :CharWidth, cw_file
-    autoload :UNICODE_VERSION, cw_file
+    char_width_file = "#{__dir__}/text/char_width.rb"
+    autoload :CharWidth, char_width_file
+    autoload :UNICODE_VERSION, char_width_file
     private_constant :CharWidth
   end
 end

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -30,32 +30,32 @@ module Terminal
     # Detect the terminal emulator application.
     #
     # Known applications:
-    # +:alacritty+,
-    # +:amiga+,
-    # +:code_edit+,
-    # +:dg_unix+,
-    # +:docker+,
-    # +:fluent+,
-    # +:hpterm+,
-    # +:hyper+,
-    # +:iterm+,
-    # +:kitty+,
-    # +:macos+,
-    # +:mintty+,
-    # +:ms_terminal+,
-    # +:ncr260+,
-    # +:nsterm+,
-    # +:terminator+,
-    # +:terminology+,
-    # +:termite+,
-    # +:vscode+,
-    # +:vt100+,
-    # +:warp+,
-    # +:wyse+,
-    # +:xnuppc+
+    # `:alacritty`,
+    # `:amiga`,
+    # `:code_edit`,
+    # `:dg_unix`,
+    # `:docker`,
+    # `:fluent`,
+    # `:hpterm`,
+    # `:hyper`,
+    # `:iterm`,
+    # `:kitty`,
+    # `:macos`,
+    # `:mintty`,
+    # `:ms_terminal`,
+    # `:ncr260`,
+    # `:nsterm`,
+    # `:terminator`,
+    # `:terminology`,
+    # `:termite`,
+    # `:vscode`,
+    # `:vt100`,
+    # `:warp`,
+    # `:wyse`,
+    # `:xnuppc`
     #
-    # Any unrecognized +TERM_PROGRAM+ value is converted to a sanitized
-    # symbol. Returns +nil+ when no terminal can be identified.
+    # Any unrecognized `TERM_PROGRAM` value is converted to a sanitized
+    # symbol. Returns `nil` when no terminal can be identified.
     #
     # @example
     #   Terminal.application # => :kitty
@@ -77,7 +77,7 @@ module Terminal
     #   @param cmd [Array<String>] command and arguments
     #   @param options [Hash] options passed to the shell runner
     #   @return [Array<Process::Status, Array<String>, Array<String>>]
-    #     +[status, stdout_lines, stderr_lines]+
+    #     `[status, stdout_lines, stderr_lines]`
     #   @example
     #     status, output, error = Terminal.sh('echo', 'hello')
     #     output # => ["hello\n"]
@@ -88,7 +88,7 @@ module Terminal
     #   @param options [Hash] options passed to the shell runner
     #   @yield [line, type] called for each output line
     #   @yieldparam line [String] the output line
-    #   @yieldparam type [Symbol] +:output+ or +:error+
+    #   @yieldparam type [Symbol] `:output` or `:error`
     #   @return [Process::Status] the exit status
     #   @example
     #     Terminal.sh('make') do |line, type|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 1.0.5
+  version: 1.0.8
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -60,13 +60,13 @@ metadata:
   yard.run: yard
   source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
   bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
-  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.5
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.8
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.13
+rubygems_version: 4.0.18
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise line
   break support and much more.