cmds 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 78e95949457351a76889d9559cace8e0d6357027
-  data.tar.gz: 1741db7b86690a11676165ccf6941696a24a63c5
+  metadata.gz: 844e8c090bc1bd1fdd4c2196bb879c329497138d
+  data.tar.gz: e2c403e462e1f37fe2a8114101942c6ed5352bae
 SHA512:
-  metadata.gz: 74d33994938b16b3fc3c33c4ef915e21d729efb50d80f8c303329a7d0513f382a9c29093bdb4c1deb719833b81476389444e2e65922a6249103a254c4482d8e8
-  data.tar.gz: de650778601f8e6c1ed8faa751edc532badf978c281111c8d7e937635f1a699d1b6e265dc11ce5788e2a736f4e871fb9ebdeaee6d441f09be05616c93c7f872a
+  metadata.gz: cb6158b6334ac66d4497619010d8d9557abf4a5ebea68d5325c100f83b49e732289ed39105133166426867cc4a3da6e6284cadba4e82f6715ccb89f1a1065057
+  data.tar.gz: b24a5986c2825e9ff8c5e7f518cf713c49b3ffa93dac464f2de1ce02625a8e02c8d635fe7c321e270b46c714beb78045a7e9612c5d8f9697324c33361d47d9c2

data/lib/cmds/spawn.rb

@@ -11,51 +11,87 @@ require 'cmds/pipe'
 require 'cmds/io_handler'
 
 class Cmds
-  # internal core function to spawn and stream inputs and/or outputs using
+  # Low-level static method to spawn and stream inputs and/or outputs using
   # threads.
   # 
-  # originally inspired by
+  # This is the core execution functionality of the whole library - everything
+  # end up here.
+  # 
+  # **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 
+  # that stuff, and if you're using this library, you probably want to use that
+  # stuff.
+  # 
+  # You should not need to use this method directly unless you are extending
+  # the library's functionality.
+  # 
+  # Originally inspired by
   # 
   # https://nickcharlton.net/posts/ruby-subprocesses-with-stdout-stderr-streams.html
   # 
   # with major modifications from looking at Ruby's open3 module.
   # 
+  # At the end of the day ends up calling `Process.spawn`.
+  # 
   # @param [String] cmd
-  #   shell-ready command string.
+  #   **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. here so that Cmds instances can pass their
-  #   `@input` instance variable -- `&io_block` overrides it.
+  #   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
-  #   blah
+  # @param [Hash{(Symbol | String) => Object}] env
+  #   Hash of `ENV` vars to provide for the command.
+  #   
+  #   We convert symbol keys to strings, but other than that just pass it
+  #   through to `Process.spawn`, which I think will `#to_s` everything.
+  #   
+  #   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 
+  #   `{}`).
   # 
   # @param [#call & (#arity ∈ {0, 1})] &io_block
-  #   optional block to handle io. behavior depends on arity:
+  #   Optional block to handle io. Behavior depends on arity:
   #   
-  #   -   arity `0`
-  #       -   block is called and expected to return an object
+  #   -   Arity `0`
+  #       -   Block is called and expected to return an object
   #           suitable for input (`nil`, `String` or `IO`-like).
-  #   -   arity `1`
-  #       -   block is called with the {Cmds::IOHandler} instance for the
+  #   -   Arity `1`
+  #       -   Block is called with the {Cmds::IOHandler} instance for the
   #           execution, which it can use to handle input and outputs.
+  #   
+  #   Don't provide input here and via `input` keyword arg.
   # 
   # @return [Fixnum]
-  #   command exit status.
+  #   Command exit status.
+  # 
+  # @raise [ArgumentError]
+  #   If `&io_block` has arity greater than 1.
   # 
   # @raise [ArgumentError]
-  #   if `&io_block` has arity greater than 1.
+  #   If input is provided via the `input` keyword arg and the `io_block`.
   # 
-  def self.spawn cmd, **opts, &io_block
+  def self.spawn  cmd,
+                  env: {},
+                  input: nil,
+                  chdir: nil,
+                  &io_block
     Cmds.debug "entering Cmds#spawn",
       cmd: cmd,
-      opts: opts,
+      env: env,
+      input: input,
+      chdir: chdir,
       io_block: io_block
     
-    env = opts[:env] || {}
-    input = opts[:input]
-    chdir = opts[:chdir]
-
     # create the handler that will be yielded to the input block
     handler = Cmds::IOHandler.new
 
@@ -63,18 +99,36 @@ 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
+        
+        # Check that `:input` kwd wasn't provided.
+        unless input.nil?
+          raise ArgumentError,
+            "Don't call Cmds.spawn with `:input` keyword arg and a block"
+        end
+        
         input = io_block.call
+        
       when 1
         # when the input block takes one argument, give it the handler and
         # ignore the return value
         io_block.call handler
 
         # if input was assigned to the handler in the block, use it as input
-        input = handler.in unless handler.in.nil?
+        unless handler.in.nil?
+          
+          # Check that `:input` kwd wasn't provided.
+          unless input.nil?
+            raise ArgumentError,
+              "Don't call Cmds.spawn with `:input` keyword arg and a block"
+          end
+          
+          input = handler.in
+        end
+        
       else
         # bad block provided
         raise ArgumentError.new NRSER.squish <<-BLOCK
@@ -270,7 +324,10 @@ class Cmds
     # Internal method that simply passes through to {Cmds.spawn}, serving as 
     # a hook point for subclasses.
     # 
-    # Accepts and returns the same things as 
+    # Accepts and returns the same things as {Cmds#stream}.
+    # 
+    # @param (see Cmds#stream)
+    # @return (see Cmds#stream)
     # 
     def spawn *args, **kwds, &io_block
       Cmds.spawn  prepare(*args, **kwds),

data/lib/cmds/util/tokenize_option.rb

@@ -36,8 +36,6 @@ class Cmds
   #   string tokens.
   # 
   def self.tokenize_option name, value, **opts
-    pp opts: opts
-    
     opts = defaults opts, TOKENIZE_OPT_KEYS
     
     unless name.is_a?(String) && name.length > 0

data/lib/cmds/version.rb

@@ -1,3 +1,3 @@
 class Cmds
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/lib/cmds.rb

@@ -296,7 +296,13 @@ class Cmds
   def prepare *args, **kwds
     @last_prepared_cmd = Cmds.format render(*args, **kwds), self.format
   end # #prepare
-
+  
+  
+  # @!group Execution Instance Methods
+  # ----------------------------------------------------------------------------
+  # 
+  # Methods that run the command.
+  # 
 
   # execute command and return `true` if it exited successfully.
   # 
@@ -423,4 +429,7 @@ class Cmds
   def err *args, **kwds, &input_block
     capture(*args, **kwds, &input_block).err
   end
+  
+  # @!endgroup Execution Instance Methods
+  
 end # Cmds

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cmds
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - nrser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-07 00:00:00.000000000 Z
+date: 2017-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nrser
@@ -232,7 +232,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.11
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: helps read, write and remember commands.