terminal_rb 0.17.2 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b65682d28124ce6b98d36529cf9eca06274f773c57e6282de858b7315ad4bccc
-  data.tar.gz: 774c2f114d5fb2049226abbafd926b8bd5f5da8661f5a31182322ee015079c14
+  metadata.gz: 76294a5517d1c24b4c85f855cf802ce01dd1fa574dfac92753edd78b7a8fd465
+  data.tar.gz: 3e95e7b5ae8f40a9e284cdd3abddbd5a77a70e0a4df40e0deed2702acaf2ed07
 SHA512:
-  metadata.gz: 53b711bfccc5b09faafe235a1ddf38ab422157fc95942e4be91e3cc0b4d1b35388a98f5f382cd206ae7435cc41499c4a44ef630b3a59d282d93e8b18569b1232
-  data.tar.gz: 71138798500123c3aa36c5eb2b470150f392294828da4fb6bca972613228cc2b777aa4f4c9d0e5178798efd3bbbc3497c943445de651a51c2a03e2263a40bbe5
+  metadata.gz: 99e9e190caea636278031df7116ce0fdaf15fa6fdf2c6c1912906862341eae25e3b6aacc77296aca15b833e4548cbad36edf7f41160fc313059c6ecbe472fb2a
+  data.tar.gz: 0b5cbc5ef6ed87179d6b74663607bec29c07ad53ca4fc7c1593577214e31d5b08281fa68a119be361eb4ce720420767d09690b5679ee2f6e43ef3061c40b7ec7

data/README.md

@@ -4,7 +4,7 @@ Terminal.rb supports you with input and output on your terminal. Simple [BBCode]
 
 - 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/Terminal)
+- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/0.19.0/Terminal)
 
 ## Features
 
@@ -60,7 +60,7 @@ TEXT
 # =>  "attribute syntax."]
 ```
 
-Have a look at the [examples](./examples/) directory to learn from code.
+Have a look at the [examples](https://codeberg.org/mblumtritt/Terminal.rb/src/branch/main/examples) directory to learn from code.
 
 ## Installation
 
@@ -70,7 +70,7 @@ You can install the gem in your system with
 gem install terminal_rb
 ```
 
-or you can use [Bundler](http://gembundler.com/) to add Terminal.rb to your own project:
+or you can use [Bundler](https://bundler.io) to add Terminal.rb to your own project:
 
 ```shell
 bundle add terminal_rb

data/bin/bbcode

@@ -42,5 +42,5 @@ rescue IOError, SystemCallError => e
   $stderr.puts "#{me}-error: #{e.message.gsub(/@ \w+ /, '')}"
   exit 1
 rescue Interrupt
-  exit 138
+  exit 130
 end

data/lib/terminal/input/ansi.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Terminal
+  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
+        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
+    end
+
+    private
+
+    def __in_option(mouse, mouse_move, focus)
+      opts = +(mouse ? '1000' : '')
+      # highlight: '1001'
+      # drag: '1002'
+      opts << ';1003' if mouse_move
+      opts << ';1004' if focus
+      # ext: '1005'
+      # sgr: '1006'
+      # urxvt: '1015'
+      # pixel: '1016'
+      "\e[?#{opts};1006" unless opts.empty?
+    end
+  end
+
+  private_constant :AnsiInput
+end

data/lib/terminal/input/dumb.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Terminal
+  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)
+        opts = dumb_keys[raw.ord] if raw.size == 1
+        return unless yield(KeyEvent.new(raw, *opts))
+      end
+    rescue IOError, SystemCallError
+      __input_error
+      false
+    ensure
+      @in_recursion -= 1
+    end
+
+    private
+
+    def dumb_keys
+      @dumb_keys ||= {
+        0x05 => ['c', 4],
+        0x08 => :Back,
+        0x09 => :Tab,
+        0x0a => :Enter,
+        0x0d => :Return,
+        0x1b => :Esc
+      }.compare_by_identity.freeze
+    end
+
+    def __getc
+      STDIN.getc
+    rescue Interrupt
+      "\x05"
+    end
+  end
+
+  private_constant :DumpInput
+end

data/lib/terminal/input.rb

@@ -3,208 +3,117 @@
 require 'io/console'
 
 module Terminal
-  class << self
-    # Supported input mode.
-    #
-    # @attribute [r] 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)
+  # @!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)
+
+  # @!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
+
+  # @!endgroup
+
+  module Input
     def input_mode
-      @input_mode ||= find_input_mode
-    end
-
-    # Read next keyboard input.
-    #
-    # The input will be returned as named key codes like "Ctrl+c" by default.
-    # This can be changed by `mode`.
-    #
-    # @deprecated Use rather {read_key_event} for better input handling.
-    #
-    # @param mode [:named, :raw, :both] modifies the result
-    # @return [String] key code ("as is") in `:raw` mode
-    # @return [String] key name in `:named` mode
-    # @return [[String, String]] key code and key name in `:both` mode
-    # @return [nil] in error case
-    def read_key(mode: :named)
-      warn(
-        'Terminal.read_key is deprecaded; use Terminal.read_key_event instead.',
-        uplevel: 1
-      )
-      event = read_key_event or return
-      return event.raw if mode == :raw
-      key, name = event
-      mode == :both ? [key, name] : name || key
-    end
-
-    # Read next {KeyEvent} from standard input.
-    #
-    # @return [KeyEvent] next event
-    # @return [nil] in error case
-    def read_key_event
-      prevent_input_recursion do
-        case input_mode
-        when :dumb
-          raw = read_dumb or return
-          opts = @dumb_keys[raw.ord] if raw.size == 1
-          KeyEvent.new(raw, *opts)
-        when :csi_u, :legacy
-          raw = read_tty or return
-          KeyEvent[raw]
-        end
+      @in_recursion = 0
+      case @input_mode = __find_input_mode
+      when :legacy, :csi_u
+        @in = IO.console
+        require_relative 'input/ansi'
+        extend AnsiInput
+      when :dumb
+        require_relative 'input/dumb'
+        extend DumpInput
+      else
+        __input_error
       end
+      @input_mode
     end
 
-    # 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
     def on_key_event(mouse: false, mouse_move: false, focus: false, &block)
-      return unless block
-      prevent_input_recursion do
-        case input_mode
-        when :dumb
-          on_bumb_key_event(&block)
-          true
-        when :csi_u, :legacy
-          on_tty_key_event(mouse_option(mouse, mouse_move, focus), &block)
-          true
-        else
-          false
-        end
-      end
-    end
-
-    private
-
-    def prevent_input_recursion
-      if (@key_event += 1) != 1
-        raise(RuntimeError, 'already reading key events', caller(2))
-      end
-      begin
-        yield
-      ensure
-        @key_event -= 1
-      end
+      input_mode
+      on_key_event(mouse: mouse, mouse_move: mouse_move, focus: focus, &block)
     end
 
-    def mouse_option(mouse, mouse_move, focus)
-      opts = +(mouse ? '1000' : '')
-      # highlight: '1001'
-      # drag: '1002'
-      opts << ';1003' if mouse_move
-      opts << ';1004' if focus
-      # ext: '1005'
-      # sgr: '1006'
-      # urxvt: '1015'
-      # pixel: '1016'
-      "\e[?#{opts};1006" unless opts.empty?
-    end
+    def read_key_event = on_key_event { return _1 }
 
-    def on_tty_key_event(opts)
-      STDIN.noecho do |stdin|
-        opts &&= raw_write("#{opts}h") ? "#{opts}l" : nil
-        while (raw = stdin.getch)
-          (yield(KeyEvent[raw]) ? next : break) if raw != "\e"
-          lesci = 0
-          while String === (nc = stdin.read_nonblock(1, exception: false))
-            lesci = raw.size if nc == "\e"
-            raw << nc
-          end
-          (yield(KeyEvent[raw]) ? next : break) if lesci < 2
-          break unless raw[1..].split("\e").all? { yield(KeyEvent["\e#{_1}"]) }
-        end
-      end
-    rescue Interrupt
-      # nop
-    rescue IOError, SystemCallError
-      @input_mode = :error
-    ensure
-      raw_write(opts) if opts
-    end
+    private
 
-    def on_bumb_key_event
-      while (raw = read_dumb)
-        opts = @dumb_keys[raw.ord] if raw.size == 1
-        return unless yield(KeyEvent.new(raw, *opts))
+    def __input_error
+      class << self
+        alias input_mode input_mode
+        def input_mode = :error
+        alias read_key_event read_key_event
+        def read_key_event = false
+        alias on_key_event on_key_event
+        def on_key_event(*_) = false
       end
+      @in = nil
     end
 
-    def find_input_mode
+    def __find_input_mode
       im = ENV['INPUT_MODE']
       return :legacy if im == 'legacy'
       return :dumb if im == 'dumb' || !STDIN.tty?
-      STDIN.noecho do |stdin|
-        return :legacy unless raw_write("\e[>1u\e[?u\e[c")
-        inp = +''
-        inp << stdin.getch until inp.rindex('c')
-        return :legacy unless inp.include?("\e[?1u")
-        at_exit { raw_write("\e[<u") }
-        :csi_u
+      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")
+      at_exit do
+        IO.console.syswrite("\e[<u")
+      rescue StandardError
+        # nop
       end
+      :csi_u
     rescue Interrupt
       :legacy
     rescue IOError, SystemCallError
+      __input_error
       :error
     end
-
-    def read_dumb
-      STDIN.getc
-    rescue Interrupt
-      "\x05"
-    rescue IOError, SystemCallError
-      @input_mode = :error
-      nil
-    end
-
-    def read_tty
-      STDIN.noecho do |stdin|
-        if (key = stdin.getch) == "\e"
-          while (nc = stdin.read_nonblock(1, exception: false))
-            String === nc ? key << nc : break
-          end
-        end
-        key
-      end
-    rescue Interrupt
-      nil
-    rescue IOError, SystemCallError
-      @input_mode = :error
-      nil
-    end
   end
 
-  @dumb_keys = {
-    0x05 => ['c', 4],
-    0x08 => :Back,
-    0x09 => :Tab,
-    0x0a => :Enter,
-    0x0d => :Return,
-    0x1b => :Esc
-  }.compare_by_identity.freeze
-
-  @key_event = 0
+  extend Input
 
+  private_constant :Input
   autoload :KeyEvent, "#{__dir__}/input/key_event.rb"
 end

data/lib/terminal/output/ansi.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Terminal
+  module AnsiOutput
+    def output_mode = :ansi
+    def ansi? = true
+    def tui? = %i[csi_u legacy].include?(input_mode)
+    def colors = (@colors ||= Detect.colors)
+
+    def columns=(value)
+      self.size = [rows, value]
+    end
+
+    def pos
+      @con&.cursor
+    rescue IOError, SystemCallError
+      @con = nil
+    end
+
+    def pos=(pos)
+      @con&.cursor = pos
+    rescue IOError, SystemCallError
+      @con = nil
+    end
+
+    def rows=(value)
+      self.size = [value, columns]
+    end
+
+    def size
+      @size ||= @con&.winsize || __default_size
+    rescue IOError, SystemCallError
+      @con = nil
+      @size = __default_size
+    end
+
+    def size=(size)
+      @con&.winsize = size
+    rescue IOError, SystemCallError
+      @con = nil
+    end
+
+    def raw_write(str)
+      @out.syswrite(str)
+    rescue IOError, SystemCallError
+      __output_error(nil)
+    end
+
+    def <<(object)
+      @out.write(Ansi.bbcode(object)) if object != nil
+      self
+    rescue IOError, SystemCallError
+      __output_error(self)
+    end
+
+    def print(*objects, bbcode: true)
+      return if objects.empty?
+      return @out.print(*objects) unless bbcode
+      @out.print(*objects.map! { Ansi.bbcode(_1) })
+    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) })
+    rescue IOError, SystemCallError
+      __output_error(nil)
+    end
+
+    def hide_cursor
+      raw_write(Ansi::CURSOR_HIDE) if (@cc += 1) == 1
+      self
+    end
+
+    def show_cursor
+      raw_write(Ansi::CURSOR_SHOW) if @cc > 0 && (@cc -= 1).zero?
+      self
+    end
+
+    def show_alt_screen
+      raw_write(Ansi::SCREEN_ALTERNATE) if (@as += 1) == 1
+      self
+    end
+
+    def hide_alt_screen
+      raw_write(Ansi::SCREEN_ALTERNATE_OFF) if @as > 0 && (@as -= 1).zero?
+      self
+    end
+
+    private
+
+    def __output_error(ret)
+      require_relative 'dumb'
+      extend DumbOutput
+      @size = @cc = @as = nil
+      __output_error(ret)
+    end
+
+    def __init_tty
+      require('io/console')
+      @con = IO.console
+      Signal.trap('WINCH') { @size = nil } if Signal.list.key?('WINCH')
+    end
+
+    private_class_method def self.extended(mod)
+      mod.instance_variable_set(:@cc, 0)
+      mod.instance_variable_set(:@as, 0)
+    end
+  end
+
+  private_constant :AnsiOutput
+end

data/lib/terminal/output/dumb.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Terminal
+  module DumbOutput
+    def output_mode = :dumb
+    def ansi? = false
+    def tui? = false
+    def colors = 2
+    def pos = nil
+    def size = (@size ||= __default_size)
+    def hide_cursor = self
+    def show_cursor = self
+    def show_alt_screen = self
+    def hide_alt_screen = self
+
+    def columns=(_)
+      # nop
+    end
+
+    def pos=(_)
+      # nop
+    end
+
+    def rows=(_)
+      # nop
+    end
+
+    def size=(_)
+      # nop
+    end
+
+    def raw_write(_) = nil
+
+    def <<(object)
+      @out.write(Ansi.plain(object)) if object != nil
+      self
+    rescue IOError, SystemCallError
+      __output_error(self)
+    end
+
+    def print(*objects, bbcode: true)
+      return if objects.empty?
+      @out.print(*objects.map!(&(bbcode ? @plain : @undecorate)))
+    rescue IOError, SystemCallError
+      __output_error(nil)
+    end
+
+    def puts(*objects, bbcode: true)
+      objects.flatten!
+      return @out.puts if objects.empty?
+      @out.puts(*objects.map!(&(bbcode ? @plain : @undecorate)))
+    rescue IOError, SystemCallError
+      __output_error(nil)
+    end
+
+    private
+
+    def __output_error(ret)
+      class << self
+        def output_mode = :error
+        def <<(_) = self
+        def print(*_) = nil
+        def puts(*_) = nil
+      end
+      @out = @plain = @undecorate = nil
+      ret
+    end
+
+    private_class_method def self.extended(mod)
+      mod.instance_variable_set(:@plain, ->(s) { Ansi.plain(s) })
+      mod.instance_variable_set(:@undecorate, ->(s) { Ansi.undecorate(s) })
+    end
+  end
+
+  private_constant :DumbOutput
+end