toys-core 0.15.6 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7afb8f468a42a9d5eb626646212238c656e9be93d7a29601631f4e3059975eaf
-  data.tar.gz: d1b66149b911a8f4a9eab94c459f15cc7400ee871f8f3db1f473d7eddbd2ba61
+  metadata.gz: be1392e6cb8f49c19e9472449943cf873209b939d11cdc1e788bb58a1083c013
+  data.tar.gz: d78818495765389e99111032e863dc21d4fa982dfde07780a5b1ff9cc96743df
 SHA512:
-  metadata.gz: ec09f204706004b5d6a914c1b2b1eabaaa0bd3d7accbbde8fe9e5d00aae3fba389676400b54abff33fb7cb79f5cb530577d099d0095838523ce9165b6659c52a
-  data.tar.gz: f47170aecd0ffe9072a6c022a9def134e88114d52c8d8f57fdc4b11aeae68971bb7ee0ad7234ddc7df8f41d2c788e2f723a241f4fb0f0dd67c62281e3a2a6da4
+  metadata.gz: 63ca5e62ed30e068d7b75a0b08e3916fc19466d92ca165d52f8f333e9538f96358027fdd676690042c5eb55d2e2569c3c1a8b8d9c32dd33f7ec3d4036230bc81
+  data.tar.gz: 61821ef2ffde83d82469c6a8d38ba092f1efc2a3254a1f848d877fda09a888fc932274e27c742c53d0480a55abc1b49fc6266359ceeca31e8851e16dac3ce0e8

data/CHANGELOG.md

@@ -1,8 +1,30 @@
 # Release History
 
+### v0.17.0 / 2025-11-07
+
+Toys-Core 0.17 supports several significant new pieces of functionality:
+
+* Support for loading tools from Rubygems. The load_gem directive loads tools from the "toys" directory in a gem, installing the gem if necessary. This makes it easy to distribute tools, securely and versioned, as gems.
+* Flag handlers can now take an optional third argument, the entire options hash. This enables significantly more powerful behavior during flag parsing, such as letting flags affect the behavior of other flags.
+
+Additional new features:
+
+* When using the :gems mixin, you can now specify installation options such as on_missing not only when you include the mixin, but also when you declare the gem.
+* Added support for an environment variable `TOYS_GIT_CACHE_WRITABLE` to disable the read-only behavior of git cache sources. This improves compatibility with environments that want to delete caches.
+
+Other fixes and documentation:
+
+* Added the standard logger gem to the toys-core dependencies to silence Ruby 3.5 warnings.
+* Updated the user guide to cover new features and fix some internal links
+
+### v0.16.0 / 2025-10-31
+
+* ADDED: Updated minimum Ruby version to 2.7
+* FIXED: ToolDefinition#includes_arguments no longer returns true if only default data is set
+
 ### v0.15.6 / 2024-05-15
 
-* FIXED: Fixed argument parsing to allow a flag value with a newline delimited by =
+* FIXED: Fixed argument parsing so flags with value delimited by "=" will support values containing newlines
 
 ### v0.15.5 / 2024-01-31
 

data/README.md

@@ -338,7 +338,7 @@ Detailed usage information can be found in the
 
 ## System requirements
 
-Toys-Core requires Ruby 2.4 or later.
+Toys-Core requires Ruby 2.7 or later.
 
 Most parts of Toys-Core work on JRuby. However, JRuby is not recommended
 because of JVM boot latency, lack of support for Kernel#fork, and other issues.
@@ -348,7 +348,7 @@ recommended because it has a few known bugs that affect Toys.
 
 ## License
 
-Copyright 2019-2023 Daniel Azuma and the Toys contributors
+Copyright 2019-2025 Daniel Azuma and the Toys contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/docs/guide.md

@@ -159,7 +159,7 @@ If only `foo` is requested, the loader will execute the `tool "foo" do` block
 to get that tool definition, but will not execute the `tool "bar" do` block.
 
 We will discuss more about the features of the loader below in the section on
-[defining functionality](#Defining_functionality).
+[defining functionality](#defining-functionality).
 
 #### Building context
 
@@ -209,16 +209,16 @@ Generally, you control CLI features by passing arguments to its constructor.
 These features include:
 
  *  How to find toys files and related code and data. See the section on
-    [defining functionality](#Defining_functionality).
+    [defining functionality](#defining-functionality).
  *  Middleware, providing common behavior for all tools. See the section on
-    [customizing the middleware stack](#Customizing_default_behavior).
+    [customizing the middleware stack](#customizing-default-behavior).
  *  Common mixins and templates available to all tools. See the section on
-    [how to define mixins and templates](#Defining_mixins_and_templates).
+    [how to define mixins and templates](#defining-mixins-and-templates).
  *  How logs, errors, and signals are reported. See the section on
-    [customizing tool output](#Customizing_tool_output).
+    [customizing tool output](#customizing-tool-output).
  *  How the executable interacts with the shell, including setting up tab
     completion. See the
-    [corresponding section](#Shell_and_command_line_integration).
+    [corresponding section](#shell-and-command-line-integration).
 
 Each of the actual parameters is covered in detail in the documentation for
 {Toys::CLI#initialize}. The configuration of a CLI cannot be changed once the
@@ -663,7 +663,7 @@ execute.
       # This is a context key that will be used to store the "--show-timing"
       # flag state. We can use `Object.new` to ensure that the key is unique
       # across other middlewares and tool definitions.
-      KEY = Object.new
+      KEY = Object.new.freeze
 
       # This method intercepts tool configuration. We use it to add a flag that
       # enables timing display.

data/lib/toys/arg_parser.rb

@@ -416,7 +416,7 @@ module Toys
     private
 
     REMAINING_HANDLER = ->(val, prev) { prev.is_a?(::Array) ? prev << val : [val] }
-    ARG_HANDLER = ->(val, _prev) { val }
+    ARG_HANDLER = ->(val) { val }
     private_constant :REMAINING_HANDLER, :ARG_HANDLER
 
     def initial_data(cli, tool, default_data)
@@ -465,7 +465,7 @@ module Toys
 
     def handle_single_flags(str)
       until str.empty?
-        str = handle_plain_flag("-#{str[0]}", str[1..-1])
+        str = handle_plain_flag("-#{str[0]}", str[1..])
       end
     end
 
@@ -521,7 +521,7 @@ module Toys
 
     def find_flag(name)
       flag_result = @tool.resolve_flag(name)
-      if flag_result.not_found? || @require_exact_flag_match && !flag_result.found_exact?
+      if flag_result.not_found? || (@require_exact_flag_match && !flag_result.found_exact?)
         @errors << FlagUnrecognizedError.new(
           value: name, suggestions: Compat.suggestions(name, @tool.used_flags)
         )
@@ -551,7 +551,12 @@ module Toys
         value = accept.convert(*Array(match))
       end
       if handler
-        value = handler.call(value, @data[key])
+        args = [value, @data[key], @data]
+        if handler.lambda?
+          limit = handler.arity.negative? ? -handler.arity - 1 : handler.arity
+          args = args[...limit]
+        end
+        value = handler.call(*args)
       end
       @data[key] = value
     end

data/lib/toys/cli.rb

@@ -628,17 +628,15 @@ module Toys
 
     def build_executor(tool, context)
       executor = proc do
-        begin
-          if !context[Context::Key::USAGE_ERRORS].empty?
-            handle_usage_errors(context, tool)
-          elsif !tool.runnable?
-            raise NotRunnableError, "No implementation for tool #{tool.display_name.inspect}"
-          else
-            yield context
-          end
-        rescue ::SignalException => e
-          handle_signal_by_tool(context, tool, e)
+        if !context[Context::Key::USAGE_ERRORS].empty?
+          handle_usage_errors(context, tool)
+        elsif !tool.runnable?
+          raise NotRunnableError, "No implementation for tool #{tool.display_name.inspect}"
+        else
+          yield context
         end
+      rescue ::SignalException => e
+        handle_signal_by_tool(context, tool, e)
       end
       tool.built_middleware.reverse_each do |middleware|
         executor = make_executor(middleware, context, executor)

data/lib/toys/compat.rb

@@ -4,13 +4,17 @@ require "rbconfig"
 
 module Toys
   ##
-  # Compatibility wrappers for older Ruby versions.
+  # Compatibility wrappers for certain Ruby implementations and versions, and
+  # other environment differences.
   #
   # @private
   #
   module Compat
     parts = ::RUBY_VERSION.split(".")
-    ruby_version = parts[0].to_i * 10000 + parts[1].to_i * 100 + parts[2].to_i
+    ruby_version = (parts[0].to_i * 10000) + (parts[1].to_i * 100) + parts[2].to_i
+
+    # @private
+    RUBY_VERSION_CODE = ruby_version
 
     # @private
     def self.jruby?
@@ -27,6 +31,11 @@ module Toys
       ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
     end
 
+    # @private
+    def self.macos?
+      ::RbConfig::CONFIG["host_os"] =~ /darwin/
+    end
+
     # @private
     def self.allow_fork?
       !jruby? && !truffleruby? && !windows?
@@ -58,86 +67,5 @@ module Toys
         []
       end
     end
-
-    # The :base argument to Dir.glob requires Ruby 2.5 or later.
-    if ruby_version >= 20500
-      # @private
-      def self.glob_in_dir(glob, dir)
-        ::Dir.glob(glob, base: dir)
-      end
-    else
-      # @private
-      def self.glob_in_dir(glob, dir)
-        ::Dir.chdir(dir) { ::Dir.glob(glob) }
-      end
-    end
-
-    # Dir.children requires Ruby 2.5 or later.
-    if ruby_version >= 20500
-      # @private
-      def self.dir_children(dir)
-        ::Dir.children(dir)
-      end
-    else
-      # @private
-      def self.dir_children(dir)
-        ::Dir.entries(dir) - [".", ".."]
-      end
-    end
-
-    # Due to a bug in Ruby < 2.7, passing an empty **kwargs splat to
-    # initialize will fail if there are no formal keyword args.
-    # This also hits TruffleRuby
-    # (see https://github.com/oracle/truffleruby/issues/2567)
-    if ruby_version >= 20700 && !truffleruby?
-      # @private
-      def self.instantiate(klass, args, kwargs, block)
-        klass.new(*args, **kwargs, &block)
-      end
-    else
-      # @private
-      def self.instantiate(klass, args, kwargs, block)
-        formals = klass.instance_method(:initialize).parameters
-        if kwargs.empty? && formals.all? { |arg| arg.first != :key && arg.first != :keyrest }
-          klass.new(*args, &block)
-        else
-          klass.new(*args, **kwargs, &block)
-        end
-      end
-    end
-
-    # File.absolute_path? requires Ruby 2.7 or later. For earlier Rubies, use
-    # an ad-hoc mechanism.
-    if ruby_version >= 20700
-      # @private
-      def self.absolute_path?(path)
-        ::File.absolute_path?(path)
-      end
-    elsif ::Dir.getwd =~ /^[a-zA-Z]:/
-      # @private
-      def self.absolute_path?(path)
-        /^[a-zA-Z]:/.match?(path)
-      end
-    else
-      # @private
-      def self.absolute_path?(path)
-        path.start_with?("/")
-      end
-    end
-
-    # The second argument to method_defined? and private_method_defined?
-    # requires Ruby 2.6 or later.
-    if ruby_version >= 20600
-      # @private
-      def self.method_defined_without_ancestors?(klass, name)
-        klass.method_defined?(name, false) || klass.private_method_defined?(name, false)
-      end
-    else
-      # @private
-      def self.method_defined_without_ancestors?(klass, name)
-        klass.instance_methods(false).include?(name) ||
-          klass.private_instance_methods(false).include?(name)
-      end
-    end
   end
 end

data/lib/toys/completion.rb

@@ -49,7 +49,7 @@ module Toys
       # @return [Toys::Completion::Context]
       #
       def with(**delta_params)
-        Context.new(**@params.merge(delta_params))
+        Context.new(**@params, **delta_params)
       end
 
       ##
@@ -195,7 +195,7 @@ module Toys
       # @private
       #
       def hash
-        string.hash ^ (partial? ? 1 : 0)
+        [@string, @partial].hash
       end
 
       ##
@@ -295,7 +295,7 @@ module Toys
         return [] unless ::File.directory?(dir)
         prefix = nil if [".", ""].include?(prefix)
         omits = [".", "..", ""]
-        children = Compat.glob_in_dir(name, dir).find_all do |child|
+        children = ::Dir.glob(name, base: dir).find_all do |child|
           !omits.include?(child)
         end
         children += ::Dir.entries(dir).find_all do |child|

data/lib/toys/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.15.6"
+    VERSION = "0.17.0"
   end
 
   ##

data/lib/toys/dsl/flag.rb

@@ -114,17 +114,20 @@ module Toys
       end
 
       ##
-      # Set the optional handler for setting/updating the value when a flag is
-      # parsed. A handler should be a Proc taking two arguments, the new given
-      # value and the previous value, and it should return the new value that
-      # should be set. You may pass the handler as a Proc (or an object
-      # responding to the `call` method) or you may pass a block.
-      #
-      # You can also pass one of the special values `:set` or `:push` as the
-      # handler. The `:set` handler replaces the previous value (equivalent to
-      # `-> (val, _prev) { val }`.) The `:push` handler expects the previous
-      # value to be an array and pushes the given value onto it; it should be
-      # combined with setting the default value to `[]` and is intended for
+      # Set the optional handler that customizes how a value is set or updated
+      # when the flag is parsed.
+      #
+      # A handler is a proc that takes up to three arguments: the given value,
+      # the previous value, and a hash containing all the data collected so far
+      # during argument parsing. It must return the new value for the flag. You
+      # You may pass the handler as a Proc (or an object responding to the
+      # `call` method) or you may provide a block.
+      #
+      # You may also specify a predefined named handler. The `:set` handler
+      # (the default) replaces the previous value (effectively
+      # `-> (val) { val }`). The `:push` handler expects the previous value to
+      # be an array and pushes the given value onto it; it should be combined
+      # with setting the default value to `[]` and is intended for
       # "multi-valued" flags.
       #
       # @param handler [Proc,:set,:push]

data/lib/toys/dsl/flag_group.rb

@@ -147,15 +147,18 @@ module Toys
       # @param default [Object] The default value. This is the value that will
       #     be set in the context if this flag is not provided on the command
       #     line. Defaults to `nil`.
-      # @param handler [Proc,nil,:set,:push] An optional handler for
-      #     setting/updating the value. A handler is a proc taking two
-      #     arguments, the given value and the previous value, returning the
-      #     new value that should be set. You may also specify a predefined
-      #     named handler. The `:set` handler (the default) replaces the
-      #     previous value (effectively `-> (val, _prev) { val }`). The
-      #     `:push` handler expects the previous value to be an array and
-      #     pushes the given value onto it; it should be combined with setting
-      #     `default: []` and is intended for "multi-valued" flags.
+      # @param handler [Proc,nil,:set,:push] An optional handler that
+      #     customizes how a value is set or updated when the flag is parsed.
+      #     A handler is a proc that takes up to three arguments: the given
+      #     value, the previous value, and a hash containing all the data
+      #     collected so far during argument parsing. The proc must return the
+      #     new value for the flag.
+      #     You may also specify a predefined named handler. The `:set` handler
+      #     (the default) replaces the previous value (effectively
+      #     `-> (val) { val }`). The `:push` handler expects the previous value
+      #     to be an array and pushes the given value onto it; it should be
+      #     combined with setting the default value to `[]` and is intended for
+      #     "multi-valued" flags.
       # @param complete_flags [Object] A specifier for shell tab completion
       #     for flag names associated with this flag. By default, a
       #     {Toys::Flag::DefaultCompletion} is used, which provides the flag's

data/lib/toys/dsl/internal.rb

@@ -12,8 +12,8 @@ module Toys
       # @private A list of method names to avoid using as getters
       #
       AVOID_GETTERS = (::Object.instance_methods + [:run, :initialize])
-                      .find_all { |name| /^[a-z]\w*$/.match?(name) }
-                      .map { |name| [name, true] }.to_h
+                      .grep(/^[a-z]\w*$/)
+                      .to_h { |name| [name, true] }
                       .freeze
 
       class << self
@@ -109,7 +109,8 @@ module Toys
           when nil
             return if !/^[a-zA-Z]\w*[!?]?$/.match?(key.to_s) ||
                       AVOID_GETTERS.key?(key) ||
-                      Compat.method_defined_without_ancestors?(tool_class, key)
+                      tool_class.method_defined?(key, false) ||
+                      tool_class.private_method_defined?(key, false)
           end
           tool_class.class_eval do
             define_method(key) do

data/lib/toys/dsl/tool.rb

@@ -436,9 +436,12 @@ module Toys
       #     current commit if already loading from git, or to `HEAD`.
       # @param as [String] Load into the given tool/namespace. If omitted,
       #     configuration will be loaded into the current namespace.
-      # @param update [Boolean] Force-fetch from the remote (unless the commit
-      #     is a SHA). This will ensure that symbolic commits, such as branch
-      #     names, are up to date. Default is false.
+      # @param update [Boolean,Integer] Whether and when to force-fetch from
+      #     the remote (unless the commit is a SHA). Force-fetching will ensure
+      #     that symbolic commits, such as branch names or HEAD, are up to date.
+      #     You can pass `true` or `false` to specify whether to update, or an
+      #     integer to update if the last update was done at least that many
+      #     seconds ago. Default is false.
       #
       # @return [self]
       #
@@ -453,9 +456,35 @@ module Toys
         raise ToolDefinitionError, "Git remote not specified" unless remote
         path ||= ""
         commit ||= source_info.git_commit || "HEAD"
-        @__loader.load_git(source_info, remote, path, commit,
-                           @__words, @__remaining_words, @__priority,
-                           update: update)
+        @__loader.load_git(source_info, remote, path, commit, update,
+                           @__words, @__remaining_words, @__priority)
+        self
+      end
+
+      ##
+      # Load configuration from a gem, as if its contents were inserted at the
+      # current location.
+      #
+      # @param name [String] Name of the gem
+      # @param version [String,Array<String>] Version requirements for the gem.
+      # @param path [String] Optional path within the gem to the file or
+      #     directory to load. Defaults to the root of the gem's toys directory.
+      # @param toys_dir [String] Optional override for the gem's toys
+      #     directory name. If not specified, the default specified by the gem
+      #     will be used.
+      # @param as [String] Load into the given tool/namespace. If omitted,
+      #     configuration will be loaded into the current namespace.
+      #
+      def load_gem(name, version: nil, path: nil, toys_dir: nil, as: nil)
+        if as
+          tool(as) do
+            load_gem(name, version: version, path: path, toys_dir: toys_dir)
+          end
+          return self
+        end
+        path ||= ""
+        @__loader.load_gem(source_info, name, version, toys_dir, path,
+                           @__words, @__remaining_words, @__priority)
         self
       end
 
@@ -504,7 +533,7 @@ module Toys
         if template_class.nil?
           raise ToolDefinitionError, "Template not found: #{name.inspect}"
         end
-        template = Compat.instantiate(template_class, args, kwargs, nil)
+        template = template_class.new(*args, **kwargs)
         yield template if block_given?
         class_exec(template, &template_class.expansion)
         self
@@ -946,15 +975,18 @@ module Toys
       # @param default [Object] The default value. This is the value that will
       #     be set in the context if this flag is not provided on the command
       #     line. Defaults to `nil`.
-      # @param handler [Proc,nil,:set,:push] An optional handler for
-      #     setting/updating the value. A handler is a proc taking two
-      #     arguments, the given value and the previous value, returning the
-      #     new value that should be set. You may also specify a predefined
-      #     named handler. The `:set` handler (the default) replaces the
-      #     previous value (effectively `-> (val, _prev) { val }`). The
-      #     `:push` handler expects the previous value to be an array and
-      #     pushes the given value onto it; it should be combined with setting
-      #     `default: []` and is intended for "multi-valued" flags.
+      # @param handler [Proc,nil,:set,:push] An optional handler that
+      #     customizes how a value is set or updated when the flag is parsed.
+      #     A handler is a proc that takes up to three arguments: the given
+      #     value, the previous value, and a hash containing all the data
+      #     collected so far during argument parsing. The proc must return the
+      #     new value for the flag.
+      #     You may also specify a predefined named handler. The `:set` handler
+      #     (the default) replaces the previous value (effectively
+      #     `-> (val) { val }`). The `:push` handler expects the previous value
+      #     to be an array and pushes the given value onto it; it should be
+      #     combined with setting the default value to `[]` and is intended for
+      #     "multi-valued" flags.
       # @param complete_flags [Object] A specifier for shell tab completion
       #     for flag names associated with this flag. By default, a
       #     {Toys::Flag::DefaultCompletion} is used, which provides the flag's

data/lib/toys/flag.rb

@@ -374,16 +374,16 @@ module Toys
     # The set handler replaces the previous value.
     # @return [Proc]
     #
-    SET_HANDLER = ->(val, _prev) { val }
+    SET_HANDLER = proc { |val| val }
 
     ##
     # The push handler pushes the given value using the `<<` operator.
     # @return [Proc]
     #
-    PUSH_HANDLER = ->(val, prev) { prev.nil? ? [val] : prev << val }
+    PUSH_HANDLER = proc { |val, prev| prev.nil? ? [val] : prev << val }
 
     ##
-    # The default handler is the set handler, replacing the previous value.
+    # The default handler is the set handler, which replaces the previous value.
     # @return [Proc]
     #
     DEFAULT_HANDLER = SET_HANDLER
@@ -401,15 +401,18 @@ module Toys
     # @param default [Object] The default value. This is the value that will
     #     be set in the context if this flag is not provided on the command
     #     line. Defaults to `nil`.
-    # @param handler [Proc,nil,:set,:push] An optional handler for
-    #     setting/updating the value. A handler is a proc taking two
-    #     arguments, the given value and the previous value, returning the
-    #     new value that should be set. You may also specify a predefined
-    #     named handler. The `:set` handler (the default) replaces the
-    #     previous value (effectively `-> (val, _prev) { val }`). The
-    #     `:push` handler expects the previous value to be an array and
-    #     pushes the given value onto it; it should be combined with setting
-    #     `default: []` and is intended for "multi-valued" flags.
+    # @param handler [Proc,nil,:set,:push] An optional handler that customizes
+    #     how a value is set or updated when the flag is parsed.
+    #     A handler is a proc that takes up to three arguments: the given
+    #     value, the previous value, and a hash containing all the data
+    #     collected so far during argument parsing. The proc must return the
+    #     new value for the flag.
+    #     You may also specify a predefined named handler. The `:set` handler
+    #     (the default) replaces the previous value (effectively
+    #     `-> (val) { val }`). The `:push` handler expects the previous value
+    #     to be an array and pushes the given value onto it; it should be
+    #     combined with setting `default: []` and is intended for
+    #     "multi-valued" flags.
     # @param complete_flags [Object] A specifier for shell tab completion for
     #     flag names associated with this flag. By default, a
     #     {Toys::Flag::DefaultCompletion} is used, which provides the flag's

data/lib/toys/input_file.rb

@@ -14,7 +14,7 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
   def self.evaluate(tool_class, words, priority, remaining_words, source, loader)
     namespace = ::Module.new
     namespace.module_eval do
-      include ::Toys::Context::Key
+      include ::Toys::Context::Key # rubocop:disable Layout/EmptyLinesAfterModuleInclusion
       @__tool_class = tool_class
     end
     path = source.source_path
@@ -25,9 +25,7 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
       const_set(name, namespace)
       ::Toys::DSL::Internal.prepare(tool_class, words, priority, remaining_words, source, loader) do
         ::Toys::ContextualError.capture_path("Error while loading Toys config!", path) do
-          # rubocop:disable Security/Eval
-          eval(str, __binding, path)
-          # rubocop:enable Security/Eval
+          eval(str, __binding, path) # rubocop:disable Security/Eval
         end
       end
     end
@@ -48,7 +46,7 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
     return nil if index.nil?
     "#{string[0, index]}" \
       "module #{module_name}; @__tool_class.class_eval do; " \
-      "#{string[index..-1]}\n" \
+      "#{string[index..]}\n" \
       "end; end\n"
   end
 end