coque 0.5.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b7ea60eb553722ddd8d3a150306e31dad188e477
-  data.tar.gz: bbbd233b0459043ccf194fbbf54618058eb3aae2
+SHA256:
+  metadata.gz: 6f9a270751ea085a375d71bc3b7a7ccd34237f4094dce63ffbffb66005b123ff
+  data.tar.gz: 89e0e4065a6eb61c27c1b41e2ecd1dd84470b83ba934e3421ea8ee119840d5cd
 SHA512:
-  metadata.gz: f23b1f42df3acef474f60ef0e0f71507b7cc99bf4d0eacf47e0cd22def9d99e4ea41210d5574056d4e9eed00d7f8f87a336096beba2fad551d7c3dc5690bfd44
-  data.tar.gz: 477b28f76c596fbbf679990fb8d6f62c42a8d09bd88ba8de993779017bd382dff6044c3ef2dff7aa21ded24c26ba3277a43594a9ef5f0789614354ae97ef3d4d
+  metadata.gz: 64b833a5a39cc7ed3a65339af2ac13c0a3f0e0461247cd899c69deab5a9a7d30ffccb7bae4da16a7fed175638a59a19aaa43c2335aba109a5105b7b27e0f5682
+  data.tar.gz: 853b5a31c91d099dc88e0881672c4fa8b465bca04ae70d553dcac9daed4c21f29501a4818fb4b04a42d8bc6e1ab021c32ae5e4a411dc3d5e3a1f1a7e44dc5aa8

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/.travis.yml

@@ -1,5 +1,4 @@
-sudo: false
 language: ruby
-rvm:
-  - 2.3.0
-before_install: gem install bundler -v 1.16.1
+before_install:
+  - gem update --system
+  - gem install bundler

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    coque (0.5.0)
+    coque (0.8.0)
 
 GEM
   remote: https://rubygems.org/
@@ -10,7 +10,7 @@ GEM
     builder (3.2.3)
     coderay (1.1.2)
     docile (1.3.1)
-    json (2.1.0)
+    json (2.3.1)
     method_source (0.9.0)
     minitest (5.11.3)
     minitest-reporters (1.2.0)
@@ -21,7 +21,7 @@ GEM
     pry (0.11.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    rake (12.3.1)
+    rake (13.0.1)
     ruby-progressbar (1.9.0)
     simplecov (0.16.1)
       docile (~> 1.1)
@@ -33,13 +33,13 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  bundler (~> 1.16)
+  bundler (~> 2.0)
   coque!
   minitest (~> 5.11)
   minitest-reporters
   pry
-  rake (~> 12.3)
+  rake (~> 13.0)
   simplecov
 
 BUNDLED WITH
-   1.16.2
+   2.2.24

data/README.md

@@ -1,5 +1,8 @@
 # Coque
 
+[![Build Status](https://travis-ci.org/worace/coque.svg?branch=master)](https://travis-ci.org/worace/coque)
+[![Gem Version](https://badge.fury.io/rb/coque.svg)](https://badge.fury.io/rb/coque)
+
 Create, manage, and interop with shell pipelines from Ruby. Like [Plumbum](https://plumbum.readthedocs.io/en/latest/), for Ruby, with native (Ruby) code streaming integration.
 
 ## Installation
@@ -99,6 +102,88 @@ Coque also includes a `Coque.source` helper for feeding Ruby enumerables into sh
 # => ["500"]
 ```
 
+#### Asynchrony and Waiting on Processes
+
+Running a Coque command forks a new process, and by default these processes run asynchronously. Calling `.run` on a Coque command or pipeline returns a `Coque::Result` object which can be used to get the output (`.to_a`) or exit code (`.exit_code`) of the process:
+
+```rb
+result = Coque['echo', 'hi'].run
+# => #<Coque::Result:0x000055da63437838 @out=#<IO:fd 15>, @pid=29236>
+puts "its running in the background..."
+its running in the background...
+result.to_a
+# => ["hi"]
+result.exit_code
+# => 0
+```
+
+However you can also just use `.wait` to block on a process while it runs:
+
+```rb
+result = Coque['echo', 'hi'].run.wait
+# => #<Coque::Result:0x000055da633c98b0 @exit_code=0, @out=#<IO:fd 17>, @pid=29536>
+```
+
+Or, use `.run!` to block on the process _and_ raise an exception if it exits with a non-zero response:
+
+```
+Coque["head", "/usr/share/dict/words"].run!
+# => nil
+Coque["head", "/usr/share/dict/pizza"].run!
+# head: cannot open '/usr/share/dict/pizza' for reading: No such file or directory
+# RuntimeError: Coque Command Failed: <Coque::Sh head /usr/share/dict/pizza>
+from /home/horace/.gem/ruby/2.4.4/gems/coque-0.7.1/lib/coque/runnable.rb:13:in `run!'
+```
+
+There's also a `to_a!` variant on commands which combines the error handling of `run!` with the array-slurping of stdout:
+
+```
+Coque['head', '-n 1', '/usr/share/dict/words'].to_a!
+=> ["A"]
+
+Coque['head', '-n 1', '/usr/share/dict/asdf'].to_a!
+head: cannot open '/usr/share/dict/asdf' for reading: No such file or directory
+RuntimeError: Coque Command Failed: <Coque::Sh head -n 1 /usr/share/dict/asdf>
+from /code/coque/lib/coque/runnable.rb:11:in `to_a!'
+```
+
+#### Named (Non-Operator) Method Alternatives
+
+The main piping and redirection methods also include named alternatives:
+
+* `|` is aliased to `pipe`
+* `>` is aliased to `out`
+* `>=` is aliased to `err`
+* `<` is aliased to `in`
+
+So these 2 invocations are equivalent:
+
+```rb
+(Coque["echo", "hi"] | Coque["wc", "-c"] > STDERR).run!
+# is the same as...
+Coque["echo", "hi"].pipe(Coque["wc", "-c"]).out(STDERR).run!
+```
+
+#### Logging
+
+You can set a logger for Coque, which will be used to output messages when commands are executed:
+
+```rb
+Coque.logger = Logger.new(STDOUT)
+(Coque["echo", "hi"] | Coque["wc", "-c"]).run!
+```
+
+Will log:
+
+```
+I, [2019-02-20T20:31:00.325777 #16749]  INFO -- : Executing Coque Command: <Pipeline <Coque::Sh echo hi> | <Coque::Sh wc -c> >
+I, [2019-02-20T20:31:00.325971 #16749]  INFO -- : Executing Coque Command: <Coque::Sh echo hi>
+I, [2019-02-20T20:31:00.327719 #16749]  INFO -- : Coque Command: <Coque::Sh echo hi> finished in 0.001683 seconds.
+I, [2019-02-20T20:31:00.327771 #16749]  INFO -- : Executing Coque Command: <Coque::Sh wc -c>
+I, [2019-02-20T20:31:00.329586 #16749]  INFO -- : Coque Command: <Coque::Sh wc -c> finished in 0.001739 seconds.
+I, [2019-02-20T20:31:00.329725 #16749]  INFO -- : Coque Command: <Pipeline <Coque::Sh echo hi> | <Coque::Sh wc -c> > finished in 0.003796 seconds.
+```
+
 ### Streaming Performance
 
 Should be little overhead compared with the equivalent pipeline from a standard shell.

data/coque.gemspec

@@ -30,8 +30,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 12.3"
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "minitest", "~> 5.11"
   spec.add_development_dependency "minitest-reporters"
   spec.add_development_dependency "pry"

data/lib/coque.rb

@@ -1,4 +1,5 @@
 require "coque/redirectable"
+require "coque/runnable"
 require "coque/cmd"
 require "coque/sh"
 require "coque/rb"
@@ -9,6 +10,15 @@ require "coque/result"
 require "coque/version"
 
 module Coque
+  @@logger = nil
+  def self.logger=(logger)
+    @@logger = logger
+  end
+
+  def self.logger
+    @@logger
+  end
+
   def self.context(dir: Dir.pwd, env: {}, disinherits_env: false)
     Context.new(dir, env, disinherits_env)
   end

data/lib/coque/cmd.rb

@@ -1,9 +1,10 @@
 module Coque
   class Cmd
     include Redirectable
+    include Runnable
     attr_reader :context
 
-    def |(other)
+    def pipe(other)
       case other
       when Cmd
         Pipeline.new([self.clone, other.clone])
@@ -12,6 +13,10 @@ module Coque
       end
     end
 
+    def |(other)
+      pipe(other)
+    end
+
     def clone
       raise "Not Implemented - Override"
     end

data/lib/coque/pipeline.rb

@@ -1,6 +1,7 @@
 module Coque
   class Pipeline
     include Redirectable
+    include Runnable
 
     attr_reader :commands
     def initialize(commands = [])
@@ -15,7 +16,7 @@ module Coque
       "<Pipeline #{commands.join(" | ")} >"
     end
 
-    def |(other)
+    def pipe(other)
       case other
       when Pipeline
         Pipeline.new(commands + other.commands)
@@ -24,6 +25,10 @@ module Coque
       end
     end
 
+    def |(other)
+      pipe(other)
+    end
+
     def stitch
       # Set head in
       if commands.first.stdin.nil?
@@ -52,7 +57,7 @@ module Coque
       end
     end
 
-    def run
+    def get_result
       stdout = stitch
       results = commands.map(&:run)
       Result.new(results.last.pid, stdout)

data/lib/coque/rb.rb

@@ -31,7 +31,7 @@ module Coque
       self
     end
 
-    def run
+    def get_result
       stdin, stdoutr, stdoutw = get_default_fds
 
       pid = fork do

data/lib/coque/redirectable.rb

@@ -4,24 +4,36 @@ module Coque
   module Redirectable
     attr_reader :stdin, :stdout, :stderr
 
-    def >(io)
+    def out(io)
       clone.tap do |c|
         c.stdout = io
       end
     end
 
-    def <(io)
+    def >(io)
+      out(io)
+    end
+
+    def in(io)
       clone.tap do |c|
         c.stdin = io
       end
     end
 
-    def >=(io)
+    def <(io)
+      self.in(io)
+    end
+
+    def err(io)
       clone.tap do |c|
         c.stderr = io
       end
     end
 
+    def >=(io)
+      err(io)
+    end
+
     def getio(io, mode = "r")
       case io
       when STDERR
@@ -53,20 +65,6 @@ module Coque
       @stdin = getio(s, "r")
     end
 
-    def to_a
-      run.to_a
-    end
-
-    def success?
-      run.success?
-    end
-
-    def run!
-      if !success?
-        raise "Coque Command Failed: #{self}"
-      end
-    end
-
     private
 
     def stdout_read

data/lib/coque/result.rb

@@ -24,7 +24,7 @@ class Coque::Result
   end
 
   def wait
-    _, status = Process.waitpid2(pid)
+    _pid, status = Process.waitpid2(pid)
     @exit_code = status.exitstatus
     self
   end

data/lib/coque/runnable.rb

@@ -0,0 +1,39 @@
+module Coque
+  module Runnable
+    def to_a
+      run.to_a
+    end
+
+    def to_a!
+      res = run
+      rows = res.to_a
+      unless res.exit_code == 0
+        raise "Coque Command Failed: #{self}"
+      end
+      rows
+    end
+
+    def success?
+      run.success?
+    end
+
+    def run!
+      if !success?
+        raise "Coque Command Failed: #{self}"
+      else
+        self
+      end
+    end
+
+    def run
+      log_start
+      get_result
+    end
+
+    def log_start
+      if Coque.logger
+        Coque.logger.info("Executing Coque Command: #{self.to_s}")
+      end
+    end
+  end
+end

data/lib/coque/sh.rb

@@ -14,7 +14,7 @@ module Coque
     end
 
     def to_s
-      "<Coque::Sh #{args.inspect}>"
+      "<Coque::Sh #{args.join(" ")}>"
     end
 
     def inspect
@@ -25,7 +25,7 @@ module Coque
       self.class.new(self.context, self.args + new_args)
     end
 
-    def run
+    def get_result
       stdin, stdoutr, stdoutw = get_default_fds
       opts = {in: stdin, stdin.fileno => stdin.fileno,
               out: stdoutw, stdoutw.fileno => stdoutw.fileno,

data/lib/coque/version.rb

@@ -1,3 +1,3 @@
 module Coque
-  VERSION = "0.5.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: coque
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Horace Williams
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-24 00:00:00.000000000 Z
+date: 2021-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.3'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -112,8 +112,6 @@ files:
 - bin/console
 - bin/setup
 - coque.gemspec
-- drake.rb
-- io.rb
 - lib/coque.rb
 - lib/coque/cmd.rb
 - lib/coque/context.rb
@@ -122,6 +120,7 @@ files:
 - lib/coque/rb.rb
 - lib/coque/redirectable.rb
 - lib/coque/result.rb
+- lib/coque/runnable.rb
 - lib/coque/sh.rb
 - lib/coque/version.rb
 - script.py
@@ -145,8 +144,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14.1
+rubygems_version: 3.2.21
 signing_key: 
 specification_version: 4
 summary: Shell command utilities with easy integration with Ruby code.

data/drake.rb

@@ -1,113 +0,0 @@
-require "open3"
-require "pry"
-
-class Pipeline
-  attr_reader :commands
-  def initialize(commands = [])
-    @commands = commands
-  end
-
-  def to_s
-    "Pipeline of #{commands.join("|")}"
-  end
-
-  def |(other)
-    case other
-    when Pipeline
-      Pipeline.new(commands + other.commands)
-    when Cmd
-      Pipeline.new(commands + [other])
-    when Crb
-      Pipeline.new(commands + [other])
-    end
-  end
-
-  def run
-    commands = self.commands
-    pids = []
-
-    in_read, in_write = IO.pipe
-    out_read = nil
-    out_write = nil
-
-    while commands.any? do
-      in_write.close
-      out_read, out_write = IO.pipe
-
-      cmd = commands.shift
-      puts "Spawn command: #{cmd}"
-      pids << cmd.run(in_read, out_write)
-
-      in_read = out_read
-      in_write = out_write
-    end
-    out_write.close
-    [pids, out_read]
-  end
-end
-
-class Cmd
-  attr_reader :args
-  def initialize(args)
-    @args = args
-  end
-
-  def to_s
-    "Cmd to run: `#{args.inspect}`"
-  end
-
-  def self.[](*args)
-    puts args.inspect
-    Cmd.new(args)
-  end
-
-  def command
-    args.join(" ")
-  end
-
-  def run(stdin, stdout)
-    spawn(args.join(" "), in: stdin, stdin => stdin, out: stdout, stdout => stdout)
-  end
-
-  def |(other)
-    case other
-    when Cmd
-      Pipeline.new([self, other])
-    when Crb
-      Pipeline.new([self, other])
-    when Pipeline
-      Pipeline.new([self] + other.commands)
-    end
-  end
-end
-
-class Crb
-  def initialize(&block)
-    @block = block
-  end
-
-  def run(stdin, stdout)
-    fork do
-      STDOUT.reopen(stdout)
-      stdin.each_line(&@block)
-    end
-  end
-
-  def |(other)
-    case other
-    when Cmd
-      Pipeline.new([self, other])
-    when Crb
-      Pipeline.new([self, other])
-    when Pipeline
-      Pipeline.new([self] + other.commands)
-    end
-  end
-end
-
-
-c = Cmd['cat', '/usr/share/dict/words'] | Cmd['head'] | Crb.new { |line| puts "crb - #{line}" }
-puts "pipeline: #{c}"
-pids, out = c.run
-puts "Spawned pids: #{pids}"
-out.each_line { |l| puts l }

data/io.rb

@@ -1,215 +0,0 @@
-require 'open3'
-
-def banner(msg)
-  puts "******* #{msg} *******"
-end
-
-def read_from_spawned_pipe
-  banner("read_from_spawned_pipe")
-  pipe_me_in, pipe_peer_out = IO.pipe
-  pipe_peer_in, pipe_me_out = IO.pipe
-
-  pid = spawn('ls',
-              out: pipe_peer_out,
-              pipe_peer_out => pipe_peer_out,
-              in: pipe_peer_in,
-              pipe_peer_in => pipe_peer_in)
-  puts "Spawned #{pid}"
-
-  pipe_peer_out.close
-  puts pipe_me_in.read
-end
-
-def read_write_to_spawned
-  banner("read_write_to_spawned")
-  pipe_me_in, pipe_peer_out = IO.pipe
-  pipe_peer_in, pipe_me_out = IO.pipe
-
-  ['a', 'b', 'c', 'ab'].each { |l| pipe_me_out.puts(l) }
-
-  pid = spawn('grep a',
-              out: pipe_peer_out,
-              pipe_peer_out => pipe_peer_out,
-              in: pipe_peer_in,
-              pipe_peer_in => pipe_peer_in)
-  puts "Spawned #{pid}"
-  pipe_me_out.close
-
-  pipe_peer_out.close
-  puts pipe_me_in.read
-end
-
-def chain_two_native_processes
-  banner("chain_two_native_processes")
-  a_in_read, a_in_write = IO.pipe
-  a_out_read, a_out_write = IO.pipe
-
-  p1 = spawn('echo "a\nb\nc\nab\n"',
-             out: a_out_write,
-             a_out_write => a_out_write,
-             in: a_in_read,
-             a_in_read => a_in_read)
-
-  b_out_read, b_out_write = IO.pipe
-
-  p2 = spawn('grep a',
-             out: b_out_write,
-             b_out_write => b_out_write,
-             in: a_out_read,
-             a_out_read => a_out_read)
-
-  puts "Spawned a: #{p1}, b: #{p2}"
-  # Q: Why do we have to close these? do the spawned processes not close them?
-  b_out_write.close
-  a_out_write.close
-  puts b_out_read.read
-end
-
-def reading_large_output
-  banner("reading_large_output")
-  a_in_read, a_in_write = IO.pipe
-  a_out_read, a_out_write = IO.pipe
-
-  p1 = spawn('cat /usr/share/dict/words',
-             out: a_out_write,
-             a_out_write => a_out_write)
-
-  a_out_write.close
-  puts a_out_read.read
-end
-
-def pipe_to_forked_ruby
-  banner("pipe_to_forked_ruby")
-  a_in_read, a_in_write = IO.pipe
-  b_out_read, b_out_write = IO.pipe
-
-  ['a', 'b', 'c', 'ab'].each { |l| a_in_write.puts(l) }
-  a_in_write.flush
-  a_in_write.close
-
-  child = fork do
-    # change our stdin to be the read end of the pipe
-    STDOUT.puts "forked process to stdout (#{STDOUT.fileno})"
-    b_out_write.puts "******* forked process to pipe (#{b_out_write.fileno}) **********"
-
-    a_in_read.each_line { |l| b_out_write.puts "child - #{l}" }
-  end
-  puts "forked #{child}"
-
-  a_in_write.close
-  b_out_write.close
-
-  b_out_read.each_line { |l| puts "read from parent - #{l}" }
-end
-
-
-def native_process_to_ruby_block
-  banner("native_process_to_ruby_block")
-  # a_in_read, a_in_write = IO.pipe
-  a_out_read, a_out_write = IO.pipe
-  b_out_read, b_out_write = IO.pipe
-  puts "parent file descriptors"
-  puts "a read: #{a_out_read.fileno}"
-  puts "a write: #{a_out_write.fileno}"
-  puts "b read: #{b_out_read.fileno}"
-  puts "b write: #{b_out_write.fileno}"
-
-  # Receives copy of a_out_write; closes when done
-  p1 = spawn('echo "a\nb\nc\nab"', out: a_out_write)
-
-  # Receives copy of
-  # a_out_read - needs to read; closed automatically?
-  # a_out_write - doesn't need, close immediately
-  # b_out_read - doesn't need, close immediately
-  # b_out_write - needs to write; close when done
-  child = fork do
-    puts "child file descriptors:"
-    puts "a read: #{a_out_read.fileno}"
-    puts "a write: #{a_out_write.fileno}"
-    puts "b read: #{b_out_read.fileno}"
-    puts "b write: #{b_out_write.fileno}"
-    a_out_write.close
-    b_out_read.close
-
-    puts "******* IN FORK **********"
-
-    # while l = a_out_read.gets
-    #   puts "working #{l}"
-    #   b_out_write.puts "child - #{l}"
-    # end
-
-    a_out_read.each_line { |l| puts "working #{l}"; b_out_write.puts "child - #{l}" }
-    puts "child done - close writer"
-    a_out_read.close
-    b_out_write.close
-    puts "Fork work done"
-  end
-
-  puts "done forked"
-
-  a_out_write.close
-  b_out_write.close
-  a_out_read.close
-
-  puts "** Display child output:"
-  b_out_read.each_line { |l| puts "read from parent - #{l}" }
-  b_out_read.close
-  puts "done reading"
-end
-
-# read_from_spawned_pipe
-# read_write_to_spawned
-# pipe_to_forked_ruby
-# reading_large_output
-# chain_two_native_processes
-# native_process_to_ruby_block
-
-def run_fork(stdin, stdout, &block)
-  fork do
-    STDOUT.reopen(stdout)
-    stdin.each_line(&block)
-  end
-end
-
-def three_step
-  writers = []
-  banner("three step")
-  a_in_read, a_in_write = IO.pipe
-  a_out_read, a_out_write = IO.pipe
-
-  a_unused = [a_out_write]
-
-  p1 = spawn('echo "a\nb\nc\nab\n"',
-             out: a_out_write,
-             a_out_write => a_out_write,
-             in: a_in_read,
-             a_in_read => a_in_read)
-
-  b_out_read, b_out_write = IO.pipe
-  b_unused = [b_out_write]
-
-  a_unused.each(&:close)
-  run_fork(a_out_read, b_out_write) { |l| puts "~~ - #{l}" }
-
-  c_out_read, c_out_write = IO.pipe
-  c_unused = [c_out_write]
-
-  p2 = spawn('grep a',
-             out: c_out_write,
-             c_out_write => c_out_write,
-             in: b_out_read,
-             b_out_read => b_out_read)
-  b_unused.each(&:close)
-
-  # Q: Why do we have to close these? do the spawned processes not close them?
-  c_unused.each(&:close)
-  puts c_out_read.read
-end
-
-# three_step
-
-def stdin_redirect
-  stdin = File.open("/usr/share/dict/words", "r")
-  spawn("head", in: stdin, stdin => stdin)
-end
-stdin_redirect