cmds 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec573a2d3357aa33be6e99e15cfbbf17208b5f7b
-  data.tar.gz: 3650ce87a15e971b126395e11e86063b7605312a
+  metadata.gz: 82780e4858c704d9607db8032e99818163e80220
+  data.tar.gz: e0ba46030000a9c252940a1a80beb1f528ea3a6c
 SHA512:
-  metadata.gz: 7a162d0e9dd3acd278e7c73274a13f14771f7c8dbd19f3bbd2427ac1830acab26930cb7daac1adb5030cbef0083fd94974cd4efb838a638bcdc26ad64e09fd35
-  data.tar.gz: dd7ad5d87fb29f2f3b36d22c8f440e6521c07df69f73a29a067910fa03bb8bd4b551623376802ea33995e7c3413a46af20878b2a4c63b49fc74edeeddf607f93
+  metadata.gz: 0c3bd920b4afeaaabc83d967aaaffbe7c24a084d2164532b741dbb96c0e03385452136ecfe3712069a716326d3725aab9a38ea5c387f9a043118235f0c16ab47
+  data.tar.gz: 4597c1e73ead17c16c850cd0d6043b0c3092c25499f858026f2ff3324975dafb0ce496f48e1eb2febd78a79308436cd5c0eaf8bedfd9e4e63d55634c497bb18f

data/cmds.gemspec

@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "pastel"
-  spec.add_development_dependency "yard"
+  spec.add_development_dependency "yard", "~> 0.9.9"
   spec.add_development_dependency "redcarpet"
+  spec.add_development_dependency 'github-markup'
 end

data/lib/cmds/capture.rb

@@ -0,0 +1,71 @@
+class Cmds
+  
+  # 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
+    
+    # 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 "configured input",
+      input: input
+    
+    # strings output will be concatenated onto
+    out = ''
+    err = ''
+
+    Cmds.debug "calling Cmds.spawn..."
+    
+    status = spawn(*args, **kwds) 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 last_prepared_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
+  
+end # class Cmds

data/lib/cmds/result.rb

@@ -2,7 +2,7 @@ require 'nrser/refinements'
 
 class Cmds
   # a simple data structure returned from calling {Cmds#capture} 
-  # on a {Cmd} instance.
+  # on a {Cmds} instance.
   # 
   # it contains the exit status code, standard output and standard error,
   # as well as the actual string command issued (after all substitutions).

data/lib/cmds/spawn.rb

@@ -262,4 +262,26 @@ class Cmds
 
     return status
   end # .spawn
+  
+  
+  protected
+  # ========================================================================
+    
+    # Internal method that simply passes through to {Cmds.spawn}, serving as 
+    # a hook point for subclasses.
+    # 
+    # Accepts and returns the same things as 
+    # 
+    def spawn *args, **kwds, &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 # #spawn
+    
+  # end protected
+  
+  
 end # Cmds

data/lib/cmds/stream.rb

@@ -11,17 +11,12 @@ class Cmds
   #   command exit status.
   # 
   def stream *args, **kwds, &io_block
-    Cmds.debug "entering Cmd#stream",
+    Cmds.debug "entering Cmds#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
+    spawn *args, **kwds, &io_block
   end # #stream
 
   # stream and raise an error if exit code is not 0.
@@ -35,16 +30,9 @@ class Cmds
   #   if exit status is not 0.
   # 
   def stream! *args, **kwds, &io_block
-    cmd = prepare(*args, **kwds)
+    status = stream *args, **kwds, &io_block
     
-    status = Cmds.spawn cmd,
-                        input: @input,
-                        # include env if mode is spawn argument
-                        env: (@env_mode == :spawn_arg ? @env : {}),
-                        chdir: @chdir,
-                        &io_block
-    
-    Cmds.check_status cmd, status
+    Cmds.check_status last_prepared_cmd, status
     
     status
   end # #stream!

data/lib/cmds/sugar.rb

@@ -22,8 +22,8 @@ end
 
 
 class Cmds
-  # create a new {Cmd} instance with the template and parameters and
-  # calls {Cmd#prepare}.
+  # create a new {Cmds} instance with the template and parameters and
+  # calls {Cmds#prepare}.
   # 
   # @param [String] template
   #   ERB template parameters are rendered into to create the command string.
@@ -42,7 +42,7 @@ class Cmds
   end
   
   
-  # create a new {Cmd} from template with parameters and call {Cmds#capture}
+  # create a new {Cmds} from template with parameters and call {Cmds#capture}
   # on it.
   # 
   # @param template (see .prepare)
@@ -61,7 +61,7 @@ class Cmds
   end
   
   
-  # create a new {Cmd} from template with parameters and call {Cmd#ok?}
+  # create a new {Cmds} from template with parameters and call {Cmd#ok?}
   # on it.
   # 
   # @param template (see .prepare)
@@ -82,7 +82,7 @@ class Cmds
   end
   
   
-  # create a new {Cmd} and 
+  # create a new {Cmds} and 
   def self.assert template, *args, **kwds, &io_block
     Cmds.new(template).capture(*args, **kwds, &io_block).assert
   end
@@ -98,7 +98,7 @@ class Cmds
   end # ::stream!
 
   
-  # creates a new {Cmd}, captures and returns stdout
+  # creates a new {Cmds}, captures and returns stdout
   # (sugar for `Cmds.capture(template, *args, **kwds, &input_block).out`).
   #
   # @see Cmd.out
@@ -116,7 +116,7 @@ class Cmds
   end
   
   
-  # creates a new {Cmd}, captures and returns stdout. raises an error if the 
+  # creates a new {Cmds}, captures and returns stdout. raises an error if the 
   # command fails.
   #
   # @see Cmd.out!
@@ -137,7 +137,7 @@ class Cmds
   end
   
   
-  # captures a new {Cmd}, captures and chomps stdout
+  # captures a new {Cmds}, captures and chomps stdout
   # (sugar for `Cmds.out(template, *args, **kwds, &input_block).chomp`).
   #
   # @see .out

data/lib/cmds/util.rb

@@ -41,11 +41,22 @@ class Cmds
         esc value.to_s
       end
     }.join ' '
-  end # ::tokenize
+  end # .tokenize
   
-  # formats a command string 
+  
+  # Formats a command string.
+  # 
+  # @param [String] string
+  #   Command string to format.
+  # 
+  # @param [nil, :squish, :pretty, #call] with
+  #   How to format the command string.
+  # 
   def self.format string, with = :squish
     case with
+    when nil
+      string
+      
     when :squish
       NRSER.squish string
       
@@ -55,7 +66,8 @@ class Cmds
     else
       with.call string
     end
-  end
+  end # .format
+  
   
   def self.pretty_format string
     string = string.gsub(/\n(\s*\n)+\n/, "\n\n")

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
 class Cmds
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

data/lib/cmds.rb

@@ -11,13 +11,16 @@ require 'cmds/shell_eruby'
 require 'cmds/result'
 require 'cmds/sugar'
 require 'cmds/stream'
+require 'cmds/capture'
 
 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.
   # 
@@ -27,9 +30,11 @@ class Cmds
   # {#stream}, etc.) accept `*args`, which will be appended to
   # these values to create the final array for rendering.   
   # 
-  # @return [Array<Object>]   
+  # @return [Array<Object>]
+  # 
   attr_reader :args
-
+  
+  
   # base/common keyword parameters to render into the command template.
   # 
   # defaults to `{}`.
@@ -39,7 +44,9 @@ class Cmds
   # 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.
@@ -49,21 +56,37 @@ class Cmds
   # 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.
+  
+  # Environment variables to set for command execution.
   # 
   # defaults to `{}`.
   # 
   # @return [Hash{String | Symbol => String}]
+  # 
   attr_reader :env
+  
+  
+  # How environment variables will be set for command execution - inline at
+  # the top of the command, or passed to `Process.spawn` as an argument.
+  # 
+  # See the `inline`
+  # 
+  # @return [:inline, :spawn_arg]
+  # 
+  attr_reader :env_mode
+  
 
   # format specifier symbol:
   # 
@@ -78,64 +101,161 @@ class Cmds
   attr_reader :format
 
 
-  # directory to run the command in.
-  # 
-  # @return [nil | String]
-  attr_reader :chdir
-
-
-  # construct a Cmd.
+  # Optional directory to run the command in, set by the `:chdir` option
+  # in {Cmds#initialize}.
   # 
-  # @param [String] template
-  #   sets the {#template} attribute.
+  # @return [nil]
+  #   If the command will not change directory to run (default behavior).
   # 
-  # @param [Hash] opts
-  # 
-  # @option opts [Array<Object>] :args
-  #   sets the {#args} attribute.
-  # 
-  # @option opts [Hash{Symbol => Object}] :kwds
-  #   sets the {#kwds} attribute.
+  # @return [String | Pathname]
+  #   If the command will change directory to run.
+  #     
+  attr_reader :chdir
+  
+  
+  
+  # The results of the last time {Cmds#prepare} was called on the instance.
   # 
-  # @option opts [String | #read] :input
-  #   sets the {#input} attribute.
+  # A little bit funky, I know, but it turns out to be quite useful.
   # 
-  # @option opts [Hash{Symbol => String}] :env
-  #   sets the {#env} attribute.
+  # @return [nil]
+  #   If {Cmds#prepare} has never been called.
   # 
-  # @option opts [:squish, :pretty] :format
-  #   sets the {#format} attribute.
+  # @return [String]
+  #   If {Cmds#prepare} has been called.
   # 
-  # @option opts [nil | String] :chdir
-  #   sets the {#chdir} attribute.
+  attr_reader :last_prepared_cmd
+  
+
+
+  # Construct a `Cmds` instance.
   # 
-  def initialize template, **opts
+  # @param [String] template
+  #   String template to use when creating the command string to send to the 
+  #   shell via {#prepare}.
+  #   
+  #   Allows ERB (positional and keyword), `%s` (positional) and `%{name}` 
+  #   (keyword) placeholders.
+  #   
+  #   Available as the {#template} attribute.
+  # 
+  # @param [Array<Object>] args:
+  #   Positional arguments to interpolate into the template on {#prepare}.
+  #   
+  #   Available as the {#args} attribute.
+  # 
+  # @param [Boolean] assert:
+  #   When `true`, execution will raise an error if the command doesn't exit 
+  #   successfully (if the command exits with any status other than `0`).
+  #   
+  #   Available as the {#assert} attribute. 
+  # 
+  # @param [nil | String | Pathname] chdir:
+  #   Optional directory to change into when executing.
+  #   
+  #   Available as the {#chdir} attribute.
+  # 
+  # @param [Hash{(String | Symbol) => String}] env:
+  #   Hash of environment variables to set when executing the command.
+  #   
+  #   Available as the {#env} attribute.
+  # 
+  # @param [:inline, :spawn_arg] env_mode:
+  #   Controls how the env vars are added to the command.
+  #   
+  #   -   `:inline` adds them to the top of the prepared string. This is nice
+  #       if you want do print the command out and paste it into a terminal.
+  #       This is the default.
+  #   
+  #   -   `:spawn_arg` passes them as an argument to `Process.spawn`. In this 
+  #       case they will not be included in the output of {#prepare} 
+  #       (or {#render}).
+  #   
+  #   Available as the {#env_mode} attribute.
+  # 
+  # @param [nil, :squish, :pretty, #call] format:
+  #   Dictates how to format the rendered template string before passing
+  #   off to the shell.
+  #   
+  #   This feature lets you write templates in a more relaxed
+  #   manner without `\` line-endings all over the place.
+  #   
+  #   -   `nil` performs **no formatting at all*.
+  #       
+  #   -   `:squish` reduces any consecutive whitespace (including newlines) to 
+  #       a single space. This is the default.
+  #   
+  #   -   `:pretty` tries to keep the general formatting but make it acceptable 
+  #       to the shell by adding `\` at the end of lines. See 
+  #       {Cmds.pretty_format}.
+  #       
+  #   -   An object that responds to `#call` will be called with the command
+  #       string as it's only argument for custom formatting.
+  #   
+  #   See {Cmds.format} for more details.
+  #   
+  #   Available as the {#format} attribute.
+  # 
+  # @param [nil | String | #read] input:
+  #   Input to send to the command on execution. Can be a string or an
+  #   `IO`-like object that responds to `#read`.
+  #   
+  #   Available as the {#input} attribute.
+  # 
+  # @param [Hash{Symbol => Object}] kwds:
+  #   Keyword arguments to shell escape and interpolate into the template on
+  #   {#prepare}.
+  #   
+  #   Available as the {#kwds} attribute.
+  # 
+  def initialize  template,
+                  args: [],
+                  assert: false,
+                  chdir: nil,
+                  env: {},
+                  env_mode: :inline,
+                  format: :squish,
+                  input: nil,
+                  kwds: {}
     Cmds.debug "Cmd constructing...",
       template: template,
-      opts: opts
+      opts: {
+        args: args,
+        kwds: kwds,
+        input: input,
+        assert: assert,
+        env: env,
+        format: format,
+        env_mode: env_mode,
+        chdir: chdir,
+      }
 
     @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
+    @args = args.freeze
+    @kwds = kwds.freeze
+    @input = input
+    @assert = assert
+    @env = env.freeze
+    @format = format
+    @env_mode = env_mode
+    @chdir = chdir
+    
+    # An internal cache of the last result of calling {#prepare}, or `nil` if
+    # {#prepare} has never been called. Kinda funky but ends up being useful.
+    @last_prepared_cmd = nil
   end # #initialize
 
 
-  # returns a new {Cmd} with the parameters and input merged in
+  # returns a new {Cmds} 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,
+    self.class.new template, {
+      args: (self.args + args),
+      kwds: (self.kwds.merge kwds),
+      input: (input_block ? input_block.call : self.input),
+      assert: self.assert,
+      env: self.env,
+      format: self.format,
+      chdir: self.chdir,
     }
   end
 
@@ -154,12 +274,12 @@ class Cmds
   #   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)
+    context = Cmds::ERBContext.new((self.args + args), self.kwds.merge(kwds))
+    erb = Cmds::ShellEruby.new Cmds.replace_shortcuts(self.template)
     rendered = NRSER.dedent erb.result(context.get_binding)
     
-    if @env_mode == :inline && !@env.empty?
-      rendered = @env.sort_by {|name, value|
+    if self.env_mode == :inline && !self.env.empty?
+      rendered = self.env.sort_by {|name, value|
         name
       }.map {|name, value|
         "#{ name }=#{ Cmds.esc value }"
@@ -179,86 +299,8 @@ class Cmds
   #   the prepared command string.
   # 
   def prepare *args, **kwds
-    Cmds.format render(*args, **kwds), @format
+    @last_prepared_cmd = Cmds.format render(*args, **kwds), self.format
   end # #prepare
-  
-
-  # 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cmds
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-11 00:00:00.000000000 Z
+date: 2017-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nrser
@@ -96,6 +96,20 @@ dependencies:
         version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.9
+- !ruby/object:Gem::Dependency
+  name: redcarpet
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: redcarpet
+  name: github-markup
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -142,6 +156,7 @@ files:
 - bin/rspec
 - cmds.gemspec
 - lib/cmds.rb
+- lib/cmds/capture.rb
 - lib/cmds/debug.rb
 - lib/cmds/erb_context.rb
 - lib/cmds/io_handler.rb