ruby-sh 2.1.4 → 2.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91cf2506446079b3fe817363924b3c6449013525842e65458a29f4c0b7c35cb3
-  data.tar.gz: 4c7bf3f948195bfe2d64e9e368a3471dfa4b7eb43396c58775851b8c3b827516
+  metadata.gz: ed7c44c0751c5a302ee4f576ff386d5e345599caf3d06e302d81c21d58bc8729
+  data.tar.gz: 16c410868acd95c98ddfd78db9883136aa3e1d4361358463b72c078a371830c0
 SHA512:
-  metadata.gz: b5e584c74dc57d72549c232120997eac68237afb27281e6172ba0377d337ce826b1056a4735737807a985865a89aa450abefc79044a8d3df0794e0e4f6476ce4
-  data.tar.gz: 44d52e9f7484e79fae0c1502fdfa67c3571b2e75fb9bb3b9c66200136586927c4378cb9f4c55ea6605498154cfc3d1be9c59caba8ad0f054acbd59de2d8e6466
+  metadata.gz: 16924112923bd153dbd9c69fee521f58e3b2fd394846ac110142cf04152a5f3d3533c2d88984c9c9d0723c64743c5e3f1003ecd0fe4620edea3d4be199030fa4
+  data.tar.gz: b9434103597b613d4a6c6aaf82da6f72ca850dccd453eea9b1e5ec561ffd2a202894dfbdcfcd2acfb17229eee780c7c47c377546e985e36dd372a233b76d8999

data/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf

data/.rubocop.yml

@@ -7,4 +7,5 @@ AllCops:
   SuggestExtensions: false
   Exclude:
     - 'bin/**/*'
+    - 'vendor/**/*'
 

data/.ruby-version

@@ -0,0 +1 @@
+3.1.1

data/Gemfile

@@ -5,6 +5,22 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in rubsh.gemspec
 gemspec
 
+# rake
 gem "rake", "~> 13.0"
-gem "rspec", "~> 3.0"
+
+# lint
+gem "rubocop", "~> 1.29"
 gem "standard", "~> 1.12"
+
+# test
+gem "rspec", "~> 3.0"
+
+# doc
+gem "yard", "~> 0.9"
+gem "redcarpet", "~> 3.5"
+
+# lsp
+gem "solargraph"
+
+# misc
+gem "overcommit", "~> 0.59"

data/Gemfile.lock

@@ -1,19 +1,44 @@
 PATH
   remote: .
   specs:
-    ruby-sh (2.1.4)
+    ruby-sh (2.2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    backport (1.2.0)
+    benchmark (0.2.1)
+    childprocess (4.1.0)
     diff-lcs (1.5.0)
+    e2mmap (0.1.0)
+    iniparse (1.5.0)
+    jaro_winkler (1.5.6)
+    json (2.6.2)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    mini_portile2 (2.8.4)
+    nokogiri (1.15.4)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
+    nokogiri (1.15.4-x86_64-linux)
+      racc (~> 1.4)
+    overcommit (0.59.1)
+      childprocess (>= 0.6.3, < 5)
+      iniparse (~> 1.4)
+      rexml (~> 3.2)
     parallel (1.22.1)
-    parser (3.1.2.0)
+    parser (3.1.2.1)
       ast (~> 2.4.1)
+    racc (1.7.1)
     rainbow (3.1.1)
     rake (13.0.6)
+    redcarpet (3.5.1)
     regexp_parser (2.5.0)
+    reverse_markdown (2.1.1)
+      nokogiri
     rexml (3.2.5)
     rspec (3.11.0)
       rspec-core (~> 3.11.0)
@@ -28,35 +53,61 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.11.0)
     rspec-support (3.11.0)
-    rubocop (1.29.1)
+    rubocop (1.35.0)
+      json (~> 2.3)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.1.2.1)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.17.0, < 2.0)
+      rubocop-ast (>= 1.20.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.18.0)
+    rubocop-ast (1.21.0)
       parser (>= 3.1.1.0)
-    rubocop-performance (1.13.3)
+    rubocop-performance (1.14.3)
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    standard (1.12.1)
-      rubocop (= 1.29.1)
-      rubocop-performance (= 1.13.3)
-    unicode-display_width (2.1.0)
+    solargraph (0.48.0)
+      backport (~> 1.2)
+      benchmark
+      bundler (>= 1.17.2)
+      diff-lcs (~> 1.4)
+      e2mmap
+      jaro_winkler (~> 1.5)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      parser (~> 3.0)
+      reverse_markdown (>= 1.0.5, < 3)
+      rubocop (>= 0.52)
+      thor (~> 1.0)
+      tilt (~> 2.0)
+      yard (~> 0.9, >= 0.9.24)
+    standard (1.16.0)
+      rubocop (= 1.35.0)
+      rubocop-performance (= 1.14.3)
+    thor (1.2.2)
+    tilt (2.3.0)
+    unicode-display_width (2.2.0)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   ruby
   x86_64-linux
 
 DEPENDENCIES
+  overcommit (~> 0.59)
   rake (~> 13.0)
+  redcarpet (~> 3.5)
   rspec (~> 3.0)
+  rubocop (~> 1.29)
   ruby-sh!
+  solargraph
   standard (~> 1.12)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.3.8

data/README.md

@@ -5,7 +5,7 @@ Rubsh (a.k.a. ruby-sh) - Inspired by [python-sh], allows you to call any program
 ```ruby
 require 'rubsh'
 
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 print(sh.cmd('ifconfig').call_with('wlan0').stdout_data)
 ```
 
@@ -34,34 +34,6 @@ When using this library you can:
 * etc.
 
 
-## Table of Contents
-
-* [Installation](#installation)
-* [Usage](#usage)
-  * [Basic Syntax](#basic-syntax)
-  * [Passing Arguments](#passing-arguments)
-  * [Exit Codes](#exit-codes)
-  * [Redirection](#redirection)
-  * [Incremental Iteration](#incremental-iteration)
-  * [Background Processes](#background-processes)
-  * [Baking](#baking)
-  * [Subcommands](#subcommands)
-  * [Piping](#piping)
-* [Reference](#reference)
-  * [Special Kwargs](#special-kwargs)
-* [FAQ](#faq)
-  * [Why doesn’t `*` work as a command argument?](#why-doesnt--work-as-a-command-argument)
-  * [How do I execute a bash builtin?](#how-do-i-execute-a-bash-builtin)
-  * [How do I call a program that isn’t in $PATH?](#how-do-i-call-a-program-that-isnt-in-path)
-  * [How do I run a command and connect it to stdout and stdin?](#how-do-i-run-a-command-and-connect-it-to-stdout-and-stdin)
-  * [How do I order keyword arguments?](#how-do-i-order-keyword-arguments)
-* [Development](#development)
-* [Contributing](#contributing)
-* [Acknowledgements](#acknowledgements)
-* [License](#license)
-* [Code Of Conduct](#code-of-conduct)
-
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -85,7 +57,7 @@ Or install it yourself as:
 
 ```ruby
 # Create a shell
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 
 # Create a command, use `command`/`cmd`
 cmd = sh.cmd("ls")
@@ -218,6 +190,11 @@ sh.cmd('ssh').call_with("myserver.com", "-p 1393", "whoami")
 myserver = sh.cmd('ssh').bake("myserver.com", p: 1393)
 myserver.call_with('whoami')
 myserver.call_with('pwd')
+
+# With a special kwarg
+sleep = sh.cmd('sleep').bake(_timeout: 2)
+sleep.call(1) # => ok
+sleep.call(3) # => a `CommandReturnFailureError` raised
 ```
 
 ### Subcommands
@@ -311,7 +288,7 @@ Glob expansion is a feature of a shell, like Bash, and is performed by the shell
 ### How do I execute a bash builtin?
 
 ```ruby
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 rawsh = sh.cmd('bash').bake('-c')
 print(rawsh.call_with('echo Hello').stdout_data) # => "Hello\n"
 ```
@@ -321,14 +298,14 @@ print(rawsh.call_with('echo Hello').stdout_data) # => "Hello\n"
 Use absolute binpath
 
 ```ruby
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 sh.cmd('/path/to/command').call()
 ```
 
-OR Use `Rubsh::Shell::Env#path`
+Or use `Rubsh::Shell::Env#path`
 
 ```ruby
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 sh.env.path << "/dir/to/command/"
 sh.cmd('command').call()
 ```
@@ -348,7 +325,7 @@ my-command --arg1=val1 arg2 --arg3=val3
 Use:
 
 ```ruby
-sh = Rubsh::Shell.new
+sh = Rubsh.new
 sh.cmd('my-command').call_with({ arg1: "val1" }, "args2", { arg3: "val3" })
 ```
 

data/Rakefile

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
 
 require "rubocop/rake_task"
-
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]

data/lib/rubsh/command.rb

@@ -46,8 +46,8 @@ module Rubsh
     end
 
     # @return [String]
-    def inspect
-      format("#<Rubsh::Command '%s'>", @progpath)
+    def to_s
+      @progpath
     end
 
     # @!visibility private

data/lib/rubsh/running_command.rb

@@ -1,5 +1,3 @@
-require "timeout"
-
 module Rubsh
   class RunningCommand
     SPECIAL_KWARGS = %i[
@@ -39,6 +37,14 @@ module Rubsh
     # @return [Number]
     attr_reader :exit_code
 
+    # @!attribute [r] started_at
+    # @return [Time]
+    attr_reader :started_at
+
+    # @!attribute [r] finished_at
+    # @return [Time]
+    attr_reader :finished_at
+
     # @!attribute [r] stdout_data
     # @return [String]
     attr_reader :stdout_data
@@ -57,6 +63,8 @@ module Rubsh
       @prog_with_args = nil
       @pid = nil
       @exit_code = nil
+      @started_at = nil
+      @finished_at = nil
       @stdout_data = "".force_encoding(::Encoding.default_external)
       @stderr_data = "".force_encoding(::Encoding.default_external)
       @in_rd = nil
@@ -109,42 +117,26 @@ module Rubsh
       extract_opts(opts)
     end
 
-    # @return [void]
-    def wait(timeout: nil)
-      timeout_occurred = false
-      _, status = nil, nil
-
-      if timeout
-        begin
-          ::Timeout.timeout(timeout) { _, status = ::Process.wait2(@pid) }
-        rescue ::Timeout::Error
-          timeout_occurred = true
+    # @return [Numeric, nil]
+    def wall_time
+      @finished_at.nil? ? nil : @finished_at - @started_at
+    end
+    alias_method :execution_time, :wall_time
 
-          ::Process.kill("TERM", @pid) # graceful stop
-          30.times do
-            _, status = ::Process.wait2(@pid, ::Process::WNOHANG | ::Process::WUNTRACED)
-            break if status
-            sleep 0.1
-          end
-          failure = @pid if status.nil?
-          failure && ::Process.kill("KILL", failure) # forceful stop
-        end
-      else
-        _, status = ::Process.wait2(@pid)
-      end
+    # @return [Boolean]
+    def ok?
+      @_ok_code.include?(@exit_code)
+    end
 
-      @exit_code = status&.exitstatus
-      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
-    rescue Errno::ECHILD, Errno::ESRCH
-      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
-    ensure
-      @out_rd_reader&.wait
-      @err_rd_reader&.wait
+    # @return [void]
+    def wait(timeout: nil)
+      wait2(timeout: timeout)
+      handle_return_code
     end
 
     # @return [String]
-    def inspect
-      format("#<Rubsh::RunningCommand '%s'>", @prog_with_args)
+    def to_s
+      @prog_with_args
     end
 
     # @!visibility private
@@ -296,6 +288,7 @@ module Rubsh
     def spawn
       args = __spawn_arguments
       @pid = ::Process.spawn(*args)
+      @started_at = Time.now
       @in_wr&.write(@_in_data) if @_in_data
       @in_wr&.close
 
@@ -317,8 +310,41 @@ module Rubsh
       @err_wr&.close
     end
 
+    def wait2(timeout: nil)
+      timeout_occurred = false
+      _, status = nil, nil
+
+      if timeout
+        begin
+          ::Timeout.timeout(timeout) { _, status = ::Process.wait2(@pid) }
+        rescue ::Timeout::Error
+          timeout_occurred = true
+
+          ::Process.kill("TERM", @pid) # graceful stop
+          30.times do
+            _, status = ::Process.wait2(@pid, ::Process::WNOHANG | ::Process::WUNTRACED)
+            break if status
+            sleep 0.1
+          end
+          failure = @pid if status.nil?
+          failure && ::Process.kill("KILL", failure) # forceful stop
+        end
+      else
+        _, status = ::Process.wait2(@pid)
+      end
+
+      @exit_code = status&.exitstatus
+      @finished_at = Time.now
+      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
+    rescue Errno::ECHILD, Errno::ESRCH
+      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
+    ensure
+      @out_rd_reader&.wait
+      @err_rd_reader&.wait
+    end
+
     def handle_return_code
-      return if @_ok_code.include?(@exit_code)
+      return if ok?
       message = format("\n\n  RAN: %s\n\n  STDOUT:\n%s\n  STDERR:\n%s\n", @prog_with_args, @stdout_data, @stderr_data)
       raise Exceptions::CommandReturnFailureError.new(@exit_code, message)
     end
@@ -331,7 +357,6 @@ module Rubsh
     def run_in_foreground
       spawn
       wait(timeout: @_timeout)
-      handle_return_code
     end
   end
 end

data/lib/rubsh/running_pipeline.rb

@@ -1,5 +1,3 @@
-require "open3"
-
 module Rubsh
   class RunningPipeline
     SPECIAL_KWARGS = %i[
@@ -24,6 +22,14 @@ module Rubsh
     # @return [Number]
     attr_reader :exit_code
 
+    # @!attribute [r] started_at
+    # @return [Time]
+    attr_reader :started_at
+
+    # @!attribute [r] finished_at
+    # @return [Time]
+    attr_reader :finished_at
+
     # @!attribute [r] stdout_data
     # @return [String]
     attr_reader :stdout_data
@@ -39,6 +45,8 @@ module Rubsh
       # Runtime
       @prog_with_args = nil
       @exit_code = nil
+      @started_at = nil
+      @finished_at = nil
       @stdout_data = "".force_encoding(::Encoding.default_external)
       @stderr_data = "".force_encoding(::Encoding.default_external)
       @in_rd = nil
@@ -73,48 +81,26 @@ module Rubsh
       @_no_err = false
     end
 
-    # @return [void]
-    def wait(timeout: nil)
-      timeout_occurred = false
-      last_status = nil
-
-      if timeout
-        begin
-          ::Timeout.timeout(timeout) { last_status = @waiters.map(&:value)[-1] }
-        rescue ::Timeout::Error
-          timeout_occurred = true
+    # @return [Numeric, nil]
+    def wall_time
+      @finished_at.nil? ? nil : @finished_at - @started_at
+    end
+    alias_method :execution_time, :wall_time
 
-          failures = []
-          @waiters.each { |w| ::Process.kill("TERM", w.pid) } # graceful stop
-          @waiters.each { |w|
-            _, status = nil, nil
-            30.times do
-              _, status = ::Process.wait2(w.pid, ::Process::WNOHANG | ::Process::WUNTRACED)
-              break if status
-              sleep 0.1
-            rescue ::Errno::ECHILD, ::Errno::ESRCH
-              status = true
-            end
-            failures << w.pid if status.nil?
-          }
-          failures.each { |pid| ::Process.kill("KILL", pid) } # forceful stop
-        end
-      else
-        last_status = @waiters.map(&:value)[-1]
-      end
+    # @return [Boolean]
+    def ok?
+      @_ok_code.include?(@exit_code)
+    end
 
-      @exit_code = last_status&.exitstatus
-      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
-    rescue ::Errno::ECHILD, ::Errno::ESRCH
-      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
-    ensure
-      @out_rd_reader&.wait
-      @err_rd_reader&.wait
+    # @return [void]
+    def wait(timeout: nil)
+      wait2(timeout: timeout)
+      handle_return_code
     end
 
     # @return [String]
-    def inspect
-      format("#<Rubsh::RunningPipeline '%s'>", @prog_with_args)
+    def to_s
+      @prog_with_args
     end
 
     # @!visibility private
@@ -203,6 +189,7 @@ module Rubsh
       cmds = @rcmds.map { |r| r.__spawn_arguments(env: @_env, cwd: @_cwd, redirection_args: {}) }
       @prog_with_args = @rcmds.map(&:__prog_with_args).join(" | ")
       @waiters = ::Open3.pipeline_start(*cmds, compile_redirection_args)
+      @started_at = Time.now
       @in_wr&.write(@_in_data) if @_in_data
       @in_wr&.close
 
@@ -224,8 +211,47 @@ module Rubsh
       @err_wr&.close
     end
 
+    def wait2(timeout: nil)
+      timeout_occurred = false
+      last_status = nil
+
+      if timeout
+        begin
+          ::Timeout.timeout(timeout) { last_status = @waiters.map(&:value)[-1] }
+        rescue ::Timeout::Error
+          timeout_occurred = true
+
+          failures = []
+          @waiters.each { |w| ::Process.kill("TERM", w.pid) } # graceful stop
+          @waiters.each { |w|
+            _, status = nil, nil
+            30.times do
+              _, status = ::Process.wait2(w.pid, ::Process::WNOHANG | ::Process::WUNTRACED)
+              break if status
+              sleep 0.1
+            rescue ::Errno::ECHILD, ::Errno::ESRCH
+              status = true
+            end
+            failures << w.pid if status.nil?
+          }
+          failures.each { |pid| ::Process.kill("KILL", pid) } # forceful stop
+        end
+      else
+        last_status = @waiters.map(&:value)[-1]
+      end
+
+      @exit_code = last_status&.exitstatus
+      @finished_at = Time.now
+      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
+    rescue ::Errno::ECHILD, ::Errno::ESRCH
+      raise Exceptions::CommandTimeoutError, "execution expired" if timeout_occurred
+    ensure
+      @out_rd_reader&.wait
+      @err_rd_reader&.wait
+    end
+
     def handle_return_code
-      return if @_ok_code.include?(@exit_code)
+      return if ok?
       message = format("\n\n  RAN: %s\n\n  STDOUT:\n%s\n  STDERR:\n%s\n", @prog_with_args, @stdout_data, @stderr_data)
       raise Exceptions::CommandReturnFailureError.new(@exit_code, message)
     end
@@ -237,7 +263,6 @@ module Rubsh
     def run_in_foreground
       spawn
       wait(timeout: @_timeout)
-      handle_return_code
     end
   end
 end

data/lib/rubsh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubsh
-  VERSION = "2.1.4"
+  VERSION = "2.2.6"
 end

data/lib/rubsh.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "open3"
+require "timeout"
+
 require_relative "rubsh/argument"
 require_relative "rubsh/command"
 require_relative "rubsh/exceptions"
@@ -10,3 +13,9 @@ require_relative "rubsh/shell/env"
 require_relative "rubsh/shell"
 require_relative "rubsh/stream_reader"
 require_relative "rubsh/version"
+
+module Rubsh
+  def self.new
+    Shell.new
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-sh
 version: !ruby/object:Gem::Version
-  version: 2.1.4
+  version: 2.2.6
 platform: ruby
 authors:
 - John Doe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-06-05 00:00:00.000000000 Z
+date: 2023-09-26 00:00:00.000000000 Z
 dependencies: []
 description: Rubsh (a.k.a. ruby-sh) - Inspired by python-sh, allows you to call any
   program as if it were a function.
@@ -18,10 +18,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".editorconfig"
 - ".overcommit.yml"
 - ".rspec"
-- ".rubocop"
 - ".rubocop.yml"
+- ".ruby-version"
 - ".yardopts"
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -41,7 +42,6 @@ files:
 - lib/rubsh/stream_reader.rb
 - lib/rubsh/version.rb
 - rubsh.gemspec
-- sig/rubsh.rbs
 homepage: https://github.com/souk4711/rubsh
 licenses:
 - MIT

data/sig/rubsh.rbs

@@ -1,4 +0,0 @@
-module Rubsh
-  VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end