terminal_rb 0.19.0 → 1.0.3

data/lib/terminal/detect.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Terminal
+  # @private
   module Detect
     class << self
       def application

data/lib/terminal/input/ansi.rb

@@ -1,45 +1,47 @@
 # frozen_string_literal: true
 
 module Terminal
+  # @private
   module AnsiInput
     attr_reader :input_mode
 
     def on_key_event(mouse: false, mouse_move: false, focus: false)
       raise('already reading key events') if (@in_recursion += 1) != 1
       return unless block_given?
-      opts = __in_option(mouse, mouse_move, focus)
-      opts &&= @in.syswrite("#{opts}h") ? "#{opts}l" : nil
-      while (raw = @in.getch)
-        (yield(KeyEvent[raw]) ? next : break) if raw != "\e"
-        lesci = 0
-        while String === (nc = @in.read_nonblock(1, exception: false))
-          lesci = raw.size if nc == "\e"
-          raw << nc
+      opts = __input_option(mouse, mouse_move, focus)
+      STDIN.noecho do
+        opts &&= @in.syswrite("#{opts}h") ? "#{opts}l" : nil
+        while (raw = @in.getch)
+          next yield(KeyEvent[raw]) if raw != "\e"
+          while String === (nc = @in.read_nonblock(1, exception: false))
+            raw << nc
+          end
+          next yield(KeyEvent[raw]) if raw.rindex("\e") < 2
+          raw[0] = ''
+          raw.split("\e").each { yield(KeyEvent["\e#{it}"]) }
         end
-        (yield(KeyEvent[raw]) ? next : break) if lesci < 2
-        break unless raw[1..].split("\e").all? { yield(KeyEvent["\e#{_1}"]) }
       end
     rescue IOError, SystemCallError
       __input_error
       false
     ensure
       @in_recursion -= 1
-      @in&.syswrite(opts) if opts
+      @in.syswrite(opts) if opts && @in
     end
 
     private
 
-    def __in_option(mouse, mouse_move, focus)
-      opts = +(mouse ? '1000' : '')
+    def __input_option(mouse, mouse_move, focus)
+      opts = (mouse ? ['1000'] : [])
       # highlight: '1001'
       # drag: '1002'
-      opts << ';1003' if mouse_move
-      opts << ';1004' if focus
+      opts << '1003' if mouse_move
+      opts << '1004' if focus
       # ext: '1005'
       # sgr: '1006'
       # urxvt: '1015'
       # pixel: '1016'
-      "\e[?#{opts};1006" unless opts.empty?
+      "\e[?#{opts.join(';')};1006" unless opts.empty?
     end
   end
 

data/lib/terminal/input/dumb.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
 module Terminal
+  # @private
   module DumpInput
     def input_mode = :dumb
 
     def on_key_event(*_)
       raise('already reading key events') if (@in_recursion += 1) != 1
       return unless block_given?
-      while (raw = __getc)
+      while (raw = STDIN.getc)
         opts = dumb_keys[raw.ord] if raw.size == 1
-        return unless yield(KeyEvent.new(raw, *opts))
+        yield(KeyEvent.new(raw, *opts))
       end
+    rescue Interrupt
+      yield(KeyEvent.new("\x05", 'c', 4))
     rescue IOError, SystemCallError
       __input_error
       false
@@ -30,12 +33,6 @@ module Terminal
         0x1b => :Esc
       }.compare_by_identity.freeze
     end
-
-    def __getc
-      STDIN.getc
-    rescue Interrupt
-      "\x05"
-    end
   end
 
   private_constant :DumpInput

data/lib/terminal/input/key_event.rb

@@ -1,68 +1,95 @@
 # frozen_string_literal: true
 
 module Terminal
+  # Represents a keyboard, mouse, or focus event read from the terminal.
   #
-  # Key event reported from {read_key_event} and {on_key_event}.
+  # Instances are immutable (frozen) and may be cached for performance.
   #
+  # @see Terminal.on_key_event
+  # @see Terminal.read_key_event
+  #
+  # @example Parse a raw escape sequence
+  #   event = Terminal::KeyEvent["\r"]
+  #   event.key     # => :Enter
+  #   event.name    # => "Enter"
+  #   event.simple? # => true
+  #
+  # @example Inspect modifier keys
+  #   event = Terminal::KeyEvent["\e[1;5A"]
+  #   event.key       # => :Up
+  #   event.name      # => "Ctrl+Up"
+  #   event.modifier? # => true
+  #   event.modifiers # => [:Ctrl]
   class KeyEvent
-    # Pressed key without any modifiers.
-    # This can be a string for simple keys like `"a"` or a Symbol like `:F12`
-    # (see {.key_names}).
-    # @return [String, Symbol] key without modifiers
+    # The key identifier.
+    #
+    # @return [Symbol, String, nil] a named key like +:Enter+, +:Tab+,
+    #   +:MBLeft+ (mouse), or a character string like +"a"+; +nil+ for
+    #   unknown sequences
     attr_reader :key
 
-    # Modifier key code. This represents the encoded key modifier like `Shift`
-    # or `Alt`.
+    # Bitmask of active modifier keys.
     #
-    # @return [Integer] modifier key code
-    attr_reader :modifier
+    # @see #modifiers
+    # @see #modifier?
+    #
+    # @return [Integer] modifier_bits bitmask
+    attr_reader :modifier_bits
 
+    # Names of active modifier keys.
+    #
+    # @see #modifier?
+    #
+    # @return [Array<Symbol>] modifier names
+    attr_reader :modifiers
+
+    # Whether any modifier keys are active.
+    #
+    # @see #modifiers
+    #
     # @attribute [r] modifier?
-    # @return [true, false] whether a key modifier was pressed
-    def modifier? = @modifier != 0
+    # @return [true, false]
+    def modifier? = @modifier_bits != 0
 
-    # Name of the key event.
-    # This can be a simple name like `"a"` or `"Shift+Ctrl+F12"` for combined
-    # keys.
+    # Human-readable name including modifier and key.
+    #
+    # @example
+    #   Terminal::KeyEvent["\e[1;5A"].name # => "Ctrl+Up"
     #
-    # @return [String] key name
+    # @return [String] e.g. `"Ctrl+Alt+a"` or `"Enter"`
     attr_reader :name
 
-    # Mouse event position.
+    # Mouse position when this is a mouse event.
     #
-    # @return [[Integer,Integer]] row and column
-    # @return nil when no coordinates are assigned
+    # @return [Array<Integer, Integer>, nil] +[row, column]+ for mouse
+    #   events, +nil+ for keyboard events
     attr_reader :position
 
-    # ANSI code sequence received from standard input.
-    # This can be a simple value like `"a"`or more complex input like
-    # `"\e[24;6~"` (for Shift+Ctrl+F12).
+    # The raw input sequence as received from the terminal.
     #
-    # @return [String] received ANSI code sequence
+    # @return [String]
     attr_reader :raw
 
+    # Whether the raw input equals the name (no modifier, no special
+    # decoding needed).
+    #
     # @attribute [r] simple?
-    # @return [true, false] whether a simple key was pressed
+    # @return [true, false]
     def simple? = @raw == @name
 
-    # All pressed keys.
-    # This is composed by all {modifier} and the {key}.
-    #
-    # @example
-    #   Terminal::KeyEvent["\e\r"].to_a
-    #   => [:Alt, :Enter]
-    #   Terminal::KeyEvent['a'].to_a
-    #   => ['a']
-    #   Terminal::KeyEvent["\e[<12;45;30m"].to_a
-    #   => [:Shift, :Alt, :MBLeftUp]
+    # Modifier names followed by the key.
     #
-    # @return [Array<Symbol, String>] all pressed keys
+    # @return [Array<Symbol, String>]
     def to_a = @ary.dup
 
     # @private
+    # Destructuring-friendly array representation.
+    #
+    # @return [Array<String>] +[raw]+ if {#simple?}
+    # @return [Array<String, String>] +[raw, name]+ otherwise
     def to_ary = simple? ? [@raw] : [@raw, @name]
 
-    # @private
+    # @return [String] the event {#name}
     def to_s = @name.dup
 
     # @private
@@ -73,48 +100,66 @@ module Terminal
       @raw.freeze
       @key.freeze
       @position.freeze
+      @modifiers.freeze
       @name.freeze
       super
     end
 
     private
 
-    def initialize(raw, key, modifier, position)
+    def initialize(raw, key, modifier_bits, position)
       @raw = raw
       @key = key
-      @modifier = modifier
+      @modifier_bits = modifier_bits
+      @modifiers =
+        MODIFIERS.filter_map { |b, n| n if modifier_bits.allbits?(b) }
       @position = position
-      @ary = MODIFIERS.filter_map { |b, n| n if (modifier & b) == b }
+      @ary = @modifiers.dup
       @ary << key if key
       @name = @ary.join('+')
     end
 
     class << self
-      # @attribute [w] caching
-      # @return [true, false] whether {KeyEvent}s should be cached
-      def caching = !!@cache
+      # Whether key event caching is enabled.
+      # When enabled, parsed events are frozen and reused for identical
+      # raw input sequences.
+      #
+      # @attribute [rw] caching
+      # @return [true, false]
+      def caching = @cache != nil
 
-      # @attribute [w] caching
       def caching=(value)
         value ? @cache ||= {} : @cache = nil
       end
 
-      # @attribute [r] key_names
-      # @return [Array<Symbol>] list of all avilable key names (see {key})
+      # All recognized key name symbols.
+      #
+      # @return [Array<Symbol>] sorted unique key names
       def key_names
         (
           @names ||=
             (@csiu.values + @csi.values + @ss3.values)
               .uniq
-              .keep_if { Symbol === _1 }
+              .keep_if { Symbol === it }
               .sort!
         ).dup
       end
 
-      # Translate an ANSI input code sequence into a related KeyEvent.
+      # Parse a raw terminal input sequence into a KeyEvent.
+      #
+      # Supports single characters, ESC sequences, CSI-u protocol,
+      # legacy function keys, and mouse events (VT200 and SGR format).
       #
-      # @param raw [String] keyboard, mouse or focus event sequence
-      # @return [KeyEvent] related key event
+      # @example Parse a single character
+      #   Terminal::KeyEvent['a'].key # => "a"
+      # @example Parse escape sequence
+      #   Terminal::KeyEvent["\e[A"].key # => :Up
+      # @example Parse mouse event
+      #   Terminal::KeyEvent["\e[<0;10;5M"].key # => :MBLeft
+      #
+      # @param raw [String] the raw escape sequence or single character
+      # @return [KeyEvent] the parsed event (frozen; cached when caching
+      #   is enabled)
       def [](raw)
         cached = @cache[raw] and return cached if @cache
         return new(raw, *@single_key[raw.ord]) if raw.size == 1
@@ -127,8 +172,8 @@ module Terminal
           return new(raw, *@ss3[raw[2].ord]) if raw.size == 3 # ESC O ?
         when '['
           return new(raw, *@ss3[raw[2].ord]) if raw.size == 3 # ESC [ ?
-          if raw.size == 6 && raw[2] == 'M' # ESC [ M b c r
-            return mouse_vt200(raw)
+          if raw.size == 6 && raw[2] == 'M'
+            return mouse_vt200(raw) # ESC [ M b c r
           end
           if raw.size > 4 && raw[2] == '1' && raw[3] == ';'
             return csi(raw) # ESC [ 1 ; ...
@@ -148,7 +193,7 @@ module Terminal
       end
 
       # @private
-      def new(raw, key = raw, modifier = 0, position = nil)
+      def new(raw, key = raw, modifier_bits = 0, position = nil)
         (@cache && position.nil? ? @cache[raw] ||= super : super).freeze
       end
 
@@ -158,8 +203,8 @@ module Terminal
 
       def esc1(raw, char)
         # ESC ?
-        key, modifier = @esc1[char.ord]
-        new(raw, key || char, modifier || 2)
+        key, modifier_bits = @esc1[char.ord]
+        new(raw, key || char, modifier_bits || 2)
       end
 
       def esc_esc(raw)
@@ -167,18 +212,18 @@ module Terminal
         # ESC ESC ...
         return esc1(raw, raw[2]) if raw.size == 3
         ret = self[raw[1..]]
-        new(raw, ret.key, ret.modifier | 2)
+        new(raw, ret.key, ret.modifier_bits | 2)
       end
 
       def csi(raw)
         # ESC [ 1 ; [~ABCDEFHPQRS]
-        # ESC [ 1 ; <modifier> [~ABCDEFHPQRS]
+        # ESC [ 1 ; <modifier_bits> [~ABCDEFHPQRS]
         return unknown(raw) if raw.size < 5
-        key, modifier = @ss3[raw[-1].ord]
-        modifier ||= 0
-        return new(raw, nil, modifier) unless key
-        modifier |= [raw[4..-2].to_i - 1, 0].max if raw.size > 5
-        new(raw, key, modifier)
+        key, modifier_bits = @ss3[raw[-1].ord]
+        modifier_bits ||= 0
+        return new(raw, nil, modifier_bits) unless key
+        modifier_bits |= [raw[4..-2].to_i - 1, 0].max if raw.size > 5
+        new(raw, key, modifier_bits)
       end
 
       def legacy(raw)
@@ -208,7 +253,7 @@ module Terminal
 
       def mouse_vt200(raw)
         # ESC [ M <btn> <col> <row>
-        mouse_event(raw, *raw[3..].chars.map! { _1.ord - 32 })
+        mouse_event(raw, *raw[3..].chars.map! { it.ord - 32 })
       end
 
       def mouse_sgr(raw)
@@ -228,25 +273,36 @@ module Terminal
         return unknown(raw) if btn < 0 || col < 1 || row < 1
         key = (btn & 1).nonzero? ? 1 : 0
         key += 2 if btn.allbits?(2)
-        modifier = btn.allbits?(4) ? 1 : 0
-        modifier += 2 if btn.allbits?(8)
-        modifier += 4 if btn.allbits?(16)
-        modifier += 256 if moved = btn.allbits?(32)
+        modifier_bits = btn.allbits?(4) ? 1 : 0
+        modifier_bits += 2 if btn.allbits?(8)
+        modifier_bits += 4 if btn.allbits?(16)
+        modifier_bits += 256 if moved = btn.allbits?(32)
         key += 4 if btn.allbits?(64)
         key += 8 if btn.allbits?(128)
-        new(raw, mouse_name(key, up, moved), modifier, [row, col])
+        new(raw, mouse_name(key, up, moved), modifier_bits, [row, col])
       end
 
       def mouse_name(key, up, moved)
-        return up ? :MBLeftUp : :MBLeft if key == 0
-        return up ? :MBMiddleUp : :MBMiddle if key == 1
-        return up ? :MBRightUp : :MBRight if key == 2
-        return moved ? :Mouse : :MBUp if key == 3
-        return :MWUp if key == 4
-        return :MWDown if key == 5
-        return :MWLeft if key == 6
-        return :MWRight if key == 7
-        :"MB_#{key - 8}#{'Up' if up}"
+        case key
+        when 0
+          up ? :MBLeftUp : :MBLeft
+        when 1
+          up ? :MBMiddleUp : :MBMiddle
+        when 2
+          up ? :MBRightUp : :MBRight
+        when 3
+          moved ? :Mouse : :MBUp
+        when 4
+          :MWUp
+        when 5
+          :MWDown
+        when 6
+          :MWLeft
+        when 7
+          :MWRight
+        else
+          :"MB_#{key - 8}#{'Up' if up}"
+        end
       end
     end
 

data/lib/terminal/input.rb

@@ -3,64 +3,73 @@
 require 'io/console'
 
 module Terminal
+  #
   # @!group Attributes
+  #
 
   # @attribute [r] self.input_mode
   #
-  # Supported input mode.
-  #
-  # @return [:csi_u]
-  #   when [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol)
-  #   supported
-  # @return [:legacy]
-  #   for standard terminal
-  # @return [:dumb]
-  #   for non-interactive input (pipes etc.)
-  # @return [:error]
-  #   when input device is not avail (closed)
+  # Detect and return the current input mode.
+  #
+  # @example
+  #   Terminal.input_mode # => :csi_u
+  #
+  # @attribute [r] input_mode
+  # @return [Symbol] +:csi_u+, +:legacy+, +:dumb+, or +:error+
 
+  #
   # @!endgroup
-
+  #
   # @!group Input methods
-
-  # @!method self.read_key_event
-  #   Read next {KeyEvent} from standard input.
   #
-  #   @return [KeyEvent] next event
-  #   @return [nil] in error case
 
   # @!method self.on_key_event(mouse: false, mouse_move: false, focus: false, &block)
-  #   Event loop for key and mouse events.
-  #
-  #   @param mouse [true, false]
-  #     whether mouse buttons should be reported
-  #   @param mouse_move [true, false]
-  #     whether mouse movement should be reported
-  #   @param focus [true, false]
-  #     whether focus/unfocus of terminal window should be reported
-  #   @yieldparam event [KeyEvent]
-  #     next event
-  #   @yieldreturn [true, false]
-  #     whether the loop should be continued
-  #   @return [true]
-  #     when the loop was started
-  #   @return [false]
-  #     when the current input device is not available
-  #   @return [nil]
-  #     when no block was given
+  #
+  #   Enter a key event loop, yielding each event to the block.
+  #
+  #   Enables optional mouse and focus event reporting. The block
+  #   receives {KeyEvent} instances until input ends or the block
+  #   breaks.
+  #
+  #   @example
+  #     Terminal.on_key_event(mouse: true) do |event|
+  #       break if event.name == 'ESC'
+  #       puts event.name
+  #     end
+  #
+  #   @param mouse [true, false] enable mouse button events
+  #   @param mouse_move [true, false] enable mouse move events
+  #   @param focus [true, false] enable terminal focus/unfocus events
+  #   @yield [event] called for each input event
+  #   @yieldparam event [KeyEvent] the parsed key event
+  #   @return [nil, false] +false+ on I/O error
+  #   @raise [RuntimeError] if already inside a key event loop
+
+  # @!method self.read_key_event
+  #
+  #   Read a single key event (blocking).
+  #
+  #   @example
+  #     event = Terminal.read_key_event
+  #     puts "You pressed: #{event.name}"
+  #
+  #   @return [KeyEvent, false] the next key event, or +false+ on error
 
+  #
   # @!endgroup
+  #
 
+  # @private
   module Input
     def input_mode
       @in_recursion = 0
       case @input_mode = __find_input_mode
       when :legacy, :csi_u
         @in = IO.console
-        require_relative 'input/ansi'
+        require_relative('input/ansi')
         extend AnsiInput
       when :dumb
-        require_relative 'input/dumb'
+        require_relative('input/dumb')
         extend DumpInput
       else
         __input_error
@@ -68,12 +77,12 @@ module Terminal
       @input_mode
     end
 
-    def on_key_event(mouse: false, mouse_move: false, focus: false, &block)
+    def on_key_event(mouse: false, mouse_move: false, focus: false, &)
       input_mode
-      on_key_event(mouse: mouse, mouse_move: mouse_move, focus: focus, &block)
+      on_key_event(mouse:, mouse_move:, focus:, &)
     end
 
-    def read_key_event = on_key_event { return _1 }
+    def read_key_event = on_key_event { return it }
 
     private
 
@@ -94,10 +103,12 @@ module Terminal
       return :legacy if im == 'legacy'
       return :dumb if im == 'dumb' || !STDIN.tty?
       con = IO.console
-      return :legacy if con.syswrite("\e[>1u\e[?u\e[c") != 12
-      inp = +''
-      inp << con.getch until inp.rindex('c')
-      return :legacy unless inp.include?("\e[?1u")
+      STDIN.noecho do
+        return :legacy if con.syswrite("\e[>1u\e[?u\e[c") != 12
+        inp = +''
+        inp << con.getch until inp.rindex('c')
+        return :legacy unless inp.include?("\e[?1u")
+      end
       at_exit do
         IO.console.syswrite("\e[<u")
       rescue StandardError

data/lib/terminal/output/ansi.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Terminal
+  # @private
   module AnsiOutput
     def output_mode = :ansi
     def ansi? = true
@@ -40,8 +41,8 @@ module Terminal
       @con = nil
     end
 
-    def raw_write(str)
-      @out.syswrite(str)
+    def raw_write(object)
+      @out.syswrite(object)
     rescue IOError, SystemCallError
       __output_error(nil)
     end
@@ -56,15 +57,48 @@ module Terminal
     def print(*objects, bbcode: true)
       return if objects.empty?
       return @out.print(*objects) unless bbcode
-      @out.print(*objects.map! { Ansi.bbcode(_1) })
+      @out.print(*objects.map! { Ansi.bbcode(it) })
     rescue IOError, SystemCallError
       __output_error(nil)
     end
 
     def puts(*objects, bbcode: true)
-      return @out.puts(objects.empty? ? nil : objects) unless bbcode
       objects.flatten!
-      @out.puts(objects.empty? ? nil : objects.map! { Ansi.bbcode(_1) })
+      return @out.puts if objects.empty?
+      return @out.puts(objects) unless bbcode
+      @out.puts(objects.map! { Ansi.bbcode(it) })
+    rescue IOError, SystemCallError
+      __output_error(nil)
+    end
+
+    def fputs(
+      *objects,
+      bbcode: true,
+      spaces: true,
+      eol: true,
+      align: nil,
+      width: columns,
+      height: nil,
+      padding: nil,
+      prefix: nil,
+      suffix: nil
+    )
+      objects.flatten!
+      @out.puts(
+        Text::Formatter.format(
+          *objects,
+          ansi: true,
+          bbcode:,
+          spaces:,
+          eol:,
+          align:,
+          width:,
+          height:,
+          padding:,
+          prefix:,
+          suffix:
+        )
+      )
     rescue IOError, SystemCallError
       __output_error(nil)
     end
@@ -101,7 +135,11 @@ module Terminal
     def __init_tty
       require('io/console')
       @con = IO.console
-      Signal.trap('WINCH') { @size = nil } if Signal.list.key?('WINCH')
+      return unless Signal.list.key?('WINCH')
+      Signal.trap('WINCH') do
+        @size = nil
+        @on_resize&.call
+      end
     end
 
     private_class_method def self.extended(mod)