toys-core 0.16.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3713d359e1b03fc22968ed9e3254c82c92e157c92146c6d5728d514eb88dc1c
-  data.tar.gz: d96baedc494f78a534a9f0a00ca64409bdbd25e1cf33ec48d2a16f59824c72b9
+  metadata.gz: be1392e6cb8f49c19e9472449943cf873209b939d11cdc1e788bb58a1083c013
+  data.tar.gz: d78818495765389e99111032e863dc21d4fa982dfde07780a5b1ff9cc96743df
 SHA512:
-  metadata.gz: 4ca769a0b88654941c7369f9fdcf22c532ae53358c554e38817beea217d9d544d20324cd2288c8d961cd37ab2527a22e82289a3726e6d5113a7c6d42f6502a56
-  data.tar.gz: c50ff7f52713c42eed61ea3e2e81e7b53d1a75ccc89b8ceaff6f4114d71d647018ecf80c529d4254234501108dd5e9f95406e297a64d5064d3f7fa88e8297b47
+  metadata.gz: 63ca5e62ed30e068d7b75a0b08e3916fc19466d92ca165d52f8f333e9538f96358027fdd676690042c5eb55d2e2569c3c1a8b8d9c32dd33f7ec3d4036230bc81
+  data.tar.gz: 61821ef2ffde83d82469c6a8d38ba092f1efc2a3254a1f848d877fda09a888fc932274e27c742c53d0480a55abc1b49fc6266359ceeca31e8851e16dac3ce0e8

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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

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)
@@ -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/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.16.0"
+    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/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
 
@@ -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/loader.rb

@@ -49,7 +49,8 @@ module Toys
                    mixin_lookup: nil,
                    middleware_lookup: nil,
                    template_lookup: nil,
-                   git_cache: nil)
+                   git_cache: nil,
+                   gems_util: nil)
       if index_file_name && ::File.extname(index_file_name) != ".rb"
         raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
@@ -73,6 +74,7 @@ module Toys
       @middleware_stack = Middleware.stack(middleware_stack)
       @delimiter_handler = DelimiterHandler.new(extra_delimiters)
       @git_cache = git_cache
+      @gems_util = gems_util
       get_tool([], -999_999)
     end
 
@@ -204,8 +206,7 @@ module Toys
                 high_priority: false,
                 update: false,
                 context_directory: nil)
-      git_cache = @git_cache || Loader.default_git_cache
-      path = git_cache.get(git_remote, path: git_path, commit: git_commit, update: update)
+      path = resolve_git_path(git_remote, git_path, git_commit, update)
       @mutex.synchronize do
         raise "Cannot add a git source after tool loading has started" if @loading_started
         priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
@@ -219,6 +220,43 @@ module Toys
       self
     end
 
+    ##
+    # Add a configuration gem source to the loader.
+    #
+    # @param gem_name [String] The name of the gem
+    # @param gem_version [String,Array<String>] The version requirements
+    # @param gem_path [String] The path from the gem's toys directory to the
+    #     relevant file or directory. Specify the empty string to use the
+    #     entire toys directory.
+    # @param high_priority [Boolean] If true, add this path at the top of the
+    #     priority list. Defaults to false, indicating the new path should be
+    #     at the bottom of the priority list.
+    # @param gem_toys_dir [String] The name of the toys directory. Optional.
+    #     Defaults to the directory specified in the gem's metadata, or the
+    #     value "toys".
+    # @param context_directory [String,nil] The context directory for tools
+    #     loaded from this source. You can pass a directory path as a string,
+    #     or `nil` to denote no context. Defaults to `nil`.
+    # @return [self]
+    #
+    def add_gem(gem_name, gem_version, gem_path,
+                high_priority: false,
+                gem_toys_dir: nil,
+                context_directory: nil)
+      gem_version, gem_path, path = resolve_gem_info(gem_name, gem_version, gem_toys_dir, gem_path)
+      @mutex.synchronize do
+        raise "Cannot add a gem source after tool loading has started" if @loading_started
+        priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
+        source = SourceInfo.create_gem_root(gem_name, gem_version, gem_path, path, priority,
+                                            context_directory: context_directory,
+                                            data_dir_name: @data_dir_name,
+                                            lib_dir_name: @lib_dir_name)
+        @roots_by_priority[priority] = source
+        @worklist << [source, [], priority]
+      end
+      self
+    end
+
     ##
     # Given a list of command line arguments, find the appropriate tool to
     # handle the command, loading it from the configuration if necessary.
@@ -439,8 +477,7 @@ module Toys
     #
     def load_path(parent_source, path, words, remaining_words, priority)
       if parent_source.git_remote
-        raise LoaderError,
-              "Git source #{parent_source.source_name} tried to load from the local file system"
+        raise LoaderError, "Git source #{parent_source.source_name} tried to load from the local file system"
       end
       source = parent_source.absolute_child(path)
       @mutex.synchronize do
@@ -454,16 +491,30 @@ module Toys
     #
     # @private This interface is internal and subject to change without warning.
     #
-    def load_git(parent_source, git_remote, git_path, git_commit, words, remaining_words, priority,
-                 update: false)
-      git_cache = @git_cache || Loader.default_git_cache
-      path = git_cache.get(git_remote, path: git_path, commit: git_commit, update: update)
+    def load_git(parent_source, git_remote, git_path, git_commit, update,
+                 words, remaining_words, priority)
+      path = resolve_git_path(git_remote, git_path, git_commit, update)
       source = parent_source.git_child(git_remote, git_path, git_commit, path)
       @mutex.synchronize do
         load_validated_path(source, words, remaining_words, priority)
       end
     end
 
+    ##
+    # Load configuration from the given gem. This is called from the `load_gem`
+    # directive in the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def load_gem(parent_source, gem_name, gem_version, gem_toys_dir, gem_path,
+                 words, remaining_words, priority)
+      gem_version, gem_path, path = resolve_gem_info(gem_name, gem_version, gem_toys_dir, gem_path)
+      source = parent_source.gem_child(gem_name, gem_version, gem_path, path)
+      @mutex.synchronize do
+        load_validated_path(source, words, remaining_words, priority)
+      end
+    end
+
     ##
     # Load a subtool block. Called from the `tool` directive in the DSL.
     #
@@ -478,6 +529,7 @@ module Toys
 
     @git_cache_mutex = ::Mutex.new
     @default_git_cache = nil
+    @default_gems_util = nil
 
     ##
     # Get a global default GitCache.
@@ -493,6 +545,20 @@ module Toys
       end
     end
 
+    ##
+    # Get a global default Gems utility.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.default_gems_util
+      @git_cache_mutex.synchronize do
+        @default_gems_util ||= begin
+          require "toys/utils/gems"
+          Utils::Gems.new
+        end
+      end
+    end
+
     ##
     # Determine the next setting for remaining_words, given a word.
     #
@@ -640,6 +706,28 @@ module Toys
 
     private
 
+    ##
+    # Resolve the file system path to the given object in the git cache
+    #
+    def resolve_git_path(git_remote, git_path, git_commit, update)
+      git_cache = @git_cache || Loader.default_git_cache
+      git_cache.get(git_remote, path: git_path, commit: git_commit, update: update)
+    end
+
+    ##
+    # Resolve information for a gem source.
+    #
+    def resolve_gem_info(gem_name, gem_version, gem_toys_dir, gem_path)
+      gems_util = @gems_util || Loader.default_gems_util
+      gems_util.activate(gem_name, *Array(gem_version))
+      gem_spec = ::Gem.loaded_specs[gem_name]
+      raise LoaderError, "Unable to find gem #{gem_name}" unless gem_spec&.gem_dir
+      gem_toys_dir ||= gem_spec.metadata["toys_dir"] || "toys"
+      gem_path = gem_path ? ::File.join(gem_toys_dir, gem_path) : gem_toys_dir
+      path = ::File.join(gem_spec.gem_dir, gem_path)
+      [gem_spec.version, gem_path, path]
+    end
+
     ##
     # Return a snapshot of all the current tool definitions that have been
     # loaded. No additional loading is done. The returned array is not in any

data/lib/toys/source_info.rb

@@ -11,6 +11,7 @@ module Toys
   # * A toys directory
   # * A single toys file
   # * A file or directory loaded from git
+  # * A file or directory loaded from a gem
   # * A config block passed directly to the CLI
   # * A tool block within a toys file
   #
@@ -143,6 +144,32 @@ module Toys
     #
     attr_reader :git_commit
 
+    ##
+    # The gem name. This is set if the source, or one of its ancestors, comes
+    # from a gem.
+    #
+    # @return [String] The gem name.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_name
+
+    ##
+    # The gem version. This is set if the source, or one of its ancestors,
+    # comes from a gem.
+    #
+    # @return [Gem::Version] The gem version.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_version
+
+    ##
+    # The path within the gem, including the toys root directory in the gem.
+    #
+    # @return [String] The path.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_path
+
     ##
     # A user-visible name of this source.
     #
@@ -191,8 +218,10 @@ module Toys
     #
     # @private This interface is internal and subject to change without warning.
     #
-    def initialize(parent, priority, context_directory, source_type, source_path, source_proc,
-                   git_remote, git_path, git_commit, source_name, data_dir_name, lib_dir_name)
+    def initialize(parent, priority, context_directory,
+                   source_type, source_path, source_proc,
+                   git_remote, git_path, git_commit, gem_name, gem_version, gem_path,
+                   source_name, data_dir_name, lib_dir_name)
       @parent = parent
       @root = parent&.root || self
       @priority = priority
@@ -204,7 +233,10 @@ module Toys
       @git_remote = git_remote
       @git_path = git_path
       @git_commit = git_commit
-      @source_name = source_name
+      @gem_name = gem_name
+      @gem_version = gem_version
+      @gem_path = gem_path
+      @source_name = source_name || default_source_name
       @data_dir_name = data_dir_name
       @lib_dir_name = lib_dir_name
       @data_dir = find_special_dir(data_dir_name)
@@ -220,18 +252,12 @@ module Toys
       unless source_type == :directory
         raise LoaderError, "relative_child is valid only on a directory source"
       end
-      child_path = ::File.join(source_path, filename)
-      child_path, type = SourceInfo.check_path(child_path, true)
+      child_path, type = SourceInfo.check_path(::File.join(source_path, filename), true)
       return nil unless child_path
-      child_git_path = ::File.join(git_path, filename) if git_path
-      source_name ||=
-        if git_path
-          "git(remote=#{git_remote} path=#{child_git_path} commit=#{git_commit})"
-        else
-          child_path
-        end
+      child_git_path = git_path.empty? ? filename : ::File.join(git_path, filename) if git_path
+      child_gem_path = gem_path.empty? ? filename : ::File.join(gem_path, filename) if gem_path
       SourceInfo.new(self, priority, context_directory, type, child_path, nil,
-                     git_remote, child_git_path, git_commit,
+                     git_remote, child_git_path, git_commit, gem_name, gem_version, child_gem_path,
                      source_name, @data_dir_name, @lib_dir_name)
     end
 
@@ -242,8 +268,8 @@ module Toys
     #
     def absolute_child(child_path, source_name: nil)
       child_path, type = SourceInfo.check_path(child_path, false)
-      source_name ||= child_path
-      SourceInfo.new(self, priority, context_directory, type, child_path, nil, nil, nil, nil,
+      SourceInfo.new(self, priority, context_directory, type, child_path, nil,
+                     nil, nil, nil, nil, nil, nil,
                      source_name, @data_dir_name, @lib_dir_name)
     end
 
@@ -252,13 +278,22 @@ module Toys
     #
     # @private This interface is internal and subject to change without warning.
     #
-    def git_child(child_git_remote, child_git_path, child_git_commit, child_path,
-                  source_name: nil)
+    def git_child(child_git_remote, child_git_path, child_git_commit, child_path, source_name: nil)
+      child_path, type = SourceInfo.check_path(child_path, false)
+      SourceInfo.new(self, priority, context_directory, type, child_path, nil,
+                     child_git_remote, child_git_path, child_git_commit, nil, nil, nil,
+                     source_name, @data_dir_name, @lib_dir_name)
+    end
+
+    ##
+    # Create a child SourceInfo with a gem source.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def gem_child(child_gem_name, child_gem_version, child_gem_path, child_path, source_name: nil)
       child_path, type = SourceInfo.check_path(child_path, false)
-      source_name ||=
-        "git(remote=#{child_git_remote} path=#{child_git_path} commit=#{child_git_commit})"
       SourceInfo.new(self, priority, context_directory, type, child_path, nil,
-                     child_git_remote, child_git_path, child_git_commit,
+                     nil, nil, nil, child_gem_name, child_gem_version, child_gem_path,
                      source_name, @data_dir_name, @lib_dir_name)
     end
 
@@ -270,7 +305,7 @@ module Toys
     def proc_child(child_proc, source_name: nil)
       source_name ||= self.source_name
       SourceInfo.new(self, priority, context_directory, :proc, source_path, child_proc,
-                     git_remote, git_path, git_commit,
+                     git_remote, git_path, git_commit, gem_name, gem_version, gem_path,
                      source_name, @data_dir_name, @lib_dir_name)
     end
 
@@ -291,8 +326,8 @@ module Toys
       when :path
         context_directory = source_path
       end
-      source_name ||= source_path
-      new(nil, priority, context_directory, type, source_path, nil, nil, nil, nil,
+      new(nil, priority, context_directory, type, source_path, nil,
+          nil, nil, nil, nil, nil, nil,
           source_name, data_dir_name, lib_dir_name)
     end
 
@@ -307,9 +342,25 @@ module Toys
                              lib_dir_name: nil,
                              source_name: nil)
       source_path, type = check_path(source_path, false)
-      source_name ||= "git(remote=#{git_remote} path=#{git_path} commit=#{git_commit})"
-      new(nil, priority, context_directory, type, source_path, nil, git_remote,
-          git_path, git_commit, source_name, data_dir_name, lib_dir_name)
+      new(nil, priority, context_directory, type, source_path, nil,
+          git_remote, git_path, git_commit, nil, nil, nil,
+          source_name, data_dir_name, lib_dir_name)
+    end
+
+    ##
+    # Create a root source info for a loaded gem.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.create_gem_root(gem_name, gem_version, gem_path, source_path, priority,
+                             context_directory: nil,
+                             data_dir_name: nil,
+                             lib_dir_name: nil,
+                             source_name: nil)
+      source_path, type = check_path(source_path, false)
+      new(nil, priority, context_directory, type, source_path, nil,
+          nil, nil, nil, gem_name, gem_version, gem_path,
+          source_name, data_dir_name, lib_dir_name)
     end
 
     ##
@@ -322,9 +373,9 @@ module Toys
                               data_dir_name: nil,
                               lib_dir_name: nil,
                               source_name: nil)
-      source_name ||= "(code block #{source_proc.object_id})"
-      new(nil, priority, context_directory, :proc, nil, source_proc, nil, nil,
-          nil, source_name, data_dir_name, lib_dir_name)
+      new(nil, priority, context_directory, :proc, nil, source_proc,
+          nil, nil, nil, nil, nil, nil,
+          source_name, data_dir_name, lib_dir_name)
     end
 
     ##
@@ -354,6 +405,18 @@ module Toys
 
     private
 
+    def default_source_name
+      if @git_remote
+        "git(remote=#{@git_remote} path=#{@git_path} commit=#{@git_commit})"
+      elsif @gem_name
+        "gem(name=#{@gem_name} version=#{@gem_version} path=#{@gem_path})"
+      elsif @source_type == :proc
+        "(code block #{@source_proc.object_id})"
+      else
+        @source_path
+      end
+    end
+
     def find_special_dir(dir_name)
       return nil if @source_type != :directory || dir_name.nil?
       dir = ::File.join(@source_path, dir_name)

data/lib/toys/standard_mixins/gems.rb

@@ -22,8 +22,8 @@ module Toys
     #
     #     tool "my_tool" do
     #       include :gems
-    #       gem "nokogiri", "~> 1.15"
     #       def run
+    #         gem "nokogiri", "~> 1.15"
     #         # Do stuff with Nokogiri
     #       end
     #     end
@@ -33,6 +33,18 @@ module Toys
     #
     #     include :gems, on_missing: :error
     #
+    # You can also pass options to the {#gem} mixin method itself:
+    #
+    #     tool "my_tool" do
+    #       include :gems
+    #       def run
+    #         # If the gem is not installed, error out instead of asking to
+    #         # install it.
+    #         gem "nokogiri", "~> 1.15", on_missing: :error
+    #         # Do stuff with Nokogiri
+    #       end
+    #     end
+    #
     # See {Toys::Utils::Gems#initialize} for a list of supported options.
     #
     module Gems
@@ -54,8 +66,8 @@ module Toys
       # @param requirements [String...] Version requirements
       # @return [void]
       #
-      def gem(name, *requirements)
-        self.class.gems.activate(name, *requirements)
+      def gem(name, *requirements, **options)
+        self.class.gem(name, *requirements, **options)
       end
 
       on_include do |**opts|
@@ -76,8 +88,15 @@ module Toys
         ##
         # @private
         #
-        def self.gem(name, *requirements)
-          gems.activate(name, *requirements)
+        def self.gem(name, *requirements, **options)
+          gems_util =
+            if options.empty?
+              gems
+            else
+              require "toys/utils/gems"
+              Utils::Gems.new(**options)
+            end
+          gems_util.activate(name, *requirements)
         end
       end
     end

data/lib/toys/tool_definition.rb

@@ -1012,15 +1012,16 @@ 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. 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 that should be set. 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/utils/git_cache.rb

@@ -274,6 +274,21 @@ module Toys
         end
       end
 
+      ##
+      # Returns whether shared source files are writable by default.
+      # Normally, shared sources are made read-only to protect them from being
+      # modified accidentally since multiple clients may be accessing them.
+      # However, you can disable this feature by setting the environment
+      # variable `TOYS_GIT_CACHE_WRITABLE` to any non-empty value. This can be
+      # useful in environments that want to clean up temporary directories and
+      # are being hindered by read-only files.
+      #
+      # @return [boolean]
+      #
+      def self.sources_writable?
+        !::ENV["TOYS_GIT_CACHE_WRITABLE"].to_s.empty?
+      end
+
       ##
       # Access a git cache.
       #
@@ -318,7 +333,7 @@ module Toys
       # @param into [String] If provided, copies the specified files into the
       #     given directory path. If omitted or `nil`, populates and returns a
       #     shared source file or directory.
-      # @param update [Boolean,Integer] Whether to update of non-SHA commit
+      # @param update [Boolean,Integer] Whether to update non-SHA commit
       #     references if they were previously loaded. This is useful, for
       #     example, if the commit is `HEAD` or a branch name. Pass `true` or
       #     `false` to specify whether to update, or an integer to update if
@@ -569,7 +584,7 @@ module Toys
           ::FileUtils.mkdir_p(source_path)
           ::FileUtils.chmod_R("u+w", source_path, force: true)
           copy_from_repo(repo_path, source_path, sha, path)
-          ::FileUtils.chmod_R("a-w", source_path, force: true)
+          ::FileUtils.chmod_R("a-w", source_path, force: true) unless GitCache.sources_writable?
         end
         repo_lock.access_source!(sha, path)
         path == "." ? source_path : ::File.join(source_path, path)

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.17.0
 platform: ruby
 authors:
 - Daniel Azuma
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line executables using the Toys DSL and classes.
 email:
@@ -78,10 +92,10 @@ homepage: https://github.com/dazuma/toys
 licenses:
 - MIT
 metadata:
-  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.16.0/file.CHANGELOG.html
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-core/v0.17.0/file.CHANGELOG.html
   source_code_uri: https://github.com/dazuma/toys/tree/main/toys-core
   bug_tracker_uri: https://github.com/dazuma/toys/issues
-  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.16.0
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-core/v0.17.0
 rdoc_options: []
 require_paths:
 - lib