toys-core 0.11.5 → 0.13.0

data/lib/toys/utils/help_text.rb

@@ -44,11 +44,12 @@ module Toys
       ##
       # Create a usage helper.
       #
-      # @param tool [Toys::Tool] The tool to document.
+      # @param tool [Toys::ToolDefinition] The tool to document.
       # @param loader [Toys::Loader] A loader that can provide subcommands.
       # @param executable_name [String] The name of the executable.
       #     e.g. `"toys"`.
-      # @param delegates [Array<Toys::Tool>] The delegation path to the tool.
+      # @param delegates [Array<Toys::ToolDefinition>] The delegation path to
+      #     the tool.
       #
       # @return [Toys::Utils::HelpText]
       #
@@ -60,8 +61,8 @@ module Toys
       end
 
       ##
-      # The Tool being documented.
-      # @return [Toys::Tool]
+      # The ToolDefinition being documented.
+      # @return [Toys::ToolDefinition]
       #
       attr_reader :tool
 
@@ -72,6 +73,8 @@ module Toys
       #     display all subtools recursively. Defaults to false.
       # @param include_hidden [Boolean] Include hidden subtools (i.e. whose
       #     names begin with underscore.) Default is false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
       # @param left_column_width [Integer] Width of the first column. Default
       #     is {DEFAULT_LEFT_COLUMN_WIDTH}.
       # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
@@ -80,13 +83,14 @@ module Toys
       #
       # @return [String] A usage string.
       #
-      def usage_string(recursive: false, include_hidden: false,
+      def usage_string(recursive: false, include_hidden: false, separate_sources: false,
                        left_column_width: nil, indent: nil, wrap_width: nil)
         left_column_width ||= DEFAULT_LEFT_COLUMN_WIDTH
         indent ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, nil, include_hidden)
+        subtools = collect_subtool_info(recursive, nil, include_hidden, separate_sources)
         assembler = UsageStringAssembler.new(
-          @tool, @executable_name, subtools, indent, left_column_width, wrap_width
+          @tool, @executable_name, subtools, separate_sources,
+          indent, left_column_width, wrap_width
         )
         assembler.result
       end
@@ -102,6 +106,8 @@ module Toys
       #     names begin with underscore.) Default is false.
       # @param show_source_path [Boolean] If true, shows the source path
       #     section. Defaults to false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
       # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
       # @param indent2 [Integer] Second indent width. Default is
       #     {DEFAULT_INDENT}.
@@ -112,13 +118,14 @@ module Toys
       # @return [String] A usage string.
       #
       def help_string(recursive: false, search: nil, include_hidden: false,
-                      show_source_path: false,
+                      show_source_path: false, separate_sources: false,
                       indent: nil, indent2: nil, wrap_width: nil, styled: true)
         indent ||= DEFAULT_INDENT
         indent2 ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, search, include_hidden)
+        subtools = collect_subtool_info(recursive, search, include_hidden, separate_sources)
         assembler = HelpStringAssembler.new(
-          @tool, @executable_name, @delegates, subtools, search, show_source_path,
+          @tool, @executable_name, @delegates, subtools, search,
+          show_source_path, separate_sources,
           indent, indent2, wrap_width, styled
         )
         assembler.result
@@ -133,6 +140,8 @@ module Toys
       #     listing subtools. Defaults to `nil` which finds all subtools.
       # @param include_hidden [Boolean] Include hidden subtools (i.e. whose
       #     names begin with underscore.) Default is false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
       # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
       # @param wrap_width [Integer,nil] Wrap width of the column, or `nil` to
       #     disable wrap. Default is `nil`.
@@ -141,17 +150,23 @@ module Toys
       # @return [String] A usage string.
       #
       def list_string(recursive: false, search: nil, include_hidden: false,
-                      indent: nil, wrap_width: nil, styled: true)
+                      separate_sources: false, indent: nil, wrap_width: nil, styled: true)
         indent ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, search, include_hidden)
-        assembler = ListStringAssembler.new(@tool, subtools, recursive, search,
+        subtools = collect_subtool_info(recursive, search, include_hidden, separate_sources)
+        assembler = ListStringAssembler.new(@tool, subtools, recursive, search, separate_sources,
                                             indent, wrap_width, styled)
         assembler.result
       end
 
       private
 
-      def find_subtools(recursive, search, include_hidden)
+      def collect_subtool_info(recursive, search, include_hidden, separate_sources)
+        subtools_by_name = list_subtools(recursive, include_hidden)
+        filter_subtools(subtools_by_name, search)
+        arrange_subtools(subtools_by_name, separate_sources)
+      end
+
+      def list_subtools(recursive, include_hidden)
         subtools_by_name = {}
         ([@tool] + @delegates).each do |tool|
           name_len = tool.full_name.length
@@ -162,20 +177,42 @@ module Toys
             subtools_by_name[local_name] = subtool
           end
         end
+        subtools_by_name
+      end
+
+      def filter_subtools(subtools_by_name, search)
+        if !search.nil? && !search.empty?
+          regex = ::Regexp.new(search, ::Regexp::IGNORECASE)
+          subtools_by_name.delete_if do |local_name, tool|
+            !regex.match?(local_name) && !regex.match?(tool.desc.to_s)
+          end
+        end
+      end
+
+      def arrange_subtools(subtools_by_name, separate_sources)
         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)
-        subtool_list.find_all do |local_name, tool|
-          regex =~ local_name || regex =~ tool.desc.to_s
+        result = {}
+        subtool_list.each do |(local_name, subtool)|
+          key = separate_sources ? subtool.source_root : nil
+          (result[key] ||= []) << [local_name, subtool]
         end
+        result.sort_by { |source, _subtools| -(source&.priority || -999_999) }
+              .map { |source, subtools| [source&.source_name || "unknown source", subtools] }
       end
 
-      ## @private
+      ##
+      # @private
+      #
       class UsageStringAssembler
-        def initialize(tool, executable_name, subtools, indent, left_column_width, wrap_width)
+        ##
+        # @private
+        #
+        def initialize(tool, executable_name, subtools, separate_sources,
+                       indent, left_column_width, wrap_width)
           @tool = tool
           @executable_name = executable_name
           @subtools = subtools
+          @separate_sources = separate_sources
           @indent = indent
           @left_column_width = left_column_width
           @wrap_width = wrap_width
@@ -184,6 +221,9 @@ module Toys
           assemble
         end
 
+        ##
+        # @private
+        #
         attr_reader :result
 
         private
@@ -193,7 +233,8 @@ module Toys
           add_flag_group_sections
           add_positional_arguments_section if @tool.runnable?
           add_subtool_list_section
-          @result = @lines.join("\n") + "\n"
+          joined_lines = @lines.join("\n")
+          @result = "#{joined_lines}\n"
         end
 
         def add_synopsis_section
@@ -226,7 +267,7 @@ module Toys
             @lines << ""
             desc_str = group.desc.to_s
             desc_str = "Flags" if desc_str.empty?
-            @lines << desc_str + ":"
+            @lines << "#{desc_str}:"
             group.flags.each do |flag|
               add_flag(flag)
             end
@@ -254,11 +295,12 @@ module Toys
         end
 
         def add_subtool_list_section
-          return if @subtools.empty?
-          @lines << ""
-          @lines << "Tools:"
-          @subtools.each do |local_name, subtool|
-            add_right_column_desc(local_name, wrap_desc(subtool.desc))
+          @subtools.each do |source_name, subtool_list|
+            @lines << ""
+            @lines << (@separate_sources ? "Tools from #{source_name}:" : "Tools:")
+            subtool_list.each do |local_name, subtool|
+              add_right_column_desc(local_name, wrap_desc(subtool.desc))
+            end
           end
         end
 
@@ -296,10 +338,15 @@ module Toys
         end
       end
 
-      ## @private
+      ##
+      # @private
+      #
       class HelpStringAssembler
+        ##
+        # @private
+        #
         def initialize(tool, executable_name, delegates, subtools, search_term,
-                       show_source_path, indent, indent2, wrap_width, styled)
+                       show_source_path, separate_sources, indent, indent2, wrap_width, styled)
           require "toys/utils/terminal"
           @tool = tool
           @executable_name = executable_name
@@ -307,6 +354,7 @@ module Toys
           @subtools = subtools
           @search_term = search_term
           @show_source_path = show_source_path
+          @separate_sources = separate_sources
           @indent = indent
           @indent2 = indent2
           @wrap_width = wrap_width
@@ -314,6 +362,9 @@ module Toys
           assemble
         end
 
+        ##
+        # @private
+        #
         attr_reader :result
 
         private
@@ -532,8 +583,17 @@ module Toys
             @lines << indent_str("Showing search results for \"#{@search_term}\"")
             @lines << ""
           end
-          @subtools.each do |local_name, subtool|
-            add_prefix_with_desc(bold(local_name), subtool.desc)
+          first_section = true
+          @subtools.each do |source_name, subtool_list|
+            @lines << "" unless first_section
+            if @separate_sources
+              @lines << indent_str(underline("From #{source_name}"))
+              @lines << ""
+            end
+            subtool_list.each do |local_name, subtool|
+              add_prefix_with_desc(bold(local_name), subtool.desc)
+            end
+            first_section = false
           end
         end
 
@@ -594,19 +654,29 @@ module Toys
         end
       end
 
-      ## @private
+      ##
+      # @private
+      #
       class ListStringAssembler
-        def initialize(tool, subtools, recursive, search_term, indent, wrap_width, styled)
+        ##
+        # @private
+        #
+        def initialize(tool, subtools, recursive, search_term, separate_sources,
+                       indent, wrap_width, styled)
           require "toys/utils/terminal"
           @tool = tool
           @subtools = subtools
           @recursive = recursive
           @search_term = search_term
+          @separate_sources = separate_sources
           @indent = indent
           @wrap_width = wrap_width
           assemble(styled)
         end
 
+        ##
+        # @private
+        #
         attr_reader :result
 
         private
@@ -626,16 +696,22 @@ module Toys
             else
               "#{top_line} under #{bold(@tool.display_name)}:"
             end
-          @lines << ""
           if @search_term
-            @lines << "Showing search results for \"#{@search_term}\""
             @lines << ""
+            @lines << "Showing search results for \"#{@search_term}\""
           end
         end
 
         def add_list
-          @subtools.each do |local_name, subtool|
-            add_prefix_with_desc(bold(local_name), subtool.desc)
+          @subtools.each do |source_name, subtool_list|
+            @lines << ""
+            if @separate_sources
+              @lines << underline("From: #{source_name}")
+              @lines << ""
+            end
+            subtool_list.each do |local_name, subtool|
+              add_prefix_with_desc(bold(local_name), subtool.desc)
+            end
           end
         end
 
@@ -662,6 +738,10 @@ module Toys
           @lines.apply_styles(str, :bold)
         end
 
+        def underline(str)
+          @lines.apply_styles(str, :underline)
+        end
+
         def indent_str(str)
           "#{' ' * @indent}#{str}"
         end

data/lib/toys/utils/terminal.rb

@@ -14,7 +14,7 @@ module Toys
     ##
     # A simple terminal class.
     #
-    # ## Styles
+    # ### Styles
     #
     # This class supports ANSI styled output where supported.
     #
@@ -120,7 +120,7 @@ module Toys
         @output = output
         @styled =
           if styled.nil?
-            output.respond_to?(:tty?) && output.tty?
+            output.respond_to?(:tty?) && output.tty? && !::ENV["NO_COLOR"]
           else
             styled ? true : false
           end
@@ -431,8 +431,13 @@ module Toys
         end
       end
 
-      ## @private
+      ##
+      # @private
+      #
       class SpinDriver
+        ##
+        # @private
+        #
         def initialize(terminal, frames, style, frame_length)
           @mutex = ::Monitor.new
           @terminal = terminal
@@ -446,6 +451,9 @@ module Toys
           @thread = @terminal.output.tty? ? start_thread : nil
         end
 
+        ##
+        # @private
+        #
         def stop
           @mutex.synchronize do
             @stopping = true

data/lib/toys/utils/xdg.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module Toys
+  module Utils
+    ##
+    # A class that provides tools for working with the XDG Base Directory
+    # Specification.
+    #
+    # This class provides utility methods that locate base directories and
+    # search paths for application state, configuration, caches, and other
+    # data, according to the [XDG Base Directory Spec version
+    # 0.8](https://specifications.freedesktop.org/basedir-spec/0.8/).
+    #
+    # Tools can use the `:xdg` mixin for convenient access to this class.
+    #
+    # ### Example
+    #
+    #     require "toys/utils/xdg"
+    #
+    #     xdg = Toys::Utils::XDG.new
+    #
+    #     # Get config file paths, in order from most to least inportant
+    #     config_files = xdg.lookup_config("my-config.toml")
+    #     config_files.each { |path| read_my_config(path) }
+    #
+    # ### Windows operation
+    #
+    # The Spec assumes a unix-like environment, and cannot be applied directly
+    # to Windows without modification. In general, this class will function on
+    # Windows, but with the following caveats:
+    #
+    #  *   All file paths must use Windows-style absolute paths, beginning with
+    #      the drive letter.
+    #  *   Environment variables that can contain multiple paths (`XDG_*_DIRS`)
+    #      use the Windows path delimiter (`;`) rather than the unix path
+    #      delimiter (`:`).
+    #  *   Defaults for home directories (`XDG_*_HOME`) will follow unix
+    #      conventions, using subdirectories under the user's profile directory
+    #      rather than the Windows known folder paths.
+    #  *   Defaults for search paths (`XDG_*_DIRS`) will be empty and will not
+    #      use the Windows known folder paths.
+    #
+    class XDG
+      ##
+      # Create an instance of XDG.
+      #
+      # @param env [Hash{String=>String}] the environment variables. Normally,
+      #     you can omit this argument, as it will default to `::ENV`.
+      #
+      def initialize(env: ::ENV)
+        @env = env
+      end
+
+      ##
+      # Returns the absolute path to the current user's home directory.
+      #
+      # @return [String]
+      #
+      def home_dir
+        @home_dir ||= validate_dir_env("HOME") || ::Dir.home
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific data files should be written.
+      # Corresponds to the value of the `$XDG_DATA_HOME` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [String]
+      #
+      def data_home
+        @data_home ||=
+          validate_dir_env("XDG_DATA_HOME") || ::File.join(home_dir, ".local", "share")
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific configuration files should be written.
+      # Corresponds to the value of the `$XDG_CONFIG_HOME` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [String]
+      #
+      def config_home
+        @config_home ||= validate_dir_env("XDG_CONFIG_HOME") || ::File.join(home_dir, ".config")
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific state files should be written.
+      # Corresponds to the value of the `$XDG_STATE_HOME` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [String]
+      #
+      def state_home
+        @state_home ||=
+          validate_dir_env("XDG_STATE_HOME") || ::File.join(home_dir, ".local", "state")
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific non-essential (cached) data should be written.
+      # Corresponds to the value of the `$XDG_CACHE_HOME` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [String]
+      #
+      def cache_home
+        @cache_home ||= validate_dir_env("XDG_CACHE_HOME") || ::File.join(home_dir, ".cache")
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific executable files may be written.
+      # Returns the value of `$HOME/.local/bin` as specified by the XDG Base
+      # Directory Spec.
+      #
+      # @return [String]
+      #
+      def executable_home
+        @executable_home ||= ::File.join(home_dir, ".local", "bin")
+      end
+
+      ##
+      # Returns the set of preference ordered base directories relative to
+      # which data files should be searched, as an array of absolute paths.
+      # The array is ordered from most to least important, and does _not_
+      # include the data home directory.
+      # Corresponds to the value of the `$XDG_DATA_DIRS` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [Array<String>]
+      #
+      def data_dirs
+        @data_dirs ||= validate_dirs_env("XDG_DATA_DIRS") ||
+                       validate_dirs(["/usr/local/share", "/usr/share"]) || []
+      end
+
+      ##
+      # Returns the set of preference ordered base directories relative to
+      # which configuration files should be searched, as an array of absolute
+      # paths. The array is ordered from most to least important, and does
+      # _not_ include the config home directory.
+      # Corresponds to the value of the `$XDG_CONFIG_DIRS` environment variable
+      # and its defaults according to the XDG Base Directory Spec.
+      #
+      # @return [Array<String>]
+      #
+      def config_dirs
+        @config_dirs ||= validate_dirs_env("XDG_CONFIG_DIRS") ||
+                         validate_dirs(["/etc/xdg"]) || []
+      end
+
+      ##
+      # Returns the absolute path to the single base directory relative to
+      # which user-specific runtime files and other file objects should be
+      # placed. May return `nil` if no such directory could be determined.
+      #
+      # @return [String,nil]
+      #
+      def runtime_dir
+        @runtime_dir = validate_dir_env("XDG_RUNTIME_DIR") unless defined? @runtime_dir
+        @runtime_dir
+      end
+
+      ##
+      # Searches the data directories for an object with the given relative
+      # path, and returns an array of absolute paths to all objects found in
+      # the data directories (i.e. in {#data_dirs} or {#data_home}), in order
+      # from most to least important.
+      #
+      # @param path [String] Relative path of the object to search for
+      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
+      #     to find. You can specify any of the types defined by
+      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
+      #     such as `file` or `directory`, or the special type `any`. Types can
+      #     be specified as strings or the  corresponding symbols. If this
+      #     argument is not provided, the default of `file` is used.
+      # @return [Array<String>]
+      #
+      def lookup_data(path, type: :file)
+        lookup_internal([data_home] + data_dirs, path, type)
+      end
+
+      ##
+      # Searches the config directories for an object with the given relative
+      # path, and returns an array of absolute paths to all objects found in
+      # the config directories (i.e. in {#config_dirs} or {#config_home}), in
+      # order from most to least important.
+      #
+      # @param path [String] Relative path of the object to search for
+      # @param type [String,Symbol,Array<String,Symbol>] The type(s) of objects
+      #     to find. You can specify any of the types defined by
+      #     [File::Stat#ftype](https://ruby-doc.org/core/File/Stat.html#method-i-ftype),
+      #     such as `file` or `directory`, or the special type `any`. Types can
+      #     be specified as strings or the  corresponding symbols. If this
+      #     argument is not provided, the default of `file` is used.
+      # @return [Array<String>]
+      #
+      def lookup_config(path, type: :file)
+        lookup_internal([config_home] + config_dirs, path, type)
+      end
+
+      ##
+      # Returns the absolute path to a directory under {#data_home}, creating
+      # it if it doesn't already exist.
+      #
+      # @param path [String] The relative path to the subdir within the base
+      #     data directory.
+      # @return [String] The absolute path to the subdir.
+      # @raise [Errno::EEXIST] If a non-directory already exists there
+      #
+      def ensure_data_subdir(path)
+        ensure_subdir_internal(data_home, path)
+      end
+
+      ##
+      # Returns the absolute path to a directory under {#config_home}, creating
+      # it if it doesn't already exist.
+      #
+      # @param path [String] The relative path to the subdir within the base
+      #     config directory.
+      # @return [String] The absolute path to the subdir.
+      # @raise [Errno::EEXIST] If a non-directory already exists there
+      #
+      def ensure_config_subdir(path)
+        ensure_subdir_internal(config_home, path)
+      end
+
+      ##
+      # Returns the absolute path to a directory under {#state_home}, creating
+      # it if it doesn't already exist.
+      #
+      # @param path [String] The relative path to the subdir within the base
+      #     state directory.
+      # @return [String] The absolute path to the subdir.
+      # @raise [Errno::EEXIST] If a non-directory already exists there
+      #
+      def ensure_state_subdir(path)
+        ensure_subdir_internal(state_home, path)
+      end
+
+      ##
+      # Returns the absolute path to a directory under {#cache_home}, creating
+      # it if it doesn't already exist.
+      #
+      # @param path [String] The relative path to the subdir within the base
+      #     cache directory.
+      # @return [String] The absolute path to the subdir.
+      # @raise [Errno::EEXIST] If a non-directory already exists there
+      #
+      def ensure_cache_subdir(path)
+        ensure_subdir_internal(cache_home, path)
+      end
+
+      private
+
+      def validate_dir_env(name)
+        path = @env[name].to_s
+        !path.empty? && Compat.absolute_path?(path) ? path : nil
+      end
+
+      def validate_dirs_env(name)
+        validate_dirs(@env[name].to_s.split(::File::PATH_SEPARATOR))
+      end
+
+      def validate_dirs(paths)
+        paths = paths.find_all { |path| Compat.absolute_path?(path) }
+        paths.empty? ? nil : paths
+      end
+
+      def lookup_internal(dirs, path, types)
+        results = []
+        types = Array(types).map(&:to_s)
+        dirs.each do |dir|
+          to_check = ::File.join(dir, path)
+          stat = ::File.stat(to_check) rescue nil # rubocop:disable Style/RescueModifier
+          if stat&.readable? && (types.include?("any") || types.include?(stat.ftype))
+            results << to_check
+          end
+        end
+        results
+      end
+
+      def ensure_subdir_internal(base_dir, path)
+        path = ::File.join(base_dir, path)
+        ::FileUtils.mkdir_p(path, mode: 0o700)
+        path
+      end
+    end
+  end
+end

data/lib/toys/wrappable_string.rb

@@ -50,14 +50,21 @@ module Toys
     end
     alias to_s string
 
-    ## @private
+    ##
+    # Tests two wrappable strings for equality
+    # @param other [Object]
+    # @return [Boolean]
+    #
     def ==(other)
       return false unless other.is_a?(WrappableString)
       other.fragments == fragments
     end
     alias eql? ==
 
-    ## @private
+    ##
+    # Returns a hash code for this object
+    # @return [Integer]
+    #
     def hash
       fragments.hash
     end