test-cmd.rb 0.5.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2396593840d674fad470e2e4fcb0f0fc74e55987fe5caec27128457b0608453
-  data.tar.gz: 3b6c43870258be5d3c0a1039e5e8436bff314ea05c03dab2866593dafbf43591
+  metadata.gz: 4a40537381e81f677332c21cfbc95b997fe0f89a4cbf4c714e2eb857da496554
+  data.tar.gz: 88ceffc1c05ed2b90f79c39c73c6a95adc5ccd9bce97ff435dea3dbea07feb89
 SHA512:
-  metadata.gz: edb9931271bfc62a1c22be0717659fa83a670652b97ef7ebe74fe98e2605b21fc4c87647c75aa20c4913a8a76e6bd1d3de7a3d28fe74f75d800293844c2b442e
-  data.tar.gz: 3f95d41e84bb4ddf323798dee95e33872e72ff32869f3c1d82f629c00e1b15e840fd93b504f5fd15c7cfa4aa4dd280da172f7edeffd017ec3b486ce7dd2d8ea3
+  metadata.gz: 362b5b2155218c63f01321c279ebb5a7cd204fbdb01af2e76ce3d767d30c4b3a13c2a2eec52de77f7bb80419d37f7fdadb44ce1c3fb97e42d708d916a0eedfa1
+  data.tar.gz: 055f87c0d765be7ec2612ba9ae3e0f49cdaf2458eac747c8399b8b57dda732dca20d4848d9cc6809393fb3dfbd295cf2d55aec50eee9fbec7f8a63d37ef8a466

data/README.md

@@ -1,11 +1,7 @@
 ## About
 
-test-cmd.rb is a library for accessing the output streams
-(both stdout and stderr) of a spawned process. The library was
-first realized in a test environment, where it provided a path
-for verifying that when code examples are run they produce the
-expected output. The library can be generally useful outside a
-test environment, too.
+test-cmd.rb provides an object-oriented interface for spawning 
+a process.
 
 ## Examples
 
@@ -14,7 +10,7 @@ test environment, too.
 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/Test/CmdMixin.html#cmd-instance_method)
-method is given the name of a command, along with any arguments:
+method takes the name or path of a command, alongside any arguments:
 
 ```ruby
 require "test/unit"
@@ -22,19 +18,19 @@ require "test/cmd"
 
 class CmdTest < Test::Unit::TestCase
   def test_ruby_stdout
-    assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
+    assert_equal "42\n", cmd("ruby", "-e", "puts 42").stdout
   end
 
   def test_ruby_stderr
-    assert_equal "bar\n", cmd(%q(ruby -e '$stderr.puts "bar"')).stderr
+    assert_equal "42\n", cmd("ruby", "-e", "warn 42").stderr
   end
 
   def test_ruby_success_exit_status
-    assert_equal 0, cmd(%q(ruby -e 'exit 0')).exit_status
+    assert_equal 0, cmd("ruby", "-e", "exit 0").exit_status
   end
 
   def test_ruby_failure_exit_status
-    assert_equal 1, cmd(%q(ruby -e 'exit 1')).exit_status
+    assert_equal 1, cmd("ruby", "-e", "exit 1").exit_status
   end
 end
 ```
@@ -50,10 +46,9 @@ covers it in more-depth:
 
 ``` ruby
 require "test/cmd"
-str = cmd("du")
-      .arg("-s").arg("-h")
-      .spawn.stdout
-puts str      
+puts cmd("du")
+       .args("-s", "-h")
+       .stdout
 ```
 
 ### IO#sync
@@ -75,7 +70,7 @@ Process.wait(pid)
 
 ##
 # cmd.rb
-p cmd("ruby test.rb").stdout # => "bar\nfoo\n"
+p cmd("ruby", "test.rb").stdout # => "bar\nfoo\n"
 ```
 
 And with output flushed to the operating system immediately:
@@ -93,36 +88,29 @@ Process.wait(pid)
 
 ##
 # cmd.rb
-p cmd("ruby test.rb").stdout # => "foo\nbar\n"
+p cmd("ruby", "test.rb").stdout # => "foo\nbar\n"
 ```
 
-## Sources
+## Documentation
 
-* [Source code (GitHub)](https://github.com/0x1eef/test-cmd.rb#readme)
-* [Source code (GitLab)](https://gitlab.com/0x1eef/test-cmd.rb#about)
+A complete API reference is available at 
+[0x1eef.github.io/x/test-cmd.rb](https://0x1eef.github.io/x/test-cmd.rb).
 
 ## Install
 
-test-cmd.rb is distributed as a RubyGem through its git repositories. <br>
-[GitHub](https://github.com/0x1eef/test-cmd.rb),
-and
-[GitLab](https://gitlab.com/0x1eef/test-cmd.rb)
-are available as sources.
-
-``` ruby
-# Gemfile
-gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.5.2"
-```
-
 **Rubygems.org**
 
-test-cmd.rb can also be installed via rubygems.org.
+test-cmd.rb can be installed via rubygems.org.
 
     gem install test-cmd.rb
 
+## Sources
+
+* [GitHub](https://github.com/0x1eef/test-cmd.rb#readme)
+* [GitLab](https://gitlab.com/0x1eef/test-cmd.rb#about)
+
 ## License
 
 [BSD Zero Clause](https://choosealicense.com/licenses/0bsd/).
 <br>
 See [LICENSE](./LICENSE).
-

data/lib/test-cmd.rb

@@ -3,23 +3,19 @@ end unless defined?(Test)
 
 ##
 # test-cmd.rb is a library for accessing the output streams
-# (both stdout and stderr) of a spawned process. The library was
-# first realized in a test environment, where it provided a path
-# for verifying that when code examples are run they produce the
-# expected output. The library can be generally useful outside a
-# test environment, too.
+# (both stdout and stderr) of a spawned process.
 class Test::Cmd
   require "tempfile"
 
   ##
   # @param [String] cmd
   #  A command to spawn.
-  # @param [Array<String>] args
-  #  An array of command-line arguments.
+  # @param [Array<String>] argv
+  #  A variable number of command-line arguments.
   # @return [Test::Cmd]
-  def initialize(cmd, args = [])
+  def initialize(cmd, *argv)
     @cmd = cmd
-    @args = args.dup
+    @argv = argv.dup
     @out = unlink!(Tempfile.new("cmd-stdout"))
     @err = unlink!(Tempfile.new("cmd-stderr"))
     @status = nil
@@ -32,17 +28,17 @@ class Test::Cmd
   # @return [Test::Cmd]
   def arg(arg)
     tap do
-      @args.push(arg)
+      @argv.push(arg)
     end
   end
 
   ##
-  # @param [Array<String, #to_s>] args
+  # @param [Array<String, #to_s>] argv
   #  One or more command-line arguments.
   # @return [Test::Cmd]
-  def args(*args)
+  def args(*argv)
     tap do
-      @args.concat(args)
+      @argv.concat(argv)
     end
   end
 
@@ -52,7 +48,7 @@ class Test::Cmd
   def spawn
     tap do
       @spawned = true
-      Process.wait Process.spawn(@cmd, *@args, {out: @out, err: @err})
+      Process.wait Process.spawn(@cmd, *@argv, {out: @out, err: @err})
       @status = $?
     end
   ensure
@@ -79,7 +75,8 @@ class Test::Cmd
     @err.close unless @err.closed?
   end
 
-  ## @return [Process::Status]
+  ##
+  # @return [Process::Status]
   #  Returns the status of a process
   def status
     spawn unless @spawned
@@ -94,16 +91,14 @@ class Test::Cmd
   end
 
   ##
-  # Yields each line of stdout when the command
-  # was successful, or each line of stderr when
-  # the command was not successful.
+  # @param [Symbol] io
+  #  The output stream as a Symbol (:stdout, :stderr).
   # @return [Enumerator]
   #  Returns an Enumerator when a block is not given.
-  def each_line
-    return enum_for(:each_line) unless block_given?
+  def each_line(io = :stdout)
+    return enum_for(:each_line, io) unless block_given?
     spawn unless @spawned
-    io = @status.success? ? @stdout : @stderr
-    io.each_line.each { yield(_1.chomp) }
+    public_send(io).each_line { yield(_1) }
   end
 
   private
@@ -112,25 +107,21 @@ class Test::Cmd
   # @api private
   def unlink!(file)
     file.tap do
-      File.chmod(0000, file.path)
+      File.chmod(0, file.path)
       file.unlink
     end
   end
 end
 
-module Test::CmdMixin
+module Test::Cmd::Mixin
   ##
-  # @param [String] cmd
-  #  A command to execute
-  # @param [Array<String>] args
-  #  An array of command-line arguments.
-  # @return [Test::Cmd]
-  #  Returns an instance of {Test::Cmd Test::Cmd}
-  def cmd(cmd, args = [])
-    Test::Cmd.new(cmd, args)
+  # @param (see Test::Cmd#initialize)
+  # @return (see Test::Cmd#initialize)
+  def cmd(cmd, *argv)
+    Test::Cmd.new(cmd, *argv)
   end
 end
 
 module Kernel
-  include Test::CmdMixin
+  include Test::Cmd::Mixin
 end

data/test/test_cmd_test.rb

@@ -2,19 +2,19 @@ require_relative "setup"
 
 class CmdTest < Test::Unit::TestCase
   def test_ruby_stdout
-    assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
+    assert_equal "42\n", cmd("ruby", "-e", "puts 42").stdout
   end
 
   def test_ruby_stderr
-    assert_equal "bar\n", cmd(%q(ruby -e '$stderr.puts "bar"')).stderr
+    assert_equal "42\n", cmd("ruby", "-e", "warn 42").stderr
   end
 
   def test_ruby_success_exit_status
-    assert_equal 0, cmd(%q(ruby -e 'exit 0')).exit_status
+    assert_equal 0, cmd("ruby", "-e", "exit 0").exit_status
   end
 
   def test_ruby_failure_exit_status
-    assert_equal 1, cmd(%q(ruby -e 'exit 1')).exit_status
+    assert_equal 1, cmd("ruby", "-e", "exit 1").exit_status
   end
 
   def test_stdout_with_fork
@@ -27,21 +27,31 @@ class CmdTest < Test::Unit::TestCase
       puts "foo"
       Process.wait(pid)
     CODE
-    assert_equal "foo\nbar\n", cmd(%Q(ruby -e '#{code}')).stdout
+    assert_equal "foo\nbar\n", cmd("ruby", "-e", code).stdout
   end
 
   def test_each_line_stdout
     run = false
-    cmd(%q(ruby -e '$stdout.puts "FooBar"'))
+    cmd("ruby", "-e", "puts 'FooBar'")
     .each_line do
       run = true
-      assert_equal _1, "FooBar"
+      assert_equal "FooBar\n", _1
     end
-    assert_equal true, run
+    assert run
+  end
+
+  def test_each_line_stderr
+    run = false
+    cmd("ruby", "-e", "warn 'BarFoo'")
+    .each_line(:stderr) do
+      run = true
+      assert_equal "BarFoo\n", _1
+    end
+    assert run
   end
 
   def test_each_line_returns_enum
     assert_instance_of Enumerator,
-                       cmd(%q(ruby -e '$stdout.puts "FooBar"')).each_line
+                       cmd("ruby", "-e", "puts 'FooBar'").each_line
   end
 end

data/test-cmd.rb.gemspec

@@ -5,13 +5,12 @@ Gem::Specification.new do |gem|
   gem.authors = ["0x1eef"]
   gem.email = ["0x1eef@protonmail.com"]
   gem.homepage = "https://github.com/0x1eef/test-cmd.rb#readme"
-  gem.version = "0.5.2"
+  gem.version = "0.7.0"
   gem.required_ruby_version = ">= 3.0"
   gem.licenses = ["0BSD"]
   gem.files = `git ls-files`.split($/)
   gem.require_paths = ["lib"]
-  gem.summary = "test-cmd.rb provides access to the output streams " \
-                "(both stdout and stderr) of a spawned process."
+  gem.summary = "An object-oriented interface for spawning a process."
   gem.metadata = { "documentation_uri" => "https://0x1eef.github.io/x/test-cmd.rb/" }
   gem.description = gem.summary
   gem.add_development_dependency "test-unit", "~> 3.5.7"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test-cmd.rb
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.7.0
 platform: ruby
 authors:
 - '0x1eef'
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-01 00:00:00.000000000 Z
+date: 2024-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -80,8 +80,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.1'
-description: test-cmd.rb provides access to the output streams (both stdout and stderr)
-  of a spawned process.
+description: An object-oriented interface for spawning a process.
 email:
 - 0x1eef@protonmail.com
 executables: []
@@ -125,6 +124,5 @@ requirements: []
 rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
-summary: test-cmd.rb provides access to the output streams (both stdout and stderr)
-  of a spawned process.
+summary: An object-oriented interface for spawning a process.
 test_files: []