cmds 0.0.9 → 0.1.0

data/lib/cmds/spawn.rb

@@ -0,0 +1,251 @@
+# stdlib
+require 'open3'
+require 'thread'
+
+# deps
+require 'nrser'
+require 'nrser/refinements'
+
+# project
+require 'cmds/pipe'
+require 'cmds/io_handler'
+
+using NRSER
+
+module Cmds
+  # internal core function to spawn and stream inputs and/or outputs using
+  # threads.
+  # 
+  # originally inspired by
+  # 
+  # https://nickcharlton.net/posts/ruby-subprocesses-with-stdout-stderr-streams.html
+  # 
+  # with major modifications from looking at Ruby's open3 module.
+  # 
+  # @param [String] cmd
+  #   shell-ready command string.
+  # 
+  # @param [nil | String | #read] input
+  #   string or readable input. here so that Cmds instances can pass their
+  #   `@input` instance variable -- `&io_block` overrides it.
+  # 
+  # @param [#call & (#arity ∈ {0, 1})] &io_block
+  #   optional block to handle io. behavior depends on arity:
+  #   
+  #   -   arity `0`
+  #       -   block is called and expected to return an object
+  #           suitable for input (`nil`, `String` or `IO`-like).
+  #   -   arity `1`
+  #       -   block is called with the {Cmds::IOHandler} instance for the
+  #           execution, which it can use to handle input and outputs.
+  # 
+  # @raise [ArgumentError]
+  #   if `&io_block` has arity greater than 1.
+  # 
+  def self.spawn cmd, input = nil, &io_block
+    Cmds.debug "entering Cmds#really_stream",
+      cmd: cmd,
+      input: input,
+      io_block: io_block
+
+    # create the handler that will be yielded to the input block
+    handler = Cmds::IOHandler.new
+
+    # handle input
+    # 
+    # if a block was provided it overrides the `input` argument.
+    # 
+    if io_block
+      case io_block.arity
+      when 0
+        # when the input block takes no arguments it returns the input
+        input = io_block.call
+      when 1
+        # when the input block takes one argument, give it the handler and
+        # ignore the return value
+        io_block.call handler
+
+        # if input was assigned to the handler in the block, use it as input
+        input = handler.in unless handler.in.nil?
+      else
+        # bad block provided
+        raise ArgumentError.new <<-BLOCK.squish
+          provided input block must have arity 0 or 1
+        BLOCK
+      end # case io_block.arity
+    end # if io_block
+
+    # hash of options that will be passed to `spawn`
+    spawn_opts = {}
+
+    Cmds.debug "looking at input...",
+      input: input
+
+    # (possibly) create the input pipe... this will be nil if the provided
+    # input is io-like. in this case it will be used directly in the 
+    # `spawn` options.
+    in_pipe = case input
+    when nil, String
+      Cmds.debug "input is a String or nil, creating pipe..."
+
+      in_pipe = Cmds::Pipe.new "INPUT", :in
+      spawn_opts[:in] = in_pipe.r
+
+      # don't buffer input
+      in_pipe.w.sync = true
+      in_pipe
+
+    else
+      Cmds.debug "input should be io-like, setting spawn opt.",
+        input: input
+      if input == $stdin
+        Cmds.debug "input is $stdin."
+      end
+      spawn_opts[:in] = input
+      nil
+
+    end # case input
+
+    # (possibly) create the output pipes.
+    # 
+    # `stream` can be told to send it's output to either:
+    # 
+    # 1.  a Proc that will invoked with each line.
+    # 2.  an io-like object that can be provided as `spawn`'s `:out` or 
+    #     `:err` options.
+    # 
+    # in case (1) a `Cmds::Pipe` wrapping read and write piped `IO` instances
+    # will be created and assigned to the relevant of `out_pipe` or `err_pipe`.
+    # 
+    # in case (2) the io-like object will be sent directly to `spawn` and
+    # the relevant `out_pipe` or `err_pipe` will be `nil`.
+    #
+    out_pipe, err_pipe = [
+      ["ERROR", :err],
+      ["OUTPUT", :out],
+    ].map do |name, sym|
+      Cmds.debug "looking at #{ name }..."
+      # see if hanlder.out or hanlder.err is a Proc
+      if handler.send(sym).is_a? Proc
+        Cmds.debug "#{ name } is a Proc, creating pipe..."
+        pipe = Cmds::Pipe.new name, sym
+        # the corresponding :out or :err option for spawn needs to be
+        # the pipe's write handle
+        spawn_opts[sym] = pipe.w
+        # return the pipe
+        pipe
+
+      else
+        Cmds.debug "#{ name } should be io-like, setting spawn opt.",
+          output: handler.send(sym)
+        spawn_opts[sym] = handler.send(sym)
+        # the pipe is nil!
+        nil
+      end
+    end # map outputs
+
+    Cmds.debug "spawning...",
+      cmd: cmd,
+      opts: spawn_opts
+
+    pid = Process.spawn cmd, spawn_opts
+
+    Cmds.debug "spawned.",
+      pid: pid
+
+    wait_thread = Process.detach pid
+    wait_thread[:name] = "WAIT"
+
+    Cmds.debug "wait thread created.",
+      thread: wait_thread
+
+    # close child ios if created
+    # the spawned process will read from in_pipe.r so we don't need it
+    in_pipe.r.close if in_pipe
+    # and we don't need to write to the output pipes, that will also happen
+    # in the spawned process
+    [out_pipe, err_pipe].each {|pipe| pipe.w.close if pipe}
+
+    # create threads to handle any pipes that were created
+
+    in_thread = if in_pipe
+      Thread.new do
+        Thread.current[:name] = in_pipe.name
+        Cmds.debug "thread started, writing input..."
+
+        in_pipe.w.write input unless input.nil?
+
+        Cmds.debug "write done, closing in_pipe.w..."
+        in_pipe.w.close
+
+        Cmds.debug "thread done."
+      end # Thread
+    end
+
+    out_thread, err_thread = [out_pipe, err_pipe].map do |pipe|
+      if pipe
+        Thread.new do
+          Thread.current[:name] = pipe.name
+          Cmds.debug "thread started"
+
+          loop do
+            Cmds.debug "blocking on gets..."
+            line = pipe.r.gets
+            if line.nil?
+              Cmds.debug "received nil, output done."
+            else
+              Cmds.debug <<-BLOCK.squish
+                received #{ line.bytesize } bytes, passing to handler.
+              BLOCK
+            end
+            handler.thread_send_line pipe.sym, line
+            break if line.nil?
+          end
+
+          Cmds.debug "reading done, closing pipe.r (unless already closed)..."
+          pipe.r.close unless pipe.r.closed?
+
+          Cmds.debug "thread done."
+        end # thread
+      end # if pipe
+    end # map threads
+
+    Cmds.debug "handing off main thread control to the handler..."
+    begin
+      handler.start
+
+      Cmds.debug "handler done."
+
+    ensure
+      # wait for the threads to complete
+      Cmds.debug "joining threads..."
+
+      [in_thread, out_thread, err_thread, wait_thread].each do |thread|
+        if thread
+          Cmds.debug "joining #{ thread[:name] } thread..."
+          thread.join
+        end
+      end
+
+      Cmds.debug "all threads done."
+    end
+
+    status = wait_thread.value.exitstatus
+    Cmds.debug "exit status: #{ status.inspect }"
+
+    Cmds.debug "checking @assert and exit status..."
+    if @assert && status != 0
+      # we don't necessarily have the err output, so we can't include it
+      # in the error message
+      msg = <<-BLOCK.squish
+        streamed command `#{ cmd }` exited with status #{ status }
+      BLOCK
+
+      raise SystemCallError.new msg, status
+    end
+
+    Cmds.debug "streaming completed."
+
+    return status
+  end # .spawn
+end # Cmds

data/lib/cmds/sugar.rb

@@ -3,270 +3,193 @@
 # global methods
 # ==============
 
-# proxies to `Cmds::capture`
-def Cmds *args, &block
-  Cmds.capture *args, &block
+# @see Cmds.capture
+def Cmds template, *args, **kwds, &input_block
+  Cmds.capture template, *args, **kwds, &input_block
 end
 
-# proxies to `Cmds::ok?`
-def Cmds? *args, &block
-  Cmds.ok? *args, &block
-end
 
-# proxies to `Cmds::assert`
-def Cmds! *args, &block
-  Cmds.assert *args, &block
+# @see Cmds.ok?
+def Cmds? template, *args, **kwds, &io_block
+  Cmds.ok? template, *args, **kwds, &io_block
 end
 
-class Cmds
-  # class methods
-  # =============
-
-  # create a new Cmd from template and subs and call it
-  # @return [Result]
-  def self.capture template, *subs, &input_block
-    new(template, options(subs, input_block)).capture
-  end
-
-  def self.ok? template, *subs, &input_block
-    new(template, options(subs, input_block)).ok?
-  end
 
-  def self.error? template, *subs, &input_block
-    new(template, options(subs, input_block)).error?
-  end
+# @see Cmds.assert
+def Cmds! template, *args, **kwds, &io_block
+  Cmds.assert template, *args, **kwds, &io_block
+end
 
-  def self.assert template, *subs, &input_block
-    new(
-      template,
-      options(subs, input_block).merge!(assert: true)
-    ).capture
-  end
 
+module Cmds
+  # create a new {Cmd} instance with the template and parameters and
+  # calls {Cmd#prepare}.
+  # 
+  # @param [String] template
+  #   ERB template parameters are rendered into to create the command string.
+  # 
+  # @param [Array<Object>] *args
+  #   positional parameters for rendering into the template.
+  # 
+  # @param [Hash{Symbol => Object}] **kwds
+  #   keyword parameters for rendering into the template.
+  # 
+  # @return [String]
+  #   rendered and formatted command string ready to be executed.
+  # 
+  def self.prepare template, *args, **kwds
+    Cmd.new(template).prepare *args, **kwds
+  end
+  
+  
+  # create a new {Cmd} from template with parameters and call {Cmds#capture}
+  # on it.
+  # 
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # 
+  # @param [#call] &input_block
+  #   optional block that returns a string or IO-like readable object to be
+  #   used as input for the execution.
+  # 
+  # @return [Result]
+  #   result with command string, exist status, stdout and stderr.
+  # 
+  def self.capture template, *args, **kwds, &input_block
+    Cmd.new(template).capture *args, **kwds, &input_block
+  end
+  
+  
+  # create a new {Cmd} from template with parameters and call {Cmd#ok?}
+  # on it.
+  # 
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &io_block (see Cmds.spawn)
+  # 
+  # @return [Result]
+  #   result with command string, exist status, stdout and stderr.
+  # 
+  def self.ok? template, *args, **kwds, &io_block
+    Cmd.new(template).ok? *args, **kwds, &io_block
+  end
+  
+  
+  def self.error? template, *args, **kwds, &io_block
+    Cmd.new(template).error? *args, **kwds, &io_block
+  end
+  
+  
+  # create a new {Cmd} and 
+  def self.assert template, *args, **kwds, &io_block
+    Cmd.new(template).capture(*args, **kwds, &io_block).assert
+  end
+  
+  
   def self.stream template, *subs, &input_block
-    Cmds.new(template).stream *subs, &input_block
+    Cmds::Cmd.new(template).stream *subs, &input_block
   end
-
+  
+  
   def self.stream! template, *subs, &input_block
-    Cmds.new(template, assert: true).stream *subs, &input_block
+    Cmds::Cmd.new(template, assert: true).stream *subs, &input_block
   end # ::stream!
 
-
-  # @api sugar
+  
+  # creates a new {Cmd}, captures and returns stdout
+  # (sugar for `Cmds.capture(template, *args, **kwds, &input_block).out`).
   #
-  # captures and returns stdout
-  # (sugar for `Cmds.capture(*template, *subs, &input_block).out`).
-  #
-  # @see .capture
-  # @see Result#out
+  # @see Cmd.out
   #
-  # @param template [String] see {.capture}.
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &input_block (see .capture)
   #
-  # @return [String] the command's stdout.
+  # @return [String]
+  #   the command's stdout.
   #
-  def self.out template, *subs, &input_block
-    capture(template, *subs, &input_block).out
+  def self.out template, *args, **kwds, &input_block
+    Cmd.new(template).out *args, **kwds, &input_block
   end
-
-
-  # @api sugar
+  
+  
+  # creates a new {Cmd}, captures and returns stdout. raises an error if the 
+  # command fails.
   #
-  # captures and returns stdout, raising an error if the command fails.
+  # @see Cmd.out!
   #
-  # @see .capture
-  # @see Result#out
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &input_block (see .capture)
   #
-  # @param template [String] see {.capture}.
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
+  # @return [String]
+  #   the command's stdout.
   #
-  # @return [String] the command's stdout.
+  # @raise [SystemCallError]
+  #   if the command fails (non-zero exit status).
   #
-  # @raise [SystemCallError] if the command fails (non-zero exit status).
-  #
-  def self.out! template, *subs, &input_block
-    Cmds.new(
-      template,
-      options(subs, input_block).merge!(assert: true),
-    ).capture.out
+  def self.out! template, *args, **kwds, &input_block
+    Cmd.new(template).out! *args, **kwds, &input_block
   end
-
-
-  # @api sugar
-  #
-  # captures and chomps stdout
-  # (sugar for `Cmds.out(*template, *subs, &input_block).chomp`).
+  
+  
+  # captures a new {Cmd}, captures and chomps stdout
+  # (sugar for `Cmds.out(template, *args, **kwds, &input_block).chomp`).
   #
   # @see .out
   #
-  # @param template [String] see {.capture}.
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &input_block (see .capture)
   #
-  # @return [String] the command's chomped stdout.
+  # @return [String]
+  #   the command's chomped stdout.
   #
-  def self.chomp template, *subs, &input_block
-    out(template, *subs, &input_block).chomp
+  def self.chomp template, *args, **kwds, &input_block
+    out(template, *args, **kwds, &input_block).chomp
   end
-
-
-  # @api sugar
-  #
+  
+  
   # captures and chomps stdout, raising an error if the command fails.
-  # (sugar for `Cmds.out!(*template, *subs, &input_block).chomp`).
+  # (sugar for `Cmds.out!(template, *args, **kwds, &input_block).chomp`).
   #
   # @see .out!
   #
-  # @param template [String] see {.capture}.
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &input_block (see .capture)
   #
-  # @return [String] the command's chomped stdout.
+  # @return [String]
+  #   the command's chomped stdout.
   #
-  # @raise [SystemCallError] if the command fails (non-zero exit status).
+  # @raise [SystemCallError]
+  #   if the command fails (non-zero exit status).
   #
-  def self.chomp! template, *subs, &input_block
-    out!(template, *subs, &input_block).chomp
+  def self.chomp! template, *args, **kwds, &input_block
+    out!(template, *args, **kwds, &input_block).chomp
   end
-
-
-  # @api sugar
-  #
+  
+  
   # captures and returns stderr
-  # (sugar for `Cmds.capture(template, *subs, &input_block).err`).
+  # (sugar for `Cmds.capture(template, *args, **kwds, &input_block).err`).
   #
   # @see .capture
-  # @see Result#err
-  #
-  # @param template [String] see {.capture}.
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @return [String] the command's stderr.
-  #
-  def self.err template, *subs, &input_block
-    capture(template, *subs, &input_block).err
-  end
-
-  # instance methods
-  # ================
-
-  alias_method :call, :capture
-
-  def ok?
-    stream == 0
-  end
-
-  def error?
-    stream != 0
-  end
-
-  # def assert
-  #   capture.raise_error
-  # end
-
-  def proxy
-    stream do |io|
-      io.in = $stdin
-    end
-  end
-
-
-  # @api sugar
-  #
-  # captures and returns stdout
-  # (sugar for `#capture(*subs, &input_block).out`).
-  #
-  # @see #capture
-  # @see Result#out
-  #
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @return [String] the command's stdout.
-  #
-  def out *subs, &input_block
-    capture(*subs, &input_block).out
-  end
-
-
-  # @api sugar
-  #
-  # captures and returns stdout
-  # (sugar for `#capture(*subs, &input_block).out`).
-  #
-  # @see #capture
-  # @see Result#out
-  #
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @return [String] the command's stdout.
-  #
-  # @raise [SystemCallError] if the command fails (non-zero exit status).
-  #
-  def out! *subs, &input_block
-    self.class.new(
-      @template,
-      merge_options(subs, input_block).merge!(assert: true),
-    ).capture.out
-  end
-
-
-  # @api sugar
   #
-  # captures and chomps stdout
-  # (sugar for `#out(*subs, &input_block).chomp`).
+  # @param template (see .prepare)
+  # @param *args (see .prepare)
+  # @param **kwds (see .prepare)
+  # @param &input_block (see .capture)
   #
-  # @see #out
+  # @return [String]
+  #   the command's stderr.
   #
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @return [String] the command's chomped stdout.
-  #
-  def chomp *subs, &input_block
-    out(*subs, &input_block).chomp
-  end
-
-
-  # @api sugar
-  #
-  # captures and chomps stdout, raising an error if the command failed.
-  # (sugar for `#out!(*subs, &input_block).chomp`).
-  #
-  # @see #capture
-  # @see Result#out
-  #
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @return [String] the command's chomped stdout.
-  #
-  # @raise [SystemCallError] if the command fails (non-zero exit status).
-  #
-  def chomp! *subs, &input_block
-    out!(*subs, &input_block).chomp
-  end
-
-
-  # @api sugar
-  #
-  # captures and returns stdout
-  # (sugar for `#capture(*subs, &input_block).err`).
-  #
-  # @param subs [Array] see {.capture}.
-  # @param input_block [Proc] see {.capture}.
-  #
-  # @see #capture
-  # @see Result#err
-  #
-  # @return [String] the command's stderr.
-  #
-  def err *subs, &input_block
-    capture(*subs, &input_block).err
+  def self.err template, *args, **kwds, &input_block
+    capture(template, *args, **kwds, &input_block).err
   end
-
-end # class Cmds
+end # Cmds