toys-core 0.11.5 → 0.12.0

data/lib/toys/source_info.rb

@@ -2,21 +2,27 @@
 
 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)
+    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
@@ -32,6 +38,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 +94,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.
     #
@@ -120,51 +165,109 @@ module Toys
     # 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)
+      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)
-      SourceInfo.new(self, context_directory, type, child_path, nil, child_path,
-                     @data_dir_name, @lib_dir_name)
+      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)
+      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)
-      context_directory = ::File.dirname(source_path)
-      new(nil, context_directory, type, source_path, nil, source_path, data_dir_name, lib_dir_name)
+      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
 
     ##

data/lib/toys/standard_middleware/apply_config.rb

@@ -19,9 +19,9 @@ 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
@@ -30,9 +30,10 @@ module Toys
       # 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/set_default_descriptions.rb

@@ -115,12 +115,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 +141,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 +166,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 +185,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 +202,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 +227,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 +244,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 +264,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?
@@ -250,7 +254,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 +264,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 +276,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_mixins/exec.rb

@@ -16,8 +16,6 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
-    # ## Features
-    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -149,7 +147,7 @@ module Toys
     #
     #     include :exec, exit_on_nonzero_status: true
     #
-    # ## Configuration Options
+    # ### Configuration Options
     #
     # A variety of options can be used to control subprocesses. These can be
     # provided to any method that starts a subprocess. You can also set
@@ -267,7 +265,7 @@ 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.
       #
-      # ## Examples
+      # ### Examples
       #
       # Run a command without a shell, and print the exit code (0 for success):
       #
@@ -303,7 +301,7 @@ 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.
       #
-      # ## Example
+      # ### Example
       #
       # Execute a small script with warnings
       #
@@ -337,7 +335,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run a proc in a forked process.
       #
@@ -377,7 +375,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system update" tool and pass it an argument.
       #
@@ -424,7 +422,7 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system update" tool and pass it an argument.
       #
@@ -459,7 +457,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Capture the output of an echo command
       #
@@ -490,7 +488,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Capture the output of a ruby script.
       #
@@ -524,7 +522,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run a proc in a forked process and capture its output:
       #
@@ -564,7 +562,7 @@ module Toys
       # Beware that some Ruby environments (e.g. JRuby, and Ruby on Windows)
       # do not support this method because they do not support fork.
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system version" tool and capture its output.
       #
@@ -612,7 +610,7 @@ module Toys
       # run a tool that uses a different bundle. It may also be necessary on
       # environments without "fork" (such as JRuby or Ruby on Windows).
       #
-      # ## Example
+      # ### Example
       #
       # Run the "system version" tool and capture its output.
       #
@@ -642,7 +640,7 @@ module Toys
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
       # yielded to it.
       #
-      # ## Example
+      # ### Example
       #
       # Run a shell script
       #