terminal_rb 0.14.0 → 0.16.0

data/lib/terminal/text.rb

@@ -24,15 +24,14 @@ module Terminal
       # some are ambiguous. The function uses {ambiguous_char_width} for each of
       # these characters.
       #
-      # @param object [#to_s] str to process
+      # @param str [#to_s] str to process
       # @param bbcode [true|false] whether to interpret embedded BBCode
       # @return [Integer] display width
       def width(str, bbcode: true)
-        str = bbcode ? Ansi.unbbcode(str) : str.to_s
-        return 0 if str.empty?
+        return 0 if (str = bbcode ? Ansi.unbbcode(str) : str.to_s).empty?
         str = str.encode(@encoding) if str.encoding != @encoding
         width = 0
-        str.scan(WIDTH_SCANNER) do |sp, gc|
+        str.scan(@scan_width) do |sp, gc|
           next width += char_width(gc) if gc
           width += 1 if sp
         end
@@ -68,14 +67,14 @@ module Terminal
         &block
       )
         unless limit
-          snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, Word)
-          return block ? lines(snippeds, &block) : to_enum(:lines, snippeds)
+          snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
+          return block ? lines(snippets, &block) : to_enum(:lines, snippets)
         end
         limit = limit.to_i
         raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
-        snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, WordEx)
-        return lim_lines(snippeds, limit, &block) if block
-        to_enum(:lim_lines, snippeds, limit)
+        snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
+        return lim_lines(snippets, limit, &block) if block
+        to_enum(:lim_lines, snippets, limit)
       end
       alias each each_line
 
@@ -98,14 +97,14 @@ module Terminal
         &block
       )
         unless limit
-          snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, Word)
-          return block ? pairs(snippeds, &block) : to_enum(:pairs, snippeds)
+          snippets = as_snippets(text, bbcode, ansi, ignore_newline, Word)
+          return block ? pairs(snippets, &block) : to_enum(:pairs, snippets)
         end
         limit = limit.to_i
         raise(ArgumentError, "invalid limit - #{limit}") if limit < 1
-        snippeds = as_snippeds(text, bbcode, ansi, ignore_newline, WordEx)
-        return lim_pairs(snippeds, limit, &block) if block
-        to_enum(:lim_pairs, snippeds, limit)
+        snippets = as_snippets(text, bbcode, ansi, ignore_newline, WordEx)
+        return lim_pairs(snippets, limit, &block) if block
+        to_enum(:lim_pairs, snippets, limit)
       end
       alias each_with_size each_line_with_size
 
@@ -123,12 +122,12 @@ module Terminal
         char.size < 2 ? 1 : char.each_char.sum { char_width(_1) }
       end
 
-      def lim_pairs(snippeds, limit)
+      def lim_pairs(snippets, limit)
         line = @empty.dup
         size = 0
         csi = nil
-        snippeds.each do |snipped|
-          if snipped == :space
+        snippets.each do |snippet|
+          if snippet == :space
             next if size == 0
             next line << ' ' if (size += 1) <= limit
             yield(line, size - 1)
@@ -136,31 +135,31 @@ module Terminal
             next size = 0
           end
 
-          if snipped == :nl
+          if snippet == :nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
             line = "#{csi}"
             next size = 0
           end
 
-          if snipped == :hard_nl
+          if snippet == :hard_nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
             line = @empty.dup
             csi = nil
             next size = 0
           end
 
-          if snipped == CsiEnd
+          if snippet == CsiEnd
             line << CsiEnd if csi
             next csi = nil
           end
 
-          next line << (csi = snipped) if snipped.is_a?(Csi)
-          next line << snipped if snipped.is_a?(Osc)
+          next line << (csi = snippet) if snippet.is_a?(Csi)
+          next line << snippet if snippet.is_a?(Osc)
 
           # Word:
 
-          if (ns = size + snipped.size) <= limit
-            line << snipped
+          if (ns = size + snippet.size) <= limit
+            line << snippet
             next size = ns
           end
 
@@ -170,16 +169,16 @@ module Terminal
           end
           yield(line, size) if size != 0
 
-          if snipped.size <= limit
-            line = "#{csi}#{snipped}"
-            next size = snipped.size
+          if snippet.size <= limit
+            line = "#{csi}#{snippet}"
+            next size = snippet.size
           end
 
-          words = snipped.split(limit)
+          words = snippet.split(limit)
           if words[-1].size <= limit
-            snipped = words.pop
-            line = "#{csi}#{snipped}"
-            size = snipped.size
+            snippet = words.pop
+            line = "#{csi}#{snippet}"
+            size = snippet.size
           else
             line = "#{csi}"
             size = 0
@@ -189,51 +188,51 @@ module Terminal
         nil
       end
 
-      def pairs(snippeds)
+      def pairs(snippets)
         line = @empty.dup
         size = 0
         csi = nil
-        snippeds.each do |snipped|
-          if snipped == :space
+        snippets.each do |snippet|
+          if snippet == :space
             next if size == 0
             line << ' '
             next size += 1
           end
 
-          if snipped == :nl
+          if snippet == :nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
             line = "#{csi}"
             next size = 0
           end
 
-          if snipped == :hard_nl
+          if snippet == :hard_nl
             line[-1] == ' ' ? yield(line.chop, size - 1) : yield(line, size)
             line = @empty.dup
             csi = nil
             next size = 0
           end
 
-          if snipped == CsiEnd
+          if snippet == CsiEnd
             line << CsiEnd if csi
             next csi = nil
           end
 
-          next line << (csi = snipped) if snipped.is_a?(Csi)
-          next line << snipped if snipped.is_a?(Osc)
+          next line << (csi = snippet) if snippet.is_a?(Csi)
+          next line << snippet if snippet.is_a?(Osc)
 
           # Word:
-          line << snipped
-          size += snipped.size
+          line << snippet
+          size += snippet.size
         end
         nil
       end
 
-      def lim_lines(snippeds, limit)
+      def lim_lines(snippets, limit)
         line = @empty.dup
         size = 0
         csi = nil
-        snippeds.each do |snipped|
-          if snipped == :space
+        snippets.each do |snippet|
+          if snippet == :space
             next if size == 0
             next line << ' ' if (size += 1) <= limit
             yield(line)
@@ -241,31 +240,31 @@ module Terminal
             next size = 0
           end
 
-          if snipped == :nl
+          if snippet == :nl
             yield(line[-1] == ' ' ? line.chop : line)
             line = "#{csi}"
             next size = 0
           end
 
-          if snipped == :hard_nl
+          if snippet == :hard_nl
             yield(line[-1] == ' ' ? line.chop : line)
             line = @empty.dup
             csi = nil
             next size = 0
           end
 
-          if snipped == CsiEnd
+          if snippet == CsiEnd
             line << CsiEnd if csi
             next csi = nil
           end
 
-          next line << (csi = snipped) if snipped.is_a?(Csi)
-          next line << snipped if snipped.is_a?(Osc)
+          next line << (csi = snippet) if snippet.is_a?(Csi)
+          next line << snippet if snippet.is_a?(Osc)
 
           # Word:
 
-          if (ns = size + snipped.size) <= limit
-            line << snipped
+          if (ns = size + snippet.size) <= limit
+            line << snippet
             next size = ns
           end
 
@@ -275,16 +274,16 @@ module Terminal
           end
           yield(line) if size != 0
 
-          if snipped.size <= limit
-            line = "#{csi}#{snipped}"
-            next size = snipped.size
+          if snippet.size <= limit
+            line = "#{csi}#{snippet}"
+            next size = snippet.size
           end
 
-          words = snipped.split(limit)
+          words = snippet.split(limit)
           if words[-1].size <= limit
-            snipped = words.pop
-            line = "#{csi}#{snipped}"
-            size = snipped.size
+            snippet = words.pop
+            line = "#{csi}#{snippet}"
+            size = snippet.size
           else
             line = "#{csi}"
             size = 0
@@ -294,46 +293,46 @@ module Terminal
         nil
       end
 
-      def lines(snippeds)
+      def lines(snippets)
         line = @empty.dup
         size = 0
         csi = nil
-        snippeds.each do |snipped|
-          if snipped == :space
+        snippets.each do |snippet|
+          if snippet == :space
             next if size == 0
             line << ' '
             next size += 1
           end
 
-          if snipped == :nl
+          if snippet == :nl
             yield(line[-1] == ' ' ? line.chop : line)
             line = "#{csi}"
             next size = 0
           end
 
-          if snipped == :hard_nl
+          if snippet == :hard_nl
             yield(line[-1] == ' ' ? line.chop : line)
             line = @empty.dup
             csi = nil
             next size = 0
           end
 
-          if snipped == CsiEnd
+          if snippet == CsiEnd
             line << CsiEnd if csi
             next csi = nil
           end
 
-          next line << (csi = snipped) if snipped.is_a?(Csi)
-          next line << snipped if snipped.is_a?(Osc)
+          next line << (csi = snippet) if snippet.is_a?(Csi)
+          next line << snippet if snippet.is_a?(Osc)
 
           # Word:
-          line << snipped
-          size += snipped.size
+          line << snippet
+          size += snippet.size
         end
         nil
       end
 
-      def as_snippeds(text, bbcode, ansi, ignore_newline, word_class)
+      def as_snippets(text, bbcode, ansi, ignore_newline, word_class)
         ret = []
         last = nil
         text.each do |txt|
@@ -344,7 +343,7 @@ module Terminal
 
           txt = txt.encode(@encoding) if txt.encoding != @encoding
 
-          txt.scan(SCAN_EXPR) do |nl, csi, osc, space, gc|
+          txt.scan(@scan_snippet) do |nl, csi, osc, space, gc|
             if gc
               next last.add(gc, char_width(gc)) if last.is_a?(word_class)
               next ret << (last = word_class.new(gc, char_width(gc)))
@@ -442,29 +441,25 @@ module Terminal
       end
     end
 
-    private_constant :Osc, :CsiEnd, :Csi, :Word, :WordEx
-
     @ambiguous_char_width = 1
-    @encoding = Encoding::UTF_8
-    @empty = String.new(encoding: @encoding).freeze
+    @empty = String.new(encoding: @encoding = Encoding::UTF_8).freeze
 
-    SCAN_EXPR =
+    @scan_snippet =
       /\G(?:
         (\r?\n)
-        | (\e\[[\d;:\?]*[ABCDEFGHJKSTfhilmnsu])
+        | (\e\[[\d;:?]*[ABCDEFGHJKSTfhilmnsu])
         | (\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
         | (\s+)
         | (\X)
       )/x
 
-    WIDTH_SCANNER =
+    @scan_width =
       /\G(?:
-        (?:\e\[[\d;:\?]*[ABCDEFGHJKSTfhilmnsu])
+        (?:\e\[[\d;:?]*[ABCDEFGHJKSTfhilmnsu])
         | (?:\e\]\d+(?:;[^\a\e]+)*(?:\a|\e\\))
         | (\s+)
         | (\X)
       )/x
-    private_constant :SCAN_EXPR, :WIDTH_SCANNER
 
     @ctrlchar_width = {
       0x00 => 0,
@@ -502,6 +497,7 @@ module Terminal
     }.compare_by_identity.freeze
 
     autoload :CharWidth, "#{__dir__}/text/char_width.rb"
-    private_constant :CharWidth
+
+    private_constant :Osc, :Csi, :CsiEnd, :Word, :WordEx, :CharWidth
   end
 end

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -10,7 +10,7 @@ require_relative 'terminal/input'
 # It automagically detects whether your terminal supports ANSI features, like
 # coloring (see {colors}) or the
 # [CSIu protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol) support
-# (see {read_key_event} and {input_mode}).
+# (see {read_key_event}, {on_key_event} and {input_mode}).
 # It calculates the display width for Unicode chars (see {Text.width}) and help
 # you to display text with word-wise line breaks (see {Text.each_line}).
 #
@@ -19,8 +19,8 @@ module Terminal
     # Return true if the current terminal supports ANSI control codes.
     # When the terminal does not support it, {colors} will return 2 (two) and
     # all output methods ({<<}, {print}, {puts}) will not forward ANSI control
-    # codes to the terminal, {read_key_event} will not support extended key
-    # codes.
+    # codes to the terminal, {read_key_event} and {on_key_event} will not
+    # support extended key codes and/or mouse events.
     #
     # @attribute [r] ansi?
     # @return [Boolean] whether ANSI control codes are supported
@@ -154,6 +154,30 @@ module Terminal
       self
     end
 
+    # 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.
     #
@@ -266,7 +290,7 @@ module Terminal
 
     # @private
     def raw_write(str)
-      @out&.write(str)
+      @out&.syswrite(str)
     rescue IOError
       @out = nil
     end
@@ -290,7 +314,7 @@ module Terminal
     end
   end
 
-  @cc = 0
+  @cc = @as = 0
   tty, @ansi = _determine_modes
 
   unless tty.nil?

data/terminal_rb.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/terminal/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'terminal_rb'
+  spec.version = Terminal::VERSION
+  spec.summary = <<~SUMMARY.tr("\n", ' ')
+    Fast terminal access with ANSI, CSIu, mouse eventing, BBCode, word-wise
+    line break support and much more.
+  SUMMARY
+  spec.description = <<~DESCRIPTION.tr("\n", ' ')
+    Terminal.rb supports you with input and output on your terminal.
+    Simple BBCode-like markup for attributes and coloring, word-wise line
+    breaks, correct special key recognition and mouse event reporting enable
+    you to implement your CLI app quickly and easily.
+  DESCRIPTION
+
+  spec.author = 'Mike Blumtritt'
+  spec.licenses = %w[MIT Ruby]
+  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['rubygems_mfa_required'] = 'true'
+  spec.metadata['yard.run'] = 'yard'
+
+  spec.required_ruby_version = '> 3.0'
+
+  spec.files = Dir['lib/**/*.rb'] + Dir['examples/*.rb']
+  spec.files << 'terminal_rb.gemspec' << '.yardopts'
+  spec.executables = %w[bbcode]
+  spec.extra_rdoc_files = %w[README.md]
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -10,8 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'Terminal.rb supports you with input and output on your terminal. Simple
-  BBCode-like markup for attributes and coloring, word-wise line breaks, and correct
-  special key recognition enable you to implement your CLI app quickly and easily. '
+  BBCode-like markup for attributes and coloring, word-wise line breaks, correct special
+  key recognition and mouse event reporting enable you to implement your CLI app quickly
+  and easily. '
 executables:
 - bbcode
 extensions: []
@@ -28,6 +29,7 @@ files:
 - examples/bbcode.rb
 - examples/info.rb
 - examples/key-codes.rb
+- examples/text.rb
 - lib/terminal.rb
 - lib/terminal/ansi.rb
 - lib/terminal/ansi/named_colors.rb
@@ -40,9 +42,11 @@ files:
 - lib/terminal/text/char_width.rb
 - lib/terminal/version.rb
 - lib/terminal_rb.rb
+- terminal_rb.gemspec
 homepage: https://codeberg.org/mblumtritt/Terminal.rb
 licenses:
 - MIT
+- Ruby
 metadata:
   source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
   bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
@@ -63,7 +67,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
-summary: Fast terminal access with ANSI, CSIu, BBCode, word-wise line break support.
+summary: Fast terminal access with ANSI, CSIu, mouse eventing, BBCode, word-wise line
+  break support and much more.
 test_files: []