command_line 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65b543edab02b25241f4283219efee33d7c5d6308726e494e74af84f16bbbd17
-  data.tar.gz: 5a4e2cf8d5eb9699163adfdf1c94a525fa75b68901684fe50aa8021dc81fa33f
+  metadata.gz: aaa71300b625158d9cf0460e8be73d20fdc1e045ff0f7dcab2e7483019f96408
+  data.tar.gz: 6d5eb5b7ff2083b75ae156c14038cc01ecbda66572a1cf8c5b9fa017f35b05f1
 SHA512:
-  metadata.gz: 002c295694393a0a0227ff5826d67dc77cc4d1a0ddf9cea8c50e7a5462750ba5d3e9f1c6c5d991d415648b89afc7260acd91769b18416239295f9d2fb9ce572b
-  data.tar.gz: 49533b8f1e135b0f0b1da7dee0f4b2df83cf8ed86477bfab60f6b7918e4f83b9a94a266c48593f27bddd6a5f9a89d24ffb7db45e3efe98a7fa616dc08d0015e2
+  metadata.gz: b4335254d86f1369417000bdecc9fd486040918368d3757976e884da50f4a213dc197b5f20de55ed0176497dcd21b3f6998774443928b9967c356019546db639
+  data.tar.gz: 8116f37462c0cda552988f526bbd75f768db92a9520646959a0cb50328930328ec4b4282ae2da44ec45ef22a66436ab6ac412d80a3f9069c45693560af84eb22

data/.rubocop.yml

@@ -13,5 +13,9 @@ Layout/IndentFirstHashElement:
 Metrics/BlockLength:
   Exclude:
     - spec/**/*
+Metrics/AbcSize:
+  Enabled: false
 Metrics/MethodLength:
-  Max: 15
+  Enabled: false
+Style/RescueModifier:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [1.1.0] (TBD)
+
+## Added
+
+- CommandLine.command_line!
+- Added a `:timeout` argument for setting a timeout.
+- Allow more than strings as arguments to pass to the command. We'll convert everything with `to_s`.
+
 # [1.0.1] (2019-08-16)
 
 ## Fixed
@@ -8,4 +16,5 @@
 
 Initial release.
 
+[1.1.0]: https://github.com/DragonRuby/command_line/compare/v1.0.1...v1.1.0
 [1.0.1]: https://github.com/DragonRuby/command_line/compare/v1.0.0...v1.0.1

data/README.md

@@ -1,5 +1,9 @@
 # CommandLine
 
+[![Version](https://img.shields.io/gem/v/command_line.svg?style=flat-square)](https://rubygems.org/gems/command_line)
+[![Linux and OS X Build](https://img.shields.io/travis/com/DragonRuby/command_line?label=Linux%20and%20OS%20X&style=flat-square)](https://travis-ci.com/DragonRuby/command_line)
+[![Windows Build](https://img.shields.io/appveyor/ci/AaronLasseigne/command-line?label=Windows&style=flat-square)](https://ci.appveyor.com/project/AaronLasseigne/command-line)
+
 CommandLine provides an easier way to run command-line applications.
 It captures all outputs, can handle applications that require stdin, and can pass environment variables.
 It's also helpful for testing commmand-line applications.
@@ -13,13 +17,13 @@ This project uses [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'command_line', '~> 1.0'
+gem 'command_line', '~> 1.1'
 ```
 
 If you want `command_line` available globally you can add this line to your application's Gemfile:
 
 ```ruby
-gem 'command_line', '~> 1.0', require: 'command_line/global'
+gem 'command_line', '~> 1.1', require: 'command_line/global'
 ```
 
 Or manually install it yourself with:
@@ -70,7 +74,23 @@ end
 Environment variables can be passed after the command and arguments are passed.
 
 ```ruby
-command_line('some_webserver', { 'PORT' => '80' })
+command_line('some_webserver', env: { 'PORT' => '80' })
+```
+
+If you're concerned about the command running too long you can set a `:timeout`.
+Exceeding the timeout will cause a `CommandLine::TimeoutError` to be raised.
+
+```ruby
+>> command_line('sleep', 5, timeout: 2)
+CommandLine::TimeoutError (execution expired)
+```
+
+You can use `command_line!` if you want to raise an error on an exit failure.
+The contents of `stderr` will be the error message.
+
+```ruby
+>> command_line!('grep')
+CommandLine::ExitFailureError (usage: grep [-abc....
 ```
 
 ### RSpec

data/lib/command_line.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'timeout'
 
 require 'command_line/result'
 require 'command_line/version'
@@ -10,15 +11,28 @@ require 'command_line/version'
 # environment variables. It's also helpful for testing commmand-line
 # applications.
 module CommandLine
+  # Top-level error class. All other errors subclass this.
+  class Error < StandardError; end
+
+  # Raised if CommandLine#command_line! is called an has an exit failure.
+  class ExitFailureError < Error; end
+
+  # Raised if a timeout is given and exceeded.
+  class TimeoutError < Error; end
+
   module_function
 
   # Run a command and get back the result.
   #
-  # @param command [String] the command to run
-  # @param args [Array<String>] any arguments passed to the command
+  # @param command [String] The command to run.
+  # @param args [Array] Any arguments passed to the command. All arguments will
+  #   be converted to strings using `to_s`.
   # @param [Hash] env: Pass environment variables to use. The key should
   #   be a String representing the environment variable name. The value
   #   is the value you want that variable to have.
+  # @param [Integer, Float, nil] Number of seconds to wait for the block to
+  #   terminate. Floats can be used to specify fractional seconds. A value of 0
+  #   or nil will execute the block without any timeout.
   #
   # @yield [stdin] Handle any input on stdin that the command needs.
   # @yieldparam stdin [IO]
@@ -33,24 +47,54 @@ module CommandLine
   #   end
   #
   # @example
-  #   command_line('some_webserver', { 'PORT' => '80' })
+  #   command_line('some_webserver', env: { 'PORT' => '80' })
   #
   # @return [Result]
-  def command_line(command, *args, env: {})
+  def command_line(command, *args, env: {}, timeout: nil)
     stdout = ''
     stderr = ''
     status = nil
 
-    Open3.popen3(env, command, *args) do |i, o, e, wait_thr|
-      yield i if block_given?
+    Open3.popen3(env, command.to_str, *args.map(&:to_s)) do |i, o, e, wait_thr|
+      begin
+        threads = []
+
+        Timeout.timeout(timeout, TimeoutError) do
+          yield i if block_given?
 
-      [
-        Thread.new { stdout = o.read },
-        Thread.new { stderr = e.read }
-      ].each(&:join)
-      status = wait_thr.value
+          threads << Thread.new { stdout = o.read }
+          threads << Thread.new { stderr = e.read }
+          threads.each(&:join)
+          status = wait_thr.value
+        end
+      rescue TimeoutError => e
+        threads.map(&:kill)
+
+        raise e
+      end
     end
 
     Result.new(stdout, stderr, status)
   end
+
+  # Same as CommandLine.command_line except that a failure on exit raises an
+  # error.
+  #
+  # @see CommandLine.command_line
+  #
+  # @example
+  #   command_line!('echo', 'hello')
+  #
+  # @example
+  #   command_line!('grep')
+  #   # => CommandLine::ExitFailureError (usage: grep ...
+  #
+  # @return [Result]
+  # @raise [CommandLine::ExitFailureError] If the application exits with an
+  #   error status. The message will be the contents of Result#stderr.
+  def command_line!(*args, &block)
+    command_line(*args, &block).tap do |result|
+      raise ExitFailureError, result.stderr if result.failure?
+    end
+  end
 end

data/lib/command_line/global.rb

@@ -6,11 +6,15 @@ require 'command_line'
 
 # Run a command and get back the result.
 #
-# @param command [String] the command to run
-# @param args [Array<String>] any arguments passed to the command
+# @param command [String] The command to run.
+# @param args [Array] Any arguments passed to the command. All arguments will
+#   be converted to strings using `to_s`.
 # @param [Hash] env: Pass environment variables to use. The key should
 #   be a String representing the environment variable name. The value
 #   is the value you want that variable to have.
+# @param [Integer, Float, nil] Number of seconds to wait for the block to
+#   terminate. Floats can be used to specify fractional seconds. A value of 0
+#   or nil will execute the block without any timeout.
 #
 # @yield [stdin] Handle any input on stdin that the command needs.
 # @yieldparam stdin [IO]
@@ -25,9 +29,28 @@ require 'command_line'
 #   end
 #
 # @example
-#   command_line('some_webserver', { 'PORT' => '80' })
+#   command_line('some_webserver', env: { 'PORT' => '80' })
 #
 # @return [Result]
 def command_line(*args, &block)
   CommandLine.command_line(*args, &block)
 end
+
+# Same as CommandLine.command_line except that a failure on exit raises an
+# error.
+#
+# @see CommandLine.command_line
+#
+# @example
+#   command_line!('echo', 'hello')
+#
+# @example
+#   command_line!('grep')
+#   # => CommandLine::ExitFailureError (usage: grep ...
+#
+# @return [Result]
+# @raise [CommandLine::ExitFailureError] If the application exits with an
+#   error status. The message will be the contents of Result#stderr.
+def command_line!(*args, &block)
+  CommandLine.command_line!(*args, &block)
+end

data/lib/command_line/result.rb

@@ -45,7 +45,7 @@ module CommandLine
     #   command_line('grep').exitstatus
     #   # => 2
     #
-    # @return [Integer,nil]
+    # @return [Integer, nil]
     def exitstatus
       @status.exitstatus
     end

data/lib/command_line/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CommandLine
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_line
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Aaron Lasseigne
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-10-16 00:00:00.000000000 Z
+date: 2019-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler