terminal_rb 0.6.0

data/lib/terminal.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require_relative 'terminal/ansi'
+require_relative 'terminal/input'
+
+#
+# Terminal access with support for ANSI control codes and
+# [BBCode-like](https://en.wikipedia.org/wiki/BBCode) embedded text attribute
+# syntax.
+#
+# It automagically detects whether your terminal supports ANSI features.
+#
+module Terminal
+  class << self
+    # Return true when the current terminal supports ANSI control codes.
+    # When the terminal does not support it, {colors} will return `2` as color
+    # count and all output methods ({<<}, {print}, {puts}) will not forward
+    # ANSI control codes to the terminal.
+    #
+    # @attribute [r] ansi?
+    # @return [Boolean] whether ANSI control codes are supported
+    def ansi? = (@mode == :ansi)
+
+    # Terminal application identifier.
+    #
+    # The detection supports a wide range of terminal emulators but may return
+    # `nil` if an unsupported terminal was found. These are the supported
+    # application IDs:
+    #
+    # - `:alacritty`,
+    # - `:amiga`,
+    # - `:code_edit`,
+    # - `:dg_unix`,
+    # - `:fluent`,
+    # - `:ghostty`,
+    # - `:hpterm`,
+    # - `:hyper`,
+    # - `:iterm`,
+    # - `:macos`,
+    # - `:mintty`,
+    # - `:ms_terminal`,
+    # - `:ncr260`,
+    # - `:nsterm`,
+    # - `:terminator`,
+    # - `:terminology`,
+    # - `:terminus`,
+    # - `:termite`,
+    # - `:tmux`,
+    # - `:vscode`,
+    # - `:vt100`,
+    # - `:warp`,
+    # - `:wezterm`,
+    # - `:wyse`,
+    # - `:xnuppc`
+    #
+    # @attribute [r] application
+    # @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 for it's dimension or ANSI
+    # is not supported in general then environment variables 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 [Boolean] 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.
+    #
+    # To show the cursor again call {show_cursor}.
+    #
+    # @return [Terminal] itself
+    def hide_cursor
+      _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
+      _write(Ansi::CURSOR_SHOW) if @cc > 0 && (@cc -= 1).zero?
+      self
+    end
+
+    # Writes the given object to the terminal.
+    # Interprets embedded BBCode.
+    #
+    # @param [#to_s] object object to write
+    # @return [Terminal] itself
+    def <<(object)
+      @out.write(@bbcode[object]) unless object.nil? || @out.nil?
+      self
+    rescue IOError
+      @out = nil
+      self
+    end
+
+    # Writes the given objects to the terminal.
+    # Optionally interprets embedded BBCode.
+    #
+    # @param [Array<#to_s>] objects any number of objects to write
+    # @param [true|false] bbcode whether to interpret embedded BBCode
+    # @return [nil]
+    def print(*objects, bbcode: true)
+      return unless @out
+      bbcode = bbcode ? @bbcode : @nobbcode
+      objects.flatten.each { @out.write(bbcode[_1]) unless _1.nil? }
+      nil
+    rescue IOError
+      @out = nil
+    end
+
+    # Writes the given objects to the terminal.
+    # Writes a newline after each objects 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
+      objects.flatten!
+      if objects.empty?
+        @out.write("\n")
+        return
+      end
+      bbcode = bbcode ? @bbcode : @nobbcode
+      objects.each do |s|
+        next @out.write("\n") if s.nil?
+        @out.write(s = bbcode[s])
+        @out.write("\n") if s[-1] != "\n"
+      end
+      nil
+    rescue IOError
+      @out = nil
+    end
+
+    private
+
+    def _write(str)
+      @out&.write(str)
+    rescue IOError
+      @out = nil
+    end
+
+    def _default_size
+      rows = ENV['LINES'].to_i
+      columns = ENV['COLUMNS'].to_i
+      [rows > 0 ? rows : 25, columns > 0 ? columns : 80]
+    end
+
+    def _determine_mode
+      # order is important:
+      return :dumb unless STDOUT.tty?
+      ENV.key?('NO_COLOR') || ENV['TERM'] == 'dumb' ? :dumb : :ansi
+    rescue IOError
+      nil
+    end
+  end
+
+  @mode = _determine_mode
+  @out = STDOUT if @mode
+  @cc = 0
+
+  if ansi?
+    @bbcode = ->(s) { Ansi.bbcode(s) }
+    @nobbcode = lambda(&:to_s)
+    @inf = STDOUT
+    @con = IO.console
+    Signal.trap('WINCH') { @size = nil } if Signal.list.key?('WINCH')
+  else
+    @bbcode = ->(s) { Ansi.plain(s) }
+    @nobbcode = ->(s) { Ansi.undecorate(s) }
+  end
+
+  dir = "#{__dir__}/terminal"
+  autoload :Text, "#{dir}/text.rb"
+  autoload :Detect, "#{dir}/detect.rb"
+  private_constant :Detect
+end

data/lib/terminal_rb.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'terminal'

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: terminal_rb
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Mike Blumtritt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Terminal access with support for ANSI control codes and
+  BBCode-like embedded text attribute syntax.
+executables:
+- bbcode
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- ".yardopts"
+- README.md
+- bin/bbcode
+- examples/24bit-colors.rb
+- examples/3bit-colors.rb
+- examples/8bit-colors.rb
+- examples/attributes.rb
+- examples/bbcode.rb
+- examples/info.rb
+- examples/key-codes.rb
+- lib/terminal.rb
+- lib/terminal/ansi.rb
+- lib/terminal/ansi/attributes.rb
+- lib/terminal/ansi/named_colors.rb
+- lib/terminal/detect.rb
+- lib/terminal/input.rb
+- lib/terminal/preload.rb
+- lib/terminal/rspec/helper.rb
+- lib/terminal/text.rb
+- lib/terminal/text/char_width.rb
+- lib/terminal/version.rb
+- lib/terminal_rb.rb
+homepage: https://codeberg.org/mblumtritt/Terminal.rb
+licenses:
+- MIT
+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
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Easy terminal access with ANSI and BBCode support.
+test_files: []