cmds 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1dd522e09d442b565bd299965feb5568ac5d830e
-  data.tar.gz: 901dde67d7c5f77571539ab2ae8ea7a3b67c9d5d
+  metadata.gz: fbffca50ed0a5b832d53b5a3f5713734ce5ecd9c
+  data.tar.gz: c3dbd1396df4501c412f6b5102aebf77fa3dc4e6
 SHA512:
-  metadata.gz: 7c5eea2077d11d90db033f8fd98ce2fb8782ac554427676087f1917fdf2f402ff6836089ab03a1e274783108b1acee9a49185e68fc7c46996b0db973c46a9b49
-  data.tar.gz: 85f29ade7132c8c083c94b4e7939aed8be3fe7a1d2153fadff115f581f9d32a43e5a5d5cfcdfe277efc6f641fd2290294e89dce2f5c27c18da6f7b27fc810b50
+  metadata.gz: 2aa6e19cf215cbc820b3f0aece36bc3fe2925a915ef59ba5825d2319cae6d7db6ce8621cad0a3ef9f6132d2037ae77e59162d6ee01a6eccd5068fd775edbc221
+  data.tar.gz: 3d6f7af1c264532734b17a83362619978f8a856476a4cf18f1f38f43077e40185dbd3af3b67e5f83ec7bfec4dde013446e2259789e05a4dc2aa5d9b73ca5d63e

data/README.md

@@ -244,7 +244,7 @@ though keys with those names may be accessed directly via `@kwds.fetch(key)` and
 to test for a key's presence or optionally include a value, append `?` to the method name:
 
 ```
-c = Cmds.new <<-BLOCK
+c = Cmds::Cmd.new <<-BLOCK
   defaults
   <% if current_host? %>
     -currentHost <%= current_host %>
@@ -350,7 +350,7 @@ Cmds.sub "50%" # => "50%"
 ## reuse commands
 
 ```
-playbook = Cmds.new "ansible-playbook -i %{inventory} %{playbook}"
+playbook = Cmds::Cmd.new "ansible-playbook -i %{inventory} %{playbook}"
 playbook.call inventory: "./hosts", playbook: "blah.yml"
 ```
 
@@ -376,7 +376,7 @@ NEEDS TEST
 can be accomplished with reuse and currying stuff
 
 ```
-playbook = Cmds.new "ansible-playbook -i %{inventory} %{playbook}", inventory: "inventory/dev"
+playbook = Cmds::Cmd.new "ansible-playbook -i %{inventory} %{playbook}", inventory: "inventory/dev"
 
 # run setup.yml on the development hosts
 playbook.call playbook: "setup.yml"
@@ -390,7 +390,7 @@ prod_playbook.call playbook: "setup.yml", inventory: "inventory/prod"
 ## input
 
 ```
-c = Cmds.new("wc", input: "blah blah blah).call
+c = Cmds::Cmd.new("wc", input: "blah blah blah).call
 ```
 
 

data/Rakefile

@@ -5,6 +5,11 @@ require 'pp'
 require 'tempfile'
 
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
 
 Bundler.require
 
@@ -52,14 +57,14 @@ namespace :debug do
   end
 
   task :proxy => :conf do
-    Cmds.new("./test/questions.rb").proxy
+    Cmds::Cmd.new("./test/questions.rb").proxy
   end
 
   namespace :capture do
     desc "capture with io-like input with debugging enabled"
     task :io_input => :conf do
       File.open "./test/lines.txt" do |f|
-        Cmds.new("./test/echo_cmd.rb", input: f).capture
+        Cmds::Cmd.new("./test/echo_cmd.rb", input: f).capture
       end
     end
   end # ns capture

data/bin/rake

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+bundle exec rake "$@"

data/bin/rspec

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+bundle exec rspec "$@"

data/cmds.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 

data/lib/cmds/cmd.rb

@@ -0,0 +1,376 @@
+require 'cmds/debug'
+require 'cmds/util'
+require 'cmds/spawn'
+require 'cmds/erb_context'
+require 'cmds/shell_eruby'
+require 'cmds/result'
+
+module Cmds
+  # a command consisting of a template, base/common parameters and input,
+  # and options.
+  # 
+  class Cmd
+    # 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{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
+    
+    
+    # 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.
+    # 
+    def initialize template, **opts
+      Cmds.debug "Cmd constructing...",
+        template: template,
+        opts: opts
+
+      @template = template
+      @args = opts[:args] || []
+      @kwds = opts[:kwds] || {}
+      @input = opts[:input] || nil
+      @assert = opts[:assert] || false
+      @env = opts[:env] || {}
+      @format = opts[:format] || :squish
+    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,
+      }
+    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)
+
+      erb.result(context.get_binding)
+    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, &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 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 # Cmd
+end # Cmds

data/lib/cmds/debug.rb

@@ -1,7 +1,7 @@
 require 'logger'
 
 # debug logging stuff
-class Cmds
+module Cmds
 
   module Debug
     # constants
@@ -98,4 +98,4 @@ class Cmds
     return unless Debug.on?
     Debug.logger.debug Debug.format(msg, values)
   end
-end # class Cmds
+end # module Cmds

data/lib/cmds/erb_context.rb

@@ -1,4 +1,4 @@
-class Cmds
+module Cmds
   class ERBContext < BasicObject
     def initialize args, kwds
       @args = args
@@ -10,7 +10,7 @@ class Cmds
       if args.empty? && block.nil?
         if sym.to_s[-1] == '?'
           key = sym.to_s[0...-1].to_sym
-          # allow `false` to be ommited as well as missing and `nil`
+          # allow `false` to be omitted as well as missing and `nil`
           # by returning `nil` if the value is "false-y"
           @kwds[key] if @kwds[key]
         else
@@ -29,4 +29,4 @@ class Cmds
       @args.fetch(@arg_index).tap {@arg_index += 1}
     end
   end # end ERBContext
-end # class Cmds
+end # module Cmds

data/lib/cmds/io_handler.rb

@@ -1,4 +1,4 @@
-class Cmds
+module Cmds
   class IOHandler
     attr_accessor :in, :out, :err
 
@@ -73,4 +73,4 @@ class Cmds
 
     # end private
   end # end IOHandler
-end # class Cmds
+end # module Cmds

data/lib/cmds/pipe.rb

@@ -1,4 +1,4 @@
-class Cmds
+module Cmds
   # stupid little wrapper around IO.pipe that can have some extra info
   # attached to it
   class Pipe

data/lib/cmds/result.rb

@@ -1,6 +1,10 @@
-class Cmds
-  # a {Result} is a simple data structure returned from calling {Cmds#capture} 
-  # on a {Cmds} instance.
+require 'nrser/refinements'
+
+using NRSER
+
+module Cmds
+  # a simple data structure returned from calling {Cmds#capture} 
+  # on a {Cmd} instance.
   # 
   # it contains the exit status code, standard output and standard error,
   # as well as the actual string command issued (after all substitutions).
@@ -52,7 +56,7 @@ class Cmds
     #
     def assert
       if error?
-        msg = NRSER.squish <<-BLOCK
+        msg = <<-BLOCK.squish
           command `#{ @cmd }` exited with status #{ @status }
           and stderr #{ err.inspect }
         BLOCK
@@ -61,5 +65,5 @@ class Cmds
       end
       self
     end # raise_error
-  end
-end # class Cmds
+  end # Result
+end # Cmds

data/lib/cmds/shell_eruby.rb

@@ -1,6 +1,6 @@
 require 'erubis'
 
-class Cmds
+module Cmds
   # extension of Erubis' EscapedEruby (which auto-escapes `<%= %>` and
   # leaves `<%== %>` raw) that calls `Cmds.expand_sub` on the value
   class ShellEruby < Erubis::EscapedEruby
@@ -8,4 +8,4 @@ class Cmds
       "::Cmds.expand_sub(#{code.strip})"
     end
   end
-end # class Cmds
+end # module Cmds