cmds 0.0.3 → 0.0.4

data/lib/cmds/stream.rb

@@ -0,0 +1,239 @@
+class Cmds
+  # stream inputs and/or outputs
+  # 
+  # originally inspired by
+  # 
+  # https://nickcharlton.net/posts/ruby-subprocesses-with-stdout-stderr-streams.html
+  # 
+  # with major modifications from looking at Ruby's open3 module.
+  #
+  def stream *subs, &input_block
+    Cmds.debug "entering Cmds#stream",
+      subs: subs,
+      input_block: input_block
+
+    # use `merge_options` to get the args and kwds (we will take custom
+    # care of input in _stream)
+    options = merge_options subs, nil
+
+    # build the command string
+    cmd = Cmds.sub @template, options[:args], options[:kwds]
+
+    # call the internal function
+    really_stream cmd, options, &input_block
+  end
+
+  private
+
+    # do the actual work...
+    def really_stream cmd, options, &input_block
+      Cmds.debug "entering Cmds#really_stream",
+        cmd: cmd,
+        options: options,
+        input_block: input_block
+
+      # create the handler that will be yielded to the input block
+      handler = IOHandler.new
+
+      # handle input
+      
+      # default to the instance variable
+      input = @input
+
+      # if a block was provided, it might provide overriding input
+      if input_block
+        case input_block.arity
+        when 0
+          # when the input block takes no arguments it returns the input
+          input = input_block.call
+        when 1
+          # when the input block takes one argument, give it the handler and
+          # ignore the return value
+          input_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 NRSER.squish <<-BLOCK
+            provided input block must have arity 0 or 1
+          BLOCK
+        end # case input.arity
+      end # if input_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 = 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 NRSER.squish <<-BLOCK
+                  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 = NRSER.squish <<-BLOCK
+          streamed command `#{ cmd }` exited with status #{ status }
+        BLOCK
+
+        raise SystemCallError.new msg, status
+      end
+
+      Cmds.debug "streaming completed."
+
+      return status
+    end #really_stream
+
+  # end private
+end

data/lib/cmds/sugar.rb

@@ -0,0 +1,76 @@
+# convenience methods
+
+# global methods
+# ==============
+
+# proxies to `Cmds::capture`
+def Cmds *args, &block
+  Cmds.capture *args, &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
+end
+
+class Cmds
+  # class methods
+  # =============
+
+  # create a new Cmd from template and subs and call it
+  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
+
+  def self.assert template, *subs, &input_block
+    new(
+      template,
+      options(subs, input_block).merge!(assert: true)
+    ).capture
+  end
+
+  def self.stream template, *subs, &input_block
+    Cmds.new(template).stream *subs, &input_block
+  end
+
+  def self.stream! template, *subs, &input_block
+    Cmds.new(template, assert: true).stream *subs, &input_block
+  end # ::stream!
+
+  # 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
+
+end # class Cmds

data/lib/cmds/util.rb

@@ -0,0 +1,254 @@
+# util functions
+class Cmds
+  # class methods
+  # =============
+
+  # shortcut for Shellwords.escape
+  # 
+  # also makes it easier to change or customize or whatever
+  def self.esc str
+    Shellwords.escape str
+  end
+
+  # escape option hash.
+  #
+  # this is only useful for the two common option styles: 
+  #
+  # -   single character keys become `-<char> <value>`
+  #
+  #         {x: 1}    => "-x 1"
+  # 
+  # -   longer keys become `--<key>=<value>` options
+  # 
+  #         {blah: 2} => "--blah=2"
+  #
+  # if you have something else, you're going to have to just put it in
+  # the cmd itself, like:
+  # 
+  #     Cmds "blah -assholeOptionOn:%{s}", "ok"
+  # 
+  # or whatever similar shit said command requires.
+  #
+  # however, if the value is an Array, it will repeat the option for each
+  # value:
+  # 
+  #     {x:     [1, 2, 3]} => "-x 1 -x 2 -x 3"
+  #     {blah:  [1, 2, 3]} => "--blah=1 --blah=2 --blah=3"
+  # 
+  # i can't think of any right now, but i swear i've seen commands that take
+  # opts that way.
+  # 
+  def self.expand_option_hash hash
+    hash.map {|key, values|
+      # keys need to be strings
+      key = key.to_s unless key.is_a? String
+
+      [key, values]
+
+    }.sort {|(key_a, values_a), (key_b, values_b)|
+      # sort by the (now string) keys
+      key_a <=> key_b
+
+    }.map {|key, values|
+      # for simplicity's sake, treat all values like an array
+      values = [values] unless values.is_a? Array
+
+      # keys of length 1 expand to `-x v` form
+      expanded = if key.length == 1
+        values.map {|value|
+          if value.nil?
+            "-#{ esc key }"
+          else
+            "-#{ esc key } #{ esc value}"
+          end
+        }
+
+      # longer keys expand to `--key=value` form
+      else
+        values.map {|value|
+          if value.nil?
+            "--#{ esc key }"
+          else
+            "--#{ esc key }=#{ esc value }"
+          end
+        }
+      end
+    }.flatten.join ' '
+  end # ::expand_option_hash
+
+  # expand one of the substitutions
+  def self.expand_sub sub
+    case sub
+    when nil
+      # nil is just an empty string, NOT an empty string bash token
+      ''
+    when Hash
+      expand_option_hash sub
+    else
+      esc sub.to_s
+    end
+  end # ::expand_sub
+
+  # substitute values into a command, escaping them for the shell and
+  # offering convenient expansions for some structures.
+  # 
+  # `cmd` is a string that can be substituted via ruby's `%` operator, like
+  # 
+  #     "git diff %s"
+  # 
+  # for positional substitution, or 
+  # 
+  #     "git diff %{path}"
+  # 
+  # for keyword substitution.
+  # 
+  # `subs` is either:
+  # 
+  # -   an Array when `cmd` has positional placeholders
+  # -   a Hash when `cmd` has keyword placeholders.
+  # 
+  # the elements of the `subs` array or values of the `subs` hash are:
+  # 
+  # -   strings that are substituted into `cmd` after being escaped:
+  #     
+  #         sub "git diff %{path}", path: "some path/to somewhere"
+  #         # => 'git diff some\ path/to\ somewhere'
+  # 
+  # -   hashes that are expanded into options:
+  #     
+  #         sub "psql %{opts} %{database} < %{filepath}",
+  #           database: "blah",
+  #           filepath: "/where ever/it/is.psql",
+  #           opts: {
+  #             username: "bingo bob",
+  #             host: "localhost",
+  #             port: 12345,
+  #           }
+  #         # => 'psql --host=localhost --port=12345 --username=bingo\ bob blah < /where\ ever/it/is.psql'
+  # 
+  def self.sub cmd, args = [], kwds = {}
+    raise TypeError.new("args must be an Array") unless args.is_a? Array
+    raise TypeError.new("kwds must be an Hash") unless kwds.is_a? Hash
+
+    context = ERBContext.new(args, kwds)
+    erb = ShellEruby.new(replace_shortcuts cmd)
+
+    NRSER.squish erb.result(context.get_binding)
+  end # ::sub
+
+  def self.options subs, input_block
+    args = []
+    kwds = {}
+    input = input_block.nil? ? nil : input_block.call
+
+    case subs.length
+    when 0
+      # nothing to do
+    when 1
+      # can either be a hash, which is interpreted as a keywords,
+      # or an array, which is interpreted as positional arguments
+      case subs[0]
+      when Hash
+        kwds = subs[0]
+
+      when Array
+        args = subs[0]
+
+      else
+        raise TypeError.new NRSER.squish <<-BLOCK
+          first *subs arg must be Array or Hash, not #{ subs[0].inspect }
+        BLOCK
+      end
+
+    when 2
+      # first arg needs to be an array, second a hash
+      unless subs[0].is_a? Array
+        raise TypeError.new NRSER.squish <<-BLOCK
+          first *subs arg needs to be an array, not #{ subs[0].inspect }
+        BLOCK
+      end
+
+      unless subs[1].is_a? Hash
+        raise TypeError.new NRSER.squish <<-BLOCK
+          second *subs arg needs to be a Hash, not #{ subs[1].inspect }
+        BLOCK
+      end
+
+      args, kwds = subs
+    else
+      raise ArgumentError.new NRSER.squish <<-BLOCK
+        must provide one or two *subs arguments, received #{ 1 + subs.length }
+      BLOCK
+    end
+
+    return {
+      args: args,
+      kwds: kwds,
+      input: input,
+    }
+  end # ::options
+
+  def self.replace_shortcuts template
+    template
+      .gsub(
+        # %s => <%= arg %>
+        /(?<=\A|[[:space:]])\%s(?=\Z|[[:space:]])/,
+        '<%= arg %>'
+      )
+      .gsub(
+        # %%s => %s (escpaing)
+        /(?<=\A|[[:space:]])(\%+)\%s(?=\Z|[[:space:]])/,
+        '\1s'
+      )
+      .gsub(
+        # %{key} => <%= key %>, %{key?} => <%= key? %>
+        /(?<=\A|[[:space:]])\%\{([a-zA-Z_]+\??)\}(?=\Z|[[:space:]])/,
+        '<%= \1 %>'
+      )
+      .gsub(
+        # %%{key} => %{key}, %%{key?} => %{key?} (escpaing)
+        /(?<=\A|[[:space:]])(\%+)\%\{([a-zA-Z_]+\??)\}(?=\Z|[[:space:]])/,
+        '\1{\2}\3'
+      )
+      .gsub(
+        # %<key>s => <%= key %>, %<key?>s => <%= key? %>
+        /(?<=\A|[[:space:]])\%\<([a-zA-Z_]+\??)\>s(?=\Z|[[:space:]])/,
+        '<%= \1 %>'
+      )
+      .gsub(
+        # %%<key>s => %<key>s, %%<key?>s => %<key?>s (escaping)
+        /(?<=\A|[[:space:]])(\%+)\%\<([a-zA-Z_]+\??)\>s(?=\Z|[[:space:]])/,
+        '\1<\2>s'
+      )
+  end # ::replace_shortcuts
+
+  # instance methods
+  # ================
+
+  # returns a new `Cmds` with the subs and input block merged in
+  def curry *subs, &input_block
+    self.class.new @template, merge_options(subs, input_block)
+  end
+
+  private
+
+    # merges options already present on the object with options
+    # provided via subs and input_block and returns a new options
+    # Hash
+    def merge_options subs, input_block
+      # get the options present in the arguments
+      options = Cmds.options subs, input_block
+      # the new args are created by appending the provided args to the
+      # existing ones
+      options[:args] = @args + options[:args]
+      # the new kwds are created by merging the provided kwds into the
+      # exising ones (new values override previous)
+      options[:kwds] = @kwds.merge options[:kwds]
+      # if there is input present via the provided block, it is used.
+      # otherwise, previous input is used, which may be `nil`
+      options[:input] ||= @input
+      return options
+    end # #merge_options
+
+  # end private
+end # class Cmds

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
 class Cmds
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end