toys-core 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcfc1b86a084e30ed82bd6712d7c4e3d1c0e4754eb4b090181a00a1d0809810a
-  data.tar.gz: 8c8b9ec8d4186ff53e6a3d5a967db37c274bc5caa57da108207af6d5138f1458
+  metadata.gz: c9a692b91f8fcd9e2aee00a360ac14b676ec1876bbf889468440e3827ce8877b
+  data.tar.gz: 6fc4cbd7769db055405a17be755dd0dc0e9612f9e5fd00451c3a1480c2924c6c
 SHA512:
-  metadata.gz: 71071ccc6322724bac6c56d8ef7889588008a0b29a5119488815f1bc1073556392d0c0697c4762cdd118a93dc1cb605f38a94c81673dcbf7a8c0f756a6063cb6
-  data.tar.gz: 27b5e9b5b252e5db056ec9a7bb2bcba68fa8d8b1c8dc20ecdbf166ca1aae905d0a68c262bb9c3d3b3f69675c097c9b0f6612494bd61b445115d525d1aa167e6f
+  metadata.gz: 9f3850a2d2d3eaf18f9ace3730a4bc34355400b8ff75308e0e739d77a5e664a7377c0fa9bacbd9726be3b99fc4bb5c5c6e742f5171d3ff4185dab90fe50f61f5
+  data.tar.gz: f0337ba0809e6e56f233fe22f2e4b423f19b36df4f1163498c8bd1ef6e545301bbbb0e51b12a92a2f218d001d5a9092e739ff088ea5caf6547e07568c4692a04

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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.
+
+* ADDED: Added `Toys::Utils::Terminal.infer_styled`, the rule a terminal uses to decide whether to style output
+* ADDED: The `FORCE_COLOR` environment variable forces styled output on, or off when set to 0 or false
+* ADDED: The `show_help` middleware includes `-h` in the default help flags
+* ADDED: `StandardUI` logs with a simple severity prefix unless verbosity is positive
+* ADDED: Issue warnings for deprecated interfaces
+* ADDED: `Utils::Pager` supports an output option
+* 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: 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`
+* FIXED: Tool-not-found suggestions include namespaces
+* FIXED: Tool initializers run within the logger level implied by the verbosity
+* FIXED: `StandardUI` no longer colors the `DEBUG` log header
+* 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
+* FIXED: Show_help writes paged help to the configured stream
+* DOCS: Documentation no longer references a few obsolete features such as the `TOYS_PATH` variable
+
 ### v0.24.0 / 2026-09-11
 
 Feature updates:

data/docs/guide.md

@@ -705,7 +705,8 @@ cli = Toys::CLI.new(logger_factory: my_logger_factory)
 #### StandardUI logging
 
 {Toys::Utils::StandardUI} implements the logger used by the `toys` gem, which
-formats log entries with the severity and timestamp using ANSI coloring.
+formats log entries with a severity prefix using ANSI coloring, and adds a
+timestamp when the tool is run with positive verbosity.
 
 You can use this logger by passing the proc returned by
 {Toys::Utils::StandardUI#logger_factory_proc} to the CLI constructor:
@@ -718,8 +719,10 @@ cli = Toys::CLI.new(logger_factory: standard_ui.logger_factory_proc)
 You can also customize the logger by subclassing StandardUI and overriding its
 methods or adjusting its parameters. In particular, you can alter the
 {Toys::Utils::StandardUI#log_header_severity_styles} mapping to adjust styling,
-or override {Toys::Utils::StandardUI#create_logger} or
-{Toys::Utils::StandardUI#format_log_entry} to adjust content and
+or override {Toys::Utils::StandardUI#create_logger},
+{Toys::Utils::StandardUI#verbose_log_format?},
+{Toys::Utils::StandardUI#format_simple_log_entry}, or
+{Toys::Utils::StandardUI#format_verbose_log_entry} to adjust content and
 formatting.
 
 ### Handling errors

data/lib/toys/arg_parser.rb

@@ -641,7 +641,8 @@ module Toys
           if @tool.runnable? || !@seen_flags.empty?
             ExtraArgumentsError.new(arguments: @unmatched_positional)
           else
-            dictionary = @loader.list_subtools(@tool.full_name).map(&:simple_name)
+            subtools = @loader.list_subtools(@tool.full_name, include_namespaces: true)
+            dictionary = subtools.map(&:simple_name)
             first_arg = @unmatched_positional.first
             ToolUnrecognizedError.new(full_name: @tool.full_name + [first_arg],
                                       suggestions: Compat.suggestions(first_arg, dictionary))

data/lib/toys/cli.rb

@@ -88,6 +88,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
@@ -351,8 +353,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.
@@ -405,9 +407,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.
@@ -581,6 +580,9 @@ module Toys
                         high_priority: false,
                         source_name: nil,
                         context_directory: :parent)
+      Warnings.warn(:add_config_path_deprecated,
+                    "CLI#add_config_path is deprecated. Use add_source instead.",
+                    uplevel: 1)
       path = SourceSpec.check_and_normalize_path(path)
       context_directory = resolve_context_directory(context_directory, path)
       spec = SourceSpec.path(path, source_name: source_name, context_directory: context_directory)
@@ -631,6 +633,9 @@ module Toys
                          source_name: nil,
                          context_directory: nil,
                          &block)
+      Warnings.warn(:add_config_block_deprecated,
+                    "CLI#add_config_block is deprecated. Use add_source instead.",
+                    uplevel: 1)
       spec = SourceSpec.block(source_name: source_name, context_directory: context_directory, &block)
       add_source(spec, high_priority: high_priority)
     end

data/lib/toys/compat.rb

@@ -22,127 +22,133 @@ module Toys
     #
     RUBY_VERSION_CODE = ruby_version
 
-    ##
-    # @private
-    # Whether the current Ruby implementation is JRuby
-    #
-    # @return [boolean]
-    #
-    def self.jruby?
-      ::RUBY_ENGINE == "jruby"
-    end
+    class << self
+      ##
+      # @private
+      # Whether the current Ruby implementation is JRuby
+      #
+      # @return [boolean]
+      #
+      def jruby?
+        ::RUBY_ENGINE == "jruby"
+      end
 
-    ##
-    # @private
-    # Whether the current Ruby implementation is TruffleRuby
-    #
-    # @return [boolean]
-    #
-    def self.truffleruby?
-      ::RUBY_ENGINE == "truffleruby"
-    end
+      ##
+      # @private
+      # Whether the current Ruby implementation is TruffleRuby
+      #
+      # @return [boolean]
+      #
+      def truffleruby?
+        ::RUBY_ENGINE == "truffleruby"
+      end
 
-    ##
-    # @private
-    # Whether we are running on Windows
-    #
-    # @return [boolean]
-    #
-    def self.windows?
-      ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
-    end
+      ##
+      # @private
+      # Whether we are running on Windows
+      #
+      # @return [boolean]
+      #
+      def windows?
+        ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+      end
 
-    ##
-    # @private
-    # Whether we are running on Mac OS
-    #
-    # @return [boolean]
-    #
-    def self.macos?
-      ::RbConfig::CONFIG["host_os"] =~ /darwin/
-    end
+      ##
+      # @private
+      # Whether we are running on Mac OS
+      #
+      # @return [boolean]
+      #
+      def macos?
+        ::RbConfig::CONFIG["host_os"] =~ /darwin/
+      end
 
-    ##
-    # @private
-    # Whether fork is supported on the current Ruby and OS
-    #
-    # @return [boolean]
-    #
-    def self.allow_fork?
-      !jruby? && !truffleruby? && !windows?
-    end
+      ##
+      # @private
+      # Whether fork is supported on the current Ruby and OS
+      #
+      # @return [boolean]
+      #
+      def allow_fork?
+        !jruby? && !truffleruby? && !windows?
+      end
 
-    ##
-    # @private
-    # Whether it is possible to get suggestions from DidYouMean. If this
-    # returns false, {Compat.suggestions} will always return the empty array.
-    #
-    # @return [boolean]
-    #
-    def self.supports_suggestions?
-      unless defined?(@supports_suggestions)
-        begin
-          require "did_you_mean"
-        rescue ::LoadError
-          require "rubygems"
+      ##
+      # @private
+      # Whether it is possible to get suggestions from DidYouMean. If this
+      # returns false, {Compat.suggestions} will always return the empty array.
+      #
+      # @return [boolean]
+      #
+      def supports_suggestions?
+        unless defined?(@supports_suggestions)
           begin
             require "did_you_mean"
           rescue ::LoadError
-            # Oh well, it's not available
+            require "rubygems"
+            begin
+              require "did_you_mean"
+            rescue ::LoadError
+              # Oh well, it's not available
+            end
           end
+          @supports_suggestions = defined?(::DidYouMean::SpellChecker)
         end
-        @supports_suggestions = defined?(::DidYouMean::SpellChecker)
+        @supports_suggestions
       end
-      @supports_suggestions
-    end
 
-    ##
-    # @private
-    # A list of suggestions from DidYouMean.
-    #
-    # @param word [String] A value that seems wrong
-    # @param list [Array<String>] A list of valid values
-    #
-    # @return [Array<String>] A possibly empty array of suggestions from the
-    #     valid list that could match the given word.
-    #
-    def self.suggestions(word, list)
-      if supports_suggestions?
-        ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
-      else
-        []
+      ##
+      # @private
+      # A list of suggestions from DidYouMean.
+      #
+      # @param word [String] A value that seems wrong
+      # @param list [Array<String>] A list of valid values
+      #
+      # @return [Array<String>] A possibly empty array of suggestions from the
+      #     valid list that could match the given word.
+      #
+      def suggestions(word, list)
+        if supports_suggestions?
+          ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
+        else
+          []
+        end
       end
-    end
 
-    ##
-    # @private
-    # A list of gems that should generally not be included in a bundle, usually
-    # because the Ruby implementation handles the library specially and cannot
-    # install the real gem. Currently, this includes the `pathname` gem for
-    # TruffleRuby, since TruffleRuby includes a special version of it.
-    #
-    # @return [Array<String>]
-    #
-    def self.gems_to_omit_from_bundles
-      if truffleruby?
-        ["pathname"]
-      else
-        []
+      ##
+      # @private
+      # A list of gems that should generally not be included in a bundle,
+      # usually because the Ruby implementation handles the library specially
+      # and cannot install the real gem. Currently, this includes the
+      # `pathname` gem for TruffleRuby, since TruffleRuby includes a special
+      # version of it.
+      #
+      # @return [Array<String>]
+      #
+      def gems_to_omit_from_bundles
+        if truffleruby?
+          ["pathname"]
+        else
+          []
+        end
       end
-    end
 
-    ##
-    # @private
-    # Sets the backtrace on an exception. In Ruby < 3.4, Exception#set_backtrace
-    # required a string array, whereas in newer Rubies, it would accept an array
-    # of backtrace locations.
-    #
-    # @param [Exception] exception
-    # @param [nil,Array<String>,Array<Thread::Backtrace::Location>] backtrace
-    #
-    def self.set_backtrace(exception, backtrace)
-      backtrace = backtrace.map(&:to_s) if RUBY_VERSION_CODE < 30400 && !backtrace.nil?
-      exception.set_backtrace(backtrace)
+      ##
+      # @private
+      # Sets the backtrace on an exception. In Ruby `< 3.4`,
+      # `Exception#set_backtrace` required a string array, whereas in newer
+      # Rubies, it would accept an array of backtrace locations.
+      #
+      # @param [Exception] exception
+      # @param [nil,Array<String>,Array<Thread::Backtrace::Location>] backtrace
+      #
+      # @return [Exception] The modified exception
+      #
+      def set_backtrace(exception, backtrace)
+        backtrace = backtrace.map(&:to_s) if RUBY_VERSION_CODE < 30400 && !backtrace.nil?
+        exception.set_backtrace(backtrace)
+        exception
+      end
     end
   end
 end

data/lib/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/lib/toys/flag.rb

@@ -377,10 +377,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/lib/toys/runner.rb

@@ -38,6 +38,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.
+  #
   class Runner
     ##
     # The singleton default logger_factory Proc, which simply returns a new
@@ -74,7 +83,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
@@ -404,15 +414,15 @@ module Toys
       end
 
       # Prepares the runtime environment for the tool, applying lib paths and
-      # initializers, and then calls the tool within its middleware stack and
-      # within the logger level implied by the verbosity, returning the
-      # resulting exit code.
+      # initializers, and then calls the tool within its middleware stack,
+      # returning the resulting exit code. The initializers and the tool both
+      # run within the logger level implied by the verbosity.
       def execute_tool(context, &block)
         @tool.source_info&.find_lib_paths&.reverse_each do |path|
           $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
         end
-        @tool.run_initializers(context)
         with_logger_level(context) do
+          @tool.run_initializers(context)
           executor = build_executor(context, &block)
           catch(:result) do
             executor.call
@@ -426,23 +436,39 @@ module Toys
       # afterward. The restoration must cover the level assignment itself,
       # because a base level that cannot be combined with the verbosity fails
       # there, and a base level left recorded behind a failed run would be
-      # picked up by later runs sharing the logger. Yields directly if the tool
-      # has no logger.
-      def with_logger_level(context)
+      # picked up by later runs sharing the logger. Also sets the verbosity on
+      # a logger that supports it, as described in {Runner}. Yields directly if
+      # the tool has no logger.
+      def with_logger_level(context, &block)
         cur_logger = context[Context::Key::LOGGER]
         return yield unless cur_logger
+        verbosity = context[Context::Key::VERBOSITY].to_i
         original_level = cur_logger.level
         base_level = @base_level || base_levels[cur_logger] || original_level
         saved_base_level = set_base_level(cur_logger, base_level)
         begin
-          cur_logger.level = base_level - context[Context::Key::VERBOSITY].to_i
-          yield
+          cur_logger.level = base_level - verbosity
+          with_logger_verbosity(cur_logger, verbosity, &block)
         ensure
           set_base_level(cur_logger, saved_base_level)
           cur_logger.level = original_level
         end
       end
 
+      # Sets the verbosity on a logger that supports it for the duration of
+      # the block, and restores it afterward. Yields directly if the logger
+      # does not have both a reader and a writer for the verbosity.
+      def with_logger_verbosity(logger, verbosity)
+        return yield unless logger.respond_to?(:verbosity) && logger.respond_to?(:verbosity=)
+        original_verbosity = logger.verbosity
+        begin
+          logger.verbosity = verbosity
+          yield
+        ensure
+          logger.verbosity = original_verbosity
+        end
+      end
+
       # The base levels currently in effect on this thread, keyed by logger
       # identity. A run that adjusts a logger's level records the base
       # level it used, for the extent of that run, because a nested run cannot

data/lib/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)
         @exit_code = exit_code || USAGE_ERROR_EXIT_CODE

data/lib/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,
@@ -297,10 +298,11 @@ module Toys
           include_hidden: context[SHOW_ALL_SUBTOOLS_KEY],
           show_source_path: @show_source_path,
           separate_sources: @separate_sources,
-          wrap_width: terminal.width
+          wrap_width: terminal.width,
+          styled: terminal.styled
         )
         require "toys/utils/pager"
-        Utils::Pager.start(command: @use_pager, fallback_io: terminal) do |io|
+        Utils::Pager.start(command: @use_pager, output: @stream, fallback_io: terminal) do |io|
           io.puts(str)
         end
       rescue Utils::HelpText::HelpGenerationError => e

data/lib/toys/standard_mixins/highline.rb

@@ -27,6 +27,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.
+    #
     module Highline
       include Mixin
 
@@ -131,10 +136,12 @@ module Toys
 
       on_initialize do |*args|
         require "toys/utils/gems"
+        require "toys/utils/terminal"
         ::Toys::Utils::Gems.activate("highline", "~> 2.0")
         require "highline"
-        self[::Toys::StandardMixins::Highline::KEY] = ::HighLine.new(*args)
-        self[::Toys::StandardMixins::Highline::KEY].use_color = $stdout.tty?
+        highline = ::HighLine.new(*args)
+        highline.use_color = ::Toys::Utils::Terminal.infer_styled(highline.output)
+        self[::Toys::StandardMixins::Highline::KEY] = highline
       end
     end
   end