toys-core 0.11.5 → 0.13.0

data/lib/toys/source_info.rb

@@ -2,28 +2,10 @@
 
 module Toys
   ##
-  # Information about source toys directories and files.
+  # Information about the source of a tool, such as the file, git repository,
+  # or block that defined it.
   #
   class SourceInfo
-    ##
-    # Create a SourceInfo.
-    # @private
-    #
-    def initialize(parent, context_directory, source_type, source_path, source_proc,
-                   source_name, data_dir_name, lib_dir_name)
-      @parent = parent
-      @context_directory = context_directory
-      @source_type = source_type
-      @source = source_type == :proc ? source_proc : source_path
-      @source_path = source_path
-      @source_proc = source_proc
-      @source_name = source_name
-      @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
-
     ##
     # The parent of this SourceInfo.
     #
@@ -32,6 +14,21 @@ module Toys
     #
     attr_reader :parent
 
+    ##
+    # The root ancestor of this SourceInfo.
+    #
+    # @return [Toys::SourceInfo] The root ancestor.
+    #
+    attr_reader :root
+
+    ##
+    # The priority of tools defined by this source. Higher values indicate a
+    # higher priority. Lower priority values could be negative.
+    #
+    # @return [Integer] The priority.
+    #
+    attr_reader :priority
+
     ##
     # The context directory path (normally the directory containing the
     # toplevel toys file or directory).
@@ -73,6 +70,30 @@ module Toys
     #
     attr_reader :source_proc
 
+    ##
+    # The git remote.
+    #
+    # @return [String] The git remote
+    # @return [nil] if this source is not fron git.
+    #
+    attr_reader :git_remote
+
+    ##
+    # The git path.
+    #
+    # @return [String] The git path. This could be the empty string.
+    # @return [nil] if this source is not fron git.
+    #
+    attr_reader :git_path
+
+    ##
+    # The git commit.
+    #
+    # @return [String] The git commit.
+    # @return [nil] if this source is not fron git.
+    #
+    attr_reader :git_commit
+
     ##
     # The user-visible name of this source.
     #
@@ -116,59 +137,150 @@ module Toys
       self
     end
 
+    ##
+    # Create a SourceInfo.
+    #
+    # @private
+    #
+    def initialize(parent, priority, context_directory, source_type, source_path, source_proc,
+                   git_remote, git_path, git_commit, source_name, data_dir_name, lib_dir_name)
+      @parent = parent
+      @root = parent&.root || self
+      @priority = priority
+      @context_directory = context_directory
+      @source_type = source_type
+      @source = source_type == :proc ? source_proc : source_path
+      @source_path = source_path
+      @source_proc = source_proc
+      @git_remote = git_remote
+      @git_path = git_path
+      @git_commit = git_commit
+      @source_name = source_name
+      @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
+
     ##
     # Create a child SourceInfo relative to the parent path.
+    #
     # @private
     #
-    def relative_child(filename)
-      raise "relative_child is valid only on a directory source" unless source_type == :directory
+    def relative_child(filename, source_name: nil)
+      unless source_type == :directory
+        raise LoaderError, "relative_child is valid only on a directory source"
+      end
       child_path = ::File.join(source_path, filename)
       child_path, type = SourceInfo.check_path(child_path, true)
       return nil unless child_path
-      SourceInfo.new(self, context_directory, type, child_path, nil, child_path,
-                     @data_dir_name, @lib_dir_name)
+      child_git_path = ::File.join(git_path, filename) if git_path
+      source_name ||=
+        if git_path
+          "git(remote=#{git_remote} path=#{child_git_path} commit=#{git_commit})"
+        else
+          child_path
+        end
+      SourceInfo.new(self, priority, context_directory, type, child_path, nil,
+                     git_remote, child_git_path, git_commit,
+                     source_name, @data_dir_name, @lib_dir_name)
     end
 
     ##
     # Create a child SourceInfo with an absolute path.
+    #
     # @private
     #
-    def absolute_child(child_path)
+    def absolute_child(child_path, source_name: nil)
       child_path, type = SourceInfo.check_path(child_path, false)
-      SourceInfo.new(self, context_directory, type, child_path, nil, child_path,
-                     @data_dir_name, @lib_dir_name)
+      source_name ||= child_path
+      SourceInfo.new(self, priority, context_directory, type, child_path, nil, nil, nil, nil,
+                     source_name, @data_dir_name, @lib_dir_name)
+    end
+
+    ##
+    # Create a child SourceInfo with a git source.
+    #
+    # @private
+    #
+    def git_child(child_git_remote, child_git_path, child_git_commit, child_path,
+                  source_name: nil)
+      child_path, type = SourceInfo.check_path(child_path, false)
+      source_name ||=
+        "git(remote=#{child_git_remote} path=#{child_git_path} commit=#{child_git_commit})"
+      SourceInfo.new(self, priority, context_directory, type, child_path, nil,
+                     child_git_remote, child_git_path, child_git_commit,
+                     source_name, @data_dir_name, @lib_dir_name)
     end
 
     ##
     # Create a proc child SourceInfo
+    #
     # @private
     #
-    def proc_child(child_proc, source_name = nil)
+    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,
-                     @data_dir_name, @lib_dir_name)
+      SourceInfo.new(self, priority, context_directory, :proc, source_path, child_proc,
+                     git_remote, git_path, git_commit,
+                     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, data_dir_name, lib_dir_name)
+    def self.create_path_root(source_path, priority,
+                              context_directory: nil,
+                              data_dir_name: nil,
+                              lib_dir_name: nil,
+                              source_name: nil)
       source_path, type = check_path(source_path, false)
-      context_directory = ::File.dirname(source_path)
-      new(nil, context_directory, type, source_path, nil, source_path, data_dir_name, lib_dir_name)
+      case context_directory
+      when :parent
+        context_directory = ::File.dirname(source_path)
+      when :path
+        context_directory = source_path
+      end
+      source_name ||= source_path
+      new(nil, priority, context_directory, type, source_path, nil, nil, nil, nil,
+          source_name, data_dir_name, lib_dir_name)
+    end
+
+    ##
+    # Create a root source info for a cached git repo.
+    #
+    # @private
+    #
+    def self.create_git_root(git_remote, git_path, git_commit, source_path, priority,
+                             context_directory: nil,
+                             data_dir_name: nil,
+                             lib_dir_name: nil,
+                             source_name: nil)
+      source_path, type = check_path(source_path, false)
+      source_name ||= "git(remote=#{git_remote} path=#{git_path} commit=#{git_commit})"
+      new(nil, priority, context_directory, type, source_path, nil, git_remote,
+          git_path, git_commit, source_name, 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, data_dir_name, lib_dir_name)
-      new(nil, nil, :proc, nil, source_proc, source_name, data_dir_name, lib_dir_name)
+    def self.create_proc_root(source_proc, priority,
+                              context_directory: nil,
+                              data_dir_name: nil,
+                              lib_dir_name: nil,
+                              source_name: nil)
+      source_name ||= "(code block #{source_proc.object_id})"
+      new(nil, priority, context_directory, :proc, nil, source_proc, nil, nil,
+          nil, source_name, data_dir_name, lib_dir_name)
     end
 
     ##
     # Check a path and determine the canonical path and type.
+    #
     # @private
     #
     def self.check_path(path, lenient)

data/lib/toys/standard_middleware/add_verbosity_flags.rb

@@ -48,6 +48,7 @@ module Toys
 
       ##
       # Configure the tool flags.
+      #
       # @private
       #
       def config(tool, _loader)
@@ -63,6 +64,7 @@ module Toys
 
       INCREMENT_HANDLER = ->(_val, cur) { cur.to_i + 1 }
       DECREMENT_HANDLER = ->(_val, cur) { cur.to_i - 1 }
+      private_constant :INCREMENT_HANDLER, :DECREMENT_HANDLER
 
       def add_verbose_flags(tool)
         verbose_flags = resolve_flags_spec(@verbose_flags, tool, DEFAULT_VERBOSE_FLAGS)

data/lib/toys/standard_middleware/apply_config.rb

@@ -19,20 +19,22 @@ module Toys
       def initialize(parent_source: nil, source_name: nil, &block)
         @source_info =
           if parent_source
-            parent_source.proc_child(block, source_name)
+            parent_source.proc_child(block, source_name: source_name)
           else
-            SourceInfo.create_proc_root(block, source_name)
+            SourceInfo.create_proc_root(block, source_name: source_name)
           end
         @block = block
       end
 
       ##
       # Appends the configuration block.
+      #
       # @private
       #
-      def config(tool, _loader)
+      def config(tool, loader)
         tool_class = tool.tool_class
-        DSL::Tool.prepare(tool_class, nil, @source_info) do
+        DSL::Internal.prepare(tool_class, tool.full_name, tool.priority, nil, @source_info,
+                              loader) do
           tool_class.class_eval(&@block)
         end
         yield

data/lib/toys/standard_middleware/handle_usage_errors.rb

@@ -33,6 +33,7 @@ module Toys
 
       ##
       # Intercept and handle usage errors during execution.
+      #
       # @private
       #
       def run(context)

data/lib/toys/standard_middleware/set_default_descriptions.rb

@@ -90,6 +90,7 @@ module Toys
 
       ##
       # Add default description text to tools.
+      #
       # @private
       #
       def config(tool, loader)
@@ -115,12 +116,12 @@ module Toys
       # By default, it uses the parameters given to the middleware object.
       # Override this method to provide different logic.
       #
-      # @param tool [Toys::Tool] The tool to document.
+      # @param tool [Toys::ToolDefinition] The tool to document.
       # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Loader} is passed with key `:loader`. Future versions
       #     of Toys may provide additional information.
       # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::Tool#desc=} for info on the format.
+      #     description. See {Toys::DSL::Tool#desc} for info on the format.
       # @return [nil] if this middleware should not set the description.
       #
       def generate_tool_desc(tool, data)
@@ -141,12 +142,12 @@ module Toys
       # By default, it uses the parameters given to the middleware object.
       # Override this method to provide different logic.
       #
-      # @param tool [Toys::Tool] The tool to document
+      # @param tool [Toys::ToolDefinition] The tool to document
       # @param data [Hash] Additional data that might be useful. Currently,
       #     the {Toys::Loader} is passed with key `:loader`. Future versions of
       #     Toys may provide additional information.
       # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
       #     format.
       # @return [nil] if this middleware should not set the long description.
       #
@@ -166,10 +167,10 @@ module Toys
       #
       # @param flag [Toys::Flag] The flag to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
       #     versions of Toys may provide additional information.
       # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::Tool#desc=} for info on the format.
+      #     description. See {Toys::DSL::Tool#desc} for info on the format.
       # @return [nil] if this middleware should not set the description.
       #
       def generate_flag_desc(flag, data) # rubocop:disable Lint/UnusedMethodArgument
@@ -185,10 +186,10 @@ module Toys
       #
       # @param flag [Toys::Flag] The flag to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
       #     versions of Toys may provide additional information.
       # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
       #     format.
       # @return [nil] if this middleware should not set the long description.
       #
@@ -202,10 +203,10 @@ module Toys
       #
       # @param arg [Toys::PositionalArg] The arg to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
-      #     Toys may provide additional information.
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
+      #     versions of Toys may provide additional information.
       # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::Tool#desc=} for info on the format.
+      #     description. See {Toys::DSL::Tool#desc} for info on the format.
       # @return [nil] if this middleware should not set the description.
       #
       def generate_arg_desc(arg, data) # rubocop:disable Lint/UnusedMethodArgument
@@ -227,10 +228,10 @@ module Toys
       #
       # @param arg [Toys::PositionalArg] The arg to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future versions of
-      #     Toys may provide additional information.
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
+      #     versions of Toys may provide additional information.
       # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
       #     format.
       # @return [nil] if this middleware should not set the long description.
       #
@@ -244,10 +245,10 @@ module Toys
       #
       # @param group [Toys::FlagGroup] The flag group to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
       #     versions of Toys may provide additional information.
       # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::Tool#desc=} for info on the format.
+      #     description. See {Toys::DSL::Tool#desc} for info on the format.
       # @return [nil] if this middleware should not set the description.
       #
       def generate_flag_group_desc(group, data) # rubocop:disable Lint/UnusedMethodArgument
@@ -264,10 +265,10 @@ module Toys
       #
       # @param group [Toys::FlagGroup] The flag group to document
       # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Tool} is passed with key `:tool`. Future
+      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
       #     versions of Toys may provide additional information.
       # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::Tool#long_desc=} for info on the
+      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
       #     format.
       # @return [nil] if this middleware should not set the long description.
       #

data/lib/toys/standard_middleware/show_help.rb

@@ -159,6 +159,8 @@ module Toys
       #     that tool.
       # @param show_source_path [Boolean] Show the source path section. Default
       #     is `false`.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
       # @param use_less [Boolean] If the `less` tool is available, and the
       #     output stream is a tty, then use `less` to display help text.
       # @param stream [IO] Output stream to write to. Default is stdout.
@@ -177,6 +179,7 @@ module Toys
                      fallback_execution: false,
                      allow_root_args: false,
                      show_source_path: false,
+                     separate_sources: false,
                      use_less: false,
                      stream: $stdout,
                      styled_output: nil)
@@ -191,6 +194,7 @@ module Toys
         @fallback_execution = fallback_execution
         @allow_root_args = allow_root_args
         @show_source_path = show_source_path
+        @separate_sources = separate_sources
         @stream = stream
         @styled_output = styled_output
         @use_less = use_less && !Compat.jruby?
@@ -198,6 +202,7 @@ module Toys
 
       ##
       # Configure flags and default data.
+      #
       # @private
       #
       def config(tool, loader)
@@ -220,6 +225,7 @@ module Toys
 
       ##
       # Display help text if requested.
+      #
       # @private
       #
       def run(context)
@@ -250,7 +256,9 @@ module Toys
         help_text = get_help_text(context, true)
         str = help_text.usage_string(
           recursive: context[RECURSIVE_SUBTOOLS_KEY],
-          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], wrap_width: terminal.width
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY],
+          separate_sources: @separate_sources,
+          wrap_width: terminal.width
         )
         terminal.puts(str)
       end
@@ -258,8 +266,11 @@ module Toys
       def show_list(context)
         help_text = get_help_text(context, true)
         str = help_text.list_string(
-          recursive: context[RECURSIVE_SUBTOOLS_KEY], search: context[SEARCH_STRING_KEY],
-          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], wrap_width: terminal.width
+          recursive: context[RECURSIVE_SUBTOOLS_KEY],
+          search: context[SEARCH_STRING_KEY],
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY],
+          separate_sources: @separate_sources,
+          wrap_width: terminal.width
         )
         terminal.puts(str)
       end
@@ -267,8 +278,11 @@ module Toys
       def show_help(context, use_extra_args)
         help_text = get_help_text(context, use_extra_args)
         str = help_text.help_string(
-          recursive: context[RECURSIVE_SUBTOOLS_KEY], search: context[SEARCH_STRING_KEY],
-          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], show_source_path: @show_source_path,
+          recursive: context[RECURSIVE_SUBTOOLS_KEY],
+          search: context[SEARCH_STRING_KEY],
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY],
+          show_source_path: @show_source_path,
+          separate_sources: @separate_sources,
           wrap_width: terminal.width
         )
         if less_path

data/lib/toys/standard_middleware/show_root_version.rb

@@ -46,6 +46,7 @@ module Toys
 
       ##
       # Adds the version flag if requested.
+      #
       # @private
       #
       def config(tool, _loader)
@@ -58,6 +59,7 @@ module Toys
 
       ##
       # This middleware displays the version.
+      #
       # @private
       #
       def run(context)

data/lib/toys/standard_mixins/bundler.rb

@@ -67,20 +67,6 @@ module Toys
     module Bundler
       include Mixin
 
-      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>]
@@ -93,7 +79,9 @@ module Toys
       #
       DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
 
+      ##
       # @private
+      #
       def self.setup_bundle(context_directory,
                             source_info,
                             gemfile_path: nil,
@@ -118,9 +106,27 @@ module Toys
         gems.bundle(groups: groups, gemfile_path: gemfile_path, retries: retries)
       end
 
+      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
+
+      ##
       # @private
+      #
       class GemfileFinder
+        ##
         # @private
+        #
         def initialize(context_directory, source_info, gemfile_names, toys_gemfile_names)
           @context_directory = context_directory
           @source_info = source_info
@@ -128,7 +134,9 @@ module Toys
           @toys_gemfile_names = toys_gemfile_names || DEFAULT_TOYS_GEMFILE_NAMES
         end
 
+        ##
         # @private
+        #
         def search(search_dir)
           case search_dir
           when ::Array
@@ -159,7 +167,8 @@ module Toys
         def search_toys
           source_info = @source_info
           while source_info
-            if source_info.source_type == :directory
+            if source_info.source_type == :directory &&
+               source_info.source_path != source_info.context_directory
               result = ::Toys::Utils::Gems.find_gemfile(source_info.source_path,
                                                         gemfile_names: @toys_gemfile_names)
               return result if result