cmds 0.2.4 → 0.2.5

data/cmds.gemspec

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # coding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'cmds/version'
@@ -17,18 +19,51 @@ Gem::Specification.new do |spec|
   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"]
-
-  spec.add_dependency 'nrser', '>= 0.0.17'
-  spec.add_dependency 'erubis', '~> 2.7'
-
-  spec.add_development_dependency "bundler", "~> 1.5"
+  
+  
+  # Dependencies
+  # ============================================================================
+  
+  # Runtime Dependencies
+  # ----------------------------------------------------------------------------
+  
+  # Mu guns
+  spec.add_dependency             "nrser",          '~> 0.1', ">= 0.1.1"
+  
+  # ERB replacement with more features
+  # 
+  # Allows custom auto-escaping, which allows us to shell quote when rendering
+  # values into command templates.
+  # 
+  spec.add_dependency             'erubis',         '~> 2.7'
+  
+  
+  # Development Dependencies
+  # ----------------------------------------------------------------------------
+  
+  # You've probably heard of Bundler. I like Bundler.
+  spec.add_development_dependency "bundler",        "~> 1.5"
+  
+  # And you've probably hear of Rake. I don't like Rake.
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
+  
+  # For coloring debug logs. Want to get rid of it when I finally get around to
+  # fixing up logging on config in NRSER and can just use that.
   spec.add_development_dependency "pastel"
-  spec.add_development_dependency "yard", "~> 0.9.9"
-  spec.add_development_dependency "redcarpet"
-  spec.add_development_dependency 'github-markup'
   
-  # A better REPL
-  spec.add_development_dependency 'pry'
+  # Testing with `rspec`
+  spec.add_development_dependency "rspec",          '~> 3.7'
+  
+  # Doc site generation with `yard`
+  spec.add_development_dependency "yard",           '~> 0.9.12'
+  
+  # These, along with `//.yardopts` config, are *supposed to* result in
+  # rendering markdown files and doc comments using
+  # GitHub-Flavored Markdown (GFM), though I'm not sure if it's totally working
+  spec.add_development_dependency "redcarpet",      '~> 3.4'
+  spec.add_development_dependency "github-markup",  '~> 1.6'
+  
+  # Nicer REPL experience
+  spec.add_development_dependency "pry",            '~> 0.10.4'
+  
 end

data/lib/cmds.rb

@@ -1,7 +1,16 @@
-# deps
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
+require 'pathname'
+
+# Deps
+# -----------------------------------------------------------------------
 require 'nrser'
 
-# project
+# Project / Package
+# -----------------------------------------------------------------------
 require 'cmds/version'
 require 'cmds/debug'
 require 'cmds/util'
@@ -13,7 +22,25 @@ require 'cmds/sugar'
 require 'cmds/stream'
 require 'cmds/capture'
 
+
+# Definitions
+# =======================================================================
+
 class Cmds
+  
+  # Constants
+  # ============================================================================
+  
+  # Absolute, expanded path to the gem's root directory.
+  # 
+  # @return [Pathname]
+  # 
+  ROOT = ( Pathname.new(__FILE__).dirname / '..' ).expand_path
+  
+  
+  # Attributes
+  # ============================================================================
+  
   # ERB stirng template (with Cmds-specific extensions) for the command.
   # 
   # @return [String]
@@ -26,9 +53,9 @@ class Cmds
   # 
   # defaults to `[]`.
   # 
-  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#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.   
+  # these values to create the final array for rendering.
   # 
   # @return [Array<Object>]
   # 
@@ -39,7 +66,7 @@ class Cmds
   # 
   # defaults to `{}`.
   # 
-  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#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.
   # 
@@ -51,7 +78,7 @@ class Cmds
   # string or readable IO-like object to use as default input to the
   # command.
   # 
-  # {#prepare} and the methods that invoke it (like {#capture}, 
+  # {#prepare} and the methods that invoke it (like {#capture},
   # {#stream}, etc.) accept an optional block that will override this
   # value if present.
   # 
@@ -113,7 +140,6 @@ class Cmds
   attr_reader :chdir
   
   
-  
   # The results of the last time {Cmds#prepare} was called on the instance.
   # 
   # A little bit funky, I know, but it turns out to be quite useful.
@@ -126,15 +152,17 @@ class Cmds
   # 
   attr_reader :last_prepared_cmd
   
-
-
+  
+  # Constructor
+  # ============================================================================
+  
   # Construct a `Cmds` instance.
   # 
   # @param [String] template
-  #   String template to use when creating the command string to send to the 
+  #   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}` 
+  #   Allows ERB (positional and keyword), `%s` (positional) and `%{name}`
   #   (keyword) placeholders.
   #   
   #   Available as the {#template} attribute.
@@ -145,10 +173,10 @@ class Cmds
   #   Available as the {#args} attribute.
   # 
   # @param [Boolean] assert:
-  #   When `true`, execution will raise an error if the command doesn't exit 
+  #   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. 
+  #   Available as the {#assert} attribute.
   # 
   # @param [nil | String | Pathname] chdir:
   #   Optional directory to change into when executing.
@@ -167,8 +195,8 @@ class Cmds
   #       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} 
+  #   -   `: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.
@@ -182,11 +210,11 @@ class Cmds
   #   
   #   -   `nil` performs **no formatting at all*.
   #       
-  #   -   `:squish` reduces any consecutive whitespace (including newlines) to 
+  #   -   `: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 
+  #   -   `: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
@@ -226,7 +254,14 @@ class Cmds
     # {#prepare} has never been called. Kinda funky but ends up being useful.
     @last_prepared_cmd = nil
   end # #initialize
-
+  
+  
+  # Instance Methods
+  # ============================================================================
+  # 
+  # That ended up here. There are many more topically organized in
+  # `//lib/cmds/*.rb` files.
+  # 
 
   # returns a new {Cmds} with the parameters and input merged in
   def curry *args, **kwds, &input_block
@@ -432,4 +467,4 @@ class Cmds
   
   # @!endgroup Execution Instance Methods
   
-end # Cmds
+end # Cmds

data/lib/cmds/io_handler.rb

@@ -3,11 +3,20 @@ class Cmds
     attr_accessor :in, :out, :err
 
     def initialize
-      @queue = Queue.new
       @in = nil
       @out = $stdout
       @err = $stderr
     end
+    
+    def out= value
+      value = value.to_s if value.is_a? Pathname
+      @out = value
+    end
+    
+    def err= value
+      value = value.to_s if value.is_a? Pathname
+      @err = value
+    end
 
     def on_out &block
       @out = block
@@ -32,6 +41,10 @@ class Cmds
     end
 
     def start
+      # Initialize a thread-safe queue for passing output from the IO threads
+      # back to the main thread
+      @queue = Queue.new
+      
       # if out is a proc, it's not done
       out_done = ! @out.is_a?(Proc)
       # same for err
@@ -73,4 +86,4 @@ class Cmds
 
     # end private
   end # end IOHandler
-end # class Cmds
+end # class Cmds

data/lib/cmds/spawn.rb

@@ -1,26 +1,51 @@
-# stdlib
+##
+# Handle the actual spawning of child processes via {Process.spawn}
+# 
+# These methods are the low-level core of the library. Everything ends up here
+# to actually execute a command, but users should not need to call them
+# directly in most cases.
+##
+
+# Requirements
+# =======================================================================
+
+# Stdlib
+# -----------------------------------------------------------------------
 require 'open3'
 require 'thread'
 
-# deps
+# Deps
+# -----------------------------------------------------------------------
 require 'nrser'
-require 'nrser/refinements'
 
-# project
+# Project / Package
+# -----------------------------------------------------------------------
 require 'cmds/pipe'
 require 'cmds/io_handler'
 
+
+# Refinements
+# =======================================================================
+
+using NRSER
+
+
+# Definitions
+# =======================================================================
+
 class Cmds
+  # @!group Spawn Methods
+  
   # Low-level static method to spawn and stream inputs and/or outputs using
   # threads.
   # 
   # This is the core execution functionality of the whole library - everything
-  # end up here.
+  # ends up here.
   # 
-  # **WARNING** - This method runs the `cmd` string **AS IS** - no escaping, 
-  # formatting, interpolation, etc. are done at this point.
+  # **_WARNING - This method runs the `cmd` string AS IS - no escaping,
+  # formatting, interpolation, etc. are done at this point._**
   # 
-  # The whole rest of the library is built on top of this method to provide 
+  # The whole rest of the library is built on top of this method to provide
   # that stuff, and if you're using this library, you probably want to use that
   # stuff.
   # 
@@ -31,7 +56,9 @@ class Cmds
   # 
   # https://nickcharlton.net/posts/ruby-subprocesses-with-stdout-stderr-streams.html
   # 
-  # with major modifications from looking at Ruby's open3 module.
+  # with major modifications from looking at Ruby's [open3][] module.
+  # 
+  # [open3]: https://ruby-doc.org/stdlib/libdoc/open3/rdoc/Open3.html
   # 
   # At the end of the day ends up calling `Process.spawn`.
   # 
@@ -39,13 +66,6 @@ class Cmds
   #   **SHELL-READY** command string. This is important - whatever you feed in
   #   here will be run **AS IS** - no escaping, formatting, etc.
   # 
-  # @param [nil | String | #read] input
-  #   String or readable input, or `nil` (meaning no input).
-  #   
-  #   Allows {Cmds} instances can pass their `@input` instance variable.
-  #   
-  #   Don't provide input here and via `io_block`.
-  # 
   # @param [Hash{(Symbol | String) => Object}] env
   #   Hash of `ENV` vars to provide for the command.
   #   
@@ -55,10 +75,23 @@ class Cmds
   #   Pretty much you want to have everything be strings or symbols for this
   #   to make any sense but we're not checking shit at the moment.
   #   
-  #   If the {Cmds#env_mode} is `:inline` it should have already prefixed 
-  #   `cmd` with the definitions and not provide this keyword (or provide 
+  #   If the {Cmds#env_mode} is `:inline` it should have already prefixed
+  #   `cmd` with the definitions and not provide this keyword (or provide
   #   `{}`).
   # 
+  # @param [nil | String | #read] input
+  #   String or readable input, or `nil` (meaning no input).
+  #   
+  #   Allows {Cmds} instances can pass their `@input` instance variable.
+  #   
+  #   Don't provide input here and via `io_block`.
+  # 
+  # @param [Hash<Symbol, Object>] **spawn_opts
+  #   Any additional options are passed as the [options][Process.spawn options]
+  #   to {Process.spawn}
+  #   
+  #   [Process.spawn options]: http://ruby-doc.org/core/Process.html#method-c-spawn
+  # 
   # @param [#call & (#arity ∈ {0, 1})] &io_block
   #   Optional block to handle io. Behavior depends on arity:
   #   
@@ -83,15 +116,20 @@ class Cmds
   def self.spawn  cmd,
                   env: {},
                   input: nil,
-                  chdir: nil,
+                  **spawn_opts,
                   &io_block
     Cmds.debug "entering Cmds#spawn",
       cmd: cmd,
       env: env,
       input: input,
-      chdir: chdir,
+      spawn_opts: spawn_opts,
       io_block: io_block
     
+    # Process.spawn doesn't like a `nil` chdir
+    if spawn_opts.key?( :chdir ) && spawn_opts[:chdir].nil?
+      spawn_opts.delete :chdir
+    end
+    
     # create the handler that will be yielded to the input block
     handler = Cmds::IOHandler.new
 
@@ -99,7 +137,7 @@ class Cmds
     # 
     # if a block was provided it overrides the `input` argument.
     # 
-    if io_block      
+    if io_block
       case io_block.arity
       when 0
         # when the input block takes no arguments it returns the input
@@ -137,17 +175,11 @@ class Cmds
       end # case io_block.arity
     end # if io_block
 
-    # hash of options that will be passed to `spawn`
-    spawn_opts = {}
-    
-    # add chdir if provided
-    spawn_opts[:chdir] = chdir if chdir
-
     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 
+    # input is io-like. in this case it will be used directly in the
     # `spawn` options.
     in_pipe = case input
     when nil, String
@@ -176,7 +208,7 @@ class Cmds
     # `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 
+    # 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
@@ -190,8 +222,11 @@ class Cmds
       ["OUTPUT", :out],
     ].map do |name, sym|
       Cmds.debug "looking at #{ name }..."
+      
+      dest = handler.public_send sym
+      
       # see if hanlder.out or hanlder.err is a Proc
-      if handler.send(sym).is_a? Proc
+      if dest.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
@@ -202,8 +237,8 @@ class Cmds
 
       else
         Cmds.debug "#{ name } should be io-like, setting spawn opt.",
-          output: handler.send(sym)
-        spawn_opts[sym] = handler.send(sym)
+          output: dest
+        spawn_opts[sym] = dest
         # the pipe is nil!
         nil
       end
@@ -321,7 +356,7 @@ class Cmds
   protected
   # ========================================================================
     
-    # Internal method that simply passes through to {Cmds.spawn}, serving as 
+    # Internal method that simply passes through to {Cmds.spawn}, serving as
     # a hook point for subclasses.
     # 
     # Accepts and returns the same things as {Cmds#stream}.
@@ -335,10 +370,11 @@ class Cmds
                   # include env if mode is spawn argument
                   env: (env_mode == :spawn_arg ? env : {}),
                   chdir: chdir,
+                  unsetenv_others: !!@unsetenv_others,
                   &io_block
     end # #spawn
     
   # end protected
   
   
-end # Cmds
+end # Cmds