terminal_rb 1.0.8 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91c150887b2ab21e509a1d8da160bc89879d9750de3246a2f84ee0c87c5a3992
-  data.tar.gz: 640cc99db38489ca6ccb57f3d7605fdc199a581ff674f20cda145b189a62747c
+  metadata.gz: 8a5e3a8b375cd45eef93b2316251d14da8732b80e27fb1192bbf8fb87a9bf297
+  data.tar.gz: f10bcbf23b3e8ecd01bc51a8772f2099dbe5950bb561bc26d854e6c3d2fb382d
 SHA512:
-  metadata.gz: 9a2f57d900145e027ea44bad3bea885a46c37c451e31cd9c0623c0d4935022ab3eb3479a76095a094d0ed3acb91d4248c2052d7b635538cf95d540af3a2b8512
-  data.tar.gz: 17b15d64bb67d748202fe7db329565d9bce197c50c00bb6005e15483acea2461d59b11f16d9910c4092532299c49047817d9e4934d54b8e8d59f1580040d4314
+  metadata.gz: a3c0cbfe105fccd17923c6ba7f43faf797b2df1fcc5d76d8bf138b1593156c5e23dc2a9700be17fa61e8f744151bb756943a482f9eca501087ffabb257e7e608
+  data.tar.gz: 60616eb76bbc7d01e1759274220390611887bbafe12f2d3b7cda8eb68dcd6cee491ce6b477235ce9a8b5e43b372e6d3e6c7a8ff81962a67eb78a20cb58fe7523

data/README.md

@@ -1,10 +1,10 @@
-# Terminal.rb v1.0.8
+# Terminal.rb v1.0.9
 
 Terminal.rb supports you with input and output on your terminal. Simple [BBCode](https://en.wikipedia.org/wiki/BBCode)-like markup for attributes and coloring, word-wise line breaks, correct special key recognition and mouse event reporting enable you to implement your CLI app quickly and easily.
 
 - Gem: [rubygems.org](https://rubygems.org/gems/terminal_rb)
 - Source: [codeberg.org](https://codeberg.org/mblumtritt/Terminal.rb)
-- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/1.0.8/Terminal)
+- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/1.0.9/Terminal)
 
 ## Features
 

data/examples/bbcode.rb

@@ -6,28 +6,28 @@ Terminal.puts <<~TEXT
 
   ✅ [b bright_green]Terminal.rb::Ansi[/b] — BBCode:[/]
 
-              [b]Bold[/b]   [\\b][d]...[/d][\\/b] [\\bold][d]   ...  [/d][\\/bold]
-               [dim]Dim[/dim]   [\\d][d]...[/d][\\/d] [\\dim][d]   ...   [/d][\\/dim]
-            [i]Italic[/i]   [\\i][d]...[/d][\\/i] [\\italic][d]  ... [/d][\\/italic]
+              [b]Bold[/b]   [\\b][d]...[/d][\\/b] [\\bold][d]........[/d][\\/bold]
+               [dim]Dim[/dim]   [\\d][d]...[/d][\\/d] [\\dim][d].........[/d][\\/dim]
+            [i]Italic[/i]   [\\i][d]...[/d][\\/i] [\\italic][d]......[/d][\\/italic]
          [u]Underline[/u]   [\\u][d]...[/d][\\/u] [\\underline][d]...[/d][\\/underline]
-              [h]Hide[/h]   [\\h][d]...[/d][\\/h] [\\hide][d]   ...  [/d][\\/hide]
+              [h]Hide[/h]   [\\h][d]...[/d][\\/h] [\\hide][d]........[/d][\\/hide]
 
-            [inv]Invert[/inv]   [\\inv][d]  ... [/d][\\/inv] [\\invert][d]...[/d][\\/invert]
+            [inv]Invert[/inv]   [\\inv][d]......[/d][\\/inv] [\\invert][d]...[/d][\\/invert]
             [strike]Strike[/strike]   [\\strike][d]...[/d][\\/strike]
-             [blink]Blink[/blink]   [\\blink][d] ...[/d][\\/blink]
+             [blink]Blink[/blink]   [\\blink][d]....[/d][\\/blink]
 
-         [u]Underline[/u]   [\\u][d] ... [/d][\\/u]   [\\underline][d]    ...   [/d][\\/underline]
-  [uu]Double underline[/uu]   [\\uu][d] ...[/d][\\/uu]  [\\double_underline][d]...[/d][\\/double_underline]
-   [cu]Curly underline[/cu]   [\\cu][d] ...[/d][\\/cu]  [\\curly_underline][d] ...[/d][\\/curly_underline]
+         [u]Underline[/u]   [\\u][d].....[/d][\\/u]   [\\underline][d]..........[/d][\\/underline]
+  [uu]Double underline[/uu]   [\\uu][d]....[/d][\\/uu]  [\\double_underline][d]...[/d][\\/double_underline]
+   [cu]Curly underline[/cu]   [\\cu][d]....[/d][\\/cu]  [\\curly_underline][d]...[/d] [\\/curly_underline]
   [dau]Dashed underline[/dau]   [\\dau][d]...[/d][\\/dau] [\\dashed_underline][d]...[/d][\\/dashed_underline]
   [dou]Dotted underline[/dou]   [\\dou][d]...[/d][\\/dou] [\\dotted_underline][d]...[/d][\\/dotted_underline]
 
-           [fraktur]Fraktur[/fraktur]   [\\fraktur][d] ... [/d][\\/fraktur]
-            [framed]Framed[/framed]   [\\framed][d]  ... [/d][\\/framed]
+           [fraktur]Fraktur[/fraktur]   [\\fraktur][d].....[/d][\\/fraktur]
+            [framed]Framed[/framed]   [\\framed][d]......[/d][\\/framed]
          [encircled]Encircled[/encircled]   [\\encircled][d]...[/d][\\/encircled]
 
-         [ovr]Overlined[/ovr]   [\\ovr][d]...[/d][\\/ovr] [\\overlined][d] ... [/d][\\/overlined]
-         [sub]Subscript[/sub]   [\\sub][d]...[/d][\\/sub] [\\subscript][d] ... [/d][\\/subscript]
+         [ovr]Overlined[/ovr]   [\\ovr][d]...[/d][\\/ovr] [\\overlined][d].....[/d][\\/overlined]
+         [sub]Subscript[/sub]   [\\sub][d]...[/d][\\/sub] [\\subscript][d].....[/d][\\/subscript]
        [sup]Superscript[/sup]   [\\sup][d]...[/d][\\/sup] [\\superscript][d]...[/d][\\/superscript]
 
 TEXT

data/lib/terminal/ansi.rb

@@ -16,7 +16,7 @@ module Terminal
   #   Terminal::Ansi[:on_blue]      # => "\e[44m"
   #
   # @example BBCode to ANSI
-  #   Terminal::Ansi.bbcode('[bold]Hello[/bold]') # => "\e[1mHello\e[m"
+  #   Terminal::Ansi.bbcode('[bold]Hello[/bold]') # => "\e[1mHello\e[22m"
   #
   module Ansi
     class << self
@@ -39,7 +39,7 @@ module Terminal
       def named_colors = NAMED_COLORS.keys.map!(&:to_sym)
 
       #
-      # @!group ANSI Control Code Generation
+      # @!group Text Attribute Code Generation
       #
 
       # Generate an ANSI escape sequence from attribute names or color
@@ -67,20 +67,12 @@ module Terminal
         "\e[#{
           attributes
             .map! do |arg|
-              case arg
-              when String
-                @attr_str_map[arg] || _invalid(arg)
-              when Symbol
-                @attr_sym_map[arg] || _invalid(arg)
-              when (0..255)
-                "38;5;#{arg}"
-              when (256..511)
-                "48;5;#{arg - 256}"
-              when (512..767)
-                "58;5;#{arg - 512}"
-              else
-                _invalid(arg)
-              end
+              next @attr_str_map[arg] || _invalid(arg) if arg.is_a?(String)
+              next @attr_sym_map[arg] || _invalid(arg) if arg.is_a?(Symbol)
+              _invalid(arg) unless arg.is_a?(Integer)
+              next "38;5;#{arg}" if arg >= 0 && arg <= 255
+              next "48;5;#{arg - 256}" if arg >= 256 && arg <= 511
+              arg >= 512 && arg <= 767 ? "58;5;#{arg - 512}" : _invalid(arg)
             end
             .join(';')
         }m"
@@ -130,10 +122,7 @@ module Terminal
       #   attribute is invalid
       def try_convert(attributes, separator: ' ')
         return unless attributes
-        cache = @convert_cache[separator]
-        hit = cache[key = attributes.to_s] and return hit
-        cache.clear if cache.size > 1024 # cache limit
-        cache[key] = unless (attributes = key.split(separator)).empty?
+        unless (attributes = attributes.to_s.split(separator)).empty?
           # attributes.uniq!
           codes = attributes.map { @attr_str_map[it] || break }
           "\e[#{codes.join(';')}m" if codes
@@ -168,7 +157,7 @@ module Terminal
       #
       # @!endgroup
       #
-      # @!group BBcode Generation
+      # @!group BBCode Generation
       #
 
       # Convert BBCode markup to ANSI escape codes.
@@ -191,11 +180,16 @@ module Terminal
       def bbcode(str)
         str = str.to_s
         return str.dup unless str.index('[')
-        str.gsub(@re_bbcode) do |match_str|
-          match = Regexp.last_match(1) or next match_str
-          next try_convert(match) || match_str if match[0] != '\\'
-          match[0] = ''
-          "[#{match}]"
+        str.gsub(@re_bbcode) do |match|
+          hit = @bbcc[match] and next hit
+          next "[#{match[2..]}" if (fc = match[1]) == '\\'
+          @bbcc.clear if @bbcc.size == 1024
+          @bbcc[match] = if fc == ']' || (att = match[1..-2].split).empty?
+            match
+          else
+            att = att.map { @attr_str_map[it] || break }
+            att ? "\e[#{att.join(';')}m" : match
+          end
         end
       end
 
@@ -211,15 +205,12 @@ module Terminal
       def unbbcode(str)
         str = str.to_s
         return str.dup unless str.index('[')
-        str.gsub(@re_bbcode) do |match_str|
-          match = Regexp.last_match(1) or next match_str
-          if match[0] == '\\'
-            match[0] = ''
-            next "[#{match}]"
-          end
-          next match_str if (match = match.split).empty?
-          next if match.all? { @attr_str_map[it] }
-          match_str
+        str.gsub(@re_bbcode) do |match|
+          hit = @bbcc[match] and next hit[0] == '[' ? hit : nil
+          next match if (fc = match[1]) == ']'
+          next "[#{match[2..]}" if fc == '\\'
+          next match if (att = match[1..-2].split).empty?
+          match unless att.map { @attr_str_map[it] || break }
         end
       end
 
@@ -237,13 +228,11 @@ module Terminal
       def escape_bbcode(str)
         str = str.to_s
         return str.dup unless str.index('[')
-        str.gsub(@re_bbcode) do |match_str|
-          fc = match_str[1]
-          next match_str if fc == '\\' || fc == ']'
-          match = Regexp.last_match(1) or next match_str
-          next match_str if (parts = match.split).empty?
-          next "[\\#{match}]" if parts.all? { @attr_str_map[it] }
-          match_str
+        str.gsub(@re_bbcode) do |match|
+          hit = @bbcc[match] and hit[1] == '\\' ? hit : "[\\#{match[1..]}"
+          next match if (fc = match[1]) == '\\' || fc == ']'
+          next match if (att = match[1..-2].split).empty?
+          att.map { @attr_str_map[it] || break } ? "[\\#{match[1..]}" : match
         end
       end
 
@@ -274,14 +263,9 @@ module Terminal
       # @return [true, false]
       def valid?(*attributes)
         attributes.all? do |arg|
-          case arg
-          when String
-            @attr_str_map[arg]
-          when Symbol
-            @attr_sym_map[arg]
-          when (0..767)
-            true
-          end
+          next @attr_str_map[arg] if arg.is_a?(String)
+          next @attr_sym_map[arg] if arg.is_a?(Symbol)
+          arg.is_a?(Integer) && arg >= 0 && arg <= 767
         end
       end
 
@@ -303,7 +287,7 @@ module Terminal
       #
       # @!endgroup
       #
-      # @!group ANSI Control Code Generation
+      # @!group Cursor and Screen Control Codes
       #
 
       # Move cursor up.
@@ -458,54 +442,26 @@ module Terminal
       # @return (see .[])
       def line_erase(part = :all) = "\e[#{@line_erase[part]}K"
 
-      # Set the terminal window title.
-      # @note Supported by Hyper, iTerm2, Kitty, macOS Terminal, Tabby,
-      #   WezTerm.
-      #
-      # @example
-      #   Terminal.raw_write(Terminal::Ansi.title('My App'))
-      #
-      # @param title [String] the title text
-      # @return (see .[])
-      def title(title) = "\e]0;#{title}\a"
-
-      # Start a hyperlink (OSC 8).
       #
-      # @note Supported by Ghostty, iTerm2, Kitty, Rio, Tabby, WezTerm.
-      #
-      # @see .link
-      # @see .link_end
-      #
-      # @param url [#to_s] the link URL
-      # @param params [Hash] optional link parameters (e.g., `id:`)
-      # @return (see .[])
-      def link_start(url, **params)
-        "\e]8;#{params.map { it.join('=') }.join(':')};#{url}\a"
-      end
-
-      # End a hyperlink.
+      # @!endgroup
       #
-      # @see .link_start
+      # @!group Terminal Integration Codes
       #
-      # @return (see .[])
-      def link_end = +LINK_END
 
-      # Create a complete hyperlink (OSC 8).
+      # Set the terminal window title.
       #
-      # @see .link_start
-      # @see .link_end
+      # @note Supported by iTerm2, Kitty, macOS Terminal, Tabby,
+      #   WezTerm.
       #
       # @example
-      #   Terminal::Ansi.link('https://example.com', 'Example')
+      #   Terminal.raw_write(Terminal::Ansi.title('My App'))
       #
-      # @param (see .link_start)
-      # @param text [String] the visible link text
+      # @param title [#to_s] the title text
       # @return (see .[])
-      def link(url, text, **params)
-        "#{link_start(url, **params)}#{text}#{LINK_END}"
-      end
+      def title(title) = "\e]0;#{_no_bell(title)}\a"
 
       # Send a desktop notification via the terminal.
+      #
       # @note Supported by Ghostty, iTerm2, Kitty, WezTerm.
       #
       # @example
@@ -513,7 +469,7 @@ module Terminal
       #
       # @param text [to_s] the notification text
       # @return (see .[])
-      def notify(text) = "\e]9;#{text}\a"
+      def notify(text) = "\e]9;#{_no_bell(text)}\a"
 
       # Show or update a progress indicator in the terminal tab/title
       # bar.
@@ -550,10 +506,100 @@ module Terminal
         "\e]9;4;#{state};#{percent.to_i.clamp(0, 100)}\a"
       end
 
+      # @comment Should we implement this?
+      #
+      #   # Request attention.
+      #   #
+      #   # @note Supported by iTerm2.
+      #   #
+      #   # @param action [true, :bounce, :once, :fireworks, false, :stop]
+      #   #   start bouncing dock icon (`true`, `:bounce`),
+      #   #   bounce dock icon once (`:once`)
+      #   #   or stop attention (`false`, `:stop`)
+      #   # @return (see .[])
+      #   def attention(action = :bounce)
+      #     "\e]1337;RequestAttention=#{
+      #       case action
+      #       when true, :bounce
+      #         'yes'
+      #       when :once, :fireworks
+      #         action
+      #       else
+      #         'no'
+      #       end
+      #     }\a"
+      #   end
+
+      # Create or start a hyperlink.
+      #
+      # @note Supported by Ghostty, iTerm2, Kitty, Rio, Tabby, WezTerm.
+      #
+      # @see .link_end
+      #
+      # @example
+      #   Terminal::Ansi.link('https://example.com', 'Example')
+      #
+      # @param url [#to_s] the link URL
+      # @param text [nil, #to_s] the visible link text
+      # @param params [Hash] optional link parameters (e.g., `id:`)
+      # @return (see .[])
+      def link(url, text = nil, **params)
+        start =
+          "\e]8;#{
+            _no_bell(params.map { it.join('=') }.join(':'))
+          };#{_no_bell(url)}\a"
+        text ? "#{start}#{_no_bell(text)}#{LINK_END}" : start
+      end
+
+      # End a hyperlink.
+      #
+      # @see .link
+      #
+      # @return (see .[])
+      def link_end = +LINK_END
+
+      # Copy text to clipboard.
+      #
+      # @note Supported by Ghostty, iTerm2, Kitty, Rio, Tabby, WezTerm.
+      #
+      # @param text [#to_s] text to copy
+      # @return (see .[])
+      def clipboard(text) = "\e]52;c;#{[text.to_s].pack('m0')}\a"
+
+      # Show or update the session status of the terminal.
+      #
+      # @note Supported by iTerm2.
+      #
+      # @example
+      #   Terminal.raw_write(Terminal::Ansi.status(text: 'Working'))
+      #   Terminal.raw_write(Terminal::Ansi.status(indicator: '#fa00fa'))
+      #   Terminal.raw_write(Terminal::Ansi.status(indicator: :f00))
+      #   Terminal.raw_write(Terminal::Ansi.status) # reset the status
+      #
+      # @param text [nil, #to_s] status text
+      # @param detail [nil, #to_s] status detail text
+      # @param color [nil, String, Symbol] text color
+      # @param indicator [nil, String, Symbol] status indicator color
+      # @return (see .[])
+      def status(text: nil, detail: nil, color: nil, indicator: nil)
+        str = text ? ";status=#{_no_bell(text)}" : ''
+        indicator = _try_rgb(indicator) and str << ";indicator=#{indicator}"
+        color = _try_rgb(color) and str << ";color=#{color}"
+        str << "detail=#{_no_bell(detail)}" if detail
+        str.empty? ? +STATUS_RESET : "\e]21337#{str}\a"
+      end
+
+      # Reset session status of the terminal.
+      #
+      # @see .status
+      #
+      # @return (see .[])
+      def status_reset = +STATUS_RESET
+
       # Scale text using the
       # [text sizing protocol](https://sw.kovidgoyal.net/kitty/text-sizing-protocol).
       #
-      # @note Only supported by Kitty.
+      # @note Supported by Kitty.
       #
       # @example Double-height Greeting
       #   Terminal::Ansi.scale('Hello Ruby!', scale: 2)
@@ -619,16 +665,23 @@ module Terminal
           caller(1)
         )
       end
+
+      def _try_rgb(str)
+        mt = /\A?#?([[:xdigit:]]{3,6})\z/.match(str.to_s)&.[](1) or return
+        "##{mt.size == 6 ? mt : mt[..2]}"
+      end
+
+      def _no_bell(str) = str.to_s.tr("\a", '')
     end
 
     @re_test =
       /
-      (?:\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
-      |
-      (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
-    /x
+        (?:\e\[[\x30-\x3f]*[\x20-\x2f]*[a-zA-Z])
+      | (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
+      /x
 
-    @re_bbcode = /(?:\[((?~[\[\]]))\])/
+    @re_bbcode_old = /(?:\[((?~[\[\]]))\])/
+    @re_bbcode = /(?:\[(?~[\[\]]))\]/
 
     color_map = {
       # foreground
@@ -818,13 +871,12 @@ module Terminal
           b = /\A(on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(s) or next h[s] = nil
           next h[s] = (v = NAMED_COLORS[b[2]]) ? "#{@cbase[b[1]]};#{v}" : nil
         end
-        h[s] = case v.size
-        when 1, 2
-          "#{@cbase[b]};5;#{v.hex}"
-        when 3
-          "#{@cbase[b]};2;#{(v[0] * 2).hex};#{(v[1] * 2).hex};#{(v[2] * 2).hex}"
-        when 6
+        h[s] = if v.size == 6
           "#{@cbase[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
+        elsif v.size == 3
+          "#{@cbase[b]};2;#{(v[0] * 2).hex};#{(v[1] * 2).hex};#{(v[2] * 2).hex}"
+        elsif v.size < 3
+          "#{@cbase[b]};5;#{v.hex}"
         end
       end
 
@@ -832,7 +884,7 @@ module Terminal
     @attr_sym_map.compare_by_identity
     @attr_sym_map.default_proc = proc { |h, s| h[s] = @attr_str_map[s.to_s] }
 
-    @convert_cache = Hash.new { |h, k| h[k] = {} }
+    @bbcc = {} # BBCode cache
 
     @screen_erase = { below: nil, above: '1', scrollback: '3' }
     @screen_erase.default = '2'
@@ -917,6 +969,16 @@ module Terminal
     # @private
     LINE_ERASE_PREV = -"#{cursor_prev_line(nil)}#{LINE_ERASE}"
 
+    # @comment Supported by Terminal, iTerm, WezTerm:
+    # @private
+    LINE_DOUBLE_HEIGHT_TOP = "\e#3"
+    # @private
+    LINE_DOUBLE_HEIGHT_BOTTOM = "\e#4"
+    # @private
+    LINE_SINGLE_WIDTH = "\e#5"
+    # @private
+    LINE_DOUBLE_WIDTH = "\e#6"
+
     # @private
     LINK_END = "\e]8;;\a"
 
@@ -925,6 +987,9 @@ module Terminal
     # @private
     PROGRESS_SHOW_INDETERMINATE = "\e]9;4;3;0\a"
 
+    # @private
+    STATUS_RESET = "\e]21337;status=;indicator=;status-color=\a"
+
     # @comment seems not widely supported:
     #   doubled: def cursor_column(column = 1) = "\e[#{column}`"
     #   doubled: def cursor_row(row = 1) = "\e[#{row}d"
@@ -942,13 +1007,6 @@ module Terminal
     #
     #   def set_scroll_region(top = nil, bottom = nil) = "\e[#{top};#{bottom}r"
 
-    # @comment other:
-    #   "\eE" same as "\r\n"
-    #   "\eD" same as "\n" but preserves column
-    #   "\eM" reverse "\n"
-    #   "\e[6n" report Cursor Position as "ESC \[ row ; col R"
-    #   "\e[21t report window’s title as ESC ] l title ESC \"
-
     # @comment TODO:
     #   https://sw.kovidgoyal.net/kitty/desktop-notifications
     #   https://sw.kovidgoyal.net/kitty/pointer-shapes

data/lib/terminal/input/dumb.rb

@@ -2,7 +2,7 @@
 
 module Terminal
   # @private
-  module DumpInput
+  module DumbInput
     def input_mode = :dumb
 
     def on_key_event(*)
@@ -32,5 +32,5 @@ module Terminal
     end
   end
 
-  private_constant :DumpInput
+  private_constant :DumbInput
 end

data/lib/terminal/input/key_event.rb

@@ -9,9 +9,9 @@ module Terminal
   # @see Terminal.read_key_event
   #
   # @example Parse a raw escape sequence
-  #   event = Terminal::KeyEvent["\r"]
-  #   event.key     # => :Enter
-  #   event.name    # => "Enter"
+  #   event = Terminal::KeyEvent["a"]
+  #   event.key     # => "a"
+  #   event.name    # => "a"
   #   event.simple? # => true
   #
   # @example Inspect modifier keys
@@ -33,7 +33,7 @@ module Terminal
     # @see #modifiers
     # @see #modifier?
     #
-    # @return [Integer] modifier_bits bitmask
+    # @return [Integer] bitmask of the active modifiers
     attr_reader :modifier_bits
 
     # Names of active modifier keys.

data/lib/terminal/input.rb

@@ -14,7 +14,6 @@ module Terminal
   # @example
   #   Terminal.input_mode # => :csi_u
   #
-  # @attribute [r] input_mode
   # @return [Symbol] `:csi_u`, `:legacy`, `:dumb`, or `:error`
 
   #
@@ -33,7 +32,7 @@ module Terminal
   #
   #   @example
   #     Terminal.on_key_event(mouse: true) do |event|
-  #       break if event.name == 'ESC'
+  #       break if event.name == 'Esc'
   #       puts event.name
   #     end
   #
@@ -69,7 +68,7 @@ module Terminal
         extend AnsiInput
       when :dumb
         require_relative('input/dumb')
-        extend DumpInput
+        extend DumbInput
       else
         __input_error
       end

data/lib/terminal/output/ansi.rb

@@ -88,19 +88,13 @@ module Terminal
       objects.flatten!
       return @out.puts if objects.empty?
       @out.puts(
-        Text::Formatter.format(
+        Text::Formatter.new(
           *objects,
           ansi: true,
           bbcode:,
           spaces:,
-          eol:,
-          align:,
-          width:,
-          height:,
-          padding:,
-          prefix:,
-          suffix:
-        )
+          eol:
+        ).format(align:, width:, height:, padding:, prefix:, suffix:)
       )
     rescue IOError, SystemCallError
       __output_error(nil)
@@ -139,16 +133,17 @@ module Terminal
       require('io/console')
       @con = IO.console
       return unless Signal.list.key?('WINCH')
-      Signal.trap('WINCH') do
-        @size = nil
-        @on_resize&.call
-      end
+      prev_winch =
+        Signal.trap('WINCH') do
+          @size = nil
+          @on_resize&.call
+          prev_winch.call if prev_winch.respond_to?(:call)
+        end
     end
 
     private_class_method def self.extended(mod)
       mod.instance_variable_set(:@cc, 0)
       mod.instance_variable_set(:@as, 0)
-      # at_exit { raw_write("#{Ansi::CURSOR_SHOW}#{Ansi::SCREEN_ALTERNATE_OFF}") }
     end
   end
 

data/lib/terminal/output/dumb.rb

@@ -69,19 +69,13 @@ module Terminal
       objects.flatten!
       return @out.puts if objects.empty?
       @out.puts(
-        Text::Formatter.format(
+        Text::Formatter.new(
           *objects,
           ansi: false,
           bbcode:,
           spaces:,
-          eol:,
-          align:,
-          width:,
-          height:,
-          padding:,
-          prefix:,
-          suffix:
-        )
+          eol:
+        ).format(align:, width:, height:, padding:, prefix:, suffix:)
       )
     rescue IOError, SystemCallError
       __output_error(nil)

data/lib/terminal/output.rb

@@ -27,7 +27,7 @@ module Terminal
     # @!group Output Attributes
     #
 
-    # @!attribute [r] tui?
+    # @attribute [r] tui?
     #
     #   Whether the terminal supports full TUI interaction (ANSI output
     #   with CSI-u or legacy keyboard input).
@@ -36,7 +36,7 @@ module Terminal
     #
     #   @return [true, false]
 
-    # @!attribute [r] ansi?
+    # @attribute [r] ansi?
     #
     #   Whether ANSI escape codes are supported.
     #
@@ -181,7 +181,6 @@ module Terminal
     # @!method show_cursor
     #   Show the cursor.
     #
-    #
     #   @note Reference-counted; safe for nested use.
     #
     #   @see .hide_cursor

data/lib/terminal/rspec/helper.rb

@@ -4,9 +4,10 @@ require 'stringio'
 
 # RSpec shared context for testing code that uses Terminal.rb.
 #
-# Stubs all Terminal I/O methods and provides `stdout`, `stdin`, and
-# `stdoutstr` test helpers. Output is captured into the `stdout` array;
-# input is read from the `stdin` array.
+# Stubs all Terminal I/O methods and provides the `stdout`, `stdout_lines`,
+# and `stdin` test helpers. Output is captured in the `stdout` StringIO;
+# `stdout_lines` returns its lines without line endings. Input is read from
+# the `stdin` array of raw key sequences.
 #
 # @example Basic usage
 #   RSpec.describe MyClass do
@@ -14,7 +15,7 @@ require 'stringio'
 #
 #     it 'prints a greeting' do
 #       my_object.greet
-#       expect(stdoutstr).to include('Hello')
+#       expect(stdout.string).to include('Hello')
 #     end
 #   end
 #

data/lib/terminal/text/char_width.rb

@@ -3,7 +3,7 @@
 module Terminal
   module Text
     # supported Unicode Standard version
-    UNICODE_VERSION = '17.0.0'
+    UNICODE_VERSION = '18.0.0'
 
     #
     # This lookup was generated based on
@@ -11,7 +11,6 @@ module Terminal
     #
     CharWidth =
       Hash.new do |h, ord|
-        next h[ord] = 1 if ord < 0xa1
         h[ord] = @char_width[@char_width_last.bsearch_index { ord <= it }] ||
           @ambiguous_char_width
       end
@@ -163,7 +162,7 @@ module Terminal
       0x5c3,
       0x5c5,
       0x5c6,
-      0x5c7,
+      0x5c9,
       0x5ff,
       0x605,
       0x60f,
@@ -276,7 +275,7 @@ module Terminal
       0xb44,
       0xb4c,
       0xb4d,
-      0xb54,
+      0xb52,
       0xb56,
       0xb61,
       0xb63,
@@ -441,9 +440,7 @@ module Terminal
       0x1a7e,
       0x1a7f,
       0x1aaf,
-      0x1add,
-      0x1adf,
-      0x1aeb,
+      0x1af0,
       0x1aff,
       0x1b03,
       0x1b33,
@@ -956,7 +953,9 @@ module Terminal
       0x10d6d,
       0x10eaa,
       0x10eac,
-      0x10ef9,
+      0x10ec8,
+      0x10ecf,
+      0x10eef,
       0x10eff,
       0x10f45,
       0x10f50,
@@ -1146,6 +1145,8 @@ module Terminal
       0x11d95,
       0x11d96,
       0x11d97,
+      0x11def,
+      0x11df0,
       0x11ef2,
       0x11ef4,
       0x11eff,
@@ -1180,11 +1181,15 @@ module Terminal
       0x16fef,
       0x16ff6,
       0x16fff,
-      0x18cd5,
+      0x18cda,
       0x18cfe,
-      0x18d1e,
+      0x18d20,
       0x18d7f,
       0x18df2,
+      0x18dff,
+      0x19191,
+      0x1919f,
+      0x191d2,
       0x1afef,
       0x1aff3,
       0x1aff4,
@@ -1192,7 +1197,7 @@ module Terminal
       0x1affc,
       0x1affe,
       0x1afff,
-      0x1b122,
+      0x1b128,
       0x1b131,
       0x1b132,
       0x1b14f,
@@ -1200,7 +1205,7 @@ module Terminal
       0x1b154,
       0x1b155,
       0x1b163,
-      0x1b167,
+      0x1b168,
       0x1b16f,
       0x1b2fb,
       0x1bc9c,
@@ -1211,6 +1216,8 @@ module Terminal
       0x1cf2d,
       0x1cf2f,
       0x1cf46,
+      0x1d126,
+      0x1d128,
       0x1d166,
       0x1d169,
       0x1d172,
@@ -1221,6 +1228,8 @@ module Terminal
       0x1d1ad,
       0x1d241,
       0x1d244,
+      0x1d25a,
+      0x1d25c,
       0x1d2ff,
       0x1d356,
       0x1d35f,
@@ -1287,6 +1296,8 @@ module Terminal
       0x1f190,
       0x1f19a,
       0x1f1ac,
+      0x1f1ad,
+      0x1f1ae,
       0x1f1ff,
       0x1f202,
       0x1f20f,
@@ -1342,13 +1353,15 @@ module Terminal
       0x1f6cf,
       0x1f6d2,
       0x1f6d4,
-      0x1f6d8,
+      0x1f6d9,
       0x1f6db,
       0x1f6df,
       0x1f6ea,
       0x1f6ec,
       0x1f6f3,
       0x1f6fc,
+      0x1f7d9,
+      0x1f7da,
       0x1f7df,
       0x1f7eb,
       0x1f7ef,
@@ -1362,17 +1375,15 @@ module Terminal
       0x1fa6f,
       0x1fa7c,
       0x1fa7f,
-      0x1fa8a,
-      0x1fa8d,
       0x1fac6,
       0x1fac7,
       0x1fac8,
-      0x1facc,
-      0x1fadc,
+      0x1facb,
+      0x1fadd,
       0x1fade,
-      0x1faea,
+      0x1faeb,
       0x1faee,
-      0x1faf8,
+      0x1fafa,
       0x1ffff,
       0x2fffd,
       0x2ffff,
@@ -1876,8 +1887,6 @@ module Terminal
       0,
       1,
       0,
-      1,
-      0,
       nil,
       1,
       nil,
@@ -2549,6 +2558,10 @@ module Terminal
       1,
       0,
       1,
+      0,
+      1,
+      0,
+      1,
       2,
       0,
       1,
@@ -2578,6 +2591,14 @@ module Terminal
       1,
       2,
       1,
+      2,
+      1,
+      2,
+      1,
+      0,
+      1,
+      0,
+      1,
       0,
       1,
       0,
@@ -2689,6 +2710,8 @@ module Terminal
       2,
       1,
       2,
+      1,
+      2,
       0,
       2,
       1,

data/lib/terminal/text/formatter.rb

@@ -9,15 +9,15 @@ module Terminal
     # @see Terminal::Text
     #
     # @example Basic word-wrapping
-    #   fmt = Terminal::Text::Formatter.new('Hello World, this is a test')
-    #   fmt.lines(width: 12)
+    #   formatter = Terminal::Text::Formatter.new('Hello World, this is a test')
+    #   formatter.lines(width: 12)
     #   # => ["Hello World,", "this is a", "test"]
     #
     # @example Formatted output with alignment
     #   Terminal::Text::Formatter.format(
     #     'Hello', align: :center, width: 20
     #   )
-    #   # => ["       Hello        "]
+    #   # => ["       Hello        "]
     class Formatter
       # Parse text into lines, optionally with display widths.
       #
@@ -55,7 +55,7 @@ module Terminal
       #
       # @param (see #initialize)
       # @param (see #format)
-      # @result (see #format)
+      # @return (see #format)
       # @raise (see #format)
       def self.format(
         *str,
@@ -80,6 +80,31 @@ module Terminal
         )
       end
 
+      # Format text with alignment.
+      #
+      # @see #fmt
+      #
+      # @example
+      #   Terminal::Text::Formatter.fmt('Hi', align: :center, width: 10)
+      #   # => ["    Hi    "]
+      #
+      # @param (see #initialize)
+      # @param (see #fmt)
+      # @return (see #fmt)
+      # @raise (see #fmt)
+      def self.fmt(
+        *str,
+        ansi: true,
+        bbcode: true,
+        spaces: true,
+        eol: true,
+        align: nil,
+        width: nil,
+        height: nil
+      )
+        new(*str, ansi:, bbcode:, spaces:, eol:).fmt(align:, width:, height:)
+      end
+
       # Create a new formatter with given text and options.
       #
       # @param str [Array<#to_s>] text to process
@@ -108,8 +133,8 @@ module Terminal
       # Word-wrap and return lines with their display widths.
       #
       # @example
-      #   fmt = Terminal::Text::Formatter.new('Hello World')
-      #   fmt.lines_with_size(width: 5)
+      #   formatter = Terminal::Text::Formatter.new('Hello World')
+      #   formatter.lines_with_size(width: 5)
       #   # => [["Hello", 5], ["World", 5]]
       #
       # @param width [#to_i, nil] maximum line width in columns;
@@ -127,8 +152,8 @@ module Terminal
       # Word-wrap and return lines as strings.
       #
       # @example
-      #   fmt = Terminal::Text::Formatter.new('Hello World')
-      #   fmt.lines(width: 5)
+      #   formatter = Terminal::Text::Formatter.new('Hello World')
+      #   formatter.lines(width: 5)
       #   # => ["Hello", "World"]
       #
       # @param width [#to_i, nil] maximum line width in columns
@@ -138,16 +163,22 @@ module Terminal
 
       # 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         "]
+      # @see #fmt
+      #
+      # @example Prefix each line
+      #   formatter = Terminal::Text::Formatter.new("Hello\nWorld")
+      #   formatter.format(prefix: '> ')
+      #   # => ["> Hello", "> World"]
+      # @example Framed box with padding
+      #   formatter = Terminal::Text::Formatter.new('Hi')
+      #   formatter.format(width: 6, padding: [1, 2], prefix: '|', suffix: '|')
+      #   # => ["|      |", "|  Hi  |", "|      |"]
       #
       # @param align [Symbol, nil] text alignment:
       #   `: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
+      #   negative values take lines from the end; `0` returns `[""]`
       # @param padding [#to_i, Array, nil] CSS-style padding
       #    - 1 value: all sides;
       #    - 2 values: [vertical, horizontal];
@@ -165,6 +196,10 @@ module Terminal
         prefix: nil,
         suffix: nil
       )
+        if padding.nil? && prefix.nil? && suffix.nil?
+          return fmt(align:, width:, height:)
+        end
+
         top, right, bottom, left = _padding(padding)
 
         if height
@@ -200,11 +235,9 @@ module Terminal
         left = left < 1 ? prefix.to_s : "#{prefix}#{space[left]}"
         right = right < 1 ? suffix.to_s : "#{space[right]}#{suffix}"
 
-        # TODO: styling
-
         case align
-        when :left
-          lws.each { |l, s| ret << "#{left}#{l}#{space[w - s]}#{right}" }
+        when nil, false
+          lws.each { |l, _| ret << "#{left}#{l}#{right}" }
         when :right
           lws.each { |l, s| ret << "#{left}#{space[w - s]}#{l}#{right}" }
         when :center
@@ -214,13 +247,58 @@ module Terminal
             ret << "#{left}#{space[s - rs]}#{l}#{space[rs]}#{right}"
           end
         else
-          lws.each { |l, _| ret << "#{left}#{l}#{right}" }
+          lws.each { |l, s| ret << "#{left}#{l}#{space[w - s]}#{right}" }
         end
 
         return ret.fill(empty, ret.size, bottom) if bottom > 0
         ret.empty? ? ret << '' : ret
       end
 
+      # Format lines with alignment.
+      #
+      # Like {#format} without padding, prefix, and suffix.
+      #
+      # @see #format
+      #
+      # @example
+      #   Terminal::Text::Formatter.new('Hi').fmt(align: :right, width: 6)
+      #   # => ["    Hi"]
+      #
+      # @param align (see #format)
+      # @param width (see #format)
+      # @param height (see #format)
+      # @return (see #format)
+      # @raise (see #format)
+      def fmt(width: nil, height: nil, align: nil)
+        if height
+          return [] if (height = height.to_i) == 0
+          height = -height if (tail = (height < 0))
+        end
+
+        lines =
+          if width
+            w = (width = width.to_i)
+            raise(ArgumentError, "invalid width - #{width.inspect}") if w < 1
+            _limited(w)
+          else
+            @unlimited || _unlimited
+          end
+
+        return [+''] if lines.empty?
+
+        lines = tail ? lines.last(height) : lines.take(height) if height
+        w ||= lines.max_by(&:last)[-1] # unless width
+
+        return lines.map(&:first) unless align
+        space = SPACE_CACHE.dup
+        return lines.map { |l, s| "#{space[w - s]}#{l}" } if align == :right
+        return lines.map { |l, s| "#{l}#{space[w - s]}" } if align != :center
+        lines.map do |l, s|
+          rs = ((s = w - s) / 2.0).round
+          rs < 1 ? l : "#{space[s - rs]}#{l}#{space[rs]}"
+        end
+      end
+
       # Whether the formatter has any content.
       #
       # @return [true, false]
@@ -229,8 +307,8 @@ module Terminal
       # Maximum display width of any line.
       #
       # @example
-      #   fmt = Terminal::Text::Formatter.new("short\na longer line")
-      #   fmt.max_line_width # => 13
+      #   formatter = Terminal::Text::Formatter.new("short\na longer line")
+      #   formatter.max_line_width # => 13
       #
       # @return [Integer] widest line in columns, `0` when empty
       def max_line_width
@@ -352,9 +430,7 @@ module Terminal
           next if current.is_a?(Space) # ignore trailing space
 
           # handle Word...
-          splitted = current.split(width)
-          last = splitted.pop
-
+          *splitted, last = current.split(width)
           if csi.empty?
             splitted.each { ret << [it.to_str, it.size] }
           else
@@ -368,7 +444,10 @@ module Terminal
           size = last.size
         end
 
-        ret.pop if ret[-1] == ['', 0]
+        if ret.size > 1
+          str, width = ret[-1]
+          ret.pop if width == 0 && str.empty?
+        end
         ret
       end
 
@@ -596,11 +675,10 @@ module Terminal
             @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]
+                next chunk.each_char { chars << it and sizes << 1 }
               end
+              chars << chunk
+              sizes << @sizes[idx]
             end
           else
             chars = @chunks
@@ -676,7 +754,7 @@ module Terminal
         | \e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\)
         | \s
         | \X
-      /x
+        /x
 
       SPACE_BYTE =
         Hash

data/lib/terminal/text.rb

@@ -42,7 +42,7 @@ module Terminal
       # @example
       #   Terminal::Text.width('Hello')                          # => 5
       #   Terminal::Text.width('[bold]Hi[/bold]')                # => 2
-      #   Terminal::Text.width('[bold]Hi[/bold]', bbcode: false) # => 14
+      #   Terminal::Text.width('[bold]Hi[/bold]', bbcode: false) # => 15
       #
       # @param str [#to_s] the string to measure
       # @param bbcode (see Formatter#initialize)
@@ -106,11 +106,30 @@ module Terminal
       #
       # @see Formatter.format
       #
+      # @example
+      #   Terminal::Text.format(
+      #     'Hello World', width: 9, align: :left, prefix: '| ', suffix: ' |'
+      #   )
+      #   # => ["| Hello     |", "| World     |"]
+      #
       # @param (see Formatter.format)
       # @return (see Formatter.format)
       # @raise (see Formatter.format)
       def format(...) = Formatter.format(...)
 
+      # Format text with alignment.
+      #
+      # @see Formatter.fmt
+      #
+      # @example
+      #   Terminal::Text.fmt('Hi', align: :center, width: 10)
+      #   # => ["    Hi    "]
+      #
+      # @param (see Formatter.fmt)
+      # @return (see Formatter.fmt)
+      # @raise (see Formatter.fmt)
+      def fmt(...) = Formatter.fmt(...)
+
       # @deprecated Use {.lines} and iterate over the result.
       #
       # @comment @param str [Array<#to_s>] text to process
@@ -163,7 +182,7 @@ module Terminal
       )
         warn(
           '[DEPRECATED] `each_line_with_size` is deprecated ' \
-            '– use `.lines_width_size.each` instead',
+            '– use `.lines_with_size.each` instead',
           category: :deprecated,
           uplevel: 1
         )
@@ -212,7 +231,6 @@ module Terminal
       def char_width(char)
         ord = char.ord
         return @ctrlchar_width[ord] if ord < 0x20
-        # 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
@@ -220,7 +238,7 @@ module Terminal
         char.each_codepoint do |cp|
           next skip = false if skip
           next skip = true if cp == 0x200d # zero width joiner
-          sum += CharWidth[cp]
+          sum += cp < 0xa1 ? 1 : CharWidth[cp]
         end
         sum
       end
@@ -231,7 +249,6 @@ module Terminal
       "🏳\u{FE0F}\u{200D}⚧\u{FE0F}" # transgender flag
     ].freeze
 
-    # indexed by ordinal, only ever asked for control characters
     @ctrlchar_width = [
       0,
       1,

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -72,28 +72,52 @@ module Terminal
 
     # Execute a shell command.
     #
-    # @overload sh(*cmd, **options)
-    #   Run a command and capture output.
+    # Output lines are collected or yielded without their trailing newline.
+    #
+    # @overload sh(*cmd, env: {}, shell: false, input: nil, **options)
+    #   Run a command and capture its output.
+    #
+    #   @example
+    #     status, output, error = Terminal.sh('echo', 'hello')
+    #     output # => ["hello"]
+    #
     #   @param cmd [Array<String>] command and arguments
-    #   @param options [Hash] options passed to the shell runner
+    #   @param env [Hash] environment variables for the command
+    #   @param shell [true, false]
+    #     when true the `cmd` is executed via the shell,
+    #     when false, the executable is direct executed
+    #     (see `Process.spawn` for this)
+    #   @param input [String, IO, Array<String>, Enumerable, nil]
+    #     data written to the command's standard input
+    #   @param options [Hash] passed to `Process.spawn`
+    #     (`:in`, `:out`, `:err` are ignored)
     #   @return [Array<Process::Status, Array<String>, Array<String>>]
     #     `[status, stdout_lines, stderr_lines]`
+    #   @return [nil] when the command can not be executed
+    #
+    # @overload sh(*cmd, env: {}, shell: false, input: nil, **options, &block)
+    #   Run a command and stream its output to a block.
+    #
     #   @example
-    #     status, output, error = Terminal.sh('echo', 'hello')
-    #     output # => ["hello\n"]
+    #     Terminal.sh('make') do |line, type|
+    #       Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
+    #     end
     #
-    # @overload sh(*cmd, **options, &block)
-    #   Run a command and stream output to a block.
     #   @param cmd [Array<String>] command and arguments
-    #   @param options [Hash] options passed to the shell runner
+    #   @param env [Hash] environment variables for the command
+    #   @param shell [true, false]
+    #     when true the `cmd` is executed via the shell,
+    #     when false, the executable is direct executed
+    #     (see `Process.spawn` for this)
+    #   @param input [String, IO, Array<String>, Enumerable, nil]
+    #     data written to the command's standard input
+    #   @param options [Hash] passed to `Process.spawn`
+    #     (`:in`, `:out`, `:err` are ignored)
     #   @yield [line, type] called for each output line
     #   @yieldparam line [String] the output line
     #   @yieldparam type [Symbol] `:output` or `:error`
     #   @return [Process::Status] the exit status
-    #   @example
-    #     Terminal.sh('make') do |line, type|
-    #       Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
-    #     end
+    #   @return [nil] when the command can not be executed
     #
     # @raise [ArgumentError] if no command is given
     def sh(*cmd, **, &)
@@ -101,7 +125,8 @@ module Terminal
       return Shell.run(*cmd, **, &) if block_given?
       out = []
       err = []
-      [Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }, out, err]
+      ret = Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }
+      [ret, out, err] if ret
     end
 
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.0.9
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -60,7 +60,7 @@ 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.8
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.9
 rdoc_options: []
 require_paths:
 - lib
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise line
   break support and much more.