toys-core 0.10.5 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f0e62a1c71082677fd2c257f95adec476cd8c1f5d83a8f42854e48cfe52d1bf
-  data.tar.gz: d5940e36d77ce386ce7be949b2e16af08454095300a5beb3ffafdf4f691abe26
+  metadata.gz: 1cf20d64fb78cfa559000a8007d3f0567db38d1c66ea220daaf8a33f1275fcad
+  data.tar.gz: da6b5f0f2e7d7bef30ded0a45b17014e0adc623583b7221f67b6b44fc9ca3805
 SHA512:
-  metadata.gz: a59b68df5403e100330518056d0e8d9b8792f9e01e36792b445413300e40e2637a86847af9afe565084a55e3bf3b332f1eff15cacc42a56c95597c94a47bd27a
-  data.tar.gz: a8d943e4ccb7a2b9f3278a0eabf4c33485fb09d2fce2440d3f3c3cdc605a30977a0d43da993018b6affb51933686f69e038b5bf1847df54e1cdfab981af77309
+  metadata.gz: e429973defa957eb444c1395c9d6c235052f7f365978d216e7fc4633ebbb7361242ce649845304cd96c47d5227e563d79021c41bd0d2529e9d9b4695edb09ae6
+  data.tar.gz: 4cc2e28b0309130bd8c524a6ab3c17018e9160db4251225ad88aa082cf1ab1226eabda6d0e1ba8691d7ee2c107e8c6b4ea661265422d045a3a27692ce4b5745a

data/CHANGELOG.md

@@ -1,10 +1,20 @@
 # Release History
 
+### 0.11.0 / 2020-08-21
+
+* ADDED: The load path can be truncated using the `truncate_load_path!` directive.
+* IMPROVED: Generated help for delegates now includes the information for the target tool, plus subtools of the delegate.
+* IMPROVED: The `:bundler` mixin searches for `gems.rb` and `.gems.rb` in addition to `Gemfile`.
+* IMPROVED: The `:budnler` mixin can load a specific Gemfile path.
+* FIXED: The loader can now find data and lib directories at the root level of a Toys directory.
+* FIXED: Exec::Result correctly reports processes that terminated due to signals.
+* FIXED: Fixed a rare Exec capture failure that resulted from a race condition when closing streams.
+
 ### 0.10.5 / 2020-07-18
 
 * IMPROVED: The bundler mixin silences bundler output during bundle setup.
 * IMPROVED: The bundler mixin allows toys and toys-core to be in the Gemfile. It checks their version requirements against the running Toys version, and either adds the corret version to the bundle or raises IncompatibleToysError.
-* IMPROVED: The bundler mixin utomatically updates the bundle if install fails (typically because a transitive dependency has been explicitly updated.)
+* IMPROVED: The bundler mixin automatically updates the bundle if install fails (typically because a transitive dependency has been explicitly updated.)
 * FIXED: Some cases of transitive dependency handling by the bundler mixin.
 * FIXED: Fixed a crash when computing suggestions, when running with a bundle on Ruby 2.6 or earlier.
 

data/docs/guide.md

@@ -1,4 +1,6 @@
+<!--
 # @title Toys-Core User Guide
+-->
 
 # Toys-Core User Guide
 

data/lib/toys/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.10.5"
+    VERSION = "0.11.0"
   end
 
   ## @private deprecated

data/lib/toys/dsl/tool.rb

@@ -1619,6 +1619,23 @@ module Toys
         self
       end
 
+      ##
+      # Remove lower-priority sources from the load path. This prevents lower-
+      # priority sources (such as Toys files from parent or global directories)
+      # from executing or defining tools.
+      #
+      # This works only if no such sources have already loaded yet.
+      #
+      # @raise [Toys::ToolDefinitionError] if any lower-priority tools have
+      #     already been loaded.
+      #
+      def truncate_load_path!
+        unless @__loader.stop_loading_at_priority(@__priority)
+          raise ToolDefinitionError,
+                "Cannot truncate load path because tools have already been loaded"
+        end
+      end
+
       ##
       # Determines whether the current Toys version satisfies the given
       # requirements.

data/lib/toys/loader.rb

@@ -8,6 +8,9 @@ module Toys
   # appropriate tool given a set of command line arguments.
   #
   class Loader
+    # @private
+    BASE_PRIORITY = -999_999
+
     ##
     # Create a Loader
     #
@@ -69,9 +72,11 @@ module Toys
       @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
+      @stop_priority = BASE_PRIORITY
+      @min_loaded_priority = 999_999
       @middleware_stack = Middleware.stack(middleware_stack)
       @delimiter_handler = DelimiterHandler.new(extra_delimiters)
-      get_tool([], -999_999)
+      get_tool([], BASE_PRIORITY)
     end
 
     ##
@@ -89,7 +94,7 @@ module Toys
         raise "Cannot add a path after tool loading has started" if @loading_started
         priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
         paths.each do |path|
-          source = SourceInfo.create_path_root(path)
+          source = SourceInfo.create_path_root(path, @data_dir_name, @lib_dir_name)
           @worklist << [source, [], priority]
         end
       end
@@ -114,7 +119,7 @@ module Toys
       @mutex.synchronize do
         raise "Cannot add a block after tool loading has started" if @loading_started
         priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-        source = SourceInfo.create_proc_root(block, name)
+        source = SourceInfo.create_proc_root(block, name, @data_dir_name, @lib_dir_name)
         @worklist << [source, [], priority]
       end
       self
@@ -178,15 +183,15 @@ module Toys
       load_for_prefix(words)
       found_tools = []
       len = words.length
-      tool_data_snapshot.each do |n, td|
-        next if n.empty?
+      all_cur_definitions.each do |tool|
+        name = tool.full_name
+        next if name.empty?
         if recursive
-          next if n.length <= len || n.slice(0, len) != words
+          next if name.length <= len || name.slice(0, len) != words
         else
-          next unless n.slice(0..-2) == words
+          next unless name.slice(0..-2) == words
         end
-        tool = td.cur_definition
-        found_tools << tool unless tool.nil?
+        found_tools << tool
       end
       sort_tools_by_name(found_tools)
       include_hidden ? found_tools : filter_hidden_subtools(found_tools)
@@ -202,8 +207,9 @@ module Toys
     def has_subtools?(words) # rubocop:disable Naming/PredicateName
       load_for_prefix(words)
       len = words.length
-      tool_data_snapshot.each do |n, td|
-        if !n.empty? && n.length > len && n.slice(0, len) == words && !td.empty?
+      all_cur_definitions.each do |tool|
+        name = tool.full_name
+        if !name.empty? && name.length > len && name.slice(0, len) == words
           return true
         end
       end
@@ -267,6 +273,20 @@ module Toys
       Tool.new(self, parent, words, priority, middleware_stack, @middleware_lookup)
     end
 
+    ##
+    # Stop search at the given priority. Returns true if successful.
+    # Called only from the DSL.
+    #
+    # @private
+    #
+    def stop_loading_at_priority(priority)
+      @mutex.synchronize do
+        return false if priority > @min_loaded_priority || priority < @stop_priority
+        @stop_priority = priority
+        true
+      end
+    end
+
     ##
     # Loads the subtree under the given prefix.
     #
@@ -278,6 +298,7 @@ module Toys
         cur_worklist = @worklist
         @worklist = []
         cur_worklist.each do |source, words, priority|
+          next if priority < @stop_priority
           remaining_words = calc_remaining_words(prefix, words)
           if source.source_proc
             load_proc(source, words, remaining_words, priority)
@@ -349,8 +370,15 @@ module Toys
 
     private
 
-    def tool_data_snapshot
-      @mutex.synchronize { @tool_data.dup }
+    def all_cur_definitions
+      result = []
+      @mutex.synchronize do
+        @tool_data.map do |_name, td|
+          tool = td.cur_definition
+          result << tool unless tool.nil?
+        end
+      end
+      result
     end
 
     def get_tool_data(words)
@@ -364,14 +392,16 @@ module Toys
     def finish_definitions_in_tree(words)
       load_for_prefix(words)
       len = words.length
-      tool_data_snapshot.each do |n, td|
-        next if n.length < len || n.slice(0, len) != words
-        td.cur_definition&.finish_definition(self)
+      all_cur_definitions.each do |tool|
+        name = tool.full_name
+        next if name.length < len || name.slice(0, len) != words
+        tool.finish_definition(self)
       end
     end
 
     def load_proc(source, words, remaining_words, priority)
       if remaining_words
+        update_min_loaded_priority(priority)
         tool_class = get_tool(words, priority).tool_class
         DSL::Tool.prepare(tool_class, remaining_words, source) do
           ContextualError.capture("Error while loading Toys config!") do
@@ -393,6 +423,7 @@ module Toys
 
     def load_relevant_path(source, words, remaining_words, priority)
       if source.source_type == :file
+        update_min_loaded_priority(priority)
         tool_class = get_tool(words, priority).tool_class
         InputFile.evaluate(tool_class, remaining_words, source)
       else
@@ -406,7 +437,7 @@ module Toys
 
     def load_index_in(source, words, remaining_words, priority)
       return unless @index_file_name
-      index_source = source.relative_child(@index_file_name, @data_dir_name, @lib_dir_name)
+      index_source = source.relative_child(@index_file_name)
       load_relevant_path(index_source, words, remaining_words, priority) if index_source
     end
 
@@ -414,7 +445,7 @@ module Toys
       return if child.start_with?(".") || child == @index_file_name ||
                 child == @preload_file_name || child == @preload_dir_name ||
                 child == @data_dir_name || child == @lib_dir_name
-      child_source = source.relative_child(child, @data_dir_name, @lib_dir_name)
+      child_source = source.relative_child(child)
       return unless child_source
       child_word = ::File.basename(child, ".rb")
       next_words = words + [child_word]
@@ -422,6 +453,10 @@ module Toys
       load_validated_path(child_source, next_words, next_remaining, priority)
     end
 
+    def update_min_loaded_priority(priority)
+      @min_loaded_priority = priority if @min_loaded_priority > priority
+    end
+
     def do_preload(path)
       if @preload_file_name
         preload_file = ::File.join(path, @preload_file_name)
@@ -483,37 +518,42 @@ module Toys
     # @private
     #
     class ToolData
-      ## @private
+      # @private
       def initialize(words)
         @words = words
         @definitions = {}
         @top_priority = @active_priority = nil
+        @mutex = ::Monitor.new
       end
 
-      ## @private
+      # @private
       def cur_definition
-        active_definition || top_definition
+        @mutex.synchronize { active_definition || top_definition }
       end
 
-      ## @private
+      # @private
       def empty?
         @definitions.empty?
       end
 
-      ## @private
+      # @private
       def get_tool(priority, loader)
-        if @top_priority.nil? || @top_priority < priority
-          @top_priority = priority
+        @mutex.synchronize do
+          if @top_priority.nil? || @top_priority < priority
+            @top_priority = priority
+          end
+          @definitions[priority] ||= loader.build_tool(@words, priority)
         end
-        @definitions[priority] ||= loader.build_tool(@words, priority)
       end
 
-      ## @private
+      # @private
       def activate_tool(priority, loader)
-        return active_definition if @active_priority == priority
-        return nil if @active_priority && @active_priority > priority
-        @active_priority = priority
-        get_tool(priority, loader)
+        @mutex.synchronize do
+          return active_definition if @active_priority == priority
+          return nil if @active_priority && @active_priority > priority
+          @active_priority = priority
+          get_tool(priority, loader)
+        end
       end
 
       private

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

@@ -11,32 +11,51 @@ module Toys
     #     defining the tool. If `false` (the default), installs the bundle just
     #     before the tool runs.
     #
-    #  *  `:groups` (Array<String>) The groups to include in setup
+    #  *  `:groups` (Array\<String\>) The groups to include in setup.
     #
-    #  *  `:search_dirs` (Array<String,Symbol>) Directories to search for a
-    #     Gemfile.
+    #  *  `: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)
@@ -45,68 +64,106 @@ module Toys
     module Bundler
       include Mixin
 
-      on_initialize do |static: false, search_dirs: nil, **kwargs|
+      on_initialize do |static: false, **kwargs|
         unless static
-          require "toys/utils/gems"
-          search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(
-            search_dirs,
-            self[::Toys::Context::Key::CONTEXT_DIRECTORY],
-            self[::Toys::Context::Key::TOOL_SOURCE]
-          )
-          ::Toys::StandardMixins::Bundler.setup_bundle(search_dirs, **kwargs)
+          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, search_dirs: nil, **kwargs|
+      on_include do |static: false, **kwargs|
         if static
-          require "toys/utils/gems"
-          search_dirs = ::Toys::StandardMixins::Bundler.resolve_search_dirs(
-            search_dirs, context_directory, source_info
-          )
-          ::Toys::StandardMixins::Bundler.setup_bundle(search_dirs, **kwargs)
+          ::Toys::StandardMixins::Bundler.setup_bundle(context_directory, source_info, **kwargs)
         end
       end
 
-      ## @private
-      def self.resolve_search_dirs(search_dirs, context_dir, source_info)
-        search_dirs ||= [:toys, :context, :current]
-        Array(search_dirs).flat_map do |dir|
-          case dir
-          when :context
-            context_dir
-          when :current
-            ::Dir.getwd
-          when :toys
-            toys_dir_stack(source_info)
-          when ::String
-            dir
-          else
-            raise ::ArgumentError, "Unrecognized search_dir: #{dir.inspect}"
-          end
-        end
-      end
+      ##
+      # Default search directories for Gemfiles.
+      # @return [Array<String,Symbol>]
+      #
+      DEFAULT_SEARCH_DIRS = [:toys, :context, :current].freeze
 
-      ## @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
-        end
-        dirs
-      end
+      ##
+      # 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(search_dirs,
+      # @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"
+        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
+      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
+            search(@context_directory)
+          when :current
+            search(::Dir.getwd)
+          when :toys
+            search_toys
+          else
+            raise ::ArgumentError, "Unrecognized search_dir: #{dir.inspect}"
+          end
+        end
+
+        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
       end
     end
   end

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

data/lib/toys/utils/gems.rb

@@ -71,6 +71,12 @@ module Toys
       class IncompatibleToysError < BundlerFailedError
       end
 
+      ##
+      # The gemfile names that are searched by default.
+      # @return [Array<String>]
+      #
+      DEFAULT_GEMFILE_NAMES = [".gems.rb", "gems.rb", "Gemfile"].freeze
+
       ##
       # Activate the given gem. If it is not present, attempt to install it (or
       # inform the user to update the bundle).
@@ -149,16 +155,33 @@ module Toys
       end
 
       ##
-      # Set up the bundle.
+      # Search for an appropriate Gemfile, and set up the bundle.
+      #
+      # @param groups [Array<String>] The groups to include in setup.
+      #
+      # @param gemfile_path [String] The path to the Gemfile to use. If `nil`
+      #     or not given, the `:search_dirs` will be searched for a Gemfile.
+      #
+      # @param search_dirs [String,Array<String>] Directories in which to
+      #     search for a Gemfile, if gemfile_path is not given. You can provide
+      #     a single directory or an array of directories.
+      #
+      # @param gemfile_names [String,Array<String>] File names that are
+      #     recognized as Gemfiles, when searching because gemfile_path is not
+      #     given. Defaults to {DEFAULT_GEMFILE_NAMES}.
       #
-      # @param groups [Array<String>] The groups to include in setup
-      # @param search_dirs [Array<String>] Directories to search for a Gemfile
       # @return [void]
       #
       def bundle(groups: nil,
-                 search_dirs: nil)
+                 gemfile_path: nil,
+                 search_dirs: nil,
+                 gemfile_names: nil)
+        Array(search_dirs).each do |dir|
+          break if gemfile_path
+          gemfile_path = Gems.find_gemfile(dir, gemfile_names: gemfile_names)
+        end
+        raise GemfileNotFoundError, "Gemfile not found" unless gemfile_path
         Gems.synchronize do
-          gemfile_path = find_gemfile(Array(search_dirs))
           if configure_gemfile(gemfile_path)
             activate("bundler", "~> 2.1")
             require "bundler"
@@ -167,9 +190,19 @@ module Toys
         end
       end
 
+      # @private
+      def self.find_gemfile(search_dir, gemfile_names: nil)
+        gemfile_names ||= DEFAULT_GEMFILE_NAMES
+        Array(gemfile_names).each do |file|
+          gemfile_path = ::File.join(search_dir, file)
+          return gemfile_path if ::File.readable?(gemfile_path)
+        end
+        nil
+      end
+
       @global_mutex = ::Monitor.new
 
-      ## @private
+      # @private
       def self.synchronize(&block)
         @global_mutex.synchronize(&block)
       end
@@ -237,14 +270,6 @@ module Toys
         raise ActivationFailedError, err.message
       end
 
-      def find_gemfile(search_dirs)
-        search_dirs.each do |dir|
-          gemfile_path = ::File.join(dir, "Gemfile")
-          return gemfile_path if ::File.readable?(gemfile_path)
-        end
-        raise GemfileNotFoundError, "Gemfile not found"
-      end
-
       def configure_gemfile(gemfile_path)
         old_path = ::ENV["BUNDLE_GEMFILE"]
         if old_path

data/lib/toys/utils/help_text.rb

@@ -32,14 +32,13 @@ module Toys
       # @return [Toys::Utils::HelpText]
       #
       def self.from_context(context)
-        orig_context = context
-        while (from = context[Context::Key::DELEGATED_FROM])
-          context = from
+        delegates = []
+        cur = context
+        while (cur = cur[Context::Key::DELEGATED_FROM])
+          delegates << cur[Context::Key::TOOL]
         end
-        delegate_target = orig_context == context ? nil : orig_context[Context::Key::TOOL_NAME]
         cli = context[Context::Key::CLI]
-        new(context[Context::Key::TOOL], cli.loader, cli.executable_name,
-            delegate_target: delegate_target)
+        new(context[Context::Key::TOOL], cli.loader, cli.executable_name, delegates: delegates)
       end
 
       ##
@@ -49,16 +48,15 @@ module Toys
       # @param loader [Toys::Loader] A loader that can provide subcommands.
       # @param executable_name [String] The name of the executable.
       #     e.g. `"toys"`.
-      # @param delegate_target [Array<String>,nil] The full name of a tool this
-      #     tool will delegate to. Default is `nil` for no delegation.
+      # @param delegates [Array<Toys::Tool>] The delegation path to the tool.
       #
       # @return [Toys::Utils::HelpText]
       #
-      def initialize(tool, loader, executable_name, delegate_target: nil)
+      def initialize(tool, loader, executable_name, delegates: [])
         @tool = tool
         @loader = loader
         @executable_name = executable_name
-        @delegate_target = delegate_target
+        @delegates = delegates
       end
 
       ##
@@ -88,8 +86,7 @@ module Toys
         indent ||= DEFAULT_INDENT
         subtools = find_subtools(recursive, nil, include_hidden)
         assembler = UsageStringAssembler.new(
-          @tool, @executable_name, @delegate_target, subtools,
-          indent, left_column_width, wrap_width
+          @tool, @executable_name, subtools, indent, left_column_width, wrap_width
         )
         assembler.result
       end
@@ -121,7 +118,7 @@ module Toys
         indent2 ||= DEFAULT_INDENT
         subtools = find_subtools(recursive, search, include_hidden)
         assembler = HelpStringAssembler.new(
-          @tool, @executable_name, @delegate_target, subtools, search, show_source_path,
+          @tool, @executable_name, @delegates, subtools, search, show_source_path,
           indent, indent2, wrap_width, styled
         )
         assembler.result
@@ -155,22 +152,29 @@ module Toys
       private
 
       def find_subtools(recursive, search, include_hidden)
-        subtools = @loader.list_subtools(@tool.full_name,
-                                         recursive: recursive, include_hidden: include_hidden)
-        return subtools if search.nil? || search.empty?
+        subtools_by_name = {}
+        ([@tool] + @delegates).each do |tool|
+          name_len = tool.full_name.length
+          subtools = @loader.list_subtools(tool.full_name,
+                                           recursive: recursive, include_hidden: include_hidden)
+          subtools.each do |subtool|
+            local_name = subtool.full_name.slice(name_len..-1).join(" ")
+            subtools_by_name[local_name] = subtool
+          end
+        end
+        subtool_list = subtools_by_name.sort_by { |(local_name, _tool)| local_name }
+        return subtool_list if search.nil? || search.empty?
         regex = ::Regexp.new(search, ::Regexp::IGNORECASE)
-        subtools.find_all do |tool|
-          regex =~ tool.display_name || regex =~ tool.desc.to_s
+        subtool_list.find_all do |local_name, tool|
+          regex =~ local_name || regex =~ tool.desc.to_s
         end
       end
 
       ## @private
       class UsageStringAssembler
-        def initialize(tool, executable_name, delegate_target, subtools,
-                       indent, left_column_width, wrap_width)
+        def initialize(tool, executable_name, subtools, indent, left_column_width, wrap_width)
           @tool = tool
           @executable_name = executable_name
-          @delegate_target = delegate_target
           @subtools = subtools
           @indent = indent
           @left_column_width = left_column_width
@@ -195,7 +199,7 @@ module Toys
         def add_synopsis_section
           synopses = []
           synopses << namespace_synopsis unless @subtools.empty?
-          synopses << (@delegate_target ? delegate_synopsis : tool_synopsis)
+          synopses << tool_synopsis
           first = true
           synopses.each do |synopsis|
             @lines << (first ? "Usage:  #{synopsis}" : "        #{synopsis}")
@@ -212,11 +216,6 @@ module Toys
           synopsis.join(" ")
         end
 
-        def delegate_synopsis
-          target = @delegate_target.join(" ")
-          "#{@executable_name} #{@tool.display_name} [ARGUMENTS FOR \"#{target}\"...]"
-        end
-
         def namespace_synopsis
           "#{@executable_name} #{@tool.display_name} TOOL [ARGUMENTS...]"
         end
@@ -256,12 +255,10 @@ module Toys
 
         def add_subtool_list_section
           return if @subtools.empty?
-          name_len = @tool.full_name.length
           @lines << ""
           @lines << "Tools:"
-          @subtools.each do |subtool|
-            tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            add_right_column_desc(tool_name, wrap_desc(subtool.desc))
+          @subtools.each do |local_name, subtool|
+            add_right_column_desc(local_name, wrap_desc(subtool.desc))
           end
         end
 
@@ -301,12 +298,12 @@ module Toys
 
       ## @private
       class HelpStringAssembler
-        def initialize(tool, executable_name, delegate_target, subtools, search_term,
+        def initialize(tool, executable_name, delegates, subtools, search_term,
                        show_source_path, indent, indent2, wrap_width, styled)
           require "toys/utils/terminal"
           @tool = tool
           @executable_name = executable_name
-          @delegate_target = delegate_target
+          @delegates = delegates
           @subtools = subtools
           @search_term = search_term
           @show_source_path = show_source_path
@@ -356,7 +353,7 @@ module Toys
           @lines << ""
           @lines << bold("SYNOPSIS")
           add_synopsis_clause(namespace_synopsis) unless @subtools.empty?
-          add_synopsis_clause(@delegate_target ? delegate_synopsis : tool_synopsis)
+          add_synopsis_clause(tool_synopsis(@tool))
         end
 
         def add_synopsis_clause(synopsis)
@@ -367,8 +364,8 @@ module Toys
           end
         end
 
-        def tool_synopsis
-          synopsis = [full_executable_name]
+        def tool_synopsis(tool_for_name)
+          synopsis = [full_executable_name(tool_for_name)]
           @tool.flag_groups.each do |flag_group|
             case flag_group
             when FlagGroup::Required
@@ -441,19 +438,14 @@ module Toys
         end
 
         def namespace_synopsis
-          synopsis = [full_executable_name, underline("TOOL"), "[#{underline('ARGUMENTS')}...]"]
+          synopsis = [full_executable_name(@tool),
+                      underline("TOOL"),
+                      "[#{underline('ARGUMENTS')}...]"]
           wrap_indent_indent2(WrappableString.new(synopsis))
         end
 
-        def delegate_synopsis
-          target = @delegate_target.join(" ")
-          args_clause = underline("ARGUMENTS FOR \"#{target}\"")
-          synopsis = [full_executable_name, "[#{args_clause}...]"]
-          wrap_indent_indent2(WrappableString.new(synopsis))
-        end
-
-        def full_executable_name
-          bold(([@executable_name] + @tool.full_name).join(" "))
+        def full_executable_name(tool_for_name)
+          bold(([@executable_name] + tool_for_name.full_name).join(" "))
         end
 
         def add_source_section
@@ -461,15 +453,22 @@ module Toys
           @lines << ""
           @lines << bold("SOURCE")
           @lines << indent_str("Defined in #{@tool.source_info.source_name}")
+          @delegates.each do |delegate|
+            @lines << indent_str("Delegated from \"#{delegate.display_name}\"" \
+                                 " defined in #{delegate.source_info.source_name}")
+          end
         end
 
         def add_description_section
-          desc = @tool.long_desc
-          if @delegate_target
-            delegate_clause =
-              "Passes all arguments to \"#{@delegate_target.join(' ')}\" if invoked directly."
-            desc = desc.empty? ? [delegate_clause] : desc + ["", delegate_clause]
+          desc = @tool.long_desc.dup
+          @delegates.each do |delegate|
+            desc << "" << "Delegated from \"#{delegate.display_name}\""
+            unless delegate.long_desc.empty?
+              desc << ""
+              desc += delegate.long_desc
+            end
           end
+          desc = desc[1..-1] if desc.first == ""
           desc = wrap_indent(desc)
           return if desc.empty?
           @lines << ""
@@ -533,10 +532,8 @@ module Toys
             @lines << indent_str("Showing search results for \"#{@search_term}\"")
             @lines << ""
           end
-          name_len = @tool.full_name.length
-          @subtools.each do |subtool|
-            tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            add_prefix_with_desc(bold(tool_name), subtool.desc)
+          @subtools.each do |local_name, subtool|
+            add_prefix_with_desc(bold(local_name), subtool.desc)
           end
         end
 
@@ -637,10 +634,8 @@ module Toys
         end
 
         def add_list
-          name_len = @tool.full_name.length
-          @subtools.each do |subtool|
-            tool_name = subtool.full_name.slice(name_len..-1).join(" ")
-            add_prefix_with_desc(bold(tool_name), subtool.desc)
+          @subtools.each do |local_name, subtool|
+            add_prefix_with_desc(bold(local_name), subtool.desc)
           end
         end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.10.5
+  version: 0.11.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-19 00:00:00.000000000 Z
+date: 2020-08-21 00:00:00.000000000 Z
 dependencies: []
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
@@ -69,10 +69,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.10.5/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.11.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.10.5
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.11.0
 post_install_message: 
 rdoc_options: []
 require_paths: