terminal_rb 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 756d1e0e016472a063f9d64650f4731ef6e8fe272d6a84c4e001119f050af3ea
-  data.tar.gz: 74c24ba64e08e6dc79605c17b0ded59ecb8784a45f95dbe5be7f231c889fdab7
+  metadata.gz: 107b7b65dc5f58b1178e01fc86adad127df49fd175e56f7e36d2bfb873fc17a9
+  data.tar.gz: dfbf4797df22ac2803034a85a00fce2c480e4530840abd0d2a900bfb98993db5
 SHA512:
-  metadata.gz: 68bb81c425cb5df44650acc351a28cbbb3eccaea53b405167f1207ba3dc528093de6322bac087fad9301da7470711b4cd399f120233637e9b92f1727e9e2d4c9
-  data.tar.gz: 9e855ec0401d22c615fd6ff25e2adae7717ecbf3578ea40425e5ef580b9520ee23130c8d49814034f682590166d2319070c17c18407962fc8782b18c1fffe4fa
+  metadata.gz: 115235b382d02c4c5242925e1bf1ff3b9928702b30682dd4a2964282b11df6339118da582e0eebc096806005f781a537688741eab2e94984db391abaf6b4ec72
+  data.tar.gz: 2718bf0147fcb7c3d84374f59c4f8ea4862c58dfd6982057196a78bd1f4308eb9c319a55ba3c41339a45a6fa994b1449b2cedb2e00ce6de5548dd3eaa5b98fa0

data/README.md

@@ -1,10 +1,10 @@
 # Terminal.rb ![version](https://img.shields.io/gem/v/terminal_rb?label=)
 
-Terminal access with super fast ANSI control codes support and [BBCode-like](https://en.wikipedia.org/wiki/BBCode) embedded text attribute syntax.
+Terminal.rb supports you with input and output on your terminal. Simple [BBCode](https://en.wikipedia.org/wiki/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.
 
 - Gem: [rubygems.org](https://rubygems.org/gems/terminal_rb)
 - Source: [codeberg.org](https://codeberg.org/mblumtritt/Terminal.rb)
-- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/Terminal)
+- Help: [rubydoc.info](https://rubydoc.info/gems/terminal_rb/index)
 
 ## Features
 

data/lib/terminal/ansi.rb

@@ -387,7 +387,7 @@ module Terminal
 
       # Erase screen part.
       #
-      # @param [:below, :above, :all, :scrollback] part screen part to erase
+      # @param part [:below, :above, :all, :scrollback] screen part to erase
       # @return (see cursor_up)
       def screen_erase(part = :all)
         "\e[#{
@@ -444,7 +444,7 @@ module Terminal
 
       # Erase part of line.
       #
-      # @param [:to_end, :to_start, :all] part line part to erase
+      # @param part [:to_end, :to_start, :all] line part to erase
       # @return (see cursor_up)
       def line_erase(part = :all)
         "\e[#{
@@ -468,7 +468,7 @@ module Terminal
       # Tabby,
       # WezTerm.
       #
-      # @param [#to_s] title text
+      # @param title [#to_s] text
       # @return (see cursor_up)
       def title(title) = "\e]0;#{title}\a"
 
@@ -481,8 +481,8 @@ module Terminal
       # Tabby,
       # WezTerm.
       #
-      # @param [#to_s] url URL to link to
-      # @param [#to_s] text text to display for the link
+      # @param url [#to_s] URL to link to
+      # @param text [#to_s] text to display for the link
       # @return (see cursor_up)
       def link(url, text) = "\e]8;;#{url}\a#{text}\e]8;;\a"
 
@@ -497,18 +497,19 @@ module Terminal
       # @example Half-height Greeting
       #   Terminal::Ansi.scale('Hello Ruby!', fracn: 1, fracd: 2, vertical: :centered)
       #
-      # @param [#to_s] text text to scale
-      # @param [Integer, nil] scale
+      # @param text [#to_s]
+      #   text to scale
+      # @param scale [Integer, nil]
       #   overall scale size, range 1..7
-      # @param [Integer, nil] width
+      # @param width [Integer, nil]
       #   with in cells, range 0..7
-      # @param [Integer, nil] fracn
+      # @param fracn [Integer, nil]
       #   numerator for the fractional scale, range: 0..15
-      # @param [Integer, nil] fracd
+      # @param fracd [Integer, nil]
       #   denominator for the fractional scale, range: 0..15, > fracn
-      # @param [:top, :bottom, :centered, nil] vertical
+      # @param vertical [:top, :bottom, :centered, nil]
       #   vertical alignment to use for fractionally scaled text
-      # @param [:left, :right, :centered, nil] horizontal
+      # @param horizontal [:left, :right, :centered, nil]
       #   horizontal alignment to use for fractionally scaled text
       # @return (see cursor_up)
       def scale(
@@ -787,66 +788,66 @@ module Terminal
     autoload :NAMED_COLORS, "#{__dir__}/ansi/named_colors.rb"
     private_constant :NAMED_COLORS
 
-    # @!visibility private
+    # @private
     RESET = self[:reset].freeze
 
-    # @!visibility private
+    # @private
     FULL_RESET = "\ec"
 
-    # @!visibility private
+    # @private
     CURSOR_HOME = cursor_pos(nil, nil).freeze
-    # @!visibility private
+    # @private
     CURSOR_FIRST_ROW = cursor_pos(1).freeze
-    # @!visibility private
+    # @private
     CURSOR_FIRST_COLUMN = cursor_column(1).freeze
 
-    # @!visibility private
+    # @private
     CURSOR_SHOW = "\e[?25h"
-    # @!visibility private
+    # @private
     CURSOR_HIDE = "\e[?25l"
 
     # @comment CURSOR_POS_SAVE_SCO = "\e[s"
     # @comment CURSOR_POS_SAVE_DEC = "\e7"
-    # @!visibility private
+    # @private
     CURSOR_POS_SAVE = "\e7"
 
     # @comment CURSOR_POS_RESTORE_SCO = "\e[u"
     # @comment CURSOR_POS_RESTORE_DEC = "\e8"
-    # @!visibility private
+    # @private
     CURSOR_POS_RESTORE = "\e8"
 
-    # @!visibility private
+    # @private
     SCREEN_ERASE = screen_erase.freeze
-    # @!visibility private
+    # @private
     SCREEN_ERASE_BELOW = screen_erase(:below).freeze
-    # @!visibility private
+    # @private
     SCREEN_ERASE_ABOVE = screen_erase(:above).freeze
-    # @!visibility private
+    # @private
     SCREEN_ERASE_SCROLLBACK = screen_erase(:scrollback).freeze
 
-    # @!visibility private
+    # @private
     SCREEN_SAVE = "\e[?47h"
-    # @!visibility private
+    # @private
     SCREEN_RESTORE = "\e[?47l"
 
-    # @!visibility private
+    # @private
     # @comment at least Kitty requires CURSOR_HOME too
     SCREEN_ALTERNATE = "\e[?1049h#{CURSOR_HOME}".freeze
-    # @!visibility private
+    # @private
     SCREEN_ALTERNATE_OFF = "\e[?1049l"
 
-    # @!visibility private
+    # @private
     SCREEN_REVERSE_MODE_ON = "\e[?5h"
-    # @!visibility private
+    # @private
     SCREEN_REVERSE_MODE_OFF = "\e[?5l"
 
-    # @!visibility private
+    # @private
     LINE_ERASE = line_erase.freeze
-    # @!visibility private
+    # @private
     LINE_ERASE_TO_END = line_erase(:to_end).freeze
-    # @!visibility private
+    # @private
     LINE_ERASE_TO_START = line_erase(:to_start).freeze
-    # @!visibility private
+    # @private
     LINE_ERASE_PREV = "#{cursor_prev_line(nil)}#{LINE_ERASE}".freeze
 
     # @comment seems not widely supported:

data/lib/terminal/input/key_event.rb

@@ -7,7 +7,7 @@ module Terminal
   class KeyEvent
     class << self
       # @attribute [w] caching
-      # @return [true, false] whether KeyCodes should be cached
+      # @return [true, false] whether {KeyEvent}s should be cached
       def caching = !!@cache
 
       # @attribute [w] caching
@@ -21,7 +21,7 @@ module Terminal
 
       # Translate a keyboard input string into a related KeyEvent
       #
-      # @param [String] raw keyboard input
+      # @param raw [String] keyboard input
       # @return [KeyEvent] related key event
       def [](raw)
         return new(raw, *@single_key[raw.ord]) if raw.size == 1
@@ -52,7 +52,7 @@ module Terminal
         unknown(raw)
       end
 
-      # @!visibility private
+      # @private
       def new(raw, key = raw, modifier = 0, extra = nil)
         @cache ? (@cache[raw] ||= super.freeze) : super.freeze
       end
@@ -164,7 +164,7 @@ module Terminal
     attr_reader :modifier
 
     # @comment for mouse events
-    # @!visibility private
+    # @private
     attr_reader :extra
 
     # Name of the key event.
@@ -188,16 +188,16 @@ module Terminal
     # @return [Array<Symbol, String>] all pressed keys
     def to_a = @ary.dup
 
-    # @!visibility private
+    # @private
     def to_ary = simple? ? [@raw] : [@raw, @name]
 
-    # @!visibility private
+    # @private
     def to_s = @name.dup
 
-    # @!visibility private
+    # @private
     def inspect = "<#{self.class.name} #{to_ary.map(&:inspect).join(' ')}>"
 
-    # @!visibility private
+    # @private
     def freeze
       @raw.freeze
       @key.freeze

data/lib/terminal/input.rb

@@ -28,7 +28,7 @@ module Terminal
     #
     # @deprecated Use rather {read_key_event} for better input handling.
     #
-    # @param [:named, :raw, :both] mode modifies the result
+    # @param mode [:named, :raw, :both] modifies the result
     # @return [String] key code ("as is") in `:raw` mode
     # @return [String] key name in `:named` mode
     # @return [[String, String]] key code and key name in `:both` mode
@@ -64,8 +64,8 @@ module Terminal
       return :dumb if im == 'dumb'
       return :legacy if im == 'legacy'
       return :dumb unless STDIN.tty?
-      if ansi? && _write("\e[>1u\e[?u\e[c") && csi_u?
-        at_exit { _write("\e[<u") }
+      if ansi? && raw_write("\e[>1u\e[?u\e[c") && csi_u?
+        at_exit { raw_write("\e[<u") }
         return :csi_u
       end
       :legacy
@@ -99,10 +99,10 @@ module Terminal
       # urxvt: '1015'
       # pixel: '1016'
       opts = each_move ? '1000;1003;1006;1015' : '1000;1006;1015'
-      opts = _write("\e[?#{opts}h") ? "\e[?#{opts}l" : nil
+      opts = raw_write("\e[?#{opts}h") ? "\e[?#{opts}l" : nil
       read_tty
     ensure
-      _write(opts) if opts
+      raw_write(opts) if opts
     end
 
     def read_tty

data/lib/terminal/rspec/helper.rb

@@ -53,7 +53,7 @@ RSpec.shared_context 'with Terminal.rb' do |ansi: true, application: :kitty, col
       nil
     end
 
-    allow(Terminal).to receive(:_write) do |object|
+    allow(Terminal).to receive(:raw_write) do |object|
       stdout.push(object = object.to_s)
       object.bytesize
     end

data/lib/terminal/shell.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Terminal
+  module Shell
+    class << self
+      def exec(cmd, env: {}, shell: false, input: nil, **options)
+        options = options.except(:in, :out, :err)
+        if shell
+          cmd = cmd.map! { _escape(_1) }.join(' ')
+        elsif cmd.size == 1 && cmd[0].include?(' ')
+          cmd = cmd[0]
+        end
+
+        input = Input.for(input)
+        ret = nil
+        with_io(options, input) do |cio, out_r, err_r, in_w|
+          thread = Process.detach(Process.spawn(env, *cmd, options))
+          begin
+            cio.each(&:close)
+            read = [out_r, err_r]
+            write = [in_w] if in_w
+            while !read.empty? || write
+              rr, wr, = IO.select(read, write)
+              if rr.include?(out_r)
+                begin
+                  yield(out_r.readline(chomp: true), :output)
+                rescue SystemCallError, IOError
+                  read.delete(out_r)
+                end
+              end
+              if rr.include?(err_r)
+                begin
+                  yield(err_r.readline(chomp: true), :error)
+                rescue SystemCallError, IOError
+                  read.delete(err_r)
+                end
+              end
+              next if wr.empty?
+              begin
+                next if input.call(in_w)
+                in_w.close
+                write = nil
+              rescue SystemCallError, IOError
+                write = nil
+              end
+            end
+          ensure
+            ret = thread.join.value
+          end
+        end
+        ret
+      rescue SystemCallError, IOError
+        nil
+      end
+
+      private
+
+      def with_io(options, input)
+        IO.pipe do |out_r, out_w|
+          IO.pipe do |err_r, err_w|
+            cio = [options[:out] = out_w, options[:err] = err_w]
+            return yield(cio, out_r, err_r) unless input
+            IO.pipe do |in_r, in_w|
+              cio << (options[:in] = in_r)
+              in_w.sync = true
+              yield(cio, out_r, err_r, in_w)
+            end
+          end
+        end
+      end
+
+      def _escape(str)
+        return +"''" if str.empty?
+        str = str.dup
+        str.gsub!(%r{[^A-Za-z0-9_\-.,:+/@\n]}, "\\\\\\&")
+        str.gsub!("\n", "'\n'")
+        str
+      end
+    end
+
+    module Input
+      def self.for(obj)
+        return unless obj
+        return CopyWriter.new(obj) if obj.respond_to?(:readpartial)
+        return CopyWriter.new(obj.to_io) if obj.respond_to?(:to_io)
+        return ArrayWriter.new(obj) if obj.is_a?(Array)
+        return EnumerableWriter.new(obj) if obj.respond_to?(:each)
+        return ArrayWriter.new(obj.to_a) if obj.respond_to?(:to_a)
+        Writer.new(obj)
+      end
+
+      class Writer
+        def call(io) = (io.write(_next) if @obj)
+        def initialize(obj) = (@obj = obj)
+        def _next = (_, @obj = @obj, nil).first
+      end
+
+      class CopyWriter < Writer
+        def call(io) = (IO.copy_stream(_next, io) if @obj)
+      end
+
+      class ArrayWriter
+        def call(io) = io.write(@ry[@idx += 1] || return)
+
+        def initialize(ary)
+          @ry = ary
+          @idx = -1
+        end
+      end
+
+      class EnumerableWriter
+        def call(io)
+          io.write(@enum.next)
+        rescue StopIteration
+          false
+        end
+
+        def initialize(enum)
+          @enum =
+            if enum.respond_to?(:enum_for)
+              enum.enum_for(:each)
+            else
+              Enumerator.new { |y| enum.each { y << _1 } }
+            end
+        end
+      end
+    end
+  end
+
+  private_constant :Shell
+end

data/lib/terminal/text/char_width.rb

@@ -3,7 +3,7 @@
 module Terminal
   module Text
     #
-    # Generated file; based on Unicode v16.0.0
+    # Generated file; based on Unicode v17.0.0
     #
     module CharWidth
       def self.[](ord) = @width[@last.bsearch_index { ord <= _1 }]
@@ -415,7 +415,9 @@ module Terminal
         0x1a7e,
         0x1a7f,
         0x1aaf,
-        0x1ace,
+        0x1add,
+        0x1adf,
+        0x1aeb,
         0x1aff,
         0x1b03,
         0x1b33,
@@ -887,7 +889,7 @@ module Terminal
         0x10d6d,
         0x10eaa,
         0x10eac,
-        0x10efb,
+        0x10ef9,
         0x10eff,
         0x10f45,
         0x10f50,
@@ -1037,6 +1039,12 @@ module Terminal
         0x11a96,
         0x11a97,
         0x11a99,
+        0x11b5f,
+        0x11b60,
+        0x11b61,
+        0x11b64,
+        0x11b65,
+        0x11b66,
         0x11c2f,
         0x11c36,
         0x11c37,
@@ -1099,13 +1107,13 @@ module Terminal
         0x16fe3,
         0x16fe4,
         0x16fef,
-        0x16ff1,
+        0x16ff6,
         0x16fff,
-        0x187f7,
-        0x187ff,
         0x18cd5,
         0x18cfe,
-        0x18d08,
+        0x18d1e,
+        0x18d7f,
+        0x18df2,
         0x1afef,
         0x1aff3,
         0x1aff4,
@@ -1178,6 +1186,14 @@ module Terminal
         0x1e4ef,
         0x1e5ed,
         0x1e5ef,
+        0x1e6e2,
+        0x1e6e3,
+        0x1e6e5,
+        0x1e6e6,
+        0x1e6ed,
+        0x1e6ef,
+        0x1e6f4,
+        0x1e6f5,
         0x1e8cf,
         0x1e8d6,
         0x1e943,
@@ -1251,7 +1267,7 @@ module Terminal
         0x1f6cf,
         0x1f6d2,
         0x1f6d4,
-        0x1f6d7,
+        0x1f6d8,
         0x1f6db,
         0x1f6df,
         0x1f6ea,
@@ -1271,14 +1287,16 @@ module Terminal
         0x1fa6f,
         0x1fa7c,
         0x1fa7f,
-        0x1fa89,
-        0x1fa8e,
+        0x1fa8a,
+        0x1fa8d,
         0x1fac6,
-        0x1facd,
+        0x1fac7,
+        0x1fac8,
+        0x1facc,
         0x1fadc,
         0x1fade,
-        0x1fae9,
-        0x1faef,
+        0x1faea,
+        0x1faee,
         0x1faf8,
         0x1ffff,
         0x2fffd,
@@ -1748,6 +1766,8 @@ module Terminal
         1,
         0,
         1,
+        0,
+        1,
         -1,
         1,
         -1,
@@ -2381,6 +2401,12 @@ module Terminal
         1,
         0,
         1,
+        0,
+        1,
+        0,
+        1,
+        0,
+        1,
         2,
         0,
         1,
@@ -2468,6 +2494,14 @@ module Terminal
         1,
         0,
         1,
+        0,
+        1,
+        0,
+        1,
+        0,
+        1,
+        0,
+        1,
         2,
         1,
         2,
@@ -2570,6 +2604,8 @@ module Terminal
         1,
         2,
         1,
+        2,
+        1,
         0,
         1,
         -1,

data/lib/terminal/text.rb

@@ -24,8 +24,8 @@ module Terminal
       # some are ambiguous. The function uses {ambiguous_char_width} for each of
       # these characters.
       #
-      # @param [#to_s] str object to process
-      # @param [true|false] bbcode whether to interpret embedded BBCode
+      # @param object [#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
@@ -45,15 +45,15 @@ module Terminal
       #   Terminal::Text.each_line('This is a simple test 😀', limit: 6).to_a
       #   # => ["This", "is a", "simple", "test", "😀"]
       #
-      # @param [#to_s, ...] text
+      # @param text [#to_s, ...]
       #   text objects to process
-      # @param [#to_i, nil] limit
+      # @param limit [#to_i, nil]
       #   optionally limit line size
-      # @param [true, false] bbcode
+      # @param bbcode [true, false]
       #   whether to interprete embedded BBCode (see {Ansi.bbcode})
-      # @param [true, false] ansi
+      # @param ansi [true, false]
       #   whether to keep embedded ANSI control codes
-      # @param [true, false] ignore_newline
+      # @param ignore_newline [true, false]
       #   wheter to ignore embedded line breaks (`"\r\n"` or `"\n"`)
       # @yield [String] text line
       # @return [Enumerator] when no block given

data/lib/terminal/version.rb

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

data/lib/terminal.rb

@@ -7,20 +7,20 @@ 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 (see {Ansi.bbcode}).
-#
 # 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}).
 # It calculates the display width for Unicode chars (see {Text.width}) and help
-# you to display text with line formatting (see {Text.each_line}).
+# you to display text with word-wise line breaks (see {Text.each_line}).
 #
 module Terminal
   class << self
     # Return true if the current terminal supports ANSI control codes.
-    # When the terminal does not support it, {colors} will return `2` and all
-    # output methods ({<<}, {print}, {puts}) will not forward ANSI control
-    # codes to the terminal, {read_key_event} will not support CSIu.
+    # 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.
     #
     # @attribute [r] ansi?
     # @return [Boolean] whether ANSI control codes are supported
@@ -31,34 +31,10 @@ module Terminal
     # 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`,
-    # - `:rio`,
-    # - `:tabby`,
-    # - `:terminator`,
-    # - `:terminology`,
-    # - `:terminus`,
-    # - `:termite`,
-    # - `:tmux`,
-    # - `:vscode`,
-    # - `:vt100`,
-    # - `:warp`,
-    # - `:wezterm`,
-    # - `:wyse`,
-    # - `:xnuppc`
+    # `:alacritty`, `:amiga`, `:code_edit`, `:dg_unix`, `:docker`, `:fluent`,
+    # `:hpterm`, `:hyper`, `:iterm`, `:macos`, `:mintty`, `:ms_terminal`,
+    # `:ncr260`, `:nsterm`, `:terminator`, `:terminology`, `:termite`,
+    # `:vt100`, `:warp`, `:wezterm`, `:wyse`, `:xnuppc`
     #
     # @attribute [r] application
     # @return [Symbol, nil] the application identifier
@@ -162,7 +138,7 @@ module Terminal
     #
     # @return [Terminal] itself
     def hide_cursor
-      _write(Ansi::CURSOR_HIDE) if ansi? && (@cc += 1) == 1
+      raw_write(Ansi::CURSOR_HIDE) if ansi? && (@cc += 1) == 1
       self
     end
 
@@ -174,14 +150,14 @@ module Terminal
     #
     # @return [Terminal] itself
     def show_cursor
-      _write(Ansi::CURSOR_SHOW) if @cc > 0 && (@cc -= 1).zero?
+      raw_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
+    # @param object [#to_s] object to write
     # @return [Terminal] itself
     def <<(object)
       @out.write(Ansi.bbcode(object)) if @out && object != nil
@@ -194,8 +170,8 @@ module Terminal
     # 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
+    # @param objects [Array<#to_s>] any number of objects to write
+    # @param bbcode [true|false] whether to interpret embedded BBCode
     # @return [nil]
     def print(*objects, bbcode: true)
       return unless @out
@@ -225,14 +201,78 @@ module Terminal
       @out = nil
     end
 
-    private
+    # Execute a command and report command output line by line
+    # or capture the output.
+    #
+    # @example Execute a command wih arguments
+    #   ret, out, = Terminal.sh('curl', '--version')
+    #   raise('command not found - curl') unless ret
+    #   puts out
+    #
+    # @example Execute shell commands and print error
+    #   ret, _, err = Terminal.sh("mkdir '/test' && cd '/test'")
+    #   raise('unable to execute') unless ret
+    #   puts("error #{ret.exitstatus}: #{err.join}") unless ret.success?
+    #
+    # @example Copy a file content to clipboard
+    #   command = ENV.fetch('CLIP_COPY', 'pbcopy')
+    #   File.open(__FILE__) do |file|
+    #     ret, = Terminal.sh(*command, input: file)
+    #     raise("command not found - #{command}") unless ret
+    #   end
+    #
+    # @overload sh(*cmd, **options)
+    #   @return [[Process::Status, output, error]]
+    #     the status of the process successfully executed,
+    #     the captured output,
+    #     the captured error output,
+    #   @return [nil]
+    #     when the command was not executable
+    #
+    # @overload sh(*cmd, **options)
+    #   @yieldparam line [String]
+    #     next received line from the process
+    #   @yieldparam type [:output, :error]
+    #     whether the received line is standard output or error
+    #   @return [Process::Status]
+    #     the status of the process successfully executed
+    #   @return [nil]
+    #     when the command was not executable
+    #
+    # @param cmd [Array<#to_s>]
+    #   command line or command with arguments
+    # @param options [Hash]
+    #   options how to execute the new process;
+    #   see `Process.spawn` for default execution options provided by Ruby
+    # @option options [Hash<String,String>] :env
+    #   key/value pairs added to the ENV of the process;
+    #   with option `:unsetenv_others` set to `true` it replaces the ENV
+    # @option options [true, false] :shell
+    #   whether to create a seperate shell or not
+    # @option options [#readpartial, #to_io, Array, #each, #to_a, #to_s] :input
+    #   piped to the command as input
+    def sh(*cmd, **options, &block)
+      return Shell.exec(cmd, **options, &block) if block_given?
+      out = []
+      err = []
+      [
+        Shell.exec(cmd, **options) do |line, type|
+          (type == :error ? err : out) << line
+        end,
+        out,
+        err
+      ]
+    end
 
-    def _write(str)
+    # @private
+    def raw_write(str)
       @out&.write(str)
     rescue IOError
       @out = nil
     end
 
+    private
+
     def _default_size
       rows = ENV['LINES'].to_i
       columns = ENV['COLUMNS'].to_i
@@ -300,5 +340,6 @@ module Terminal
   dir = "#{__dir__}/terminal"
   autoload :Text, "#{dir}/text.rb"
   autoload :Detect, "#{dir}/detect.rb"
-  private_constant :Detect
+  autoload :Shell, "#{dir}/shell.rb"
+  private_constant :Detect, :Shell
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -9,8 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Terminal access with super fast ANSI control codes support, modern CSIu
-  input, word-wise line break, BBCode-like embedded text attribute syntax. '
+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. '
 executables:
 - bbcode
 extensions: []
@@ -34,6 +35,7 @@ files:
 - lib/terminal/input.rb
 - lib/terminal/input/key_event.rb
 - lib/terminal/rspec/helper.rb
+- lib/terminal/shell.rb
 - lib/terminal/text.rb
 - lib/terminal/text/char_width.rb
 - lib/terminal/version.rb
@@ -52,7 +54,7 @@ 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
@@ -61,7 +63,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, BBCode, word-wise line break support.
 test_files: []