eksek 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 38c99ca643c947821f164f389981a9958424ede39ba1aeea5ba956265291d0ff
+  data.tar.gz: bc09955bf615924204cad88a4a7b840826633184b6830207cb1193e71f132346
+SHA512:
+  metadata.gz: a91f53242d38998a7b2ab739050379b07108697c488f9dc69120e8538c6ee1299a66cc07ea203bca54aa76341d8c817f107af365cbaa669f6c365704ca780757
+  data.tar.gz: 2918aa0f4ecea9affba5a6d531a7fa7cfd89ae2186ae30f033efda40e9480a91157afe4d20879591e7e8013a92a19adea79284dcc8cbc966737d6b6624080f7f

data/.gemspec

@@ -0,0 +1,18 @@
+Gem::Specification.new do |s|
+  s.name = 'eksek'
+  s.version = '0.1.0'
+  s.authors = ['Johnny Lee-Othon', 'Thomas Bretzke']
+  s.homepage = 'https://github.com/taccon/eksek'
+  s.summary = 'A better backticks'
+  s.description = <<~END
+    Execute shell commands and easily get stdout, stderr, exit code, and more
+  END
+  s.license = 'ISC'
+
+  s.files = Dir['.gemspec', 'lib/**/*.rb', 'license.txt', 'readme.md']
+
+  s.required_ruby_version = '~> 2.3'
+  s.add_development_dependency 'rspec','~> 3'
+  s.add_development_dependency 'rubocop', '~> 0'
+  s.add_development_dependency 'bundler', '~> 1.0'
+end

data/README.md

@@ -0,0 +1,84 @@
+# eksek
+
+[![Travis](https://img.shields.io/travis/jleeothon/eksek.svg)](https://travis-ci.org/jleeothon/eksek)
+
+`eksek` is a library to run shell commands synchronously and obtain any of the standard output, standard error, and exit code with flexibility.
+
+## Features
+
+### Basic usage
+
+Use the `eksek` to execute a command:
+
+```ruby
+eksek 'echo Hello'
+```
+
+This returns an `EksekResult` object providing the following methods:
+
+- `exit` returns the exit code.
+- `stdout` returns the standard output as a string.
+- `stderr` returns the standard error as a string.
+- `success?` returns `true` or `false` depending of the exit code (`0` for `true`).
+- `success!` throws an exception if the command exited with a non-0 code.
+
+The `success!` method can be chained with any other of the above ones and it is wrapped in the convenience method `eksek!` to have a "fail or return" like so:
+
+```ruby
+puts eksek!('echo Hello').stdout # Hello
+
+# The above is essentially the same as:
+
+puts eksek('echo Hello').success!.stdout
+```
+
+### Writing to stdin
+
+To write into the standard input a block can be used:
+
+```ruby
+r = eksek('read A; echo $A') { |stdin| stdin.write "Hello" }
+r.success!
+```
+
+If the block returns a `String` or `IO`, it will be written into the stdio.
+
+```ruby
+r = eksek('read A; echo $A') { "Hello" }
+r.success!
+
+r = eksek('read A; echo $A') { File.open('myfile.txt') }
+r.success!
+```
+
+### Passing other options
+
+`eksek` has the same signature as `Process#spawn`. This means that:
+
+- the first parameter can optionally be a hash, passed as the process environment;
+- the command can be passed as a single string or as variable-length arguments;
+- other options can be passed as hash arguments.
+
+Additionally, the environment will have its keys stringified, so that symbols can be used too. For example:
+
+```ruby
+r = eksek { A: 'Hello' }, 'echo $A'
+puts r.stdout # Hello
+
+r = eksek 'echo', 'Hello'
+puts r.stdout # Hello
+
+r = eksek 'echo $PWD', chdir: '/tmp'
+puts r.stdout # /tmp
+```
+
+### Further information
+
+In case you prefer an object oriented method, you can also use the `Eksekuter` class that is used by the `eksek` method directly. The following examples are basically the same:
+
+```ruby
+# With eksek
+eksek 'echo Hello' { 'This goes to stdin.' }
+# With Eksekuter
+Eksekuter.new('echo Hello').run { 'This goes to stdin.' }
+```

data/lib/eksek.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'eksekuter'
+
+# Executes shell commands and can be specified to return the standard output,
+# standard error, etc.
+# Accepts the same options as Process.spawn e.g. :chdir, :env.
+module Kernel
+  private
+
+  def eksek *args, **opts, &block
+    Eksekuter.new(*args, **opts).run(&block)
+  end
+
+  def eksek! *args, **opts, &block
+    eksek(*args, **opts, &block).success!
+  end
+end

data/lib/eksek_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Represents an error in the executio of a system call when success! was
+# required.
+class EksekError < StandardError
+end

data/lib/eksek_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'eksek_error'
+
+# Describes a result object to be used for evaluating
+# return values from a command
+class EksekResult
+  # rubocop:disable Metrics/ParameterLists
+  def initialize env, cmd, exit_code, success, stdout, stderr
+    @env = env
+    @cmd = cmd
+    @exit_code = exit_code
+    @success = success
+    @stdout = stdout
+    @stderr = stderr
+  end
+  # rubocop:enable Metrics/ParameterLists
+
+  attr_reader :exit_code, :stdout, :stderr
+
+  def success?
+    @success
+  end
+
+  def success!
+    raise EksekError, "Command failed: #{@cmd.inspect}" unless success?
+    self
+  end
+
+  def to_s
+    stdout
+  end
+end

data/lib/eksekuter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+require_relative 'eksek_result'
+
+# Class that command execution is delegated to by Eksek.
+class Eksekuter
+  def initialize *args, **opts
+    @env = args[0].is_a?(Hash) ? args.shift : {}
+    @env = @env.each_with_object({}) { |(k, v), o| o[k.to_s] = v }
+    @cmd = args.size == 1 ? args.first : args
+    @opts = opts
+  end
+
+  def run &block
+    spawn_process
+    write_and_close_stdin(&block)
+    wait
+    read_and_close_stdout_stderr
+    assemble_result
+  end
+
+  private
+
+  attr_reader(
+    :cmd,
+    :env,
+    :err_str,
+    :opts,
+    :out_str,
+    :process_status,
+    :stdin,
+    :wait_thr,
+  )
+
+  def stdout
+    @stdout ||= StringIO.new('', 'r')
+  end
+
+  def stderr
+    @stderr ||= StringIO.new('', 'r')
+  end
+
+  def spawn_process
+    @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(env, *cmd, opts)
+    nil
+  end
+
+  def write_and_close_stdin
+    return if stdin.closed? || !block_given?
+    block_result = yield stdin
+    block_result = StringIO.new(block_result) if block_result.is_a? String
+    IO.copy_stream(block_result, stdin) if block_result.respond_to? :read
+    stdin.close
+    nil
+  end
+
+  def wait
+    @process_status = wait_thr.value
+  end
+
+  def read_and_close_stdout_stderr
+    streams = [stdout, stderr]
+    @out_str, @err_str = streams.map(&:read).map(&:chomp)
+    streams.each(&:close)
+    nil
+  end
+
+  def assemble_result
+    EksekResult.new(
+      env,
+      cmd,
+      process_status.exitstatus,
+      process_status.success?,
+      out_str,
+      err_str,
+    )
+  end
+end

data/license.txt

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2018, Johnny Enrique Lee-Othon
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: eksek
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johnny Lee-Othon
+- Thomas Bretzke
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: 'Execute shell commands and easily get stdout, stderr, exit code, and
+  more
+
+'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gemspec"
+- README.md
+- lib/eksek.rb
+- lib/eksek_error.rb
+- lib/eksek_result.rb
+- lib/eksekuter.rb
+- license.txt
+homepage: https://github.com/taccon/eksek
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: A better backticks
+test_files: []