terminal_rb 0.20.0 → 1.0.3

data/lib/terminal/output.rb

@@ -2,213 +2,227 @@
 
 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?
+    # @!group Attributes
     #
-    # @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.
+    #   Current 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
+    #
 
-    # @!group Output attributes
+    # @!attribute [r] tui?
+    #
+    #   Whether the terminal supports full TUI interaction (ANSI output
+    #   with CSI-u or legacy keyboard input).
+    #
+    #   @see .input_mode
+    #
+    #   @return [true, false]
 
-    # @attribute [r] ansi?
+    # @!attribute [r] ansi?
     #
-    # @see output_mode
-    # @see tui?
+    #   Whether ANSI escape codes are supported.
     #
-    # @return [true, false]
-    #   whether ANSI control codes are supported for output
+    #   @see output_mode
+    #   @see tui?
+    #
+    #   @return [true, false]
 
     # @attribute [r] colors
     #
-    # Number of supported colors.
-    # The detection checks various conditions to find the correct value. The
-    # most common values are
+    #   Number of colors supported by the terminal.
     #
-    # - `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)
+    #   @see .true_color?
     #
-    # @return [Integer]
-    #   number of supported colors
+    #   @return [Integer] one of 2, 8, 16, 256, or 16777216
 
-    # @attribute [r] true_color?
+    # Whether the terminal supports true color (24-bit, 16.7 million
+    # colors).
     #
-    # @see colors
+    # @see .colors
     #
+    # @attribute [r] true_color?
     # @return [true, false]
-    #   whether true colors are supported
     def true_color? = (colors == 16_777_216)
 
-    # @attribute [r] columns
+    # @attribute [rw] size
+    #
+    #   The terminal size.
+    #
+    #   @return [Array<Integer, Integer>] +[rows, columns]+
+
+    # Terminal width in columns.
     #
-    # Screen column count.
-    # See {size} for support and detection details.
+    # @see .size
     #
+    # @attribute [rw] columns
     # @return [Integer]
-    #   number of available columns
     def columns = size[1]
-    #
-    # @attribute [w] columns
 
-    # @attribute [r] rows
+    # Terminal height in rows.
     #
-    # Screen row count.
-    # See {size} for support and detection details.
+    # @see .size
     #
+    # @attribute [rw] rows
     # @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).
+    # @attribute [rw] pos
     #
-    # @return [[Integer, Integer]]
-    #   cursor position as rows and columns
-    # @return [nil]
-    #   for incompatible terminals
+    #   Current cursor position.
+    #   This is only available when ANSI is supported ({ansi?} return true).
     #
-    # @attribute [w] pos
+    #   @return [Array<Integer, Integer>, nil] +[row, column]+ or +nil+ if
+    #     unavailable
 
-    # @attribute [r] size
+    # Whether the terminal has been resized since the last size query.
     #
-    # Screen size as a tuple of {rows} and {columns}.
+    # @see .on_resize
     #
-    # 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.
+    # @attribute [r] resized?
+    # @return [true, false]
+    def resized? = @size.nil?
+
     #
-    # @see rows
-    # @see columns
+    # @!endgroup
     #
-    # @return [[Integer, Integer]]
-    #   available screen size as rows and columns
+    # @!group Output Methods
     #
-    # @attribute [w] size
-
-    # @!endgroup
-
-    # @!group Output methods
 
     # @!method <<(object)
     #
-    #   Writes the given object to the terminal.
-    #   Interprets embedded BBCode (see {Ansi.bbcode}).
+    #   Output an object with BBCode markup processing.
     #
-    #   @param object [#to_s] object to write
-    #   @return [Terminal] itself
+    #   @example
+    #     Terminal << '[bold]Hello[/bold] World'
+    #
+    #   @param object [#to_s, nil] the object to output; +nil+ is ignored
+    #   @return [self]
 
     # @!method print(*objects, bbcode: true)
     #
-    #   Writes the given objects to the terminal.
-    #   Optionally interprets embedded BBCode (see {Ansi.bbcode}).
+    #   Print objects to the terminal.
+    #
+    #   @example
+    #     Terminal.print('[green]OK[/]')
+    #     Terminal.print('press the [red] button', bbcode: false)
     #
-    #   @param objects [Array<#to_s>] any number of objects to write
-    #   @param bbcode [true|false] whether to interpret embedded BBCode
+    #   @param objects [Array<#to_s>] objects to print
+    #   @param bbcode (see Terminal::Text::Formatter#initialize)
     #   @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.
+    #   Print objects to the terminal followed by newlines.
     #
-    #   Optionally interprets embedded BBCode (see {Ansi.bbcode}).
+    #   @example
+    #     Terminal.puts('[bold]Hello[/bold]', '[italic]World[/italic]')
     #
-    #   @param objects [Array<#to_s>] any number of objects to write
-    #   @param bbcode [true|false] whether to interpret embedded BBCode
+    #   @param objects [Array<#to_s>] objects to print
+    #   @param bbcode (see Terminal::Text::Formatter#initialize)
     #   @return [nil]
 
-    # @!endgroup
+    # @!method fputs(*objects, bbcode: true, spaces: true, eol: true, align: nil, width: nil, height: nil, padding: nil, prefix: nil, suffix: nil)
+    #
+    #   Formatted output with word-wrapping, alignment, and padding.
+    #
+    #   @see Terminal::Text::Formatter.format
+    #
+    #   @example
+    #     Terminal.fputs('Hello World', align: :center, width: 40)
+    #
+    #   @param objects [Array<#to_s>] text to process
+    #   @param bbcode (see Terminal::Text::Formatter#initialize)
+    #   @param spaces (see Terminal::Text::Formatter#initialize)
+    #   @param eol (see Terminal::Text::Formatter#initialize)
+    #   @param (see Terminal::Text::Formatter#format)
+    #   @return [nil]
+    #   @raise (see Terminal::Text::Formatter#format)
 
-    # @!group Output helper methods
+    # @!method raw_write(object)
+    #
+    #   Write raw bytes directly to the terminal without BBCode or ANSI
+    #   processing.
+    #
+    #   @param object [#to_s] object to write
+    #   @return [Integer, nil] bytes written, or +nil+ on error
 
     # @!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.
+    #   @note Reference-counted; safe for nested use.
+    #
+    #   Calls are reference-counted — nested calls are safe; the cursor
+    #   is only hidden on the first call and shown when the last matching
+    #   {show_cursor} is called.
     #
-    #   @return [Terminal] itself
+    #   @see .show_cursor
+    #
+    #   @return [self]
 
     # @!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
+    #   @note Reference-counted; safe for nested use.
+    #
+    #   @see .hide_cursor
+    #
+    #   @return [self]
 
     # @!method show_alt_screen
     #
-    #   Show the alternate screen.
-    #   Will not send the control code if the alternate screen is already used.
+    #   Switch to the alternate screen buffer.
+    #
+    #   @note Reference-counted; safe for nested use.
     #
-    #   When you called {show_alt_screen} n-times you need to call
-    #   {hide_alt_screen} n-times to show the default screen again.
+    #   @see .hide_alt_screen
     #
-    #   @return [Terminal] itself
+    #   @return [self]
 
     # @!method hide_alt_screen
     #
-    #   Hide the alternate screen.
-    #   Will not send the control code if the alternate screen is not used.
+    #   Switch back from the alternate screen buffer.
+    #
+    #   @note Reference-counted; safe for nested use.
     #
-    #   When you called {show_alt_screen} n-times you need to call
-    #   {hide_alt_screen} n-times to show the default screen again.
+    #   @see .show_alt_screen
     #
-    #   @return [Terminal] itself
+    #   @return [self]
 
-    # Define callback executed when terminal is resized
+    # Register a callback to be invoked when the terminal is resized.
     #
-    # @return [Terminal] itself
+    # @example
+    #   Terminal.on_resize { puts "New size: #{Terminal.size}" }
+    #
+    # @yield called on terminal resize
+    # @return [self]
     def on_resize(&block)
-      block ? @on_resize = block : @on_resize&.call
+      @on_resize = block
       self
     end
 
+    #
     # @!endgroup
+    #
 
     private
 
@@ -228,18 +242,18 @@ module Terminal
 
   tty, ansi = __output_modes
   if tty.nil?
-    require_relative 'output/dumb'
+    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'
+      require_relative('output/ansi')
       extend AnsiOutput
       __init_tty if tty
     else
-      require_relative 'output/dumb'
+      require_relative('output/dumb')
       extend DumbOutput
     end
   end

data/lib/terminal/rspec/helper.rb

@@ -1,5 +1,34 @@
 # frozen_string_literal: true
 
+# RSpec shared context for testing code that uses Terminal.rb.
+#
+# Stubs all Terminal I/O methods and provides +stdout+, +stdin+, and
+# +stdoutstr+ test helpers. Output is captured into the +stdout+ array;
+# input is read from the +stdin+ array.
+#
+# @example Basic usage
+#   RSpec.describe MyClass do
+#     include_context 'with Terminal.rb'
+#
+#     it 'prints a greeting' do
+#       my_object.greet
+#       expect(stdoutstr).to include('Hello')
+#     end
+#   end
+#
+# @example Custom terminal settings
+#   include_context 'with Terminal.rb', ansi: false, colors: 8,
+#     size: [40, 120]
+#
+# @param ansi [true, false] mock ANSI support (default: +true+)
+# @param application [Symbol] mock terminal application
+#   (default: +:kitty+)
+# @param colors [Integer, Symbol] mock color depth; use +:true_color+
+#   for 16777216 (default: +256+)
+# @param size [Array<Integer, Integer>] mock terminal size as
+#   +[rows, columns]+ (default: +[25, 80]+)
+# @param pos [Array<Integer, Integer>] mock cursor position as
+#   +[row, column]+ (default: +[1, 1]+)
 RSpec.shared_context 'with Terminal.rb' do |ansi: true, application: :kitty, colors: 256, size: [25, 80], pos: [1, 1]|
   let(:stdout) { [] }
   let(:stdin) { [] }
@@ -34,7 +63,7 @@ RSpec.shared_context 'with Terminal.rb' do |ansi: true, application: :kitty, col
 
     allow(Terminal).to receive(:print) do |*objects, bbcode: true|
       bbcode = bbcode_[bbcode]
-      objects.flatten.each { stdout.push(bbcode[_1]) unless _1.nil? }
+      objects.flatten.each { stdout.push(bbcode[it]) unless it.nil? }
       nil
     end
 

data/lib/terminal/shell.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module Terminal
+  # @private
   module Shell
     class << self
-      def exec(cmd, env: {}, shell: false, input: nil, **options)
+      def run(*cmd, env: {}, shell: false, input: nil, **options)
         options = options.except(:in, :out, :err)
-        cmd = cmd.map! { _escape(_1) }.join(' ') if shell
+        cmd = cmd.map! { _escape(it) }.join(' ') if shell
         input = Input[input]
         thread = nil
 
@@ -64,19 +65,22 @@ module Terminal
 
       def _escape(str)
         return "''" if str.empty?
-        str.gsub(%r{[^A-Za-z0-9_\-.,:+/@\n]}, "\\\\\\&").gsub("\n", "'\n'")
+        str = str.gsub(%r{[^A-Za-z0-9_\-.,:+/@\n]}, "\\\\\\&")
+        str.gsub!("\n", "'\n'")
+        str
       end
     end
 
+    # @private
     module Input
       def self.[](obj)
         return unless obj
         return copy_writer(obj) if obj.respond_to?(:readpartial)
         return copy_writer(obj.to_io) if obj.respond_to?(:to_io)
-        return array_writer(obj) if obj.is_a?(Array)
+        return array_writer(obj) if Array === obj
         if obj.respond_to?(:each)
           return enum_writer(obj.enum_for(:each)) if obj.respond_to?(:enum_for)
-          return enum_writer(Enumerator.new { |y| obj.each { y << _1 } })
+          return enum_writer(Enumerator.new { |y| obj.each { y << it } })
         end
         return array_writer(obj.to_a) if obj.respond_to?(:to_a)
         proc do |io|
@@ -93,7 +97,7 @@ module Terminal
       end
 
       def self.array_writer(array, idx = -1)
-        proc { _1.write(array[idx += 1] || next) }
+        proc { it.write(array[idx += 1] || next) }
       end
 
       def self.enum_writer(enum)