qbash 0.4.0 → 0.4.2

data/lib/qbash.rb

@@ -1,24 +1,7 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'backtrace'
 require 'logger'
@@ -33,25 +16,64 @@ require 'tago'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Kernel
-  # Execute a single bash command.
+  # Execute a single bash command safely with proper error handling.
+  #
+  # QBash provides a safe way to execute shell commands with proper error handling,
+  # logging, and stdin/stdout management. It's designed to be simple for basic use
+  # cases while offering powerful options for advanced scenarios.
+  #
+  # == Basic Usage
+  #
+  #   # Execute a command and get its output
+  #   year = qbash('date +%Y')
+  #   puts "Current year: #{year}"
+  #
+  #   # Execute a command that might fail
+  #   files = qbash('find /tmp -name "*.log"')
+  #
+  # == Working with Exit Codes
+  #
+  #   # Get both output and exit code
+  #   output, code = qbash('grep "error" /var/log/system.log', both: true)
+  #   puts "Command succeeded" if code.zero?
   #
-  # For example:
+  #   # Accept multiple exit codes as valid
+  #   result = qbash('grep "pattern" file.txt', accept: [0, 1])
   #
-  #  year = qbash('date +%Y')
+  # == Providing Input via STDIN
   #
-  # If exit code is not zero, an exception will be raised.
+  #   # Pass data to command's stdin
+  #   result = qbash('wc -l', stdin: "line 1\nline 2\nline 3")
   #
-  # To escape arguments, use +Shellwords.escape()+ method.
+  # == Environment Variables
   #
-  # Stderr automatically merges with stdout.
+  #   # Set environment variables for the command
+  #   output = qbash('echo $NAME', env: { 'NAME' => 'Ruby' })
   #
-  # If you need full control over the process started, provide
-  # a block, which will receive process ID (integer) once the process
-  # is started.
+  # == Logging
+  #
+  #   # Enable detailed logging to stdout
+  #   qbash('ls -la', log: $stdout)
+  #
+  #   # Use custom logger with specific level
+  #   logger = Logger.new($stdout)
+  #   qbash('make all', log: logger, level: Logger::INFO)
+  #
+  # == Process Control
+  #
+  #   # Get control over long-running process
+  #   qbash('sleep 30') do |pid|
+  #     puts "Process #{pid} is running..."
+  #     # Do something while process is running
+  #     # Process will be terminated when block exits
+  #   end
+  #
+  # For command with multiple arguments, you can use +Shellwords.escape()+ to
+  # properly escape each argument. Stderr automatically merges with stdout.
   #
   # Read this <a href="https://github.com/yegor256/qbash">README</a> file for more details.
   #
-  # @param [String] cmd The command to run, for example +echo "Hello, world!"+
+  # @param [String, Array] cmd The command to run (String or Array of arguments)
   # @param [String] stdin The +stdin+ to provide to the command
   # @param [Hash] env Hash of environment variables
   # @param [Loog|IO] log Logging facility with +.debug()+ method (or +$stdout+, or nil if should go to +/dev/null+)
@@ -62,82 +84,77 @@ module Kernel
   def qbash(cmd, stdin: '', env: {}, log: Loog::NULL, accept: [0], both: false, level: Logger::DEBUG)
     env.each { |k, v| raise "env[#{k}] is nil" if v.nil? }
     cmd = cmd.reject { |a| a.nil? || (a.is_a?(String) && a.empty?) }.join(' ') if cmd.is_a?(Array)
-    mtd =
-      case level
-      when Logger::DEBUG
-        :debug
-      when Logger::INFO
-        :info
-      when Logger::WARN
-        :warn
-      when Logger::ERROR
-        :error
-      else
-        raise "Unknown log level #{level}"
+    logit =
+      lambda do |msg|
+        mtd =
+          case level
+          when Logger::DEBUG
+            :debug
+          when Logger::INFO
+            :info
+          when Logger::WARN
+            :warn
+          when Logger::ERROR
+            :error
+          else
+            raise "Unknown log level #{level}"
+          end
+        if log.nil?
+          # nothing to print
+        elsif log.respond_to?(mtd)
+          log.__send__(mtd, msg)
+        else
+          log.print("#{msg}\n")
+        end
       end
-    if log.nil?
-      # nothing to print
-    elsif log.respond_to?(mtd)
-      log.__send__(mtd, "+ #{cmd}")
-    else
-      log.print("+ #{cmd}\n")
-    end
+    logit["+ #{cmd}"]
     buf = ''
     e = 1
     start = Time.now
-    Open3.popen2e(env, "/bin/bash -c #{Shellwords.escape(cmd)}") do |sin, sout, thr|
+    Open3.popen2e(env, "/bin/bash -c #{Shellwords.escape(cmd)}") do |sin, sout, ctrl|
+      consume =
+        lambda do
+          loop do
+            break if sout.eof?
+            ln = sout.gets
+            next if ln.nil?
+            next if ln.empty?
+            buf += ln
+            ln = "##{ctrl.pid}: #{ln}"
+            logit[ln]
+          rescue IOError => e
+            logit[e.message]
+            break
+          end
+        end
       sin.write(stdin)
       sin.close
       if block_given?
-        closed = false
-        watch =
-          Thread.new do
-            until closed
-              begin
-                ln = sout.gets
-              rescue IOError => e
-                ln = Backtrace.new(e).to_s
-              end
-              ln = "##{thr.pid}: #{ln}"
-              if log.nil?
-                # no logging
-              elsif log.respond_to?(mtd)
-                log.__send__(mtd, ln)
-              else
-                log.print(ln)
-              end
-              buf += ln
-            end
-          end
-        pid = thr.pid
+        watch = Thread.new { consume.call }
+        watch.abort_on_exception = true
+        pid = ctrl.pid
         yield pid
+        sout.close
+        watch.join(0.01)
+        watch.kill if watch.alive?
         begin
-          Process.kill('TERM', pid)
-        rescue Errno::ESRCH
-          # simply ignore it
-        end
-        closed = true
-        watch.join
-      else
-        until sout.eof?
+          Process.getpgid(pid) # should be dead already (raising Errno::ESRCH)
+          Process.kill('TERM', pid) # let's try to kill it
           begin
-            ln = sout.gets
-          rescue IOError => e
-            ln = Backtrace.new(e).to_s
-          end
-          if log.nil?
-            # no logging
-          elsif log.respond_to?(mtd)
-            log.__send__(mtd, ln)
-          else
-            log.print(ln)
+            Process.getpgid(pid) # should be dead now (raising Errno::ESRCH)
+            raise "Process ##{pid} did not terminate after SIGTERM"
+          rescue Errno::ESRCH
+            logit["Process ##{pid} killed with SIGTERM"]
           end
-          buf += ln
-        end
-        e = thr.value.to_i
-        if !accept.nil? && !accept.include?(e)
-          raise "The command '#{cmd}' failed with exit code ##{e} in #{start.ago}\n#{buf}"
+        rescue Errno::ESRCH
+          logit["Process ##{pid} exited gracefully"]
         end
+      else
+        consume.call
+      end
+      e = ctrl.value.to_i
+      if !accept.nil? && !accept.include?(e)
+        raise "The command '#{cmd}' failed with exit code ##{e} in #{start.ago}\n#{buf}"
       end
     end
     return [buf, e] if both

data/qbash.gemspec

@@ -1,24 +1,7 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'English'
 
@@ -26,7 +9,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.required_ruby_version = '>=3.2'
   s.name = 'qbash'
-  s.version = '0.4.0'
+  s.version = '0.4.2'
   s.license = 'MIT'
   s.summary = 'Quick Executor of a BASH Command'
   s.description =

data/test/test__helper.rb

@@ -1,34 +1,31 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 $stdout.sync = true
 
 require 'simplecov'
-SimpleCov.start
-
 require 'simplecov-cobertura'
-SimpleCov.formatter = SimpleCov::Formatter::CoberturaFormatter
+unless SimpleCov.running || ENV['PICKS']
+  SimpleCov.command_name('test')
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::CoberturaFormatter
+    ]
+  )
+  SimpleCov.minimum_coverage 1
+  SimpleCov.minimum_coverage_by_file 1
+  SimpleCov.start do
+    add_filter 'test/'
+    add_filter 'vendor/'
+    add_filter 'target/'
+    track_files 'lib/**/*.rb'
+    track_files '*.rb'
+  end
+end
 
 require 'minitest/autorun'
-
 require 'minitest/reporters'
 Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]

data/test/test_qbash.rb

@@ -1,24 +1,7 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2024-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'minitest/autorun'
 require 'tmpdir'
@@ -98,7 +81,7 @@ class TestQbash < Minitest::Test
 
   def test_kills_in_thread
     Thread.new do
-      qbash('sleep 9999') do |pid|
+      qbash('sleep 9999', accept: nil) do |pid|
         Process.kill('KILL', pid)
       end
     end.join
@@ -109,9 +92,10 @@ class TestQbash < Minitest::Test
     buf = Loog::Buffer.new
     Dir.mktmpdir do |home|
       flag = File.join(home, 'started.txt')
+      cmd = "while true; do date; touch #{Shellwords.escape(flag)}; sleep 0.001; done"
       Thread.new do
         stdout =
-          qbash("while true; do date; touch #{Shellwords.escape(flag)}; sleep 0.001; done", log: buf) do |pid|
+          qbash(cmd, log: buf, accept: nil) do |pid|
             loop { break if File.exist?(flag) }
             Process.kill('KILL', pid)
           end
@@ -130,4 +114,21 @@ class TestQbash < Minitest::Test
       refute_empty(stdout)
     end
   end
+
+  def test_exists_after_background_stop
+    stop = false
+    t =
+      Thread.new do
+        qbash('trap "" TERM; tail -f /dev/null', accept: nil) do
+          loop { break if stop }
+        end
+      end
+    t.abort_on_exception = true
+    sleep(0.1)
+    stop = true
+    t.join(0.01)
+    t.kill
+    sleep(0.01)
+    refute_predicate(t, :alive?)
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: qbash
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Yegor Bugayenko
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backtrace
@@ -72,8 +71,8 @@ email: yegor256@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
 - LICENSE.txt
+- README.md
 files:
 - ".0pdd.yml"
 - ".gitattributes"
@@ -83,17 +82,20 @@ files:
 - ".github/workflows/markdown-lint.yml"
 - ".github/workflows/pdd.yml"
 - ".github/workflows/rake.yml"
+- ".github/workflows/reuse.yml"
+- ".github/workflows/typos.yml"
 - ".github/workflows/xcop.yml"
 - ".github/workflows/yamllint.yml"
 - ".gitignore"
 - ".pdd"
 - ".rubocop.yml"
 - ".rultor.yml"
-- ".simplecov"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
+- LICENSES/MIT.txt
 - README.md
+- REUSE.toml
 - Rakefile
 - lib/qbash.rb
 - qbash.gemspec
@@ -105,7 +107,6 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options:
 - "--charset=UTF-8"
 require_paths:
@@ -121,8 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Quick Executor of a BASH Command
 test_files: []

data/.simplecov

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-#
-# Copyright (c) 2024-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
-
-if Gem.win_platform?
-  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter[
-    SimpleCov::Formatter::HTMLFormatter
-  ]
-  SimpleCov.start do
-    add_filter '/test/'
-    add_filter '/features/'
-  end
-else
-  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
-    [SimpleCov::Formatter::HTMLFormatter]
-  )
-  SimpleCov.start do
-    add_filter '/test/'
-    add_filter '/features/'
-    minimum_coverage 10
-  end
-end