terminal_rb 0.6.0

data/lib/terminal/ansi.rb

@@ -0,0 +1,593 @@
+# frozen_string_literal: true
+
+module Terminal
+  #
+  # Fast ANSI control code and BBCode processing.
+  #
+  module Ansi
+    class << self
+      # Supported attribute names.
+      #
+      # @see []
+      #
+      # @attribute [r] attributes
+      # @return [Array<Symbol>] all attribute names
+      def attributes = ATTRIBUTES_S.keys
+
+      # Supported 3/4-bit color names.
+      #
+      # @see []
+      #
+      # @attribute [r] colors
+      # @return [Array<Symbol>] all color names
+      def colors = COLORS_S.keys
+
+      # Supported basic 24-bit (Kitty compatible) color names.
+      #
+      # @see []
+      #
+      # @attribute [r] named_colors
+      # @return [Array<Symbol>] all basic named_colors names
+      def named_colors = NAMED_COLORS.keys.map!(&:to_sym)
+
+      #
+      # @!group ANSI control code generator functions
+      #
+
+      # Combine given ANSI {attributes}, {colors}, {named_colors} and color
+      # codes.
+      #
+      # Colors can specified by their name for ANSI 3-bit and 4-bit colors.
+      # For 8-bit ANSI colors use 2-digit hexadecimal values `00`...`ff`.
+      #
+      # To use RGB ANSI colors (24-bit colors) specify 3-digit or 6-digit
+      # hexadecimal values `000`...`fff` or `000000`...`ffffff`.
+      # This represent the `RRGGBB` values (or `RGB` for short version) like you
+      # may known from CSS color notation.
+      #
+      # To use a color as background color prefix the color attribute with `bg_`
+      # or `on_`.
+      # To use a color as underline color prefix the color attribute with `ul_`.
+      # To clarify that a color attribute have to be used as foreground
+      # color use the prefix `fg_`.
+      #
+      # @example Valid Foreground Color Attributes
+      #   Terminal::Ansi[:yellow]
+      #   Terminal::Ansi[:fg_fab]
+      #   Terminal::Ansi[:fg_00aa00]
+      #   Terminal::Ansi[:af]
+      #   Terminal::Ansi[:fg_af]
+      #   Terminal::Ansi['#fab']
+      #   Terminal::Ansi['#00aa00']
+      #   Terminal::Ansi['lightblue']
+      #
+      # @example Valid Background Color Attributes
+      #   Terminal::Ansi[:bg_yellow]
+      #   Terminal::Ansi[:bg_fab]
+      #   Terminal::Ansi[:bg_00aa00]
+      #   Terminal::Ansi[:bg_af]
+      #   Terminal::Ansi['bg#00aa00']
+      #   Terminal::Ansi['bg_lightblue']
+      #
+      #   Terminal::Ansi[:on_yellow]
+      #   Terminal::Ansi[:on_fab]
+      #   Terminal::Ansi[:on_00aa00]
+      #   Terminal::Ansi[:on_af]
+      #   Terminal::Ansi['on#00aa00']
+      #   Terminal::Ansi['on_lightblue']
+      #
+      # @example Valid Underline Color Attributes
+      #   Terminal::Ansi[:underline, :ul_yellow]
+      #   Terminal::Ansi[:underline, :ul_fab]
+      #   Terminal::Ansi[:underline, :ul_00aa00]
+      #   Terminal::Ansi[:underline, :ul_fa]
+      #   Terminal::Ansi[:underline, :ul_bright_yellow]
+      #   Terminal::Ansi[:underline, 'ul#00aa00']
+      #   Terminal::Ansi['underline', 'ul_lightblue']
+      #
+      # @example Combined attributes:
+      #   Terminal::Ansi[:bold, :italic, :bright_white, :on_0000cc]
+      #
+      # @see valid?
+      #
+      # @param attributes [Array<Symbol, String>] attribute names to be used
+      # @return [String] combined ANSI attributes
+      def [](*attributes)
+        return +'' if attributes.empty?
+        "\e[#{
+          attributes
+            .map do |arg|
+              case arg
+              when String
+                ATTRIBUTES[arg] || COLORS[arg] || _color(arg) || _invalid(arg)
+              when Symbol
+                ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(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
+            end
+            .join(';')
+        }m"
+      end
+
+      # Test if given String contains ANSI control codes.
+      #
+      # @param str [#to_s] object to be tested
+      # @return [true, false] whether if attributes are found
+      def ansi?(str) = TEST.match?(str.to_s)
+
+      # Decorate given argument with ANSI attributes and colors.
+      #
+      # @example
+      #   Terminal::Ansi.decorate(
+      #     'Hello World!',
+      #     :bold, :italic, :bright_white, :on_00c
+      #   )
+      #   # => "\e[1;3;97;48;2;0;0;204mHello World!\e[m"
+      #
+      # @see []
+      # @see undecorate
+      #
+      # @param str [#to_s] object to be decorated
+      # @param attributes [Array<Symbol, String>] attribute names to be used
+      # @param reset [true, false] whether to include reset code for ANSI attributes
+      # @return [String] `str` converted and decorated with the ANSI `attributes`
+      def decorate(str, *attributes, reset: true)
+        attributes = self[*attributes]
+        attributes.empty? ? "#{str}" : "#{attributes}#{str}#{"\e[m" if reset}"
+      end
+
+      # Remove ANSI functions, attributes and colors from given string.
+      #
+      # @example
+      #   Terminal::Ansi.undecorate("\e[1;3;97;48;2;0;0;204mHello World!\e[m")
+      #   # => "Hello World!"
+      #
+      # @see decorate
+      #
+      # @param str [#to_s] string to be modified
+      # @return [String] string without ANSI attributes
+      def undecorate(str) = str.to_s.gsub(TEST, '')
+
+      # Try to combine given ANSI attributes and colors.
+      # The attributes and colors have to be separated by given `separator``.
+      #
+      # @example Valid Attribute String
+      #   Terminal::Ansi.try_convert('bold italic blink red on#00ff00')
+      #   # => "\e[1;3;5;31;48;2;0;255;0m"
+      #
+      # @example Invalid Attribute String
+      #   Terminal::Ansi.try_convert('cool bold on green')
+      #   # => nil
+      #
+      # @see []
+      #
+      # @param attributes [#to_s] attributes separated by given `separator`
+      # @param separator [String] attribute separator char
+      # @return [String] combined ANSI attributes
+      # @return [nil] when string does not contain valid attributes
+      def try_convert(attributes, separator: ' ')
+        return unless attributes
+        return if (attributes = attributes.to_s.split(separator)).empty?
+        "\e[#{
+          attributes
+            .map! { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) || return }
+            .join(';')
+        }m"
+      end
+
+      # Test if all given attributes are valid.
+      #
+      # @see []
+      #
+      # @param attributes [Array<Symbol, String>] attribute names to be used
+      # @return [true, false] whether if all given attributes are valid
+      def valid?(*attributes)
+        attributes.all? do |arg|
+          case arg
+          when String
+            ATTRIBUTES[arg] || COLORS[arg] || _color(arg)
+          when Symbol
+            ATTRIBUTES_S[arg] || COLORS_S[arg] || _color(arg)
+          when (0..767)
+            true
+          end
+        end
+      end
+
+      #
+      # @!endgroup
+      #
+      # @!group BBcode related functions
+      #
+
+      # Replace embedded BBCode-like attributes with ANSI control codes.
+      #
+      # @example
+      #   Terminal::Ansi.bbcode "[b]Bold[/b] Text"
+      #   # => "\e[1mBold\e[22m Text"
+      #
+      # @see unbbcode
+      # @see []
+      #
+      # @param str [#to_s] string to be modified
+      # @return [String] string with ANSI attributes
+      def bbcode(str)
+        str
+          .to_s
+          .gsub(BBCODE) do |match_str|
+            next match_str if (match = Regexp.last_match[1]).empty?
+            next "[#{match[1..]}]" if match[0] == '\\'
+            try_convert(match) || match_str
+          end
+      end
+
+      # Remove embedded BBCode-like attributes.
+      #
+      # @example
+      #   Terminal::Ansi.unbbcode "[b]Bold[/b] Text"
+      #   # => "Bold Text"
+      #
+      # @see bbcode
+      #
+      # @param str [#to_s] string to be modified
+      # @return [String] string without BBCode
+      def unbbcode(str)
+        str
+          .to_s
+          .gsub(BBCODE) do |match_str|
+            next match_str if (match = Regexp.last_match[1]).empty?
+            next "[#{match[1..]}]" if match[0] == '\\'
+            next match_str if (match = match.split).empty?
+            next if match.all? { ATTRIBUTES[_1] || COLORS[_1] || _color(_1) }
+            match_str
+          end
+      end
+
+      #
+      # @!endgroup
+      #
+      # @!group Other tool functions
+      #
+
+      # Remove any BBCode-like and/or ANSI attributes.
+      #
+      # @see undecorate
+      # @see unbbcode
+      #
+      # @param str [#to_s] string to be modified
+      # @return [String] string without BBCode and ANSI control codes.
+      def plain(str) = unbbcode(str).gsub(TEST, '')
+
+      # Create nice colored text.
+      #
+      # @param str [#to_s] string to enrich with color
+      # @param frequency [Float] color change frequency
+      # @param spread [Float] number of chars with same color
+      # @param seed [Float] start index on sinus curve
+      # @return [String] fancy text
+      def rainbow(str, frequency: 0.3, spread: 0.8, seed: 1.1)
+        pos = -1
+        str
+          .to_s
+          .chars
+          .map! do |char|
+            i = (seed + ((pos += 1) / spread)) * frequency
+            "\e[38;2;#{(Math.sin(i) * 255).abs.to_i};" \
+              "#{(Math.sin(i + PI2_THIRD) * 255).abs.to_i};" \
+              "#{(Math.sin(i + PI4_THIRD) * 255).abs.to_i}m#{char}"
+          end
+          .join << RESET
+      end
+
+      #
+      # @!endgroup
+      #
+      # @!group Cursor manipulation
+      #
+
+      # Move cursor given lines up.
+      #
+      # @param lines [Integer] number of lines to move
+      # @return [String] ANSI control code
+      def cursor_up(lines = 1) = "\e[#{lines}A"
+
+      # Move cursor given lines down.
+      #
+      # @param (see cursor_up)
+      # @return (see cursor_up)
+      def cursor_down(lines = 1) = "\e[#{lines}B"
+
+      # Move cursor given columns forward.
+      #
+      # @param columns [Integer] number of columns to move
+      # @return (see cursor_up)
+      def cursor_forward(columns = 1) = "\e[#{columns}C"
+
+      # Move cursor given columns back.
+      #
+      # @param (see forward)
+      # @return (see cursor_up)
+      def cursor_back(columns = 1) = "\e[#{columns}D"
+
+      # Move cursor to the beginning of the given next line.
+      #
+      # @param (see up)
+      # @return (see cursor_up)
+      def cursor_next_line(lines = 1) = "\e[#{lines}E"
+
+      # Move cursor to the beginning of the given previous line.
+      #
+      # @param (see up)
+      # @return (see cursor_up)
+      def cursor_prev_line(lines = 1) = "\e[#{lines}F"
+
+      # Move cursor to given column in the current row.
+      #
+      # @param column [Integer] column index
+      # @return (see cursor_up)
+      def cursor_column(column = 1) = "\e[#{column}G"
+
+      # Move to given row and column.
+      #
+      # @param row [Integer] row index
+      # @param column [Integer] column index
+      # @return (see cursor_up)
+      def cursor_pos(row, column = nil)
+        return column ? "\e[;#{column}H" : "\e[H" unless row
+        column ? "\e[#{row};#{column}H" : "\e[#{row}H"
+      end
+
+      # Show cursor.
+      #
+      # @return (see cursor_up)
+      def cursor_show = +CURSOR_SHOW
+
+      # Hide cursor.
+      #
+      # @return (see cursor_up)
+      def cursor_hide = +CURSOR_HIDE
+
+      # Save current cursor position.
+      #
+      # @return (see cursor_up)
+      def cursor_save_pos = +CURSOR_POS_SAVE
+
+      # Restore saved cursor position.
+      #
+      # @return (see cursor_up)
+      def cursor_restore_pos = +CURSOR_POS_RESTORE
+
+      #
+      # @!endgroup
+      #
+      # @!group Screen manipulation
+      #
+
+      # Erase screen part.
+      #
+      # @return (see cursor_up)
+      def screen_erase(part = :all)
+        "\e[#{
+          case part
+          when :below
+            # nop
+          when :above
+            '1'
+          when :scrollback
+            '3'
+          else # all
+            '2'
+          end
+        }J"
+      end
+
+      # Safe current screen.
+      #
+      # @return (see cursor_up)
+      def screen_save = +SCREEN_SAVE
+
+      # Restore current screen.
+      #
+      # @return (see cursor_up)
+      def screen_restore = +SCREEN_RESTORE
+
+      # Use alternative screen buffer.
+      #
+      # @return (see cursor_up)
+      def screen_alternate = +SCREEN_ALTERNATE
+
+      # Do not longer use alternative screen buffer.
+      #
+      # @return (see cursor_up)
+      def screen_alternate_off = +SCREEN_ALTERNATE_OFF
+
+      # Scroll window given lines up.
+      #
+      # @param lines [Integer] number of lines to scroll
+      # @return (see cursor_up)
+      def screen_scroll_up(lines = 1) = "\e[#{lines}S"
+
+      # Scroll window given lines down.
+      #
+      # @param (see scroll_up)
+      # @return (see cursor_up)
+      def screen_scroll_down(lines = 1) = "\e[#{lines}T"
+
+      #
+      # @!endgroup
+      #
+      # @!group Other ANSI control functions
+      #
+
+      # Erase part of line.
+      #
+      # @return (see cursor_up)
+      def line_erase(part = :all)
+        "\e[#{
+          case part
+          when :to_end
+            # nop
+          when :to_start
+            '1'
+          else # :all
+            '2'
+          end
+        }K"
+      end
+
+      # Set window title.
+      # This is not widely supported.
+      #
+      # @param [#to_s] title text
+      # @return (see cursor_up)
+      def title(title) = "\e]2;#{title}\a"
+
+      # Set  tab title.
+      # This is not widely supported.
+      #
+      # @param (see title)
+      # @return (see cursor_up)
+      def tab_title(title) = "\e]0;#{title}\a"
+
+      # Create a hyperlink.
+      # This is not widely supported.
+      #
+      # @param [#to_s] url URL to link to
+      # @param [#to_s] text text to display for the link
+      # @return (see cursor_up)
+      def link(url, text) = "\e]8;;#{url}\a#{text}\e]8;;\a"
+
+      #
+      # @!endgroup
+      #
+
+      private
+
+      def _invalid(att)
+        raise(
+          ArgumentError,
+          "unknown ANSI attribute - #{att.inspect}",
+          caller(1)
+        )
+      end
+
+      def _color(str)
+        b, v = /\A(fg|bg|on|ul)?_?#?([[:xdigit:]]{1,6})\z/.match(str)&.captures
+        if v
+          return(
+            case v.size
+            when 1, 2
+              "#{COLOR_BASE[b]};5;#{v.hex}"
+            when 3
+              "#{COLOR_BASE[b]};2;#{(v[0] * 2).hex};#{
+                (v[1] * 2).hex
+              };#{(v[2] * 2).hex}"
+            when 6
+              "#{COLOR_BASE[b]};2;#{v[0, 2].hex};#{v[2, 2].hex};#{v[4, 2].hex}"
+            end
+          )
+        end
+        b, v = /\A(fg|bg|on|ul)?_?([a-z]{3,}[0-9]{0,3})\z/.match(str)&.captures
+        return unless v
+        name = NAMED_COLORS[v] and return "#{COLOR_BASE[b]};#{name}"
+      end
+    end
+
+    COLOR_BASE =
+      { 'bg' => '48', 'on' => '48', 'ul' => '58' }.tap { _1.default = '38' }
+        .freeze
+
+    TEST =
+      /
+      (?:\e\[[\d;:\?]*[ABCDEFGHJKSTfminsuhl])
+      |
+      (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
+    /x
+
+    BBCODE = /(?:\[((?~[\[\]]))\])/
+
+    PI2_THIRD = 2.0 * Math::PI / 3.0
+    PI4_THIRD = 4.0 * Math::PI / 3.0
+
+    private_constant :COLOR_BASE, :TEST, :BBCODE, :PI2_THIRD, :PI4_THIRD
+
+    require_relative 'ansi/attributes'
+
+    autoload :NAMED_COLORS, "#{__dir__}/ansi/named_colors.rb"
+    private_constant :NAMED_COLORS
+
+    # @!visibility private
+    RESET = self[:reset].freeze
+
+    # @!visibility private
+    FULL_RESET = "\ec"
+
+    # @!visibility private
+    CURSOR_HOME = cursor_pos(nil, nil).freeze
+    # @!visibility private
+    CURSOR_FIRST_ROW = cursor_pos(1).freeze
+    # @!visibility private
+    CURSOR_FIRST_COLUMN = cursor_column(1).freeze
+
+    # @!visibility private
+    CURSOR_SHOW = "\e[?25h"
+    # @!visibility private
+    CURSOR_HIDE = "\e[?25l"
+
+    # CURSOR_POS_SAVE_SCO = "\e[s"
+    # CURSOR_POS_SAVE_DEC = "\e7"
+    # @!visibility private
+    CURSOR_POS_SAVE = "\e7"
+
+    # CURSOR_POS_RESTORE_SCO = "\e[u"
+    # CURSOR_POS_RESTORE_DEC = "\e8"
+    # @!visibility private
+    CURSOR_POS_RESTORE = "\e8"
+
+    # @!visibility private
+    SCREEN_ERASE = screen_erase.freeze
+    # @!visibility private
+    SCREEN_ERASE_BELOW = screen_erase(:below).freeze
+    # @!visibility private
+    SCREEN_ERASE_ABOVE = screen_erase(:above).freeze
+    # @!visibility private
+    SCREEN_ERASE_SCROLLBACK = screen_erase(:scrollback).freeze
+
+    # @!visibility private
+    SCREEN_SAVE = "\e[?47h"
+    # @!visibility private
+    SCREEN_RESTORE = "\e[?47l"
+    # @!visibility private
+    SCREEN_ALTERNATE = "\e[?1049h"
+    # @!visibility private
+    SCREEN_ALTERNATE_OFF = "\e[?1049l"
+
+    # @!visibility private
+    LINE_ERASE = line_erase.freeze
+    # @!visibility private
+    LINE_ERASE_TO_END = line_erase(:to_end).freeze
+    # @!visibility private
+    LINE_ERASE_TO_START = line_erase(:to_start).freeze
+    # @!visibility private
+    LINE_ERASE_PREV = "#{cursor_prev_line(nil)}#{LINE_ERASE}".freeze
+
+    # @comment seems not widely supported:
+    # @comment  doubled!? def cursor_column(column = 1) = "\e[#{column}`"
+    # @comment  doubled!? def cursor_row(row = 1) = "\e[#{row}d"
+    # @comment  def cursor_column_rel(columns = 1) = "\e[#{columns}a"
+    # @comment  def cursor_row_rel(rows = 1) = "\e[#{rows}e"
+    # @comment  def cursor_tab(count = 1) = "\e[#{column}I"
+    # @comment  def cursor_reverse_tab(count = 1) = "\e[#{count}Z"
+    # @comment  def chars_delete(count = 1) = "\e[#{count}P"
+    # @comment  def chars_erase(count = 1) = "\e[#{count}X"
+    # @comment  def notify(title) = "\e]9;#{title}\a"
+  end
+end