terminal_rb 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ccb3312146fca100bd13e4c079e5cf6f4a33e73ef9eb526765df1309ae5168e
-  data.tar.gz: ce4f5679183067ac7f7d84196db0ad9a06a22878fda79ec302fbacc8047699fa
+  metadata.gz: a718915d07704084ceeb6a395a4a40d97feb52c17048f8024b3493afb0d8a1c5
+  data.tar.gz: 252bb2965c7b5d33e58fb0752e1bb171cbe259de315494f5e547803554c843a7
 SHA512:
-  metadata.gz: 8a898bce2dc22f5b1d873ace6cef5ea53046318d68bc80062898ec7be43553acde5a7709c1b1043666533e91fbecec3e66dd0372c0adb1642803b4273f0c91d0
-  data.tar.gz: d9a06bd5ef76f97a0331bb2e05681fae5103dbe69a21c8e5ac0b97cb7342a6569d0e595b90b00744f22ed9253fc858fdbcd8e81e37ce595bfd1bb830c5cea2b9
+  metadata.gz: 9d006c4e463e3522b3e3c63bd343d2806cf4dd11bdaa6e9cf82b73ee7fe84d40296b9d919d3b0ea7664edca354e28e99302e0e01b87f04e5fa0dd5ccecd4a6b2
+  data.tar.gz: bb3a2b01dbd455bd66c2dbddcbd29dfca325d134b40b34b1de14168cb8c0c20be001f0bd20e78cd64f18a56bde7fe17a73673e7d7c249cb446cafeaef1c27f80

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/index)
+- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/0.18.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
 

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

data/lib/terminal/output.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module Terminal
+  class << self
+    # @!group Attributes
+
+    # @attribute [r] tui?
+    #
+    # Return `true` if the current terminal supports ANSI control codes for
+    # input _and_ output.
+    # In this case not only all output methods ({<<}, {print}, {puts}) will
+    # forward ANSI control codes to the terminal and translate BBCode
+    # (see {Ansi.bbcode}). But also the input methods {read_key_event} and
+    # {on_key_event} will support extended key codes, mouse  and focus events.
+    #
+    # @see output_mode
+    # @see ansi?
+    #
+    # @return [true, false]
+    #   whether ANSI control codes are supported for input and output
+
+    # @attribute [r] output_mode
+    #
+    # Supported output mode.
+    #
+    # @return [:ansi]
+    #   All output methods ({<<}, {print}, {puts}) will forward ANSI control
+    #   codes to the terminal and translate BBCode (see {Ansi.bbcode}).
+    # @return [:dumb]
+    #   All output methods will not forward ANSI control codes and BBCodes will
+    #   be removed.
+    #   The {colors} method will just return 2 (two).
+    # @return [:error]
+    #   When the output device signaled an error or was closed, nothing will
+    #   be written to the terminal.
+
+    # @!endgroup
+
+    # @!group Output attributes
+
+    # @attribute [r] ansi?
+    #
+    # @see output_mode
+    # @see tui?
+    #
+    # @return [true, false]
+    #   whether ANSI control codes are supported for output
+
+    # @attribute [r] colors
+    #
+    # Number of supported colors.
+    # The detection checks various conditions to find the correct value. The
+    # most common values are
+    #
+    # - `16_777_216` for 24-bit encoding ({true_color?} return true)
+    # - `256` for 8-Bit encoding
+    # - `52` for some Unix terminals with an extended color palette
+    # - `8` for 3-/4-bit encoding
+    # - `2` if ANSI is not supported in general ({ansi?} return false)
+    #
+    # @return [Integer]
+    #   number of supported colors
+
+    # @attribute [r] true_color?
+    #
+    # @see colors
+    #
+    # @return [true, false]
+    #   whether true colors are supported
+    def true_color? = (colors == 16_777_216)
+
+    # @attribute [r] columns
+    #
+    # Screen column count.
+    # See {size} for support and detection details.
+    #
+    # @return [Integer]
+    #   number of available columns
+    def columns = size[1]
+    #
+    # @attribute [w] columns
+
+    # @attribute [r] rows
+    #
+    # Screen row count.
+    # See {size} for support and detection details.
+    #
+    # @return [Integer]
+    #   number of available rows
+    def rows = size[0]
+    #
+    # @attribute [w] rows
+
+    # @attribute [r] pos
+    #
+    # Current cursor position.
+    # This is only available when ANSI is supported ({ansi?} return true).
+    #
+    # @return [[Integer, Integer]]
+    #   cursor position as rows and columns
+    # @return [nil]
+    #   for incompatible terminals
+    #
+    # @attribute [w] pos
+
+    # @attribute [r] size
+    #
+    # Screen size as a tuple of {rows} and {columns}.
+    #
+    # If the terminal does not support the report of it's dimension or ANSI
+    # is not supported in general then environment variables `COLUMNS` and
+    # `LINES` will be used.
+    # If this failed `[25, 80]` will be returned as default.
+    #
+    # Setting the terminal size is not widely supported.
+    #
+    # @see rows
+    # @see columns
+    #
+    # @return [[Integer, Integer]]
+    #   available screen size as rows and columns
+    #
+    # @attribute [w] size
+
+    # @!endgroup
+
+    # @!group Output methods
+
+    # @!method <<(object)
+    #
+    #   Writes the given object to the terminal.
+    #   Interprets embedded BBCode (see {Ansi.bbcode}).
+    #
+    #   @param object [#to_s] object to write
+    #   @return [Terminal] itself
+
+    # @!method print(*objects, bbcode: true)
+    #
+    #   Writes the given objects to the terminal.
+    #   Optionally interprets embedded BBCode (see {Ansi.bbcode}).
+    #
+    #   @param objects [Array<#to_s>] any number of objects to write
+    #   @param bbcode [true|false] whether to interpret embedded BBCode
+    #   @return [nil]
+
+    # @!method puts(*objects, bbcode: true)
+    #
+    #   Writes the given objects to the terminal.
+    #   Writes a newline after each object that does not already end with a
+    #   newline sequence in it's String represenation.
+    #   If called without any arguments, writes a newline only.
+    #
+    #   Optionally interprets embedded BBCode (see {Ansi.bbcode}).
+    #
+    #   @param objects [Array<#to_s>] any number of objects to write
+    #   @param bbcode [true|false] whether to interpret embedded BBCode
+    #   @return [nil]
+
+    # @!endgroup
+
+    # @!group Output helper methods
+
+    # @!method hide_cursor
+    #
+    #   Hide the cursor.
+    #   Will not send the control code if the cursor is already hidden.
+    #
+    #   When you called {hide_cursor} n-times you need to call {show_cursor}
+    #   n-times to show the cursor again.
+    #
+    #   @return [Terminal] itself
+
+    # @!method show_cursor
+    #
+    #   Show the cursor.
+    #   Will not send the control code if the cursor is not hidden.
+    #
+    #   When you called {hide_cursor} n-times you need to call {show_cursor}
+    #   n-times to show the cursor again.
+    #
+    #   @return [Terminal] itself
+
+    # @!method show_alt_screen
+    #
+    #   Show the alternate screen.
+    #   Will not send the control code if the alternate screen is already used.
+    #
+    #   When you called {show_alt_screen} n-times you need to call
+    #   {hide_alt_screen} n-times to show the default screen again.
+    #
+    #   @return [Terminal] itself
+
+    # @!method hide_alt_screen
+    #
+    #   Hide the alternate screen.
+    #   Will not send the control code if the alternate screen is not used.
+    #
+    #   When you called {show_alt_screen} n-times you need to call
+    #   {hide_alt_screen} n-times to show the default screen again.
+    #
+    #   @return [Terminal] itself
+
+    # @!endgroup
+
+    private
+
+    def __default_size
+      rows = ENV['LINES'].to_i
+      columns = ENV['COLUMNS'].to_i
+      [rows > 0 ? rows : 25, columns > 0 ? columns : 80]
+    end
+
+    def __output_modes
+      return false if ENV.key?('NO_COLOR') || ENV['TERM'] == 'dumb'
+      [tty = STDOUT.tty?, ENV['ANSI'] == 'force' || tty]
+    rescue IOError, SystemCallError
+      nil
+    end
+  end
+
+  tty, ansi = __output_modes
+  if tty.nil?
+    require_relative 'output/dumb'
+    extend DumbOutput
+    __output_error(nil)
+  else
+    @out = STDOUT
+    @out.sync = true if defined?(@out.sync)
+    if ansi
+      require_relative 'output/ansi'
+      extend AnsiOutput
+      __init_tty if tty
+    else
+      require_relative 'output/dumb'
+      extend DumbOutput
+    end
+  end
+end

data/lib/terminal/rspec/helper.rb

@@ -53,9 +53,13 @@ RSpec.shared_context 'with Terminal.rb' do |ansi: true, application: :kitty, col
       nil
     end
 
-    allow(Terminal).to receive(:raw_write) do |object|
-      stdout.push(object = object.to_s)
-      object.bytesize
+    if ansi
+      allow(Terminal).to receive(:raw_write) do |object|
+        stdout.push(object = object.to_s)
+        object.bytesize
+      end
+    else
+      allow(Terminal).to receive(:raw_write).and_return(nil)
     end
 
     allow(Terminal).to receive(:read_key_event) do

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require_relative 'terminal/ansi'
+require_relative 'terminal/output'
 require_relative 'terminal/input'
+require_relative 'terminal/ansi'
 
 #
 # Terminal access with support for ANSI control codes and
@@ -16,41 +17,7 @@ require_relative 'terminal/input'
 #
 module Terminal
   class << self
-    # Return `true` if the current terminal supports ANSI control codes for
-    # output.
-    # In this case all output methods ({<<}, {print}, {puts}) will forward ANSI
-    # control codes to the terminal and translate BBCode (see {Ansi.bbcode}).
-    #
-    # When `false` is returned (ANSI is not supported) the output methods will
-    # not forward ANSI control codes and BBCodes will be removed.
-    # The {colors} method will just return 2 (two).
-    #
-    # @see tui?
-    #
-    # @attribute [r] ansi?
-    # @return [true, false] whether ANSI control codes are supported for output
-    def ansi? = @ansi
-
-    # Return `true` if the current terminal supports ANSI control codes for
-    # input _and_ output.
-    # In this case not only all output methods ({<<}, {print}, {puts}) will
-    # forward ANSI control codes to the terminal and translate BBCode
-    # (see {Ansi.bbcode}). But also the input methods {read_key_event} and
-    # {on_key_event} will support extended key codes, mouse  and focus events.
-    #
-    # @see ansi?
-    #
-    # @attribute [r] tui?
-    # @return [true, false]
-    #   whether ANSI control codes are supported for input and output
-    def tui?
-      case input_mode
-      when :csi_u, :legacy
-        @ansi
-      else
-        false
-      end
-    end
+    # @!group Attributes
 
     # Terminal application identifier.
     #
@@ -66,190 +33,9 @@ module Terminal
     # @return [Symbol, nil] the application identifier
     def application = (@application ||= Detect.application)
 
-    # Number of supported colors.
-    # The detection checks various conditions to find the correct value. The
-    # most common values are
-    #
-    # - `16_777_216` for 24-bit encoding ({true_color?} return true)
-    # - `256` for 8-Bit encoding
-    # - `52` for some Unix terminals with an extended color palette
-    # - `8` for 3-/4-bit encoding
-    # - `2` if ANSI is not supported in general ({ansi?} return false)
-    #
-    # @attribute [r] colors
-    # @return [Integer] number of supported colors
-    def colors = (@colors ||= ansi? ? Detect.colors : 2)
-
-    # Screen column count.
-    # See {size} for support and detection details.
-    #
-    # @attribute [r] columns
-    # @return [Integer] number of available columns
-    def columns = size[1]
-
-    # @attribute [w] columns
-    def columns=(value)
-      self.size = [rows, value]
-    end
-
-    # Current cursor position.
-    # This is only available when ANSI is supported ({ansi?} return true).
-    #
-    # @attribute [r] pos
-    # @return [[Integer, Integer]] cursor position as rows and columns
-    # @return [nil] for incompatible terminals
-    def pos
-      @con&.cursor
-    rescue IOError
-      @con = nil
-    end
-
-    # @attribute [w] pos
-    def pos=(pos)
-      @con&.cursor = pos
-    rescue IOError
-      @con = nil
-    end
-
-    # Screen row count.
-    # See {size} for support and detection details.
-    #
-    # @attribute [r] rows
-    # @return [Integer] number of available rows
-    def rows = size[0]
-
-    # @attribute [w] rows
-    def rows=(value)
-      self.size = [value, columns]
-    end
-
-    # Screen size as a tuple of {rows} and {columns}.
-    #
-    # If the terminal does not support the report of it's dimension or ANSI
-    # is not supported in general then environment variables `COLUMNS` and
-    # `LINES` will be used.
-    # If this failed `[25, 80]` will be returned as default.
-    #
-    # Setting the terminal size is not widely supported.
-    #
-    # @see rows
-    # @see columns
-    #
-    # @attribute [r] size
-    # @return [[Integer, Integer]] available screen size as rows and columns
-    def size
-      @size ||= @inf&.winsize || _default_size
-    rescue IOError
-      @inf = nil
-      @size = _default_size
-    end
-
-    # @attribute [w] size
-    def size=(size)
-      @inf&.winsize = size
-    rescue IOError
-      @inf = nil
-    end
-
-    # @see colors
-    # @attribute [r] true_color?
-    # @return [true, false] whether true colors are supported
-    def true_color? = (colors == 16_777_216)
-
-    # Hide the cursor.
-    # Will not send the control code if the cursor is already hidden.
-    #
-    # When you called {hide_cursor} n-times you need to call {show_cursor}
-    # n-times to show the cursor again.
-    #
-    # @return [Terminal] itself
-    def hide_cursor
-      raw_write(Ansi::CURSOR_HIDE) if ansi? && (@cc += 1) == 1
-      self
-    end
-
-    # Show the cursor.
-    # Will not send the control code if the cursor is not hidden.
-    #
-    # When you called {hide_cursor} n-times you need to call {show_cursor}
-    # n-times to show the cursor again.
-    #
-    # @return [Terminal] itself
-    def show_cursor
-      raw_write(Ansi::CURSOR_SHOW) if @cc > 0 && (@cc -= 1).zero?
-      self
-    end
+    # @!endgroup
 
-    # Show the alternate screen.
-    # Will not send the control code if the alternate screen is already used.
-    #
-    # When you called {show_alt_screen} n-times you need to call
-    # {hide_alt_screen} n-times to show the default screen again.
-    #
-    # @return [Terminal] itself
-    def show_alt_screen
-      raw_write(Ansi::SCREEN_ALTERNATE) if ansi? && (@as += 1) == 1
-      self
-    end
-
-    # Hide the alternate screen.
-    # Will not send the control code if the alternate screen is not used.
-    #
-    # When you called {show_alt_screen} n-times you need to call
-    # {hide_alt_screen} n-times to show the default screen again.
-    #
-    # @return [Terminal] itself
-    def hide_alt_screen
-      raw_write(Ansi::SCREEN_ALTERNATE_OFF) if @as > 0 && (@as -= 1).zero?
-      self
-    end
-
-    # Writes the given object to the terminal.
-    # Interprets embedded BBCode.
-    #
-    # @param object [#to_s] object to write
-    # @return [Terminal] itself
-    def <<(object)
-      @out.write(Ansi.bbcode(object)) if @out && object != nil
-      self
-    rescue IOError
-      @out = nil
-      self
-    end
-
-    # Writes the given objects to the terminal.
-    # Optionally interprets embedded BBCode.
-    #
-    # @param objects [Array<#to_s>] any number of objects to write
-    # @param bbcode [true|false] whether to interpret embedded BBCode
-    # @return [nil]
-    def print(*objects, bbcode: true)
-      return unless @out
-      return @out.print(*objects) unless bbcode
-      objects.each { @out.write(Ansi.bbcode(_1)) }
-      nil
-    rescue IOError
-      @out = nil
-    end
-
-    # Writes the given objects to the terminal.
-    # Writes a newline after each object that does not already end with a
-    # newline sequence in it's String represenation.
-    # If called without any arguments, writes a newline only.
-    #
-    # Optionally interprets embedded BBCode.
-    #
-    # @param (see print)
-    # @return (see print)
-    def puts(*objects, bbcode: true)
-      return unless @out
-      return @out.puts if objects.empty?
-      return @out.puts(objects) unless bbcode
-      objects.flatten!
-      objects.empty? ? @out.puts : @out.puts(objects.map! { Ansi.bbcode(_1) })
-    rescue IOError
-      @out = nil
-    end
+    # @!group Tool methods
 
     # Execute a command and report command output line by line
     # or capture the output.
@@ -316,77 +102,7 @@ module Terminal
       ]
     end
 
-    # @private
-    def raw_write(str)
-      @out&.syswrite(str)
-    rescue IOError
-      @out = nil
-    end
-
-    private
-
-    def _default_size
-      rows = ENV['LINES'].to_i
-      columns = ENV['COLUMNS'].to_i
-      [rows > 0 ? rows : 25, columns > 0 ? columns : 80]
-    end
-
-    def _determine_modes
-      # order is important!
-      tty = STDOUT.tty?
-      return tty, true if ENV['ANSI'] == 'force'
-      return false, false if ENV.key?('NO_COLOR') || ENV['TERM'] == 'dumb'
-      [tty, tty]
-    rescue IOError
-      [nil, false]
-    end
-  end
-
-  @cc = @as = 0
-  tty, @ansi = _determine_modes
-
-  unless tty.nil?
-    @out = STDOUT
-    @out.sync = true
-    if tty
-      @inf = STDOUT
-      @con = IO.console
-      Signal.trap('WINCH') { @size = nil } if Signal.list.key?('WINCH')
-    end
-  end
-
-  unless @ansi
-    @plain = ->(s) { Ansi.plain(s) }
-    @undecorate = ->(s) { Ansi.undecorate(s) }
-
-    class << self
-      alias << <<
-      def <<(object)
-        @out.write(Ansi.plain(object)) if @out && object != nil
-        self
-      rescue IOError
-        @out = nil
-        self
-      end
-
-      alias print print
-      def print(*objects, bbcode: true)
-        return if @out.nil? || objects.empty?
-        @out.print(*objects.map!(&(bbcode ? @plain : @undecorate)))
-      rescue IOError
-        @out = nil
-      end
-
-      alias puts puts
-      def puts(*objects, bbcode: true)
-        return unless @out
-        objects.flatten!
-        return @out.puts if objects.empty?
-        @out.puts(objects.map!(&(bbcode ? @plain : @undecorate)))
-      rescue IOError
-        @out = nil
-      end
-    end
+    # @!endgroup
   end
 
   dir = "#{__dir__}/terminal"

data/terminal_rb.gemspec

@@ -21,7 +21,9 @@ Gem::Specification.new do |spec|
   spec.homepage = 'https://codeberg.org/mblumtritt/Terminal.rb'
   spec.metadata['source_code_uri'] = spec.homepage
   spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
-  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/terminal_rb'
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/terminal_rb/#{
+    Terminal::VERSION
+  }"
   spec.metadata['rubygems_mfa_required'] = 'true'
   spec.metadata['yard.run'] = 'yard'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -35,7 +35,12 @@ files:
 - lib/terminal/ansi/named_colors.rb
 - lib/terminal/detect.rb
 - lib/terminal/input.rb
+- lib/terminal/input/ansi.rb
+- lib/terminal/input/dumb.rb
 - lib/terminal/input/key_event.rb
+- lib/terminal/output.rb
+- lib/terminal/output/ansi.rb
+- lib/terminal/output/dumb.rb
 - lib/terminal/rspec/helper.rb
 - lib/terminal/shell.rb
 - lib/terminal/text.rb
@@ -50,7 +55,7 @@ licenses:
 metadata:
   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
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/0.18.0
   rubygems_mfa_required: 'true'
   yard.run: yard
 rdoc_options: []
@@ -67,7 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise line
   break support and much more.