toys-core 0.3.4 → 0.3.5

data/lib/toys/core_version.rb

@@ -32,5 +32,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.3.4".freeze
+  CORE_VERSION = "0.3.5".freeze
 end

data/lib/toys/helpers/exec.rb

@@ -27,7 +27,7 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "logger"
+require "toys/utils/exec"
 
 module Toys
   module Helpers
@@ -37,98 +37,71 @@ module Toys
     # in a string. Also provides an interface for controlling a spawned
     # process's streams.
     #
-    # ## Configuration options
-    #
-    # A variety of options can be used to control subprocesses. These include:
-    #
-    # *  **:env** (Hash) Environment variables to pass to the subprocess
-    # *  **:log_level** (Integer) If set, the actual command will be logged
-    #    at the given level.
-    # *  **:in_from** (`:controller`,String) Connects the input stream of the
-    #    subprocess. If set to `:controller`, the controller will control the
-    #    input stream. If set to a string, that string will be written to the
-    #    input stream. If not set, the input stream will be connected to the
-    #    STDIN for the Toys process itself.
-    # *  **:out_to** (`:controller`,`:capture`) Connects the standard output
-    #    stream of the subprocess. If set to `:controller`, the controller
-    #    will control the output stream. If set to `:capture`, the output will
-    #    be captured in a string that is available in the
-    #    {Toys::Helpers::Exec::Result} object. If not set, the subprocess
-    #    standard out is connected to STDOUT of the Toys process.
-    # *  **:err_to** (`:controller`,`:capture`) Connects the standard error
-    #    stream of the subprocess. See `:out_to` for more details.
-    # *  **:out_err_to** (`:controller`,`:capture`) Combines the standard out
-    #    and error streams of the subprocess and connects them. See `:out_to`
-    #    for more details.
-    # *  **:exit_on_nonzero_status** (Boolean) If true, a nonzero status code
-    #    will cause the entire tool to terminate. Default is false.
-    #
-    # In addition, any options recognized by `Process#spawn` are supported.
-    # These include `:umask`, `:pgroup`, `:chdir`, and many others.
-    #
-    # Configuration options may be provided to any method that starts a
-    # subprocess. You may also set default values for this tool by calling
-    # {Toys::Helpers::Exec#configure_exec}.
+    # This is a frontend for {Toys::Utils::Exec}. More information is
+    # available in that class's documentation.
     #
     module Exec
+      ## @private
+      def self.extended(context)
+        context[Exec] = Utils::Exec.new do |k|
+          case k
+          when :logger
+            context[Context::LOGGER]
+          when :nonzero_status_handler
+            if context[Context::EXIT_ON_NONZERO_STATUS]
+              proc { |s| context.exit(s.exitstatus) }
+            end
+          end
+        end
+      end
+
       ##
       # Set default configuration keys.
       #
       # @param [Hash] opts The default options. See the section on
-      #     configuration options in the {Toys::Helpers::Exec} module docs.
+      #     configuration options in the {Toys::Utils::Exec} docs.
       #
       def configure_exec(opts = {})
-        @exec_config ||= {}
-        @exec_config.merge!(opts)
+        self[Exec].config_defaults(opts)
       end
 
       ##
       # Execute a command. The command may be given as a single string to pass
       # to a shell, or an array of strings indicating a posix command.
       #
-      # If you provide a block, a {Toys::Helpers::Exec::Controller} will be
+      # If you provide a block, a {Toys::Utils::Exec::Controller} will be
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [String,Array<String>] cmd The command to execute.
       # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Helpers::Exec} module docs.
-      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
-      #     for the subprocess streams.
+      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess streams.
       #
-      # @return [Toys::Helpers::Result] The subprocess result, including
-      #     exit code and any captured output.
+      # @return [Toys::Utils::Result] The subprocess result, including the exit
+      #     code and any captured output.
       #
       def exec(cmd, opts = {}, &block)
-        exec_opts = ExecOpts.new(self)
-        exec_opts.add(@exec_config) if defined? @exec_config
-        exec_opts.add(opts)
-        executor = Executor.new(exec_opts, cmd)
-        executor.execute(&block)
+        self[Exec].exec(cmd, Exec._setup_exec_opts(opts, self), &block)
       end
 
       ##
       # Spawn a ruby process and pass the given arguments to it.
       #
-      # If you provide a block, a {Toys::Helpers::Exec::Controller} will be
+      # If you provide a block, a {Toys::Utils::Exec::Controller} will be
       # yielded to it, allowing you to interact with the subprocess streams.
       #
       # @param [String,Array<String>] args The arguments to ruby.
       # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Helpers::Exec} module docs.
-      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
+      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     for the subprocess streams.
       #
-      # @return [Toys::Helpers::Result] The subprocess result, including
-      #     exit code and any captured output.
+      # @return [Toys::Utils::Result] The subprocess result, including the exit
+      #     code and any captured output.
       #
       def ruby(args, opts = {}, &block)
-        cmd =
-          if args.is_a?(Array)
-            [[Exec.ruby_binary, "ruby"]] + args
-          else
-            "#{Exec.ruby_binary} #{args}"
-          end
-        exec(cmd, opts, &block)
+        self[Exec].ruby(args, Exec._setup_exec_opts(opts, self), &block)
       end
 
       ##
@@ -136,14 +109,14 @@ module Toys
       #
       # @param [String] cmd The shell command to execute.
       # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Helpers::Exec} module docs.
-      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
-      #     for the subprocess streams.
+      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess streams.
       #
       # @return [Integer] The exit code
       #
       def sh(cmd, opts = {})
-        exec(cmd, opts).exit_code
+        self[Exec].sh(cmd, Exec._setup_exec_opts(opts, self))
       end
 
       ##
@@ -154,315 +127,24 @@ module Toys
       #
       # @param [String,Array<String>] cmd The command to execute.
       # @param [Hash] opts The command options. See the section on
-      #     configuration options in the {Toys::Helpers::Exec} module docs.
-      # @yieldparam controller [Toys::Helpers::Exec::Controller] A controller
-      #     for the subprocess streams.
+      #     configuration options in the {Toys::Utils::Exec} module docs.
+      # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
+      #     the subprocess streams.
       #
       # @return [String] What was written to standard out.
       #
       def capture(cmd, opts = {})
-        exec(cmd, opts.merge(out_to: :capture)).captured_out
-      end
-
-      ##
-      # Returns the paty to the Ruby binary
-      # @return [String] Path to the Ruby binary
-      #
-      def self.ruby_binary
-        ::File.join(::RbConfig::CONFIG["bindir"], ::RbConfig::CONFIG["ruby_install_name"])
-      end
-
-      ##
-      # An object of this type is passed to a subcommand control block.
-      # You may use this object to interact with the subcommand's streams,
-      # and/or send signals to the process.
-      #
-      class Controller
-        ## @private
-        def initialize(ins, out, err, out_err, pid)
-          @in = ins
-          @out = out
-          @err = err
-          @out_err = out_err
-          @pid = pid
-        end
-
-        ##
-        # Return the subcommand's standard input stream (which can be written
-        # to), if the command was configured with `in_from: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
-        #
-        attr_reader :in
-
-        ##
-        # Return the subcommand's standard output stream (which can be read
-        # from), if the command was configured with `out_to: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
-        #
-        attr_reader :out
-
-        ##
-        # Return the subcommand's standard error stream (which can be read
-        # from), if the command was configured with `err_to: :controller`.
-        # Returns `nil` otherwise.
-        # @return [IO,nil]
-        #
-        attr_reader :err
-
-        ##
-        # Return the subcommand's combined standard output and error stream
-        # (which can be read from), if the command was configured with
-        # `out_err_to: :controller`. Returns `nil` otherwise.
-        # @return [IO,nil]
-        #
-        attr_reader :out_err
-
-        ##
-        # Returns the process ID.
-        # @return [Integer]
-        #
-        attr_reader :pid
-
-        ##
-        # Send the given signal to the process. The signal may be specified
-        # by name or number.
-        #
-        # @param [Integer,String] signal The signal to send.
-        #
-        def kill(signal)
-          ::Process.kill(signal, pid)
-        end
-      end
-
-      ##
-      # The return result from a subcommand
-      #
-      class Result
-        ## @private
-        def initialize(out, err, out_err, status)
-          @captured_out = out
-          @captured_err = err
-          @captured_out_err = out_err
-          @status = status
-        end
-
-        ##
-        # Returns the captured output string, if the command was configured
-        # with `out_to: :capture`. Returns `nil` otherwise.
-        # @return [String,nil]
-        #
-        attr_reader :captured_out
-
-        ##
-        # Returns the captured error string, if the command was configured
-        # with `err_to: :capture`. Returns `nil` otherwise.
-        # @return [String,nil]
-        #
-        attr_reader :captured_err
-
-        ##
-        # Returns the captured combined output and error string, if the command
-        # was configured with `out_err_to: :capture`. Returns `nil` otherwise.
-        # @return [String,nil]
-        #
-        attr_reader :captured_out_err
-
-        ##
-        # Returns the status code object.
-        # @return [Process::Status]
-        #
-        attr_reader :status
-
-        ##
-        # Returns the numeric status code.
-        # @return [Integer]
-        #
-        def exit_code
-          status.exitstatus
-        end
-
-        ##
-        # Returns true if the subprocess terminated with a zero status.
-        # @return [Boolean]
-        #
-        def success?
-          exit_code.zero?
-        end
-
-        ##
-        # Returns true if the subprocess terminated with a nonzero status.
-        # @return [Boolean]
-        #
-        def error?
-          !exit_code.zero?
-        end
+        self[Exec].capture(cmd, Exec._setup_exec_opts(opts, self))
       end
 
-      ##
-      # An internal helper class storing the configuration of a subcommand invocation
-      # @private
-      #
-      class ExecOpts
-        ##
-        # Option keys that belong to exec configuration rather than spawn
-        # @private
-        #
-        CONFIG_KEYS = %i[
-          exit_on_nonzero_status
-          env
-          log_level
-          in_from
-          out_to
-          err_to
-          out_err_to
-        ].freeze
-
-        def initialize(context)
-          @context = context
-          @config = {exit_on_nonzero_status: @context.get(Context::EXIT_ON_NONZERO_STATUS)}
-          @spawn_opts = {}
-        end
-
-        def add(config)
-          config.each do |k, v|
-            if CONFIG_KEYS.include?(k)
-              @config[k] = v
-            else
-              @spawn_opts[k] = v
-            end
-          end
-        end
-
-        attr_reader :config
-        attr_reader :spawn_opts
-        attr_reader :context
-      end
-
-      ##
-      # An object that manages the execution of a subcommand
-      # @private
-      #
-      class Executor
-        def initialize(exec_opts, cmd)
-          @cmd = Array(cmd)
-          @config = exec_opts.config
-          @context = exec_opts.context
-          @spawn_opts = exec_opts.spawn_opts.dup
-          @captures = {}
-          @controller_streams = {}
-          @join_threads = []
-          @child_streams = []
-        end
-
-        def execute(&block)
-          setup_in_stream
-          setup_out_stream(:out, :out_to, :out)
-          setup_out_stream(:err, :err_to, :err)
-          setup_out_stream(:out_err, :out_err_to, [:out, :err])
-          log_command
-          wait_thread = start_process
-          status = control_process(wait_thread, &block)
-          create_result(status)
-        end
-
-        private
-
-        def log_command
-          unless @config[:log_level] == false
-            cmd_str = @cmd.size == 1 ? @cmd.first : @cmd.inspect
-            @context.logger.add(@config[:log_level] || ::Logger::INFO, cmd_str)
-          end
-        end
-
-        def start_process
-          args = []
-          args << @config[:env] if @config[:env]
-          args.concat(@cmd)
-          pid = ::Process.spawn(*args, @spawn_opts)
-          @child_streams.each(&:close)
-          ::Process.detach(pid)
-        end
-
-        def control_process(wait_thread)
-          begin
-            if block_given?
-              controller = Controller.new(
-                @controller_streams[:in], @controller_streams[:out], @controller_streams[:err],
-                @controller_streams[:out_err], wait_thread.pid
-              )
-              yield controller
-            end
-          ensure
-            @controller_streams.each_value(&:close)
-          end
-          @join_threads.each(&:join)
-          wait_thread.value
-        end
-
-        def create_result(status)
-          if @config[:exit_on_nonzero_status]
-            exit_status = status.exitstatus
-            @context.exit(exit_status) if exit_status != 0
-          end
-          Result.new(@captures[:out], @captures[:err], @captures[:out_err], status)
-        end
-
-        def setup_in_stream
-          setting = @config[:in_from]
-          if setting
-            r, w = ::IO.pipe
-            @spawn_opts[:in] = r
-            w.sync = true
-            @child_streams << r
-            case setting
-            when :controller
-              @controller_streams[:in] = w
-            when String
-              write_string_thread(w, setting)
-            else
-              raise "Unknown type for in_from"
-            end
-          end
-        end
-
-        def setup_out_stream(stream_name, config_key, spawn_key)
-          setting = @config[config_key]
-          if setting
-            r, w = ::IO.pipe
-            @spawn_opts[spawn_key] = w
-            @child_streams << w
-            case setting
-            when :controller
-              @controller_streams[stream_name] = r
-            when :capture
-              @join_threads << capture_stream_thread(r, stream_name)
-            else
-              raise "Unknown type for #{config_key}"
-            end
-          end
-        end
-
-        def write_string_thread(stream, string)
-          ::Thread.new do
-            begin
-              stream.write string
-            ensure
-              stream.close
-            end
+      ## @private
+      def self._setup_exec_opts(opts, context)
+        return opts unless opts.key?(:exit_on_nonzero_status)
+        nonzero_status_handler =
+          if opts[:exit_on_nonzero_status]
+            proc { |s| context.exit(s.exitstatus) }
           end
-        end
-
-        def capture_stream_thread(stream, name)
-          ::Thread.new do
-            begin
-              @captures[name] = stream.read
-            ensure
-              stream.close
-            end
-          end
-        end
+        opts.merge(nonzero_status_handler: nonzero_status_handler)
       end
     end
   end