terminal_rb 0.17.2 → 0.19.0

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