toys-core 0.10.2 → 0.11.1

data/lib/toys/source_info.rb

@@ -10,7 +10,7 @@ module Toys
     # @private
     #
     def initialize(parent, context_directory, source_type, source_path, source_proc,
-                   source_name, data_dir, lib_dir)
+                   source_name, data_dir_name, lib_dir_name)
       @parent = parent
       @context_directory = context_directory
       @source_type = source_type
@@ -18,8 +18,10 @@ module Toys
       @source_path = source_path
       @source_proc = source_proc
       @source_name = source_name
-      @data_dir = data_dir
-      @lib_dir = lib_dir
+      @data_dir_name = data_dir_name
+      @lib_dir_name = lib_dir_name
+      @data_dir = find_special_dir(data_dir_name)
+      @lib_dir = find_special_dir(lib_dir_name)
     end
 
     ##
@@ -118,15 +120,13 @@ module Toys
     # Create a child SourceInfo relative to the parent path.
     # @private
     #
-    def relative_child(filename, data_dir_name, lib_dir_name)
-      raise "no parent path for relative_child" unless source_path
+    def relative_child(filename)
+      raise "relative_child is valid only on a directory source" unless source_type == :directory
       child_path = ::File.join(source_path, filename)
       child_path, type = SourceInfo.check_path(child_path, true)
       return nil unless child_path
-      data_dir = SourceInfo.find_special_dir(type, child_path, data_dir_name)
-      lib_dir = SourceInfo.find_special_dir(type, child_path, lib_dir_name)
-      SourceInfo.new(self, context_directory, type, child_path, source_proc, child_path,
-                     data_dir, lib_dir)
+      SourceInfo.new(self, context_directory, type, child_path, nil, child_path,
+                     @data_dir_name, @lib_dir_name)
     end
 
     ##
@@ -135,7 +135,8 @@ module Toys
     #
     def absolute_child(child_path)
       child_path, type = SourceInfo.check_path(child_path, false)
-      SourceInfo.new(self, context_directory, type, child_path, source_proc, child_path, nil, nil)
+      SourceInfo.new(self, context_directory, type, child_path, nil, child_path,
+                     @data_dir_name, @lib_dir_name)
     end
 
     ##
@@ -144,25 +145,26 @@ module Toys
     #
     def proc_child(child_proc, source_name = nil)
       source_name ||= self.source_name
-      SourceInfo.new(self, context_directory, :proc, source_path, child_proc, source_name, nil, nil)
+      SourceInfo.new(self, context_directory, :proc, source_path, child_proc, source_name,
+                     @data_dir_name, @lib_dir_name)
     end
 
     ##
     # Create a root source info for a file path.
     # @private
     #
-    def self.create_path_root(source_path)
+    def self.create_path_root(source_path, data_dir_name, lib_dir_name)
       source_path, type = check_path(source_path, false)
       context_directory = ::File.dirname(source_path)
-      new(nil, context_directory, type, source_path, nil, source_path, nil, nil)
+      new(nil, context_directory, type, source_path, nil, source_path, data_dir_name, lib_dir_name)
     end
 
     ##
     # Create a root source info for a proc.
     # @private
     #
-    def self.create_proc_root(source_proc, source_name)
-      new(nil, nil, :proc, nil, source_proc, source_name, nil, nil)
+    def self.create_proc_root(source_proc, source_name, data_dir_name, lib_dir_name)
+      new(nil, nil, :proc, nil, source_proc, source_name, data_dir_name, lib_dir_name)
     end
 
     ##
@@ -189,14 +191,11 @@ module Toys
       end
     end
 
-    ##
-    # Determine the data directory path, if any.
-    # @private
-    #
-    def self.find_special_dir(type, source_path, dir_name)
-      return nil if source_path.nil? || dir_name.nil?
-      source_path = ::File.dirname(source_path) if type == :file
-      dir = ::File.join(source_path, dir_name)
+    private
+
+    def find_special_dir(dir_name)
+      return nil if @source_type != :directory || dir_name.nil?
+      dir = ::File.join(@source_path, dir_name)
       dir if ::File.directory?(dir) && ::File.readable?(dir)
     end
   end

data/lib/toys/standard_mixins/bundler.rb

@@ -7,32 +7,55 @@ module Toys
     #
     # The following parameters can be passed when including this mixin:
     #
-    #  *  `:groups` (Array<String>) The groups to include in setup
+    #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
+    #     defining the tool. If `false` (the default), installs the bundle just
+    #     before the tool runs.
     #
-    #  *  `:search_dirs` (Array<String,Symbol>) Directories to search for a
-    #     Gemfile.
+    #  *  `:groups` (Array\<String\>) The groups to include in setup.
+    #
+    #  *  `:gemfile_path` (String) The path to the Gemfile to use. If `nil` or
+    #     not given, the `:search_dirs` will be searched for a Gemfile.
+    #
+    #  *  `:search_dirs` (String,Symbol,Array\<String,Symbol\>) Directories to
+    #     search for a Gemfile.
     #
     #     You can pass full directory paths, and/or any of the following:
-    #      *  `:context` - the current context directory
-    #      *  `:current` - the current working directory
-    #      *  `:toys` - the Toys directory containing the tool definition
+    #      *  `:context` - the current context directory.
+    #      *  `:current` - the current working directory.
+    #      *  `:toys` - the Toys directory containing the tool definition, and
+    #         any of its parents within the Toys directory hierarchy.
     #
     #     The default is to search `[:toys, :context, :current]` in that order.
+    #     See {DEFAULT_SEARCH_DIRS}.
+    #
+    #     For most directories, the bundler mixin will look for the files
+    #     ".gems.rb", "gems.rb", and "Gemfile", in that order. In `:toys`
+    #     directories, it will look only for ".gems.rb" and "Gemfile", in that
+    #     order. These can be overridden by setting the `:gemfile_names` and/or
+    #     `:toys_gemfile_names` arguments.
+    #
+    #  *  `:gemfile_names` (Array\<String\>) File names that are recognized as
+    #     Gemfiles when searching in directories other than Toys directories.
+    #     Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
+    #
+    #  *  `:toys_gemfile_names` (Array\<String\>) File names that are
+    #     recognized as Gemfiles when wearching in Toys directories.
+    #     Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
     #
     #  *  `:on_missing` (Symbol) What to do if a needed gem is not installed.
     #
     #     Supported values:
-    #      *  `:confirm` - prompt the user on whether to install (default)
-    #      *  `:error` - raise an exception
-    #      *  `:install` - just install the gem
+    #      *  `:confirm` - prompt the user on whether to install (default).
+    #      *  `:error` - raise an exception.
+    #      *  `:install` - just install the gem.
     #
     #  *  `:on_conflict` (Symbol) What to do if bundler has already been run
     #     with a different Gemfile.
     #
     #     Supported values:
-    #      *  `:error` - raise an exception (default)
-    #      *  `:ignore` - just silently proceed without bundling again
-    #      *  `:warn` - print a warning and proceed without bundling again
+    #      *  `:error` - raise an exception (default).
+    #      *  `:ignore` - just silently proceed without bundling again.
+    #      *  `:warn` - print a warning and proceed without bundling again.
     #
     #  *  `:terminal` (Toys::Utils::Terminal) Terminal to use (optional)
     #  *  `:input` (IO) Input IO (optional, defaults to STDIN)
@@ -41,48 +64,106 @@ module Toys
     module Bundler
       include Mixin
 
-      on_initialize do
-        |groups: nil,
-         search_dirs: nil,
-         on_missing: nil,
-         on_conflict: nil,
-         terminal: nil,
-         input: nil,
-         output: nil|
+      on_initialize do |static: false, **kwargs|
+        unless static
+          context_directory = self[::Toys::Context::Key::CONTEXT_DIRECTORY]
+          source_info = self[::Toys::Context::Key::TOOL_SOURCE]
+          ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        end
+      end
+
+      on_include do |static: false, **kwargs|
+        if static
+          ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
+        end
+      end
+
+      ##
+      # Default search directories for Gemfiles.
+      # @return [Array<String,Symbol>]
+      #
+      DEFAULT_SEARCH_DIRS = [:toys, :context, :current].freeze
+
+      ##
+      # The gemfile names that are searched by default in Toys directories.
+      # @return [Array<String>]
+      #
+      DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
+
+      # @private
+      def self.setup_bundle(context_directory,
+                            source_info,
+                            gemfile_path: nil,
+                            search_dirs: nil,
+                            gemfile_names: nil,
+                            toys_gemfile_names: nil,
+                            groups: nil,
+                            on_missing: nil,
+                            on_conflict: nil,
+                            terminal: nil,
+                            input: nil,
+                            output: nil)
         require "toys/utils/gems"
-        search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(search_dirs, self)
+        gemfile_path ||= begin
+          gemfile_finder = GemfileFinder.new(context_directory, source_info,
+                                             gemfile_names, toys_gemfile_names)
+          gemfile_finder.search(search_dirs || DEFAULT_SEARCH_DIRS)
+        end
         gems = ::Toys::Utils::Gems.new(on_missing: on_missing, on_conflict: on_conflict,
                                        terminal: terminal, input: input, output: output)
-        gems.bundle(groups: groups, search_dirs: search_dirs)
+        gems.bundle(groups: groups, gemfile_path: gemfile_path)
       end
 
-      ## @private
-      def self.resolve_search_dirs(search_dirs, context)
-        search_dirs ||= [:toys, :context, :current]
-        Array(search_dirs).flat_map do |dir|
-          case dir
+      # @private
+      class GemfileFinder
+        # @private
+        def initialize(context_directory, source_info, gemfile_names, toys_gemfile_names)
+          @context_directory = context_directory
+          @source_info = source_info
+          @gemfile_names = gemfile_names
+          @toys_gemfile_names = toys_gemfile_names || DEFAULT_TOYS_GEMFILE_NAMES
+        end
+
+        # @private
+        def search(search_dir)
+          case search_dir
+          when ::Array
+            search_array(search_dir)
+          when ::String
+            ::Toys::Utils::Gems.find_gemfile(search_dir, gemfile_names: @gemfile_names)
           when :context
-            context[::Toys::Context::Key::CONTEXT_DIRECTORY]
+            search(@context_directory)
           when :current
-            ::Dir.getwd
+            search(::Dir.getwd)
           when :toys
-            toys_dir_stack(context[::Toys::Context::Key::TOOL_SOURCE])
-          when ::String
-            dir
+            search_toys
           else
             raise ::ArgumentError, "Unrecognized search_dir: #{dir.inspect}"
           end
         end
-      end
 
-      ## @private
-      def self.toys_dir_stack(source_info)
-        dirs = []
-        while source_info
-          dirs << source_info.source_path if source_info.source_type == :directory
-          source_info = source_info.parent
+        private
+
+        def search_array(search_dirs)
+          search_dirs.each do |search_dir|
+            result = search(search_dir)
+            return result if result
+          end
+          nil
+        end
+
+        def search_toys
+          source_info = @source_info
+          while source_info
+            if source_info.source_type == :directory
+              result = ::Toys::Utils::Gems.find_gemfile(source_info.source_path,
+                                                        gemfile_names: @toys_gemfile_names)
+              return result if result
+            end
+            source_info = source_info.parent
+          end
+          nil
         end
-        dirs
       end
     end
   end

data/lib/toys/standard_mixins/exec.rb

@@ -728,7 +728,7 @@ module Toys
       def self._setup_clean_process(cmd)
         raise ::ArgumentError, "Toys process is unknown" unless ::Toys.executable_path
         cmd = ::Shellwords.split(cmd) if cmd.is_a?(::String)
-        cmd = Array(::Toys.executable_path) + cmd
+        cmd = [::RbConfig.ruby, "--disable=gems", ::Toys.executable_path] + cmd
         if defined?(::Bundler)
           if ::Bundler.respond_to?(:with_unbundled_env)
             ::Bundler.with_unbundled_env { yield(cmd) }

data/lib/toys/utils/exec.rb

@@ -547,7 +547,7 @@ module Toys
         ##
         # The process ID.
         #
-        # Exactly one of `exception` and `pid` will be non-nil.
+        # Exactly one of {#exception} and {#pid} will be non-nil.
         #
         # @return [Integer] if the process start was successful
         # @return [nil] if the process could not be started.
@@ -557,7 +557,7 @@ module Toys
         ##
         # The exception raised when the process failed to start.
         #
-        # Exactly one of `exception` and `pid` will be non-nil.
+        # Exactly one of {#exception} and {#pid} will be non-nil.
         #
         # @return [Exception] if the process failed to start.
         # @return [nil] if the process start was successful.
@@ -722,15 +722,20 @@ module Toys
         ##
         # Wait for the subcommand to complete, and return a result object.
         #
+        # Closes the control streams if present. The stdin stream is always
+        # closed, even if the call times out. The stdout and stderr streams are
+        # closed only after the command terminates.
+        #
         # @param timeout [Numeric,nil] The timeout in seconds, or `nil` to
         #     wait indefinitely.
         # @return [Toys::Utils::Exec::Result] The result object
         # @return [nil] if a timeout occurred.
         #
         def result(timeout: nil)
+          close_streams(:in)
           return nil if @wait_thread && !@wait_thread.join(timeout)
           @result ||= begin
-            close_streams
+            close_streams(:out)
             @join_threads.each(&:join)
             Result.new(name, @captures[:out], @captures[:err], @wait_thread&.value, @exception)
                   .tap { |result| @result_callback&.call(result) }
@@ -738,13 +743,13 @@ module Toys
         end
 
         ##
-        # Close all the controller's streams.
+        # Close the controller's streams.
         # @private
         #
-        def close_streams
-          @in.close if @in && !@in.closed?
-          @out.close if @out && !@out.closed?
-          @err.close if @err && !@err.closed?
+        def close_streams(which)
+          @in.close if which != :out && @in && !@in.closed?
+          @out.close if which != :in && @out && !@out.closed?
+          @err.close if which != :in && @err && !@err.closed?
           self
         end
 
@@ -773,7 +778,21 @@ module Toys
       end
 
       ##
-      # The result returned from a subcommand execution.
+      # The result returned from a subcommand execution. This includes the
+      # identifying name of the execution (if any), the result status of the
+      # execution, and any captured stream output.
+      #
+      # Possible result statuses are:
+      #
+      #  *  The process failed to start. {Result#failed?} will return true, and
+      #     {Result#exception} will return an exception describing the failure
+      #     (often an errno).
+      #  *  The process executed and exited with a normal exit code. Either
+      #     {Result#success?} or {Result#error?} will return true, and
+      #     {Result.exit_code} will return the numeric exit code.
+      #  *  The process executed but was terminated by an uncaught signal.
+      #     {Result#signaled?} will return true, and {Result#term_signal} will
+      #     return the numeric signal code.
       #
       class Result
         ## @private
@@ -809,11 +828,13 @@ module Toys
         attr_reader :captured_err
 
         ##
-        # The status code object.
+        # The Ruby process status object, providing various information about
+        # the ending state of the process.
         #
-        # Exactly one of `exception` and `status` will be non-nil.
+        # Exactly one of {#exception} and {#status} will be non-nil.
         #
-        # @return [Process::Status] The status code.
+        # @return [Process::Status] The status, if the process was successfully
+        #     spanwed and terminated.
         # @return [nil] if the process could not be started.
         #
         attr_reader :status
@@ -821,7 +842,7 @@ module Toys
         ##
         # The exception raised if a process couldn't be started.
         #
-        # Exactly one of `exception` and `status` will be non-nil.
+        # Exactly one of {#exception} and {#status} will be non-nil.
         #
         # @return [Exception] The exception raised from process start.
         # @return [nil] if the process started successfully.
@@ -829,33 +850,76 @@ module Toys
         attr_reader :exception
 
         ##
-        # The numeric status code.
+        # The numeric status code for a process that exited normally,
         #
-        # This will be a nonzero integer if the process failed to start. That
-        # is, `exit_code` will never be `nil`, even if `status` is `nil`.
+        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # non-nil.
         #
-        # @return [Integer]
+        # @return [Integer] the numeric status code, if the process started
+        #     successfully and exited normally.
+        # @return [nil] if the process did not start successfully, or was
+        #     terminated by an uncaught signal.
         #
         def exit_code
-          status ? status.exitstatus : 127
+          status&.exitstatus
+        end
+
+        ##
+        # The numeric signal code that caused process termination.
+        #
+        # Exactly one of {#exception}, {#exit_code}, and {#term_signal} will be
+        # non-nil.
+        #
+        # @return [Integer] The signal that caused the process to terminate.
+        # @return [nil] if the process did not start successfully, or executed
+        #     and exited with a normal exit code.
+        #
+        def term_signal
+          status&.termsig
+        end
+
+        ##
+        # Returns true if the subprocess failed to start, or false if the
+        # process was able to execute.
+        #
+        # @return [Boolean]
+        #
+        def failed?
+          status.nil?
+        end
+
+        ##
+        # Returns true if the subprocess terminated due to an unhandled signal,
+        # or false if the process failed to start or exited normally.
+        #
+        # @return [Boolean]
+        #
+        def signaled?
+          !term_signal.nil?
         end
 
         ##
-        # Returns true if the subprocess terminated with a zero status.
+        # Returns true if the subprocess terminated with a zero status, or
+        # false if the process failed to start, terminated due to a signal, or
+        # returned a nonzero status.
         #
         # @return [Boolean]
         #
         def success?
-          exit_code.zero?
+          code = exit_code
+          !code.nil? && code.zero?
         end
 
         ##
-        # Returns true if the subprocess terminated with a nonzero status.
+        # Returns true if the subprocess terminated with a nonzero status, or
+        # false if the process failed to start, terminated due to a signal, or
+        # returned a zero status.
         #
         # @return [Boolean]
         #
         def error?
-          !exit_code.zero?
+          code = exit_code
+          !code.nil? && !code.zero?
         end
       end
 
@@ -887,10 +951,10 @@ module Toys
           return controller if @config_opts[:background]
           begin
             @block&.call(controller)
+            controller.result
           ensure
-            controller.close_streams
+            controller.close_streams(:both)
           end
-          controller.result
         end
 
         private