terminal_rb 1.0.6 → 1.0.9

data/lib/terminal.rb

@@ -72,28 +72,52 @@ module Terminal
 
     # Execute a shell command.
     #
-    # @overload sh(*cmd, **options)
-    #   Run a command and capture output.
+    # Output lines are collected or yielded without their trailing newline.
+    #
+    # @overload sh(*cmd, env: {}, shell: false, input: nil, **options)
+    #   Run a command and capture its output.
+    #
+    #   @example
+    #     status, output, error = Terminal.sh('echo', 'hello')
+    #     output # => ["hello"]
+    #
     #   @param cmd [Array<String>] command and arguments
-    #   @param options [Hash] options passed to the shell runner
+    #   @param env [Hash] environment variables for the command
+    #   @param shell [true, false]
+    #     when true the `cmd` is executed via the shell,
+    #     when false, the executable is direct executed
+    #     (see `Process.spawn` for this)
+    #   @param input [String, IO, Array<String>, Enumerable, nil]
+    #     data written to the command's standard input
+    #   @param options [Hash] passed to `Process.spawn`
+    #     (`:in`, `:out`, `:err` are ignored)
     #   @return [Array<Process::Status, Array<String>, Array<String>>]
     #     `[status, stdout_lines, stderr_lines]`
+    #   @return [nil] when the command can not be executed
+    #
+    # @overload sh(*cmd, env: {}, shell: false, input: nil, **options, &block)
+    #   Run a command and stream its output to a block.
+    #
     #   @example
-    #     status, output, error = Terminal.sh('echo', 'hello')
-    #     output # => ["hello\n"]
+    #     Terminal.sh('make') do |line, type|
+    #       Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
+    #     end
     #
-    # @overload sh(*cmd, **options, &block)
-    #   Run a command and stream output to a block.
     #   @param cmd [Array<String>] command and arguments
-    #   @param options [Hash] options passed to the shell runner
+    #   @param env [Hash] environment variables for the command
+    #   @param shell [true, false]
+    #     when true the `cmd` is executed via the shell,
+    #     when false, the executable is direct executed
+    #     (see `Process.spawn` for this)
+    #   @param input [String, IO, Array<String>, Enumerable, nil]
+    #     data written to the command's standard input
+    #   @param options [Hash] passed to `Process.spawn`
+    #     (`:in`, `:out`, `:err` are ignored)
     #   @yield [line, type] called for each output line
     #   @yieldparam line [String] the output line
     #   @yieldparam type [Symbol] `:output` or `:error`
     #   @return [Process::Status] the exit status
-    #   @example
-    #     Terminal.sh('make') do |line, type|
-    #       Terminal.puts(type == :error ? "[red]#{line}[/]" : line)
-    #     end
+    #   @return [nil] when the command can not be executed
     #
     # @raise [ArgumentError] if no command is given
     def sh(*cmd, **, &)
@@ -101,7 +125,8 @@ module Terminal
       return Shell.run(*cmd, **, &) if block_given?
       out = []
       err = []
-      [Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }, out, err]
+      ret = Shell.run(*cmd, **) { |l, t| (t == :error ? err : out) << l }
+      [ret, out, err] if ret
     end
 
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: terminal_rb
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.9
 platform: ruby
 authors:
 - Mike Blumtritt
@@ -60,7 +60,7 @@ metadata:
   yard.run: yard
   source_code_uri: https://codeberg.org/mblumtritt/Terminal.rb
   bug_tracker_uri: https://codeberg.org/mblumtritt/Terminal.rb/issues
-  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.6
+  documentation_uri: https://rubydoc.info/gems/terminal_rb/1.0.9
 rdoc_options: []
 require_paths:
 - lib
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Fast terminal access with ANSI, CSIu, mouse events, BBCode, word-wise line
   break support and much more.