test-cmd.rb 0.12.4 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9543aef60b39eebdd49dcd4a1a33b9f08841cdc7ad0176402266d0236bdb483c
-  data.tar.gz: 44f38f751770d9cee2d734a768b07d10a67227d3841aec53648a9ecff89ca26a
+  metadata.gz: ceedd530e04b4429280815527f9c18213db595390d6c554854a843c9c9a7717e
+  data.tar.gz: 98ad59766cd5aa84d4fbed39ca8d2465fd6be4fa3d7895707f6341fbad37e6c4
 SHA512:
-  metadata.gz: be9bba3851638c04d87a114f92fc2ee28b8683e3df14b13b9a37f7a9749ea0075589def7acf65c8b554e62f6e8575b9ccde4aa9f61b024f65a6455f360686559
-  data.tar.gz: 04db2f4f1b84bb1ce41acfa570778bcec93d64593d58825356c1b9e48ff08b181f8c13c516bbfe70fa8065ecf18b83488df1a8ac1354632e3513765be24a47c6
+  metadata.gz: f25e60111e111074f5dd1cdba6ba10f7074a5a2fbe9ddbf57ef08a3d1ecc1096e4119331c98ab74736b689aedf8c5f4b784cd18db7255bb7df01de314a1b1dd5
+  data.tar.gz: 368188e8228ea2974e2db19d284efabb70ce3a0a2c773d73e372078a82034fa93e69ff9e586c62fc570b49039f4bc759d1b0da1cf8e240ac7f3b631893d5dff3

data/.rubocop.yml

@@ -8,16 +8,20 @@ require:
 inherit_gem:
   standard: config/base.yml
 
+##
+# Enabled
 AllCops:
   TargetRubyVersion: 3.1
   Include:
     - 'lib/**/*.rb'
     - 'test/**/*.rb'
 
-Style/MultilineIfModifier:
-  Exclude:
-    - 'lib/test-cmd.rb'
-
+##
+# Disabled
 Layout/MultilineMethodCallIndentation:
   Exclude:
     - 'test/*.rb'
+Layout/ArgumentAlignment:
+  Enabled: false
+Style/MultilineIfModifier:
+  Enabled: false

data/README.md

@@ -1,16 +1,21 @@
 ## About
 
 test-cmd.rb provides an object-oriented interface for spawning
-a command.
+a command on UNIX-like operating systems. The library is intended
+to be simple, lightweight, and easy to use.
 
 ## Examples
 
-### Callbacks
+### Commands
+
+#### Callbacks
 
 The success and failure callbacks provide hooks for when
 a command exits successfully or unsuccessfully. The callbacks
 are passed an instance of
-[Test::Cmd](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html):
+[Test::Cmd](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html)
+that has access to the command's process ID, exit status,
+standard ouput stream, and standard error stream:
 
 ``` ruby
 require "test-cmd"
@@ -19,12 +24,14 @@ cmd("ruby", "-e", "exit 0")
   .failure { print "The command [#{_1.pid}] was unsuccessful", "\n" }
 ```
 
-### Test::Unit
+#### Assertions
 
 The following example demonstrates how tests might be written with
 test-unit from the standard library. The
 [`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Kernel.html#cmd-instance_method)
-method takes the name or path of a command, alongside any arguments:
+method takes the name or path of a command, alongside any arguments. The tests
+assert against the exit status, standard output stream, and standard error
+stream of the spawned ruby process:
 
 ```ruby
 require "test/unit"
@@ -68,8 +75,8 @@ test-cmd.rb can be installed via rubygems.org:
 
 ## Sources
 
-* [GitHub](https://github.com/0x1eef/test-cmd.rb#readme)
-* [GitLab](https://gitlab.com/0x1eef/test-cmd.rb#about)
+* [github.com/@0x1eef](https://github.com/0x1eef/test-cmd.rb#readme)
+* [gitlab.com/@0x1eef](https://gitlab.com/0x1eef/test-cmd.rb#about)
 
 ## License
 

data/lib/test/cmd.rb

@@ -1,11 +1,9 @@
-unless defined?(Test)
-  module Test
-  end
-end
+module Test
+end unless defined?(Test)
 
 ##
 # test-cmd.rb provides an object oriented interface
-# for spawning a command.
+# for spawning a command
 class Test::Cmd
   ##
   # @api private
@@ -48,51 +46,19 @@ class Test::Cmd
   # @return [Test::Cmd]
   def spawn
     return self if @spawned
-
     tap do
-      out, err = Pipe.pair, Pipe.pair
       @spawned = true
-      t = Thread.new do
-        Process.spawn(@cmd, *@argv, {out: out.w, err: err.w})
-        Process.wait
-        @status = $?
-      rescue Errno::ENOENT => ex
-        @cmd, @argv, @stderr = "false", [], ex.message
-        @enoent = true
-        retry
-      end
-      loop do
-        io, _ = IO.select([out.r, err.r], nil, nil, 0.01)
-        io&.include?(out.r) ? @stdout << out.r.read(1) : nil
-        io&.include?(err.r) ? @stderr << err.r.read(1) : nil
-        break unless t.alive? || IO.select([out.r, err.r], nil, nil, 0.01)
-      end
-    ensure
-      [out, err].each(&:close)
+      @out, @err = Pipe.pair, Pipe.pair
+      produce(@out, @err)
     end
   end
 
-  ##
-  # @return [String]
-  #  Returns the contents of stdout
-  def stdout
-    spawn
-    @stdout
-  end
-
-  ##
-  # @return [String]
-  #  Returns the contents of stderr
-  def stderr
-    spawn
-    @stderr
-  end
-
   ##
   # @return [Process::Status]
   #  Returns the status of a process
   def status
     spawn
+    consume(@producer, @out, @err)
     @status
   end
 
@@ -111,6 +77,31 @@ class Test::Cmd
   end
   alias_method :exitstatus, :exit_status
 
+  ##
+  # @group IO
+
+  ##
+  # @return [String]
+  #  Returns the contents of stdout
+  def stdout
+    spawn
+    consume(@producer, @out, @err)
+    @stdout
+  end
+
+  ##
+  # @return [String]
+  #  Returns the contents of stderr
+  def stderr
+    spawn
+    consume(@producer, @out, @err)
+    @stderr
+  end
+  # @endgroup
+
+  ##
+  # @group Predicates
+
   ##
   # @return [Boolean]
   #  Returns true when a command exited successfully
@@ -119,52 +110,117 @@ class Test::Cmd
   end
 
   ##
-  # Yields an instance of {Test::Cmd Test::Cmd}.
-  #
+  # @return [Boolean]
+  #  Returns true when a command has been spawned
+  def spawned?
+    @spawned
+  end
+
+  ##
+  # @return [Boolean]
+  #  Returns true when a command is running
+  def alive?
+    @producer&.alive?
+  end
+  alias_method :running?, :alive?
+
+  ##
+  # Sends SIGKILL to a running command
+  # @return [void]
+  def kill!
+    return unless alive?
+    Process.kill("SIGKILL", @pid)
+  end
+
+  ##
+  # @return [Boolean]
+  #  Returns true when a command can't be found
+  def command_not_found?
+    spawn
+    consume(@producer, @out, @err)
+    @enoent
+  end
+  alias_method :not_found?, :command_not_found?
+  # @endgroup
+
+  ##
+  # @group Callbacks
+
+  ##
+  # @yieldparam [Test::Cmd] cmd
+  #  Yields an instance of {Test::Cmd Test::Cmd}
   # @example
   #   cmd("ruby", "-e", "exit 0")
   #     .success { print "Command [#{_1.pid}] exited successfully", "\n" }
   #     .failure { }
-  #
   # @return [Test::Cmd]
   def success
     tap do
       spawn
+      consume(@producer, @out, @err)
       status.success? ? yield(self) : nil
     end
   end
 
   ##
-  # Yields an instance of {Test::Cmd Test::Cmd}.
-  #
+  # @yieldparam [Test::Cmd] cmd
+  #  Yields an instance of {Test::Cmd Test::Cmd}
   # @example
   #   cmd("ruby", "-e", "exit 1")
   #     .success { }
   #     .failure { print "Command [#{_1.pid}] exited unsuccessfully", "\n" }
-  #
   # @return [Test::Cmd]
   def failure
     tap do
       spawn
+      consume(@producer, @out, @err)
       status.success? ? nil : yield(self)
     end
   end
+  # @endgroup
+
+  private
 
   ##
-  # @return [Boolean]
-  #  Returns true when a command has been spawned
-  def spawned?
-    @spawned
+  # @param [Test::Cmd::Pipe] out
+  #  A pipe for stdout
+  # @param [Test::Cmd::Pipe] err
+  #  A pipe for stderr
+  # @return [Thread]
+  #  Returns a thread for a spawned command
+  def produce(out, err)
+    @producer = Thread.new do
+      @pid = Process.spawn(@cmd, *@argv, {out: out.w, err: err.w})
+      Process.wait
+      @status = $?
+    rescue Errno::ENOENT => ex
+      @cmd, @argv, @stderr = "false", [], ex.message
+      @enoent = true
+      retry
+    end
   end
 
   ##
-  # @return [Boolean]
-  #  Returns true when a command can't be found
-  def command_not_found?
-    spawn
-    @enoent
+  # @param [Thread] thread
+  #  A thread for a spawned command
+  # @param [Test::Cmd::Pipe] out
+  #  A pipe for stdout
+  # @param [Test::Cmd::Pipe] err
+  #  A pipe for stderr
+  # @return [void]
+  def consume(thread, out, err)
+    return if @consumed
+    sleep 0.01 while thread.alive?
+    loop do
+      io, _ = IO.select([out.r, err.r], nil, nil, 0.01)
+      io&.include?(out.r) ? @stdout << out.r.read(1) : nil
+      io&.include?(err.r) ? @stderr << err.r.read(1) : nil
+      break unless thread.alive? || IO.select([out.r, err.r], nil, nil, 0.01)
+    end
+  ensure
+    [out, err].each(&:close)
+    @consumed = true
   end
-  alias_method :not_found?, :command_not_found?
 end
 
 module Kernel

data/test-cmd.rb.gemspec

@@ -4,14 +4,13 @@ Gem::Specification.new do |gem|
   gem.name = "test-cmd.rb"
   gem.authors = ["0x1eef"]
   gem.email = ["0x1eef@protonmail.com"]
-  gem.homepage = "https://github.com/0x1eef/test-cmd.rb#readme"
-  gem.version = "0.12.4"
+  gem.homepage = "https://github.com/1robertrb/test-cmd.rb#readme"
+  gem.version = "1.0.0"
   gem.required_ruby_version = ">= 3.0"
   gem.licenses = ["0BSD"]
   gem.files = `git ls-files`.split($/)
   gem.require_paths = ["lib"]
-  gem.summary = "An object-oriented interface for spawning a command"
-  gem.metadata = { "documentation_uri" => "https://0x1eef.github.io/x/test-cmd.rb/" }
+  gem.summary = "test-cmd.rb provides an object-oriented interface for spawning a command"
   gem.description = gem.summary
   gem.add_development_dependency "test-unit", "~> 3.5.7"
   gem.add_development_dependency "yard", "~> 0.9"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: test-cmd.rb
 version: !ruby/object:Gem::Version
-  version: 0.12.4
+  version: 1.0.0
 platform: ruby
 authors:
 - '0x1eef'
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -80,7 +79,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.1'
-description: An object-oriented interface for spawning a command
+description: test-cmd.rb provides an object-oriented interface for spawning a command
 email:
 - 0x1eef@protonmail.com
 executables: []
@@ -89,7 +88,6 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/specs.yml"
 - ".gitignore"
-- ".gitlab-ci.yml"
 - ".projectile"
 - ".rubocop.yml"
 - Gemfile
@@ -101,12 +99,10 @@ files:
 - test-cmd.rb.gemspec
 - test/cmd_test.rb
 - test/setup.rb
-homepage: https://github.com/0x1eef/test-cmd.rb#readme
+homepage: https://github.com/1robertrb/test-cmd.rb#readme
 licenses:
 - 0BSD
-metadata:
-  documentation_uri: https://0x1eef.github.io/x/test-cmd.rb/
-post_install_message:
+metadata: {}
 rdoc_options: []
 require_paths:
 - lib
@@ -121,8 +117,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
-summary: An object-oriented interface for spawning a command
+summary: test-cmd.rb provides an object-oriented interface for spawning a command
 test_files: []

data/.gitlab-ci.yml

@@ -1,16 +0,0 @@
-stages:
-  - test
-
-test-ruby31:
-  stage: test
-  image: ruby:3.1.2
-  script:
-    - bundle install
-    - bundle exec ruby test/*_test.rb
-
-test-ruby32:
-  stage: test
-  image: ruby:3.2.0
-  script:
-    - bundle install
-    - bundle exec ruby test/*_test.rb