toys 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a607f5cce147c21bdd90781026767b310054e69bbbff8c9a1103fdbd3d77b6b
-  data.tar.gz: ab0b2ff711816c75e2a50206e93ae19673c21f88618a3332e0642387b7baa6f3
+  metadata.gz: e494ced1b44b862aee77dd732210549374c571b55b4da8d503034ef3f87bba6f
+  data.tar.gz: bceadfc53e8b691951eef4ea4ef6d8b2f666590f745185322577d4bb5ccff82e
 SHA512:
-  metadata.gz: a99af47c6944f33da01db83f1aeb9d77021424cf2ef3b739c7f34caeaffac8dfbcfa25fff7e6ce73d742c4d4d44cabd1ab2b6521d3b64aeaf7d9adb5aeff0ffa
-  data.tar.gz: 3d853bf3958d6894a5388830c5f4c2595f3631a13280741d93cc70410d43374c690273a23314bd1758b558a523b0d3d4372446f3054a2d616cf9b78db0d526bd
+  metadata.gz: 40b86310b2d3ad6ce6b16ba738f4d8f543943f008a41b77fdc91b8f858afe50fa2104b3adebb2719aba98e6e920ce7f86f5df00a3c9d8824b4ea85e395fa5710
+  data.tar.gz: e468cd88b4042956bf12cbead2316c592799e667d61299ae69ab66d7cf457f5cef727a3d3cbb1589c3bf3cc16d76a89f8e8c4fff036a343fc6ad5a488456c2c9

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Release History
 
+### v0.25.0 / 2026-10-10
+
+This is a release candidate release toward version 1.0. It includes a variety of fixes and small features, largely around adherence to clig.dev and other common CLI guidelines.
+
+* Major updates
+    * ADDED: The `-h` flag is now a standard help flag, similar to `--help`.
+* Updates to tool lookup
+    * ADDED: Toys now loads global tools from the XDG config directories
+    * ADDED: The `TOYS_GLOBAL_SOURCES` environment variable selects which global sources are searched
+    * BREAKING CHANGE: The `TOYS_PATH` environment variable is no longer supported. Use `XDG_CONFIG_HOME`, `XDG_CONFIG_DIRS`, or `TOYS_GLOBAL_SOURCES` instead.
+    * BREAKING CHANGE: Toys no longer loads global tools from `/etc/.toys.rb` or `/etc/.toys/`. Move them into `/etc/xdg/toys` instead.
+    * BREAKING CHANGE: Removed the `Toys::StandardCLI::TOYS_PATH_ENV` constant.
+* Updates to logging and warnings
+    * ADDED: Warnings are displayed when a tool invokes a deprecated interface. They can be turned off by setting `TOYS_SUPPRESS_WARNINGS` to a nonempty value.
+    * ADDED: Logs display with a simplified severity prefix unless verbosity is positive
+    * FIXED: The `DEBUG` log prefix is no longer colored white
+    * FIXED: Logs emitted from tool initializers honor the verbosity
+* Updates to ANSI coloring control
+    * ADDED: The `FORCE_COLOR` environment variable forces styled output on, or off when set to 0 or false
+    * FIXED: An empty `NO_COLOR` environment variable no longer disables styled output, per the no-color.org spec
+    * FIXED: Styled output is disabled when the `TERM` environment variable is set to `dumb`
+    * FIXED: The highline mixin decides whether to use color from its own output stream, and honors `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+    * FIXED: Help text displayed through a pager honors the styled output setting, including `NO_COLOR`, `FORCE_COLOR`, and `TERM=dumb`
+* Other fixes
+    * FIXED: Bash tab completion discards stderr from the completion command, preventing unwanted output if warnings are emitted.
+    * FIXED: Tool-not-found suggestions include namespaces
+    * FIXED: The `:push` handler creates a new array rather than appending in place, so that a frozen or non-cloneable default doesn't cause problems
+    * FIXED: Re-vendor `simple_xdg` 0.1.2 to pick up home directory fix
+    * FIXED: Re-vendor `git_cache` 0.2.0 to report an unwritable cache directory clearly and fix repo lock races
+
 ### v0.24.0 / 2026-09-11
 
 * Feature: The `toys do` builtin provides an `--on-missing-gem` flag that governs how the `--gem` flag handles gems that are not installed.

data/README.md

@@ -108,9 +108,10 @@ Toys searches up the directory hierarchy for Toys files. So it will find this
 also read multiple files if it finds them, so you can "scope" your tools more
 specifically or generally by locating them in your directory hierarchy.
 
-If you want to define "global" tools that apply anywhere, write a Toys file
-either in your home directory, or in the system configuration directory
-(usually `/etc`). Toys always searches these locations.
+If you want to define "global" tools that apply anywhere, write a Toys file in
+your home directory, or put tool files in the `toys` directory under your user
+configuration directory (usually `~/.config/toys`) or the system configuration
+directory (usually `/etc/xdg/toys`). Toys searches these locations by default.
 
 ### A more sophisticated example
 

data/bin/toys

@@ -8,4 +8,11 @@ $LOAD_PATH.delete(::ENV["TOYS_LIB_PATH"])
 $LOAD_PATH.unshift(::ENV["TOYS_LIB_PATH"])
 require "toys"
 
-exit(::Toys::StandardCLI.new.run(::ARGV))
+begin
+  cli = ::Toys::StandardCLI.new
+rescue ::Toys::StandardCLI::InvalidGlobalSourcesError => e
+  # Not Kernel#warn, which -W0 would silence, hiding why toys exited.
+  $stderr.puts(e.message) # rubocop:disable Style/StderrPuts
+  exit(2)
+end
+exit(cli.run(::ARGV))

data/core-docs/toys/cli.rb

@@ -85,6 +85,8 @@ module Toys
     #     as an argument, and returns a `Logger` to use when running that tool.
     #     Optional. If not provided (and no global logger is set),
     #     {Toys::CLI.default_logger_factory} is called to get a basic default.
+    #     See {Toys::Runner} for how a logger can receive the verbosity of
+    #     the run.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the level the logger has
@@ -314,8 +316,8 @@ module Toys
     # source list. If the given search directory path does not exist or does
     # not contain either the file or directory, nothing is added.
     #
-    # The main Toys executable uses this method to load tools from directories
-    # in the `TOYS_PATH`.
+    # The main Toys executable uses this method to load tools from the
+    # directories in its upward walk and from the home directory.
     #
     # @param search_path [String,Pathname] A directory path to search for the
     #     well-known source file and directory. Must be a String or a Pathname.
@@ -349,9 +351,6 @@ module Toys
     # given directory and works up through parent directories until it reaches
     # the file system root or it encounters one of the "terminate" directories.
     #
-    # The main Toys executable uses this method to load tools from the current
-    # directory and its ancestors.
-    #
     # @param start [String,Pathname,nil] The first directory path to search.
     #     If not given, defaults to the current working directory. If provided,
     #     must be a String or a Pathname. Paths should generally be absolute.

data/core-docs/toys/core.rb

@@ -9,6 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.24.0"
+    VERSION = "0.25.0"
   end
 end

data/core-docs/toys/flag.rb

@@ -264,10 +264,12 @@ module Toys
     SET_HANDLER = proc { |val| val }
 
     ##
-    # The push handler pushes the given value using the `<<` operator.
+    # The push handler appends the given value, returning a new array. The
+    # previous array is not modified, so a shared or frozen default array
+    # can be used safely.
     # @return [Proc]
     #
-    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev << val }
+    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev + [val] }
 
     ##
     # The default handler is the set handler, which replaces the previous value.

data/core-docs/toys/runner.rb

@@ -34,6 +34,15 @@ module Toys
   #       end
   #     end
   #
+  # While a tool runs, the Runner sets the level of the tool's logger to reflect
+  # the verbosity, as described under the `base_level` parameter of
+  # {#initialize}. A logger can also receive the verbosity itself, by
+  # implementing a `verbosity` attribute: if the logger responds to both
+  # `verbosity` and `verbosity=`, the Runner sets it to the verbosity (an
+  # Integer) for the duration of the run, and restores the previous value
+  # afterward. This lets a logger vary its behavior, such as its formatting, by
+  # verbosity independently of its level.
+  #
   # **_Defined in the toys-core gem_**
   #
   class Runner
@@ -72,7 +81,8 @@ module Toys
     # @param logger_factory [Proc,nil] A proc that takes a
     #     {Toys::ToolDefinition} as an argument, and returns a logger to use
     #     when running that tool. If not given,
-    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used.
+    #     {Toys::Runner::DEFAULT_LOGGER_FACTORY} is used. See {Toys::Runner}
+    #     for how a logger can receive the verbosity of the run.
     # @param base_level [Integer,nil] The logger level that corresponds to zero
     #     verbosity. If not provided, the level the logger has before a run
     #     adjusts it is used (typically Logger::WARN). A run nested inside

data/core-docs/toys/standard_middleware/handle_usage_errors.rb

@@ -22,8 +22,9 @@ module Toys
       #     occurs. Default is {USAGE_ERROR_EXIT_CODE}.
       # @param stream [IO] Output stream to write to. Default is stderr.
       # @param styled_output [boolean,nil] Cause the tool to display help text
-      #     with ansi styles. If `nil`, display styles if the output stream is
-      #     a tty. Default is `nil`.
+      #     with ansi styles. If `nil`, whether to display styles is inferred
+      #     from the output stream and the environment. See
+      #     {Toys::Utils::Terminal.infer_styled}. Default is `nil`.
       #
       def initialize(exit_code: nil, stream: $stderr, styled_output: nil)
         # Source available in the toys-core gem

data/core-docs/toys/standard_middleware/show_help.rb

@@ -17,7 +17,7 @@ module Toys
       # Default help flags
       # @return [Array<String>]
       #
-      DEFAULT_HELP_FLAGS = ["-?", "--help"].freeze
+      DEFAULT_HELP_FLAGS = ["-h", "-?", "--help"].freeze
 
       ##
       # Default usage flags
@@ -165,8 +165,9 @@ module Toys
       #     false) if the output stream is not a tty.
       # @param stream [IO] Output stream to write to. Default is stdout.
       # @param styled_output [boolean,nil] Cause the tool to display help text
-      #     with ansi styles. If `nil`, display styles if the output stream is
-      #     a tty. Default is `nil`.
+      #     with ansi styles. If `nil`, whether to display styles is inferred
+      #     from the output stream and the environment. See
+      #     {Toys::Utils::Terminal.infer_styled}. Default is `nil`.
       #
       def initialize(help_flags: false,
                      usage_flags: false,

data/core-docs/toys/standard_mixins/highline.rb

@@ -25,6 +25,11 @@ module Toys
     # The arguments will be passed on to the
     # [HighLine constructor](https://www.rubydoc.info/gems/highline/HighLine:initialize).
     #
+    # Whether the HighLine object uses color is inferred from its output
+    # stream and the environment, using the same rule as a terminal. See
+    # {Toys::Utils::Terminal.infer_styled}. You can override it by setting
+    # `use_color` on the HighLine object.
+    #
     # **_Defined in the toys-core gem_**
     #
     module Highline

data/core-docs/toys/utils/git_cache.rb

@@ -16,7 +16,9 @@ module Toys
       # Access a git cache.
       #
       # @param cache_dir [String] The path to the cache directory. Defaults to
-      #     a specific directory in the user's XDG cache.
+      #     a specific directory in the user's XDG cache. Cache data is stored
+      #     in a subdirectory named for the cache format version, so that clients
+      #     using incompatible formats can share a cache directory safely.
       #
       def initialize(cache_dir: nil)
         # Source available in the toys-core gem
@@ -98,8 +100,9 @@ module Toys
       # repositories are requested, they will be reloaded from the remote
       # repository from scratch.
       #
-      # Be careful not to remove repos that are currently in use by other
-      # Toys::Utils::GitCache clients.
+      # This waits for any in-progress {#get} calls for these repos to finish.
+      # However, be careful not to remove repos whose shared sources are
+      # currently in use by other Toys::Utils::GitCache clients.
       #
       # @param remotes [Array<String>,:all,nil] The remotes to remove. If set
       #     to :all or nil, removes all repos.

data/core-docs/toys/utils/pager.rb

@@ -30,14 +30,18 @@ module Toys
       #     stream. Default is `true`.
       # @param exec_service [Toys::Utils::Exec] The service to use for
       #     executing commands, or `nil` (the default) to use a default.
+      # @param output [IO,StringIO,nil] The stream to which the pager process
+      #     writes its output, and the default fallback stream. If `nil` (the
+      #     default), the pager process inherits the parent's standard output.
       # @param fallback_io [IO] An IO-like object to write to if the pager is
-      #     disabled. Defaults to `$stdout`.
+      #     disabled or could not be executed. Defaults to the `output` stream
+      #     if one is given, otherwise `$stdout`.
       # @param rescue_broken_pipes [boolean] If `true` (the default), broken
       #     pipes are silently rescued. This prevents the exception from
       #     propagating out if the pager is interrupted. Set this parameter to
       #     `false` to disable this behavior.
       #
-      def initialize(command: true, exec_service: nil, fallback_io: nil,
+      def initialize(command: true, exec_service: nil, output: nil, fallback_io: nil,
                      rescue_broken_pipes: true)
         # Source available in the toys-core gem
       end
@@ -71,12 +75,32 @@ module Toys
       #
       attr_accessor :command
 
+      ##
+      # The stream to which the pager process writes its output, or `nil` if
+      # the pager process inherits the parent's standard output.
+      #
+      # @return [IO,StringIO,nil]
+      #
+      attr_accessor :output
+
       ##
       # The IO stream used if the pager is disabled or could not be executed.
+      # If not set explicitly, this is the {#output} stream if one is set,
+      # otherwise `$stdout`.
       #
       # @return [IO]
       #
-      attr_accessor :fallback_io
+      def fallback_io
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Set the IO stream used if the pager is disabled or could not be
+      # executed. Set to `nil` to use the default.
+      #
+      # @param value [IO,nil]
+      #
+      attr_writer :fallback_io
 
       class << self
         ##
@@ -91,8 +115,12 @@ module Toys
         #     stream. Default is `true`.
         # @param exec_service [Toys::Utils::Exec] The service to use for
         #     executing commands, or `nil` (the default) to use a default.
+        # @param output [IO,StringIO,nil] The stream to which the pager process
+        #     writes its output, and the default fallback stream. If `nil` (the
+        #     default), the pager process inherits the parent's standard output.
         # @param fallback_io [IO] An IO-like object to write to if the pager is
-        #     disabled. Defaults to `$stdout`.
+        #     disabled or could not be executed. Defaults to the `output` stream
+        #     if one is given, otherwise `$stdout`.
         # @param rescue_broken_pipes [boolean] If `true` (the default), broken
         #     pipes are silently rescued. This prevents the exception from
         #     propagating out if the pager is interrupted. Set this parameter to
@@ -107,6 +135,7 @@ module Toys
         #
         def start(command: true,
                   exec_service: nil,
+                  output: nil,
                   fallback_io: nil,
                   rescue_broken_pipes: true,
                   &block)

data/core-docs/toys/utils/standard_ui.rb

@@ -16,6 +16,32 @@ module Toys
     # **_Defined in the toys-core gem_**
     #
     class StandardUI
+      ##
+      # The logger class created by {StandardUI#create_logger}. It is a
+      # standard `Logger` that also has a `verbosity` attribute, which the
+      # {Toys::Runner} sets to the verbosity of the run, as described in
+      # {Toys::Runner}. The formatter installed by {StandardUI#create_logger}
+      # uses it to choose a format.
+      #
+      # **_Defined in the toys-core gem_**
+      #
+      class VerbosityLogger < ::Logger
+        ##
+        # Create a logger. Takes the same arguments as the standard `Logger`.
+        # The verbosity is initially zero.
+        #
+        def initialize(*args, **kwargs)
+          # Source available in the toys-core gem
+        end
+
+        ##
+        # The verbosity of the current run, or zero if not running.
+        #
+        # @return [Integer]
+        #
+        attr_accessor :verbosity
+      end
+
       ##
       # Create a Standard UI.
       #
@@ -114,10 +140,17 @@ module Toys
       # specification in {Toys::Runner}, this must take a {Toys::ToolDefinition}
       # as an argument, and return a `Logger`.
       #
-      # The base implementation returns a logger that writes to the UI's
-      # terminal, using {#format_log_entry} as the formatter. It sets the level
-      # to `Logger::WARN` by default. Either this method or the helper methods
-      # can be overridden to change this behavior.
+      # The base implementation returns a
+      # {Toys::Utils::StandardUI::VerbosityLogger}, which receives the
+      # verbosity of the run from the {Toys::Runner}. The logger writes to the
+      # UI's terminal. It formats each entry using {#format_verbose_log_entry}
+      # if {#verbose_log_format?} returns true for the verbosity, or
+      # {#format_simple_log_entry} otherwise. It sets the level to
+      # `Logger::WARN` by default. Either this method or the helper methods can
+      # be overridden to change this behavior.
+      #
+      # If {#format_log_entry} is overridden, however, the override formats
+      # every entry regardless of verbosity. That behavior is deprecated.
       #
       # @param _tool {Toys::ToolDefinition} The tool definition of the tool to
       #     be executed
@@ -175,10 +208,54 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      ##
+      # Determines whether loggers created by this UI's logger factory use
+      # the verbose format, {#format_verbose_log_entry}, rather than the simple
+      # format, {#format_simple_log_entry}, for the given verbosity.
+      #
+      # The base implementation returns true if the verbosity is positive. This
+      # method can be overridden to change the behavior of loggers created by
+      # this UI.
+      #
+      # @param verbosity [Integer] The verbosity of the run.
+      # @return [boolean]
+      #
+      def verbose_log_format?(verbosity)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Implementation of the formatter used by loggers created by this UI's
+      # logger factory when the simple format is in effect. This interface is
+      # defined by the standard `Logger` class.
+      #
+      # The base implementation prefixes the first line of the message with the
+      # severity, styled using {#log_header_severity_styles}. If the message is
+      # an exception, it includes the exception message and class, but omits
+      # the backtrace.
+      #
+      # This method can be overridden to change the behavior of loggers created
+      # by this UI.
+      #
+      # @param severity [String]
+      # @param _time [Time]
+      # @param _progname [String]
+      # @param msg [Object]
+      # @return [String]
+      #
+      def format_simple_log_entry(severity, _time, _progname, msg)
+        # Source available in the toys-core gem
+      end
+
       ##
       # Implementation of the formatter used by loggers created by this UI's
-      # logger factory. This interface is defined by the standard `Logger`
-      # class.
+      # logger factory when the verbose format is in effect. This interface is
+      # defined by the standard `Logger` class.
+      #
+      # The base implementation prefixes the message with a header containing
+      # the timestamp and severity, styled using {#log_header_severity_styles}.
+      # If the message is an exception, it includes the exception message and
+      # class, followed by the backtrace.
       #
       # This method can be overridden to change the behavior of loggers created
       # by this UI.
@@ -189,7 +266,32 @@ module Toys
       # @param msg [Object]
       # @return [String]
       #
-      def format_log_entry(severity, time, _progname, msg)
+      def format_verbose_log_entry(severity, time, _progname, msg)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # A legacy formatter for loggers created by this UI's logger factory.
+      # This interface is defined by the standard `Logger` class.
+      #
+      # The base implementation calls {#format_verbose_log_entry}, and is not
+      # used by loggers created by this UI's logger factory unless it is
+      # overridden. If a subclass overrides this method, the override is used
+      # to format every entry regardless of verbosity, and
+      # {#verbose_log_format?}, {#format_verbose_log_entry}, and
+      # {#format_simple_log_entry} are not called by the logger. The override
+      # may call `super` to get the verbose format.
+      #
+      # @deprecated Override {#format_simple_log_entry} and
+      #     {#format_verbose_log_entry} instead.
+      #
+      # @param severity [String]
+      # @param time [Time]
+      # @param progname [String]
+      # @param msg [Object]
+      # @return [String]
+      #
+      def format_log_entry(severity, time, progname, msg)
         # Source available in the toys-core gem
       end
     end

data/core-docs/toys/utils/terminal.rb

@@ -106,13 +106,55 @@ module Toys
         # Source available in the toys-core gem
       end
 
+      ##
+      # Infers whether styled output should be written to the given output,
+      # from the output itself and the environment. This is the rule a
+      # terminal uses when it is not told explicitly whether to style output,
+      # and it is available to tools that write styled output by other means.
+      #
+      # The following checks are applied in order, and the first that applies
+      # decides the result:
+      #
+      #  1. If the `FORCE_COLOR` environment variable is set to `0` or `false`
+      #     (in any case), output is not styled. This follows Node.js and the
+      #     chalk library, which are the most common consumers of
+      #     `FORCE_COLOR`, rather than the
+      #     [force-color.org](https://force-color.org) standard, which would
+      #     force styling on for these values.
+      #  2. If the `FORCE_COLOR` environment variable is set to any other
+      #     nonempty value, output is styled. Following the force-color.org
+      #     standard, this overrides `NO_COLOR`, so that color can be forced
+      #     for one run even when `NO_COLOR` is set as a general preference.
+      #     An empty `FORCE_COLOR` is treated as if it were unset, also
+      #     following the force-color.org standard.
+      #  3. If the `NO_COLOR` environment variable is set to a nonempty value,
+      #     output is not styled, following the
+      #     [no-color.org](https://no-color.org) standard.
+      #  4. If the `TERM` environment variable is set to `dumb`, output is not
+      #     styled.
+      #  5. Otherwise, output is styled if the output is a tty.
+      #
+      # Note that all styling is affected, not only color. Also note that an
+      # explicit choice, such as passing `styled: true` or `styled: false` to
+      # {Terminal#initialize}, takes precedence over all of these checks,
+      # because this method is then not called at all.
+      #
+      # @param output [IO,Logger,nil] The output stream.
+      # @param env [Hash{String=>String}] The environment. Defaults to `ENV`.
+      # @return [boolean] Whether output should be styled.
+      #
+      def self.infer_styled(output, env: ::ENV)
+        # Source available in the toys-core gem
+      end
+
       ##
       # Create a terminal.
       #
       # @param input [IO,nil] Input stream.
       # @param output [IO,Logger,nil] Output stream or logger.
       # @param styled [boolean,nil] Whether to output ansi styles. If `nil`, the
-      #     setting is inferred from whether the output has a tty.
+      #     setting is inferred from the output and the environment. See
+      #     {Terminal.infer_styled}.
       #
       def initialize(input: $stdin, output: $stdout, styled: nil)
         # Source available in the toys-core gem

data/core-docs/toys/utils/xdg.rb

@@ -63,6 +63,12 @@ module Toys
       ##
       # Returns the absolute path to the current user's home directory.
       #
+      # Uses the value of the `$HOME` environment variable if it is an absolute
+      # path, otherwise falls back to the system's notion of the home directory.
+      # If no home directory can be determined (for example, when `$HOME` is
+      # unset and the current user has no passwd entry, as can happen in a
+      # container run under an arbitrary UID), returns the filesystem root `"/"`.
+      #
       # @return [String]
       #
       def home_dir
@@ -359,7 +365,7 @@ module Toys
       # Version of the simple_xdg gem
       # @return [String]
       #
-      VERSION = "0.1.1"
+      VERSION = "0.1.2"
     end
   end
 end

data/core-docs/toys/warnings.rb

@@ -0,0 +1,96 @@
+module Toys
+  ##
+  # A warning reporter that supports throttling of repeated messages and
+  # environment variable based silencing. Used in particular to display
+  # deprecation warnings.
+  #
+  # **_Defined in the toys-core gem_**
+  #
+  module Warnings
+    ##
+    # @return [Integer] The default value for {Warnings.max_count}.
+    #
+    DEFAULT_MAX_COUNT = 5
+
+    ##
+    # @return [String] The name of an environment variable that, when set to a
+    #     non-empty value, suppresses warnings emitted by this module.
+    #
+    SUPPRESS_WARNINGS_ENV = "TOYS_SUPPRESS_WARNINGS"
+
+    FURTHER_SUPPRESSED_MSG = "further warnings suppressed"
+    private_constant :FURTHER_SUPPRESSED_MSG
+
+    ENV_SUPPRESSION_MSG = "to suppress these warnings altogether, set #{SUPPRESS_WARNINGS_ENV} to a nonempty value"
+    private_constant :ENV_SUPPRESSION_MSG
+
+    @mutex = ::Mutex.new
+    @max_count = DEFAULT_MAX_COUNT
+
+    class << self
+      ##
+      # The maximum number of times a warning with the same identity will be
+      # displayed before further instances are suppressed, or nil to keep
+      # displaying each warning regardless of how many times it has repeated.
+      # Defaults to {DEFAULT_MAX_COUNT}. Can be set using
+      # {Toys::Warnings.max_count=}.
+      #
+      # @return [Integer,nil]
+      #
+      attr_reader :max_count
+
+      ##
+      # Set the maximum number of times a warning with the same identity will
+      # be displayed before further instances are suppressed. Must be a
+      # nonnegative integer, or nil to keep displaying each warning regardless
+      # of how many times it has repeated. The value 0 suppresses warnings
+      # unconditionally.
+      #
+      # @param value [Integer,nil] The new max_count value
+      #
+      def max_count=(value)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Displays a warning message.
+      #
+      # You must pass an identifier object and a message string. The identifier
+      # should identify "which" warning is being displayed, and is used to
+      # count repeated warnings so they can be throttled after a certain number
+      # of instances.
+      #
+      # Uses the Ruby `Kernel#warn` method, so it is affected by `$VERBOSE` and
+      # the `-W0` flag. Does not currently support the `category:` argument to
+      # `Kernel#warn` because it is not supported in Ruby 2.7, and in newer
+      # Rubies, common values such as `category: :deprecated` default to silent,
+      # whereas this method should not be silent unless explicitly requested.
+      #
+      # @param identifier [Object] An object that identifies the warning for
+      #     counting purposes. Generally this should be a fixed small set of
+      #     objects, preferably symbols, as each identifier seen is used as a
+      #     hash key and never deleted.
+      # @param message [String] The warning message
+      # @param uplevel [Integer,nil] If given and set to a nonnegative Integer,
+      #     the warning will be prepended with the caller frame, that many
+      #     stack levels above the call site. If not given or set to nil, the
+      #     caller is not included in the report.
+      # @param max_count [Integer,nil,:default] The maximum number of times a
+      #     warning with the same identity will be displayed before further
+      #     instances are suppressed. Must be a nonnegative integer, or nil to
+      #     keep displaying each warning regardless of how many times it has
+      #     repeated. The value 0 suppresses warnings of this identifier
+      #     unconditionally. The special value `:default` (which is used if the
+      #     argument is not provided) falls back to {Toys::Warnings.max_count}.
+      #
+      # @return [Integer] The number of times this warning's identifier has
+      #     happened, regardless of whether it was actually displayed.
+      #
+      def warn(identifier, message, uplevel: nil, max_count: :default)
+        # Source available in the toys-core gem
+      end
+    end
+
+    reset_counts
+  end
+end

data/core-docs/toys-core.rb

@@ -53,7 +53,8 @@
 #   {Toys::Middleware}, which are resolved by name through
 #   {Toys::ModuleLookup}, as well as {Toys::WrappableString},
 #   {Toys::ToolNameSplitter} which interprets delimiters in tool names, the
-#   named sentinel {Toys::UniqueKey}, and the error classes.
+#   named sentinel {Toys::UniqueKey}, the warning reporter {Toys::Warnings},
+#   and the error classes.
 #
 # The deliberate upward dependencies are:
 #

data/docs/guide.md

@@ -233,7 +233,7 @@ However, Toys adds a few standard flags globally to every tool. (It is possible
 for individual tools to override these flags, but most tools should support
 them.) These standard flags include:
 
- *  `--help` (also `-?`) which displays the full help screen for the tool.
+ *  `--help` (also `-h` or `-?`) which displays the full help screen for the tool.
  *  `--usage` which displays a shorter usage screen for the tool.
  *  `--verbose` (also `-v`) which increases the verbosity. This affects the
     tool's logging display, increasing the number of log levels shown. This
@@ -1461,6 +1461,19 @@ tool file the error occurred, but doesn't give you the entire stack trace
 (which could include a number of frames internal to the Toys framework). If you
 want to see the full stack trace, set the `TOYS_TRACE` environment variable.
 
+### Warnings
+
+Toys may display warnings on the standard error stream, for example when a
+tool uses a feature of Toys that has been deprecated. These warnings are
+separate from the logger described above, and are not affected by verbosity
+or by the `--quiet` flag. If the same warning is triggered repeatedly during a
+single run, Toys displays only the first few instances.
+
+To suppress these warnings entirely, set the `TOYS_SUPPRESS_WARNINGS`
+environment variable to a nonempty value. Because Toys uses Ruby's standard
+`Kernel#warn` mechanism to display them, they are also silenced if Ruby
+warnings are disabled, for example by running Ruby with the `-W0` flag.
+
 ### Running tools from tools
 
 A common operation a tool might want to do is "call" another tool. This can be
@@ -1723,12 +1736,26 @@ When Toys runs, it looks for tools in a **search path**. Specifically:
     working directory*.
 2.  It does the same in the *parent directory* of the current directory, and
     then its parent, and so on until it hits either the root of the file system
-    or one of the global directories described in (3).
-3.  It looks in a list of *global directories*, specified in the environment
-    variable `TOYS_PATH`. This variable can contain a colon-delimited list of
-    directory paths. If the variable is not set, the current user's *home
-    directory*, and the system configuration directory (`/etc` on Unix systems)
-    are used by default. Toys does *not* search parents of global directories.
+    or the current user's *home directory*. The home directory itself is not
+    part of this step.
+3.  It looks in a list of *global sources*:
+    *   A `.toys.rb` file and/or a `.toys` directory in the current user's
+        home directory.
+    *   The `toys` directory under the user configuration directory given by
+        the `XDG_CONFIG_HOME` environment variable (`~/.config/toys` by
+        default).
+    *   The `toys` directory under each system configuration directory given by
+        the colon-delimited `XDG_CONFIG_DIRS` environment variable
+        (`/etc/xdg/toys` by default), in order.
+
+    Unlike `.toys` directories, the `toys` directories under the configuration
+    directories are not tied to any project directory, so tools loaded from
+    them have no
+    [context directory](#working-directory-and-context-directory) by default.
+
+    Toys does *not* search parents of global sources. If the current working
+    directory is inside one of the `toys` configuration directories, Toys
+    skips steps (1) and (2) and loads only the global sources.
 
 It uses the *first* implementation that it finds for the requested tool. For
 example, if the tool `greet` is defined in the `.toys.rb` file in the current
@@ -1756,6 +1783,15 @@ That is, they may be different depending on what directory you are in. However,
 step (3) is *not* context-dependent, and is searched regardless of where you
 are located. Tools defined here are *global*, available everywhere.
 
+You can choose which global sources are searched by setting the
+`TOYS_GLOBAL_SOURCES` environment variable. The global sources form three
+groups: `home` (the home directory), `user` (the user configuration directory),
+and `site` (the system configuration directories). Set the variable to a
+comma-delimited list of the groups to search, in that order. For example,
+`TOYS_GLOBAL_SOURCES=user,site` omits the home directory. Set it to `none` to
+search no global sources, which can be useful for reproducible runs in CI. If
+the variable is unset or empty, all three groups are searched.
+
 #### Stopping search
 
 Though it is uncommon practice, it is possible to stop the search process and

data/lib/toys/standard_cli.rb

@@ -66,10 +66,27 @@ module Toys
     DEFAULT_VERSION_FLAG_DESC = "Show the version of Toys."
 
     ##
-    # Name of the toys path environment variable.
+    # Name of the environment variable that selects which groups of global
+    # sources are searched.
     # @return [String]
     #
-    TOYS_PATH_ENV = "TOYS_PATH"
+    GLOBAL_SOURCES_ENV = "TOYS_GLOBAL_SOURCES"
+
+    ##
+    # The groups of global sources, in search order. The `home` group is
+    # `$HOME/.toys.rb` and `$HOME/.toys/`, the `user` group is the `toys`
+    # tool directory under `$XDG_CONFIG_HOME`, and the `site` group is the
+    # `toys` tool directories under each of `$XDG_CONFIG_DIRS`.
+    # @return [Array<String>]
+    #
+    GLOBAL_SOURCE_GROUPS = ["home", "user", "site"].freeze
+
+    ##
+    # Raised by the constructor if the `TOYS_GLOBAL_SOURCES` environment
+    # variable has an invalid value.
+    #
+    class InvalidGlobalSourcesError < ::StandardError
+    end
 
     ##
     # Create a standard CLI, configured with the appropriate paths and
@@ -77,7 +94,8 @@ module Toys
     #
     # @param custom_paths [String,Array<String>] Custom paths to use. If set,
     #     the CLI uses only the given paths. If not, the CLI will search for
-    #     paths from the current directory and global paths.
+    #     paths from the current directory and global paths, as selected by
+    #     the `TOYS_GLOBAL_SOURCES` environment variable.
     # @param include_builtins [boolean] Add the builtin tools. Default is true.
     # @param cur_dir [String,nil] Starting search directory for sources.
     #     Defaults to the current working directory.
@@ -87,6 +105,8 @@ module Toys
     # @param gems_util [Toys::Utils::Gems,nil] A custom Gems utility instance
     #     to use when resolving gem sources. Optional. If nil or not
     #     specified, uses a process-wide default Gems utility.
+    # @raise [InvalidGlobalSourcesError] if no custom paths are given and the
+    #     `TOYS_GLOBAL_SOURCES` environment variable has an invalid value.
     #
     def initialize(custom_paths: nil,
                    include_builtins: true,
@@ -112,7 +132,7 @@ module Toys
       if custom_paths
         Array(custom_paths).each { |path| add_source(path) }
       else
-        add_current_directory_paths(cur_dir)
+        add_default_sources(cur_dir)
       end
       add_builtins if include_builtins
     end
@@ -130,21 +150,171 @@ module Toys
     end
 
     ##
-    # Add paths for the given current directory and its ancestors, plus the
-    # global paths.
+    # Add the sources found by the default search: the current directory and
+    # its ancestors, followed by the selected global sources.
     #
-    # @param cur_dir [String] The starting directory path, or nil to use the
-    #     current directory
+    # @param cur_dir [String,nil] The starting directory path, or nil to use
+    #     the current directory
     # @return [self]
     #
-    def add_current_directory_paths(cur_dir)
-      cur_dir = skip_toys_dir(cur_dir || ::Dir.pwd, TOPLEVEL_TOOL_DIR_NAME)
-      global_dirs = default_global_dirs
-      add_search_path_hierarchy(start: cur_dir, terminate: global_dirs)
-      global_dirs.each { |path| add_search_path(path) }
+    def add_default_sources(cur_dir)
+      groups = selected_global_groups
+      warn_removed_global_paths
+      require "toys/utils/xdg"
+      xdg = Utils::XDG.new
+      home_dir = real_directory(xdg.home_dir)
+      user_dirs = [real_directory(::File.join(xdg.config_home, "toys"))].compact
+      site_dirs = xdg.config_dirs.map { |dir| real_directory(::File.join(dir, "toys")) }.compact
+      walk_dirs = upward_walk_dirs(cur_dir || ::Dir.pwd, home_dir, user_dirs + site_dirs)
+      walk_dirs.each { |dir| add_search_path(dir) }
+      warn_etc_toys_files(walk_dirs)
+      add_global_sources(groups, home_dir, user_dirs, site_dirs)
       self
     end
 
+    ##
+    # Parse and validate the global sources environment variable.
+    #
+    # @return [Array<String>] The selected groups
+    # @raise [InvalidGlobalSourcesError] if the value is invalid
+    #
+    def selected_global_groups
+      value = ::ENV[GLOBAL_SOURCES_ENV].to_s
+      return GLOBAL_SOURCE_GROUPS if value.empty?
+      return [] if value == "none"
+      groups = value.split(",", -1)
+      return groups if GLOBAL_SOURCE_GROUPS.select { |group| groups.include?(group) } == groups
+      raise InvalidGlobalSourcesError,
+            "Invalid value for #{GLOBAL_SOURCES_ENV}: #{value.inspect}. Expected \"none\", or a" \
+            " comma-delimited list of groups from #{GLOBAL_SOURCE_GROUPS.join(',')} in that order."
+    end
+
+    ##
+    # Add the global sources in the selected groups, skipping any directory
+    # that resolves to one already added.
+    #
+    # @param groups [Array<String>] The selected groups
+    # @param home_dir [String,nil] The real path of the home directory
+    # @param user_dirs [Array<String>] Real paths of the user tool directories
+    # @param site_dirs [Array<String>] Real paths of the site tool directories
+    #
+    def add_global_sources(groups, home_dir, user_dirs, site_dirs)
+      added_dirs = []
+      if groups.include?("home") && home_dir
+        add_search_path(home_dir)
+        home_toys_dir = real_directory(::File.join(home_dir, TOPLEVEL_TOOL_DIR_NAME))
+        added_dirs << home_toys_dir if home_toys_dir
+      end
+      tool_dirs = []
+      tool_dirs.concat(user_dirs) if groups.include?("user")
+      tool_dirs.concat(site_dirs) if groups.include?("site")
+      tool_dirs.each do |dir|
+        next if added_dirs.include?(dir) || !::File.readable?(dir)
+        added_dirs << dir
+        add_source(SourceSpec.path(dir))
+      end
+    end
+
+    ##
+    # Returns the directories searched by the upward walk from the given
+    # directory, or none if the directory is inside a global tool directory.
+    #
+    # @param cur_dir [String] The starting directory
+    # @param home_dir [String,nil] The real path of the home directory
+    # @param global_tool_dirs [Array<String>] Real paths of the global tool
+    #     directories
+    # @return [Array<String>]
+    #
+    def upward_walk_dirs(cur_dir, home_dir, global_tool_dirs)
+      cur_dir = real_directory(cur_dir) || ::File.expand_path(cur_dir)
+      cur_dir = skip_toys_dir(cur_dir, TOPLEVEL_TOOL_DIR_NAME)
+      return [] if global_tool_dirs.any? { |dir| path_within?(cur_dir, dir) }
+      walk_up(cur_dir, home_dir)
+    end
+
+    ##
+    # Returns the directories visited by the upward walk, starting at the
+    # given directory and stopping before the given terminating directory or
+    # after the root.
+    #
+    # @param start [String] The starting directory
+    # @param terminate [String,nil] The directory to stop before
+    # @return [Array<String>]
+    #
+    def walk_up(start, terminate)
+      dirs = []
+      dir = start
+      loop do
+        break if dir == terminate
+        dirs << dir
+        parent = ::File.dirname(dir)
+        break if parent == dir
+        dir = parent
+      end
+      dirs
+    end
+
+    ##
+    # Determines whether the given path is the given directory or is inside
+    # it, comparing whole path components.
+    #
+    # @param path [String] The path to check
+    # @param dir [String] The directory
+    # @return [boolean]
+    #
+    def path_within?(path, dir)
+      loop do
+        return true if path == dir
+        parent = ::File.dirname(path)
+        return false if parent == path
+        path = parent
+      end
+    end
+
+    ##
+    # Returns the real path of the given directory, or nil if it does not
+    # exist or is not a directory.
+    #
+    # @param path [String] The directory path
+    # @return [String,nil]
+    #
+    def real_directory(path)
+      return nil unless ::File.directory?(path)
+      ::File.realpath(path)
+    rescue ::SystemCallError
+      nil
+    end
+
+    ##
+    # Warns if the removed `TOYS_PATH` environment variable is set.
+    #
+    def warn_removed_global_paths
+      return if ::ENV["TOYS_PATH"].to_s.empty?
+      Warnings.warn(:toys_path_removed,
+                    "TOYS_PATH is no longer supported and is ignored. To relocate global tool" \
+                    " directories, set XDG_CONFIG_HOME or XDG_CONFIG_DIRS. To suppress them, set" \
+                    " #{GLOBAL_SOURCES_ENV}. To load tools from a path once, use `toys do --path`.",
+                    max_count: 1)
+    end
+
+    ##
+    # Warns if the removed `/etc` toys file or directory exists and was not
+    # loaded by the upward walk.
+    #
+    # @param walk_dirs [Array<String>] The directories visited by the walk
+    #
+    def warn_etc_toys_files(walk_dirs)
+      etc_dir = real_directory("/etc")
+      return if etc_dir.nil? || walk_dirs.include?(etc_dir)
+      file_path = ::File.join(etc_dir, TOPLEVEL_TOOL_FILE_NAME)
+      dir_path = ::File.join(etc_dir, TOPLEVEL_TOOL_DIR_NAME)
+      return unless ::File.exist?(file_path) || ::File.exist?(dir_path)
+      Warnings.warn(:etc_toys_removed,
+                    "/etc/#{TOPLEVEL_TOOL_FILE_NAME} and /etc/#{TOPLEVEL_TOOL_DIR_NAME} are no longer" \
+                    " loaded. Move global tools into the /etc/xdg/toys directory instead.",
+                    max_count: 1)
+    end
+
     ##
     # Step out of any toys dir.
     #
@@ -165,21 +335,6 @@ module Toys
       end
     end
 
-    ##
-    # Returns the default set of global source directories.
-    #
-    # @return [Array<String>]
-    #
-    def default_global_dirs
-      paths = ::ENV[TOYS_PATH_ENV].to_s.split(::File::PATH_SEPARATOR)
-      paths = [::Dir.home, "/etc"] if paths.empty?
-      paths
-        .compact
-        .uniq
-        .select { |path| ::File.directory?(path) && ::File.readable?(path) }
-        .map { |path| ::File.realpath(::File.expand_path(path)) }
-    end
-
     ##
     # Returns the middleware for the standard Toys CLI.
     #

data/lib/toys/version.rb

@@ -5,5 +5,5 @@ module Toys
   # Current version of the Toys command line executable.
   # @return [String]
   #
-  VERSION = "0.24.0"
+  VERSION = "0.25.0"
 end

data/share/bash-completion.sh

@@ -2,5 +2,5 @@ if [[ $# -eq 0 ]]; then
   set -- "toys"
 fi
 for arg in "$@"; do
-  complete -C "toys system bash-completion eval" -o nospace "$arg"
+  complete -C "toys system bash-completion eval 2>/dev/null" -o nospace "$arg"
 done

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toys
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Daniel Azuma
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.24.0
+        version: 0.25.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.24.0
+        version: 0.25.0
 description: Toys is a configurable command line tool. Write commands in Ruby using
   a simple DSL, and Toys will provide the command line executable and take care of
   all the details such as argument parsing, online help, and error reporting. Toys
@@ -108,6 +108,7 @@ files:
 - core-docs/toys/utils/standard_ui.rb
 - core-docs/toys/utils/terminal.rb
 - core-docs/toys/utils/xdg.rb
+- core-docs/toys/warnings.rb
 - core-docs/toys/wrappable_string.rb
 - docs/guide.md
 - lib/toys.rb
@@ -130,10 +131,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.24.0/file.CHANGELOG.html
-  source_code_uri: https://github.com/dazuma/toys/tree/toys/v0.24.0/toys
+  changelog_uri: https://dazuma.github.io/toys/gems/toys/v0.25.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/dazuma/toys/tree/toys/v0.25.0/toys
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.24.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys/v0.25.0
 rdoc_options: []
 require_paths:
 - lib
@@ -148,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A configurable command line tool
 test_files: []