sh.rb in methadone-1.2.0

- old
+ new

@@ -3,12 +3,11 @@
   require 'ostruct'
 elsif RUBY_VERSION =~ /^1.8/
   begin
   require 'open4'
   rescue LoadError
-    STDERR.puts "!! For Ruby #{RUBY_VERSION}, the open4 library must be installed"
-    raise
+    warn "For Ruby #{RUBY_VERSION}, the open4 library must be installed or SH won't work"
   end
 else
   require 'open3'
 end
 
@@ -70,10 +69,14 @@
     # Run a shell command, capturing and logging its output.
     # If the command completed successfully, it's output is logged at DEBUG.
     # If not, its output as logged at INFO.  In either case, its
     # error output is logged at WARN.
     #
-    # command:: the command to run
+    # command:: the command to run as a String or Array of String.  The String form is simplest, but
+    #           is open to injection.  If you need to execute a command that is assembled from some portion
+    #           of user input, consider using an Array of String.  This form prevents tokenization that occurs
+    #           in the String form.  The first element is the command to execute,
+    #           and the remainder are the arguments. See Methadone::ExecutionStrategy::Base for more info.
     # options:: options to control the call. Currently responds to:
     #           +:expected+:: an Int or Array of Int representing error codes, <b>in addition to 0</b>, that are
     #                         expected and therefore constitute success.  Useful for commands that don't use
     #                         exit codes the way you'd like
     # block:: if provided, will be called if the command exited nonzero.  The block may take 0, 1, 2, or 3 arguments.