test-cmd.rb 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37a0fdfc106f74072dd6368cad33bdce7bd610a142a52b3996cf73e8a058e28e
-  data.tar.gz: f2eaa7173ee120d6bcf067554b3cabb8845b49efc555a8fc87083f30066992af
+  metadata.gz: d9c8ce3140a3961899e285245cbd7d6ceee4caf38508b268ba5500388bfa1aa8
+  data.tar.gz: 907ef5b303a8edfbdcb79930a40274c6976c79a9f78f5754c456adcff745f1e8
 SHA512:
-  metadata.gz: ad30fbeb8c4800d9f111ab23540878dd7b5d8cffc2229f41a8e4991fee00ebae1f47f6113f1bd2b8be70ac1fcf0af98424f86c3bd14de31aacbed5109d9fa5ce
-  data.tar.gz: 178e1d4842f6855d05ad9e9630c98a63338eebab148bafe2b75f85d3fac0a13a1eac7d1f819552adebcc85d2e6033ef8f52f612ea1f518476addf58c146dfa69
+  metadata.gz: 03ab91c5888319ad5d6beb8ab45eac1d4749ba39607e09e5d7866af08027dced706b428c6dd80d077ac53ed4536c594068d87394ffdaaf3c0528d11c5fc690fb
+  data.tar.gz: eba0d96c1277ab435d51a2a8ce21c6269d98527224d15982a9ed3c967df56e820285b964fe8a984b9ceb6ec1cb468098777c733a220564be0c25399e6e190211

data/README.md

@@ -13,21 +13,14 @@ test environment, too.
 
 The following example demonstrates how tests might be written with
 test-unit from the standard library. The
-[`Test::Cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html)
-module implements a
-[`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
-method that can be included into a
-testcase. The
-[`cmd`](https://0x1eef.github.io/x/test-cmd.rb/Test/Cmd.html#cmd-class_method)
-method takes the command to run as its first and only argument:
+[`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:
 
 ```ruby
 require "test/unit"
 require "test/cmd"
 
 class CmdTest < Test::Unit::TestCase
-  include Test::Cmd
-
   def test_ruby_stdout
     assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
   end
@@ -46,6 +39,23 @@ class CmdTest < Test::Unit::TestCase
 end
 ```
 
+### Builder
+
+test-cmd.rb provides an API that is similar to Rust's
+[Command API](https://doc.rust-lang.org/std/process/struct.Command.html).
+<br>
+The
+[API reference](https://0x1eef.github.io/x/test-cmd.rb)
+covers it in more-depth:
+
+``` ruby
+require "test/cmd"
+str = cmd("du")
+      .arg("-s").arg("-h")
+      .spawn.stdout
+puts str      
+```
+
 ### IO#sync
 
 Sometimes it can be neccessary to bypass Ruby's internal buffer and flush
@@ -101,7 +111,7 @@ are available as sources.
 
 ``` ruby
 # Gemfile
-gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.4.1"
+gem "test-cmd.rb", github: "0x1eef/test-cmd.rb", tag: "v0.5.0"
 ```
 
 **Rubygems.org**

data/lib/test-cmd.rb

@@ -1,76 +1,124 @@
 module Test
-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.
-module Test::Cmd
-  class Result
+  ##
+  # 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.
+  class Test::Cmd
     require "tempfile"
+
+    ##
+    # @param [String] cmd
+    #  A command to spawn.
+    # @param [Array<String>] args
+    #  An array of command-line arguments.
+    # @return [Test::Cmd]
+    def initialize(cmd, args = [])
+      @cmd = cmd
+      @args = args.dup
+      @out = Tempfile.new("cmd-stdout").tap(&:unlink)
+      @err = Tempfile.new("cmd-stderr").tap(&:unlink)
+      @status = nil
+      @spawned = false
+    end
+
+    ##
+    # @param [String, #to_s] arg
+    #  A command-line argument.
+    # @return [Test::Cmd]
+    def arg(arg)
+      tap do
+        @args.push(arg)
+      end
+    end
+
+    ##
+    # @param [Array<String, #to_s>] args
+    #  One or more command-line arguments.
+    # @return [Test::Cmd]
+    def args(*args)
+      tap do
+        @args.concat(args)
+      end
+    end
+
+    ##
+    # Spawns a command.
+    # @return [Test::Cmd]
+    def spawn
+      tap do
+        @spawned = true
+        Process.wait Process.spawn(@cmd, *@args, {out: @out, err: @err})
+        @status = $?
+      end
+    ensure
+      [stdout,stderr]
+    end
+
     ##
     # @return [String]
-    #  Returns the contents of stdout
-    attr_reader :stdout
+    #  Returns the contents of stdout.
+    def stdout
+      spawn unless @spawned
+      @stdout ||= @out.tap(&:rewind).read
+    ensure
+      @out.close unless @out.closed?
+    end
 
     ##
     # @return [String]
-    #  Returns the contents of stderr
-    attr_reader :stderr
+    #  Returns the contents of stderr.
+    def stderr
+      spawn unless @spawned
+      @stderr ||= @err.tap(&:rewind).read
+    ensure
+      @err.close unless @err.closed?
+    end
 
     ## @return [Process::Status]
     #  Returns the status of a process
-    attr_reader :status
-
-    ##
-    # @param [Tempfile] stdout
-    # @param [Tempfile] stderr
-    # @param [Process::Status] pstatus
-    # @return [Test::Cmd::Result]
-    def initialize(stdout, stderr, pstatus)
-      @stdout = stdout.tap(&:rewind).read
-      @stderr = stderr.tap(&:rewind).read
-      @status = pstatus
+    def status
+      spawn unless @spawned
+      @status
     end
 
     ##
     # @return [Integer]
     #  Returns the exit status of a process
     def exit_status
-      @status.exitstatus
+      status.exitstatus
     end
 
     ##
     # Yields each line of stdout when the command
     # was successful, or each line of stderr when
     # the command was not successful.
-    #
     # @return [Enumerator]
     #  Returns an Enumerator when a block is not given.
     def each_line
       return enum_for(:each_line) unless block_given?
+      spawn unless @spawned
       io = @status.success? ? @stdout : @stderr
       io.each_line.each { yield(_1.chomp) }
     end
   end
 
-  ##
-  # @param [String] cmd
-  #  A command to execute
-  #
-  # @return [Test::Cmd::Result]
-  #  Returns an instance of {Test::Cmd::Result Test::Cmd::Result}
-  def cmd(cmd)
-    out = Tempfile.new("cmd-stdout").tap(&:unlink)
-    err = Tempfile.new("cmd-stderr").tap(&:unlink)
-    Process.wait spawn(cmd, {err:, out:})
-    Result.new(out, err, $?)
-  ensure
-    out.close
-    err.close
+  module CmdMixin
+    ##
+    # @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)
+    end
   end
-  module_function :cmd
+end
+
+module Kernel
+  include Test::CmdMixin
 end

data/test/test_cmd_test.rb

@@ -1,8 +1,6 @@
 require_relative "setup"
 
 class CmdTest < Test::Unit::TestCase
-  include Test::Cmd
-
   def test_ruby_stdout
     assert_equal "foo\n", cmd(%q(ruby -e '$stdout.puts "foo"')).stdout
   end

data/test-cmd.rb.gemspec

@@ -5,13 +5,14 @@ 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.4.1"
+  gem.version = "0.5.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.metadata = { "documentation_uri" => "https://0x1eef.github.io/x/test-cmd.rb/" }
   gem.description = gem.summary
   gem.add_development_dependency "test-unit", "~> 3.5.7"
   gem.add_development_dependency "yard", "~> 0.9"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: test-cmd.rb
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - '0x1eef'
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-07 00:00:00.000000000 Z
+date: 2024-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-unit
@@ -90,7 +90,8 @@ files:
 homepage: https://github.com/0x1eef/test-cmd.rb#readme
 licenses:
 - 0BSD
-metadata: {}
+metadata:
+  documentation_uri: https://0x1eef.github.io/x/test-cmd.rb/
 post_install_message:
 rdoc_options: []
 require_paths: