qbash 0.0.1 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fccb41b161a6c90a23d521fa77e25afa0524e90fe208e3438c9b4d5af83d6c78
-  data.tar.gz: 85260c4600d72f50d1c3fe38030ea9a939c62e335c5ca2851b25d9d5a2c68696
+  metadata.gz: d3ac44ac6da719be360ee7785811de7c2b465efbe274c8ae9f7b0992647c05c0
+  data.tar.gz: cf4e840be85b2b9fc19df98fc2e7f45f45b6c93a525b209a4f715be104870ef5
 SHA512:
-  metadata.gz: c709f5c9ca3b1683d11e9bbc019e84fbf4a9c782e043fe36f88b0467f3a63123713eea48a0d8bd2f24c3ebb9fbbb2edaf4c796b0dc73615ccea8e4f5bb248953
-  data.tar.gz: 2343e378d673146501843e35998b7e3efbd0ca8f32e3ee1e67b46dc96319d0f1e0fa23caf118da2e883135360b00a168ce7b4e5809bcd8e6c02726273ee87585
+  metadata.gz: 5eaf974307cfb04ead1c2a890c6c34cb68c1ba9a1f4a3e1f2b858f5eda0579361296fb5e95f8fd3349455f07b5acf4ea8a9fac400f6cde5ace0d1f7381b64cb9
+  data.tar.gz: 554613f18dd98fcac12d7e0d4ce56f1cc8d0aaeaea5866fad42ef41f5bb96dfaddb37d00b75fdefde6665eb0b59f1f1add15668d618379e1e14829457b87844f

data/Gemfile

@@ -31,7 +31,7 @@ gem 'rake', '13.2.1', require: false
 gem 'random-port', '~>0.0', require: false
 gem 'rspec-rails', '7.0.1', require: false
 gem 'rubocop', '1.66.1', require: false
-gem 'rubocop-performance', '1.21.1', require: false
+gem 'rubocop-performance', '1.22.1', require: false
 gem 'rubocop-rspec', '3.0.5', require: false
 gem 'simplecov', '0.22.0', require: false
 gem 'simplecov-cobertura', '2.1.0', require: false

data/Gemfile.lock

@@ -196,7 +196,7 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.32.3)
       parser (>= 3.3.1.0)
-    rubocop-performance (1.21.1)
+    rubocop-performance (1.22.1)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rspec (3.0.5)
@@ -252,7 +252,7 @@ DEPENDENCIES
   random-port (~> 0.0)
   rspec-rails (= 7.0.1)
   rubocop (= 1.66.1)
-  rubocop-performance (= 1.21.1)
+  rubocop-performance (= 1.22.1)
   rubocop-rspec (= 3.0.5)
   simplecov (= 0.22.0)
   simplecov-cobertura (= 2.1.0)

data/README.md

@@ -1,15 +1,21 @@
 # Quick and Simple Executor of Bash Commands
 
-[![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/bash)](http://www.rultor.com/p/yegor256/bash)
+[![DevOps By Rultor.com](http://www.rultor.com/b/yegor256/qbash)](http://www.rultor.com/p/yegor256/qbash)
 [![We recommend RubyMine](https://www.elegantobjects.org/rubymine.svg)](https://www.jetbrains.com/ruby/)
 
-[![rake](https://github.com/yegor256/bash/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/bash/actions/workflows/rake.yml)
-[![PDD status](http://www.0pdd.com/svg?name=yegor256/bash)](http://www.0pdd.com/p?name=yegor256/bash)
-[![Gem Version](https://badge.fury.io/rb/bash.svg)](http://badge.fury.io/rb/bash)
-[![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/bash.svg)](https://codecov.io/github/yegor256/bash?branch=master)
-[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/yegor256/bash/master/frames)
-[![Hits-of-Code](https://hitsofcode.com/github/yegor256/bash)](https://hitsofcode.com/view/github/yegor256/bash)
-[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/bash/blob/master/LICENSE.txt)
+[![rake](https://github.com/yegor256/qbash/actions/workflows/rake.yml/badge.svg)](https://github.com/yegor256/qbash/actions/workflows/rake.yml)
+[![PDD status](http://www.0pdd.com/svg?name=yegor256/qbash)](http://www.0pdd.com/p?name=yegor256/qbash)
+[![Gem Version](https://badge.fury.io/rb/qbash.svg)](http://badge.fury.io/rb/qbash)
+[![Test Coverage](https://img.shields.io/codecov/c/github/yegor256/qbash.svg)](https://codecov.io/github/yegor256/qbash?branch=master)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/yegor256/qbash/master/frames)
+[![Hits-of-Code](https://hitsofcode.com/github/yegor256/qbash)](https://hitsofcode.com/view/github/yegor256/qbash)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/qbash/blob/master/LICENSE.txt)
+
+How do you execute a new shell command from Ruby?
+There are [many ways](https://stackoverflow.com/questions/2232).
+None of them offers a one-liner that would execute a command, print
+its output to the console or a logger, and then raise an exception if
+the exit code is not zero. This small gem offers exactly this one-liner.
 
 First, install it:
 
@@ -17,7 +23,7 @@ First, install it:
 gem install qbash
 ```
 
-Simply execute a bash command from Ruby:
+Then, you can use [qbash][qbash] global function:
 
 ```ruby
 require 'qbash'
@@ -33,7 +39,48 @@ stdout = qbash('cat > $FILE', env: { 'FILE' => 'a.txt' }, stdin: 'Hello!')
 ```
 
 It's possible to configure the logging facility too, with the help
-of the [loog](https://github.com/yegor256/loog) gem.
+of the [loog](https://github.com/yegor256/loog) gem (the output
+will be returned _and_ printed to the logger):
+
+```ruby
+require 'loog'
+qbash('echo "Hello, world!"', loog: Loog::VERBOSE)
+```
+
+You can also make it return both stdout and exit code, with the help
+of the `both` option set to `true`:
+
+```ruby
+stdout, code = qbash('cat a.txt', both: true, accept: [])
+```
+
+Here, the `accept` param contains the list of exit codes that are "acceptable"
+and won't lead to runtime failures. When the list is empty, all exists are
+acceptable (there will be no failures ever).
+
+The command may be provided as an array, which automatically will be
+converted to a string by joining all items with spaces between them.
+
+```ruby
+qbash(
+  [
+    'echo "Hello, world!"'
+    '&& echo "How are you?"',
+    '&& cat /etc/passwd'
+  ]
+)
+```
+
+It is very much recommended to escape all command-line values with the help
+of the [Shellwords.escape()][shellwords] utility method, for example:
+
+```ruby
+file = '/tmp/test.txt'
+qbash("cat #{Shellwords.escape(file)}")
+```
+
+Without such an escaping, in this example, a space inside the `file`
+will lead to an unpredicatable result of the execution.
 
 ## How to contribute
 
@@ -50,3 +97,6 @@ bundle exec rake
 ```
 
 If it's clean and you don't see any error messages, submit your pull request.
+
+[shellwords]: https://ruby-doc.org/stdlib-3.0.1/libdoc/shellwords/rdoc/Shellwords.html
+[qbash]: https://rubydoc.info/github/yegor256/qbash/master/Kernel#qbash-instance_method

data/lib/qbash.rb

@@ -20,9 +20,10 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
-require 'open3'
-require 'loog'
 require 'backtrace'
+require 'loog'
+require 'open3'
+require 'shellwords'
 
 # Execute one bash command.
 #
@@ -36,15 +37,19 @@ module Kernel
   #
   # To escape arguments, use +Shellwords.escape()+ method.
   #
-  # @param [String] cmd The command to run
-  # @param [String] stdin Input string
-  # @param [Hash] env Environment variables
-  # @param [Loog] loog Logging facility with +.debug()+ method
-  # @param [Array] accept List of accepted exit codes (accept all if empty)
+  # @param [String] cmd The command to run, for example +echo "Hello, world!"+
+  # @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+)
+  # @param [Array] accept List of accepted exit codes (accepts all if the list is empty)
   # @param [Boolean] both If set to TRUE, the function returns an array +(stdout, code)+
-  # @return [String] Stdout
-  def qbash(cmd, stdin: '', env: {}, loog: Loog::NULL, accept: [0], both: false)
-    loog.debug("+ #{cmd}")
+  # @return [String] Everything that was printed to the +stdout+ by the command
+  def qbash(cmd, stdin: '', env: {}, log: Loog::NULL, accept: [0], both: false)
+    if log.respond_to?(:debug)
+      log.debug("+ #{cmd}")
+    else
+      log.print("+ #{cmd}\n")
+    end
     buf = ''
     e = 1
     cmd = cmd.join(' ') if cmd.is_a?(Array)
@@ -57,7 +62,11 @@ module Kernel
         rescue IOError => e
           ln = Backtrace.new(e).to_s
         end
-        loog.debug(ln)
+        if log.respond_to?(:debug)
+          log.debug(ln)
+        else
+          log.print("#{ln}\n")
+        end
         buf += ln
       end
       e = thr.value.to_i

data/qbash.gemspec

@@ -26,7 +26,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.0.1'
+  s.version = '0.0.3'
   s.license = 'MIT'
   s.summary = 'Quick Executor of a BASH Command'
   s.description =

data/test/test_qbash.rb

@@ -44,6 +44,10 @@ class TestQbash < Minitest::Test
     assert_equal('123', qbash(['printf 1;', 'printf 2;', 'printf 3']))
   end
 
+  def test_log_to_console
+    qbash('echo Hello world!', log: $stdout)
+  end
+
   def test_with_stdin
     Dir.mktmpdir do |home|
       f = File.join(home, 'a b c.txt')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qbash
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.3
 platform: ruby
 authors:
 - Yegor Bugayenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-16 00:00:00.000000000 Z
+date: 2024-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: backtrace