terminal_rb 0.12.2 → 0.14.0

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.12.2'
+  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.12.2
+  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: []
@@ -29,12 +30,12 @@ files:
 - examples/key-codes.rb
 - lib/terminal.rb
 - lib/terminal/ansi.rb
-- lib/terminal/ansi/attributes.rb
 - lib/terminal/ansi/named_colors.rb
 - lib/terminal/detect.rb
 - 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
@@ -53,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
@@ -62,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: []