toys-core 0.7.0 → 0.8.0

data/lib/toys/standard_mixins/exec.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -52,15 +44,43 @@ module Toys
     # by `Process#spawn`, and some options supported by {Toys::Utils::Exec}
     # itself.
     #
-    # In addition, this mixin supports one more option,
-    # `exit_on_nonzero_status`. When set to true, if any subprocess returns a
-    # nonzero result code, the tool will immediately exit with that same code,
-    # similar to `set -e` in a bash script.
+    # You can set default configuration by passing options to the `include`
+    # directive. For example, to log commands at the debug level for all
+    # subprocesses spawned by this tool:
+    #
+    #     include :exec, log_level: Logger::DEBUG
+    #
+    # Two special options are also recognized by the mixin.
+    #
+    #  *  A **:result_callback** proc may take a second argument. If it does,
+    #     the context object is passed as the second argument. This is useful
+    #     if a `:result_callback` is applied to the entire tool by passing it
+    #     to the `include` directive. In that case, `self` is not set to the
+    #     context object as it normally would be in a tool's `run` method, so
+    #     you cannot access it otherwise. For example, here is how to log the
+    #     exit code for every subcommand:
+    #
+    #         tool "mytool" do
+    #           callback = proc do |result, context|
+    #             context.logger.info "Exit code: #{result.exit_code}"
+    #           end
+    #           include :exec, result_callback: callback
+    #           # ...
+    #         end
     #
-    # You can set initial configuration by passing options to the `include`
-    # directive. For example:
+    #     You may also pass a symbol as the `:result_callback`. The method with
+    #     that name is then called as the callback. The method must take one
+    #     argument, the result object.
     #
-    #     include :exec, exit_on_nonzero_status: true
+    #  *  If **:exit_on_nonzero_status** is set to true, a nonzero exit code
+    #     returned by the subprocess will also cause the tool to exit
+    #     immediately with that same code.
+    #
+    #     This is particularly useful as an option to the `include` directive,
+    #     where it causes any subprocess failure to abort the tool, similar to
+    #     setting `set -e` in a bash script.
+    #
+    #         include :exec, exit_on_nonzero_status: true
     #
     module Exec
       include Mixin
@@ -71,15 +91,16 @@ module Toys
       #
       KEY = ::Object.new.freeze
 
-      to_initialize do |opts = {}|
-        tool = self
-        opts = Exec._setup_exec_opts(opts, tool)
-        tool[KEY] = Utils::Exec.new(opts) do |k|
+      on_initialize do |opts = {}|
+        require "toys/utils/exec"
+        context = self
+        opts = Exec._setup_exec_opts(opts, context)
+        context[KEY] = Utils::Exec.new(opts) do |k|
           case k
           when :logger
-            tool[Tool::Keys::LOGGER]
+            context[Context::Key::LOGGER]
           when :cli
-            tool[Tool::Keys::CLI]
+            context[Context::Key::CLI]
           end
         end
       end
@@ -90,10 +111,12 @@ module Toys
       # All options listed in the {Toys::Utils::Exec} documentation are
       # supported, plus the `exit_on_nonzero_status` option.
       #
-      # @param [Hash] opts The default options.
+      # @param opts [Hash] The default options.
+      # @return [self]
       #
       def configure_exec(opts = {})
         self[KEY].configure_defaults(Exec._setup_exec_opts(opts, self))
+        self
       end
 
       ##
@@ -103,16 +126,17 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. All options listed in the
+      # @param cmd [String,Array<String>] The command to execute.
+      # @param opts [Hash] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec(cmd, opts = {}, &block)
         self[KEY].exec(cmd, Exec._setup_exec_opts(opts, self), &block)
@@ -124,16 +148,17 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. All options listed in the
+      # @param args [String,Array<String>] The arguments to ruby.
+      # @param opts [Hash] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller for
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec_ruby(args, opts = {}, &block)
         self[KEY].exec_ruby(args, Exec._setup_exec_opts(opts, self), &block)
@@ -146,16 +171,17 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. Most options listed in the
+      # @param func [Proc] The proc to call.
+      # @param opts [Hash] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec_proc(func, opts = {}, &block)
         self[KEY].exec_proc(func, Exec._setup_exec_opts(opts, self), &block)
@@ -168,16 +194,17 @@ module Toys
       # If the process is not set to run in the background, and a block is
       # provided, a {Toys::Utils::Exec::Controller} will be yielded to it.
       #
-      # @param [String,Array<String>] cmd The tool to execute.
-      # @param [Hash] opts The command options. Most options listed in the
+      # @param cmd [String,Array<String>] The tool to execute.
+      # @param opts [Hash] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
       #     for the subprocess streams.
       #
-      # @return [Toys::Utils::Exec::Controller,Toys::Utils::Exec::Result] The
-      #     subprocess controller or result, depending on whether the process
-      #     is running in the background or foreground.
+      # @return [Toys::Utils::Exec::Controller] The subprocess controller, if
+      #     the process is running in the background.
+      # @return [Toys::Utils::Exec::Result] The result, if the process ran in
+      #     the foreground.
       #
       def exec_tool(cmd, opts = {}, &block)
         func = Exec._make_tool_caller(cmd)
@@ -194,8 +221,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String,Array<String>] cmd The command to execute.
-      # @param [Hash] opts The command options. All options listed in the
+      # @param cmd [String,Array<String>] The command to execute.
+      # @param opts [Hash] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -216,8 +243,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String,Array<String>] args The arguments to ruby.
-      # @param [Hash] opts The command options. All options listed in the
+      # @param args [String,Array<String>] The arguments to ruby.
+      # @param opts [Hash] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -238,8 +265,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [Proc] func The proc to call.
-      # @param [Hash] opts The command options. Most options listed in the
+      # @param func [Proc] The proc to call.
+      # @param opts [Hash] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -261,8 +288,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String,Array<String>] cmd The tool to execute.
-      # @param [Hash] opts The command options. Most options listed in the
+      # @param cmd [String,Array<String>] The tool to execute.
+      # @param opts [Hash] The command options. Most options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -282,8 +309,8 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # @param [String] cmd The shell command to execute.
-      # @param [Hash] opts The command options. All options listed in the
+      # @param cmd [String] The shell command to execute.
+      # @param opts [Hash] The command options. All options listed in the
       #     {Toys::Utils::Exec} documentation are supported, plus the
       #     `exit_on_nonzero_status` option.
       # @yieldparam controller [Toys::Utils::Exec::Controller] A controller
@@ -298,12 +325,13 @@ module Toys
       ##
       # Exit if the given status code is nonzero. Otherwise, returns 0.
       #
-      # @param [Integer,Process::Status,Toys::Utils::Exec::Result] status
+      # @param status [Integer,Process::Status,Toys::Utils::Exec::Result]
+      # @return [Integer]
       #
       def exit_on_nonzero_status(status)
         status = status.exit_code if status.respond_to?(:exit_code)
         status = status.exitstatus if status.respond_to?(:exitstatus)
-        Tool.exit(status) unless status.zero?
+        Context.exit(status) unless status.zero?
         0
       end
 
@@ -314,14 +342,24 @@ module Toys
       end
 
       ## @private
-      def self._setup_exec_opts(opts, tool)
-        return opts unless opts.key?(:exit_on_nonzero_status)
-        nonzero_status_handler =
-          if opts[:exit_on_nonzero_status]
-            proc { |s| tool.exit(s.exitstatus) }
-          end
-        opts = opts.merge(nonzero_status_handler: nonzero_status_handler)
-        opts.delete(:exit_on_nonzero_status)
+      def self._setup_exec_opts(opts, context)
+        if opts.key?(:exit_on_nonzero_status)
+          result_callback =
+            if opts[:exit_on_nonzero_status]
+              proc { |r| context.exit(r.exit_code) if r.error? }
+            end
+          opts = opts.merge(result_callback: result_callback)
+          opts.delete(:exit_on_nonzero_status)
+        elsif opts.key?(:result_callback)
+          orig_callback = opts[:result_callback]
+          result_callback =
+            if orig_callback.is_a?(::Symbol)
+              context.method(orig_callback)
+            elsif orig_callback.respond_to?(:call)
+              proc { |r| orig_callback.call(r, context) }
+            end
+          opts = opts.merge(result_callback: result_callback)
+        end
         opts
       end
     end

data/lib/toys/standard_mixins/fileutils.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 require "fileutils"

data/lib/toys/standard_mixins/gems.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * Redistributions of source code must retain the above copyright notice,
-#   this list of conditions and the following disclaimer.
-# * Redistributions in binary form must reproduce the above copyright notice,
-#   this list of conditions and the following disclaimer in the documentation
-#   and/or other materials provided with the distribution.
-# * Neither the name of the copyright holder, nor the names of any other
-#   contributors to this software, may be used to endorse or promote products
-#   derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -55,20 +47,26 @@ module Toys
     module Gems
       include Mixin
 
-      to_include do |opts = {}|
-        @__gems = Utils::Gems.new(opts)
+      on_include do |opts = {}|
+        @__gems_opts = opts
 
+        ## @private
         def self.gems
-          @__gems
+          require "toys/utils/gems"
+          # rubocop:disable Naming/MemoizedInstanceVariableName
+          @__gems ||= Utils::Gems.new(@__gems_opts)
+          # rubocop:enable Naming/MemoizedInstanceVariableName
         end
 
+        ## @private
         def self.gem(name, *requirements)
           gems.activate(name, *requirements)
         end
       end
 
       ##
-      # Returns a tool-wide instance of {Toys::Utils::Gems}.
+      # A tool-wide instance of {Toys::Utils::Gems}.
+      # @return [Toys::Utils::Gems]
       #
       def gems
         self.class.gems
@@ -77,8 +75,9 @@ module Toys
       ##
       # Activate the given gem.
       #
-      # @param [String] name Name of the gem
-      # @param [String...] requirements Version requirements
+      # @param name [String] Name of the gem
+      # @param requirements [String...] Version requirements
+      # @return [void]
       #
       def gem(name, *requirements)
         self.class.gems.activate(name, *requirements)