cmds 0.1.5 → 0.2.0

data/lib/cmds.rb

@@ -1,3 +1,408 @@
+# deps
+require 'nrser'
+
+# project
 require 'cmds/version'
-require 'cmds/cmd'
+require 'cmds/debug'
+require 'cmds/util'
+require 'cmds/spawn'
+require 'cmds/erb_context'
+require 'cmds/shell_eruby'
+require 'cmds/result'
 require 'cmds/sugar'
+
+class Cmds
+  # ERB stirng template (with Cmds-specific extensions) for the command.
+  # 
+  # @return [String]
+  attr_reader :template
+
+  # base/common positional parameters to render into the command
+  # template.
+  # 
+  # defaults to `[]`.
+  # 
+  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#stream}, etc.) accept `*args`, which will be appended to
+  # these values to create the final array for rendering.   
+  # 
+  # @return [Array<Object>]   
+  attr_reader :args
+
+  # base/common keyword parameters to render into the command template.
+  # 
+  # defaults to `{}`.
+  # 
+  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#stream}, etc.) accept `**kwds`, which will be merged on top of
+  # these values to create the final hash for rendering.
+  # 
+  # @return [Hash{Symbol => Object}]
+  attr_reader :kwds
+
+  # string or readable IO-like object to use as default input to the
+  # command.
+  # 
+  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#stream}, etc.) accept an optional block that will override this
+  # value if present.
+  # 
+  # @return [String | #read]
+  attr_reader :input
+
+  # if `true`, will execution will raise an error on non-zero exit code.
+  # 
+  # defaults to `false`.
+  # 
+  # @return [Boolean]
+  attr_reader :assert
+
+  # environment variables to set for command execution.
+  # 
+  # defaults to `{}`.
+  # 
+  # @return [Hash{String | Symbol => String}]
+  attr_reader :env
+
+  # format specifier symbol:
+  # 
+  # -   `:squish`
+  #     -   collapse rendered command string to one line.
+  # -   `:pretty`
+  #     -   clean up and backslash suffix line endings.
+  # 
+  # defaults to `:squish`.
+  # 
+  # @return [:squish | :pretty]
+  attr_reader :format
+
+
+  # directory to run the command in.
+  # 
+  # @return [nil | String]
+  attr_reader :chdir
+
+
+  # construct a Cmd.
+  # 
+  # @param [String] template
+  #   sets the {#template} attribute.
+  # 
+  # @param [Hash] opts
+  # 
+  # @option opts [Array<Object>] :args
+  #   sets the {#args} attribute.
+  # 
+  # @option opts [Hash{Symbol => Object}] :kwds
+  #   sets the {#kwds} attribute.
+  # 
+  # @option opts [String | #read] :input
+  #   sets the {#input} attribute.
+  # 
+  # @option opts [Hash{Symbol => String}] :env
+  #   sets the {#env} attribute.
+  # 
+  # @option opts [:squish, :pretty] :format
+  #   sets the {#format} attribute.
+  # 
+  # @option opts [nil | String] :chdir
+  #   sets the {#chdir} attribute.
+  # 
+  def initialize template, **opts
+    Cmds.debug "Cmd constructing...",
+      template: template,
+      opts: opts
+
+    @template = template
+    @args = (opts[:args] || []).freeze
+    @kwds = (opts[:kwds] || {}).freeze
+    @input = opts[:input] || nil
+    @assert = opts[:assert] || false
+    @env = (opts[:env] || {}).freeze
+    @format = opts[:format] || :squish
+    @env_mode = opts[:env_mode] || :inline
+    @chdir = opts[:chdir] || nil
+  end # #initialize
+
+
+  # returns a new {Cmd} with the parameters and input merged in
+  def curry *args, **kwds, &input_block
+    self.class.new @template, {
+      args: (@args + args),
+      kwds: (@kwds.merge kwds),
+      input: (input ? input.call : @input),
+      assert: @assert,
+      env: @env,
+      format: @format,
+      chdir: @chdir,
+    }
+  end
+
+
+  # render parameters into `@template`.
+  # 
+  # @note the returned string is **not** formatted for shell execution.
+  #       Cmds passes this string through {Cmds.format} before execution,
+  #       which addresses newlines in the rendered string through "squishing"
+  #       everything down to one line or adding `\` to line ends.
+  # 
+  # @param args (see #capture)
+  # @param kwds (see #capture)
+  # 
+  # @return [String]
+  #   the rendered command string.
+  # 
+  def render *args, **kwds
+    context = Cmds::ERBContext.new((@args + args), @kwds.merge(kwds))
+    erb = Cmds::ShellEruby.new Cmds.replace_shortcuts(@template)
+    rendered = NRSER.dedent erb.result(context.get_binding)
+    
+    if @env_mode == :inline && !@env.empty?
+      rendered = @env.sort_by {|name, value|
+        name
+      }.map {|name, value|
+        "#{ name }=#{ Cmds.esc value }"
+      }.join("\n\n") + "\n\n" + rendered
+    end
+    
+    rendered
+  end
+
+
+  # prepare a shell-safe command string for execution.
+  # 
+  # @param args (see #capture)
+  # @param kwds (see #capture)
+  # 
+  # @return [String]
+  #   the prepared command string.
+  # 
+  def prepare *args, **kwds
+    Cmds.format render(*args, **kwds), @format
+  end # #prepare
+
+
+  def stream *args, **kwds, &io_block
+    Cmds.debug "entering Cmd#stream",
+      args: args,
+      kwds: kwds,
+      io_block: io_block
+    
+    Cmds.spawn  prepare(*args, **kwds),
+                input: @input,
+                # include env if mode is spawn argument
+                env: (@env_mode == :spawn_arg ? @env : {}),
+                chdir: @chdir,
+                &io_block
+  end # #stream
+
+
+  # executes the command and returns a {Cmds::Result} with the captured
+  # outputs.
+  # 
+  # @param [Array<Object>] args
+  #   positional parameters to append to those in `@args` for rendering 
+  #   into the command string.
+  # 
+  # @param [Hash{Symbol => Object}] kwds
+  #   keyword parameters that override those in `@kwds` for rendering
+  #   into the command string.
+  # 
+  # @param [#call] input_block
+  #   optional block that returns a string or readable object to override
+  #   `@input`.
+  # 
+  # @return [Cmds::Result]
+  #   result of execution with command string, status, stdout and stderr.
+  # 
+  def capture *args, **kwds, &input_block
+    Cmds.debug "entering Cmds#capture",
+      args: args,
+      kwds: kwds,
+      input: input
+    
+    # prepare the command string
+    cmd = prepare *args, **kwds
+    
+    # extract input from block via `call` if one is provided,
+    # otherwise default to instance variable (which may be `nil`)
+    input = input_block.nil? ? @input : input_block.call
+    
+    Cmds.debug "prepared",
+      cmd: cmd,
+      input: input
+    
+    # strings output will be concatenated onto
+    out = ''
+    err = ''
+
+    Cmds.debug "calling Cmds.spawn..."
+    
+    status = Cmds.spawn(
+      cmd,
+      # include env if mode is spawn argument
+      env: (@env_mode == :spawn_arg ? @env : {}),
+      chdir: @chdir
+    ) do |io|
+      # send the input to stream, which sends it to spawn
+      io.in = input
+
+      # and concat the output lines as they come in
+      io.on_out do |line|
+        out += line
+      end
+
+      io.on_err do |line|
+        err += line
+      end
+    end
+    
+    Cmds.debug "Cmds.spawn completed",
+      status: status
+
+    # build a Result
+    # result = Cmds::Result.new cmd, status, out_reader.value, err_reader.value
+    result = Cmds::Result.new cmd, status, out, err
+
+    # tell the Result to assert if the Cmds has been told to, which will
+    # raise a SystemCallError with the exit status if it was non-zero
+    result.assert if @assert
+
+    return result
+  end # #capture
+
+
+  alias_method :call, :capture
+
+
+  # execute command and return `true` if it exited successfully.
+  # 
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  # 
+  # @return [Boolean]
+  #   `true` if exit code was `0`.
+  # 
+  def ok? *args, **kwds, &io_block
+    stream(*args, **kwds, &io_block) == 0
+  end
+
+
+  # execute command and return `true` if it failed.
+  # 
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  # 
+  # @return [Boolean]
+  #   `true` if exit code was not `0`.
+  # 
+  def error? *args, **kwds, &io_block
+    stream(*args, **kwds, &io_block) != 0
+  end
+
+
+  # def assert
+  #   capture.raise_error
+  # end
+
+
+  def proxy
+    stream do |io|
+      io.in = $stdin
+    end
+  end
+
+
+  # captures and returns stdout
+  # (sugar for `#capture(*args, **kwds, &input_block).out`).
+  #
+  # @see #capture
+  # @see Result#out
+  #
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  #
+  # @return [String]
+  #   the command's stdout.
+  #
+  def out *args, **kwds, &input_block
+    capture(*args, **kwds, &input_block).out
+  end
+
+
+  # captures and returns stdout
+  # (sugar for `#capture(*args, **kwds, &input_block).out`).
+  #
+  # @see #capture
+  # @see Result#out
+  #
+  # @param args [Array] see {.capture}.
+  # @param kwds [Proc] see {.capture}.
+  #
+  # @return [String] the command's stdout.
+  #
+  # @raise [SystemCallError] if the command fails (non-zero exit status).
+  #
+  def out! *args, **kwds, &input
+    capture(*args, **kwds, &input).assert.out
+  end
+
+
+  # captures and chomps stdout
+  # (sugar for `#out(*subs, &input_block).chomp`).
+  #
+  # @see #out
+  #
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  #
+  # @return [String]
+  #   the command's chomped stdout.
+  #
+  def chomp *args, **kwds, &input_block
+    out(*args, **kwds, &input_block).chomp
+  end
+
+
+  # captures and chomps stdout, raising an error if the command failed.
+  # (sugar for `#out!(*subs, &input_block).chomp`).
+  #
+  # @see #capture
+  # @see Result#out
+  #
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  #
+  # @return [String]
+  #   the command's chomped stdout.
+  #
+  # @raise [SystemCallError]
+  #   if the command fails (non-zero exit status).
+  #
+  def chomp! *args, **kwds, &input
+    out!(*args, **kwds, &input).chomp
+  end
+
+
+  # captures and returns stdout
+  # (sugar for `#capture(*subs, &input_block).err`).
+  #
+  # @param *args (see #capture)
+  # @param **kwds (see #capture)
+  # @param &input_block (see #capture)
+  # 
+  # @see #capture
+  # @see Result#err
+  #
+  # @return [String]
+  #   the command's stderr.
+  #
+  def err *args, **kwds, &input_block
+    capture(*args, **kwds, &input_block).err
+  end
+end # Cmds

data/scratch/proxy.rb

@@ -1,5 +1,5 @@
 require 'cmds'
 
 Cmds.enable_debug do
-  Cmds::Cmd.new("./test/questions.rb").proxy
+  Cmds.new("./test/questions.rb").proxy
 end

data/spec/cmds/assert_spec.rb

@@ -11,6 +11,6 @@ describe "Cmds::assert" do
 
   it "should be chainable when the command is ok" do
     expect( Cmds!("echo hey").out ).to eq "hey\n"
-    expect( Cmds::Cmd.new("echo hey").capture.assert.out ).to eq "hey\n"
+    expect( Cmds.new("echo hey").capture.assert.out ).to eq "hey\n"
   end
 end # Cmds::run

data/spec/cmds/capture_spec.rb

@@ -3,13 +3,13 @@ require 'spec_helper'
 describe "Cmds::capture" do
   it "captures stdout" do
     expect(
-      Cmds::Cmd.new(%{ruby -e '$stdout.puts "hey"'}).capture.out
+      Cmds.new(%{ruby -e '$stdout.puts "hey"'}).capture.out
     ).to eq "hey\n"
   end
 
   it "captures stderr" do
     expect(
-      Cmds::Cmd.new(%{ruby -e '$stderr.puts "ho"'}).capture.err
+      Cmds.new(%{ruby -e '$stderr.puts "ho"'}).capture.err
     ).to eq "ho\n"
   end
 
@@ -42,8 +42,8 @@ describe "Cmds::capture" do
   end # context echo_cmd.rb 'hello world!'
 
   it "is reusable" do
-    args_cmd = Cmds::Cmd.new "./test/echo_cmd.rb <%= arg %>"
-    kwds_cmd = Cmds::Cmd.new "./test/echo_cmd.rb <%= s %>"
+    args_cmd = Cmds.new "./test/echo_cmd.rb <%= arg %>"
+    kwds_cmd = Cmds.new "./test/echo_cmd.rb <%= s %>"
 
     args = ["arg one", "arg two", "arg three"]
 
@@ -70,12 +70,12 @@ describe "Cmds::capture" do
     }
 
     it "accepts input via options" do
-      cmd = Cmds::Cmd.new(ECHO_CMD, input: input)
+      cmd = Cmds.new(ECHO_CMD, input: input)
       expect( echo_cmd_stdin cmd.capture ).to eq input
     end
 
     it "accepts input via block" do
-      cmd = Cmds::Cmd.new ECHO_CMD
+      cmd = Cmds.new ECHO_CMD
       expect( echo_cmd_stdin cmd.capture { input } ).to eq input
     end
 
@@ -84,7 +84,7 @@ describe "Cmds::capture" do
         input = f.read
         f.rewind
 
-        cmd = Cmds::Cmd.new ECHO_CMD
+        cmd = Cmds.new ECHO_CMD
         expect( echo_cmd_stdin cmd.capture { f } ).to eq input
       end
     end

data/spec/cmds/chomp_spec.rb

@@ -34,12 +34,12 @@ end # Cmds.chomp!
 
 describe "Cmds#chomp" do
   it "gets echo output" do
-    expect( Cmds::Cmd.new("echo %s").chomp "hey there!" ).to eq "hey there!"
+    expect( Cmds.new("echo %s").chomp "hey there!" ).to eq "hey there!"
   end
 
   it "reads input" do
     expect(
-      Cmds::Cmd.new("ruby -e %{script}").chomp(script: "puts STDIN.read") {
+      Cmds.new("ruby -e %{script}").chomp(script: "puts STDIN.read") {
         "hey there!"
       }
     ).to eq "hey there!"
@@ -48,18 +48,18 @@ end # Cmds#chomp
 
 describe "Cmds#chomp!" do
   it "gets echo output" do
-    expect( Cmds::Cmd.new("echo %s").chomp! "hey there!" ).to eq "hey there!"
+    expect( Cmds.new("echo %s").chomp! "hey there!" ).to eq "hey there!"
   end
 
   it "reads input" do
     expect(
-      Cmds::Cmd.new("ruby -e %{script}").chomp!(script: "puts STDIN.read") {
+      Cmds.new("ruby -e %{script}").chomp!(script: "puts STDIN.read") {
         "hey there!"
       }
     ).to eq "hey there!"
   end
 
   it "errors when the command fails" do
-    expect { Cmds::Cmd.new("false").chomp! }.to raise_error SystemCallError
+    expect { Cmds.new("false").chomp! }.to raise_error SystemCallError
   end
 end # Cmds#chomp!

data/spec/cmds/curry_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe "Cmds::curry" do
   it "currys" do
-    base = Cmds::Cmd.new "#{ ECHO_CMD } <%= x %> <%= y %>"
+    base = Cmds.new "#{ ECHO_CMD } <%= x %> <%= y %>"
 
     x1 = base.curry x: 1
     x2 = base.curry x: 2

data/spec/cmds/env_spec.rb

@@ -4,17 +4,17 @@ describe "Cmds ENV vars" do
   r_echo_cmd = %{ruby -e "puts ENV['BLAH']"}
   
   it "sets basic (path-like) string ENV var" do
-    cmd = Cmds::Cmd.new r_echo_cmd, env: {BLAH: "x:y:z"}
+    cmd = Cmds.new r_echo_cmd, env: {BLAH: "x:y:z"}
     expect(cmd.chomp!).to eq "x:y:z"
   end
   
   it "sets a string with spaces in it correctly" do
-    cmd = Cmds::Cmd.new r_echo_cmd, env: {BLAH: "hey there"}
+    cmd = Cmds.new r_echo_cmd, env: {BLAH: "hey there"}
     expect(cmd.chomp!).to eq "hey there"
   end
   
   it "accepts string keys" do
-    cmd = Cmds::Cmd.new r_echo_cmd, env: {
+    cmd = Cmds.new r_echo_cmd, env: {
       'BLAH' => [
         "/usr/local/bin",
         "/usr/bin",

data/spec/cmds/err_spec.rb

@@ -17,13 +17,13 @@ end # Cmds.err
 describe "Cmds#err" do
   it "gets echo error output" do
     expect( 
-      Cmds::Cmd.new("echo %s 1>&2").err "hey there!"
+      Cmds.new("echo %s 1>&2").err "hey there!"
     ).to eq "hey there!\n"
   end
 
   it "reads input" do
     expect(
-      Cmds::Cmd.new("ruby -e %{script}").
+      Cmds.new("ruby -e %{script}").
         err(script: "$stderr.puts STDIN.read") {
           "hey there!"
         }

data/spec/cmds/error_spec.rb

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 describe "Cmds.error?" do
   it "works through instance method" do
-    expect( Cmds::Cmd.new("true").error? ).to be false
-    expect( Cmds::Cmd.new("false").error? ).to be true
+    expect( Cmds.new("true").error? ).to be false
+    expect( Cmds.new("false").error? ).to be true
   end
 
   it "works through class method" do

data/spec/cmds/ok_spec.rb

@@ -2,8 +2,8 @@ require 'spec_helper'
 
 describe "Cmds::ok?" do
   it "works through instance method" do
-    expect( Cmds::Cmd.new("true").ok? ).to be true
-    expect( Cmds::Cmd.new("false").ok? ).to be false
+    expect( Cmds.new("true").ok? ).to be true
+    expect( Cmds.new("false").ok? ).to be false
   end
 
   it "works through class method" do

data/spec/cmds/out_spec.rb

@@ -34,12 +34,12 @@ end # Cmds.out!
 
 describe "Cmds#out" do
   it "gets echo output" do
-    expect( Cmds::Cmd.new("echo %s").out "hey there!" ).to eq "hey there!\n"
+    expect( Cmds.new("echo %s").out "hey there!" ).to eq "hey there!\n"
   end
 
   it "reads input" do
     expect(
-      Cmds::Cmd.new("ruby -e %{script}").out(script: "puts STDIN.read") {
+      Cmds.new("ruby -e %{script}").out(script: "puts STDIN.read") {
         "hey there!"
       }
     ).to eq "hey there!\n"
@@ -48,18 +48,18 @@ end # Cmds#out
 
 describe "Cmds#out!" do
   it "gets echo output" do
-    expect( Cmds::Cmd.new("echo %s").out! "hey there!" ).to eq "hey there!\n"
+    expect( Cmds.new("echo %s").out! "hey there!" ).to eq "hey there!\n"
   end
 
   it "reads input" do
     expect(
-      Cmds::Cmd.new("ruby -e %{script}").out!(script: "puts STDIN.read") {
+      Cmds.new("ruby -e %{script}").out!(script: "puts STDIN.read") {
         "hey there!"
       }
     ).to eq "hey there!\n"
   end
 
   it "errors when the command fails" do
-    expect { Cmds::Cmd.new("false").out! }.to raise_error SystemCallError
+    expect { Cmds.new("false").out! }.to raise_error SystemCallError
   end
 end # Cmds#out!

data/spec/cmds/prepare_spec.rb

@@ -17,8 +17,8 @@ describe "Cmds.prepare" do
   it "should work with a keyword substitutions with String keys" do
     expect(
       # NOTE  since we use **kwds in #prepare which only accepts symbol keys,
-      #       have to load kwds with string keys in through Cmd.new
-      Cmds::Cmd.new(
+      #       have to load kwds with string keys in through Cmds.new
+      Cmds.new(
         "psql <%= opts %> <%= database %> < <%= filepath %>", {
           kwds: {
             'database' => "blah",
@@ -199,4 +199,12 @@ describe "Cmds.prepare" do
       end
     end # % proceeded by =
   end # shortcuts
+  
+  context "tokenize multiple args as shell list" do
+    it "should expand args as space-separated list" do
+      expect(
+        Cmds.prepare "git add <%= *args %>", "x", "y", "z"
+      ).to eq "git add x y z"
+    end
+  end
 end # ::sub

data/spec/cmds/stream_spec.rb

@@ -5,7 +5,7 @@ describe "Cmds::stream" do
 
   it "writes to $stdout and $stderr by default" do
     out, err = temp_outs do
-      Cmds::Cmd.new('./test/tick.rb <%= times %>').stream times: times
+      Cmds.new('./test/tick.rb <%= times %>').stream times: times
     end
 
     expect(out).to eq times.times.map{|_| "#{_}\n"}.join
@@ -15,7 +15,7 @@ describe "Cmds::stream" do
   it "handles writes in blocks" do
     out_count = 0
     err_count = 0
-    Cmds::Cmd.new('./test/tick.rb <%= times %>').stream(times: times) do |io|
+    Cmds.new('./test/tick.rb <%= times %>').stream(times: times) do |io|
       io.on_out do |line|
         out_count += 1
       end
@@ -32,7 +32,7 @@ describe "Cmds::stream" do
     it "accepts string value input from a block" do
 
       out, err = temp_outs do
-        Cmds::Cmd.new("wc -l").stream do
+        Cmds.new("wc -l").stream do
           <<-BLOCK
             one
             two
@@ -47,7 +47,7 @@ describe "Cmds::stream" do
 
     it "accepts stream value input from a block" do
       out, err = temp_outs do
-        Cmds::Cmd.new("wc -l").stream do
+        Cmds.new("wc -l").stream do
           File.open "./test/lines.txt"
         end
       end

data/spec/cmds_spec.rb

@@ -9,7 +9,7 @@ describe Cmds do
     expect(Cmds.chomp! "echo 'here'").to eq 'here'
     
     expect(
-      Cmds::Cmd.new("head %{opts} %s").
+      Cmds.new("head %{opts} %s").
         prepare("/dev/random", opts: {c: 64})
     ).to eq "head -c 64 /dev/random"