toys-core 0.11.5 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae396604e3a0005b460ad94f95187b603f36e8d10d1147da2a78b069232f7963
-  data.tar.gz: 267209d6e7ab4575053219eee5fb1c6be47b9bd6ac6468b6da5c9abb9ed227c2
+  metadata.gz: 2e6f3ce99b43220466c4b43842c1fa78d3cfca815ecc559be749518d26156be9
+  data.tar.gz: 8a3dbb068001b3a52d5b070ae0f8652aeea5f1763ae19a938aa84da693023c2c
 SHA512:
-  metadata.gz: 527f51e0e679f93786ecd671ff14386615e2014e0dbd4995fd4bb6e58040cb00b27d83d3721c412eb8cc83fdc82fe7dff63c97e0e3d8bca8f8b8d7b04a5d9f41
-  data.tar.gz: 07c617895710b6f5dd69c6fdb16613c2ed7474361a1cbd8617ae1d271eca647ffa457e77bec7e1b30915b1e01ad25173c74251f1728f261a5d5565ca29b80d68
+  metadata.gz: de8dc024af7e706749b65a8e2b4fe9430e380b58add4bc9b643bc357dce7d5a5109057a2aaccdbfb657410def1372494b020cab59b1ebd03de83d2359a0746ab
+  data.tar.gz: 96b6ca463c27eff9fe403d365afe15a6d4c75bed057b8dc162b40c696b0f31606738197c5bdb68ed759d9c0a0f29af0e4ddd4aed929e41649cb6a46b67909ea8

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Release History
 
+### v0.12.0 / 2021-08-05
+
+Toys-Core 0.12.0 is a major release with significant new features and bug fixes, and a few breaking interface changes. Additionally, this release now requires Ruby 2.4 or later.
+
+Breaking interface changes:
+
+* The Toys::Tool class has been renamed Toys::ToolDefinition so that the old name can be used for class-based tool definition.
+* Tool definition now raises ToolDefinitionError if whitespace, control characters, or certain punctuation are used in a tool name.
+* Toys::Loader#add_path no longer supports multiple paths. Use add_path_set instead.
+* The "name" argument was renamed to "source_name" in Toys::Loader#add_block and Toys::CLI#add_config_block
+
+New functionality:
+
+* The DSL now supports a class-based tool definition syntax (in addition to the existing block-based syntax). Some users may prefer this new class-based style as more Ruby-like.
+* You can now load tools from a remote git repository using the load_git directive.
+* Whitespace is now automatically considered a name delimiter when defining tools.
+* There is now an extensible settings mechanism to activate less-common tool behavior. Currently there is one setting, which causes subtools to inherit their parent's methods by default.
+* The load directive can load into a new tool.
+* Added a new utility class and mixin that provides XDG Base Directory information.
+* Added a new utility class and mixin that provides cached access to remote git repos.
+* The help text generator now supports splitting the subtool list by source.
+* Loader and CLI methods that add tool configs now uniformly provide optional source_name and context_directory arguments.
+* Toys::SourceInfo now supports getting the root ancestor and priority of a source.
+* Toys::ToolDefinition now has a direct accessor for the source root. This is always set for a tool, even if it isn't marked as finished.
+
+Fixes:
+
+* Fixed some bundler integration issues that occurred when the bundle is being installed in a separate path such as a vendor directory.
+* Toys::ContextualError now includes the full backtrace of the cause.
+* Cleaned up some unused memory objects during tool loading and lookup.
+
 ### v0.11.5 / 2021-03-28
 
 * BREAKING CHANGE: The exit_on_nonzero_status option to exec now exits on signals and failures to spawn, in addition to error codes.

data/README.md

@@ -34,7 +34,7 @@ Install the **toys-core** gem using:
 You may also install the **toys** gem, which brings in **toys-core** as a
 dependency.
 
-Toys-Core requires Ruby 2.3 or later.
+Toys-Core requires Ruby 2.4 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.

data/lib/toys-core.rb

@@ -70,8 +70,10 @@ require "toys/compat"
 require "toys/completion"
 require "toys/context"
 require "toys/core"
+require "toys/dsl/base"
 require "toys/dsl/flag"
 require "toys/dsl/flag_group"
+require "toys/dsl/internal"
 require "toys/dsl/positional_arg"
 require "toys/dsl/tool"
 require "toys/errors"
@@ -83,7 +85,8 @@ require "toys/middleware"
 require "toys/mixin"
 require "toys/module_lookup"
 require "toys/positional_arg"
+require "toys/settings"
 require "toys/source_info"
 require "toys/template"
-require "toys/tool"
+require "toys/tool_definition"
 require "toys/wrappable_string"

data/lib/toys/acceptor.rb

@@ -602,11 +602,11 @@ module Toys
         Simple.new(type_desc: "boolean", well_known_spec: spec) do |s|
           if s.nil?
             default
+          elsif s.empty?
+            REJECT
           else
             s = s.downcase
-            if s.empty?
-              REJECT
-            elsif TRUE_STRINGS.any? { |t| t.start_with?(s) }
+            if TRUE_STRINGS.any? { |t| t.start_with?(s) }
               true
             elsif FALSE_STRINGS.any? { |f| f.start_with?(s) }
               false

data/lib/toys/arg_parser.rb

@@ -261,7 +261,7 @@ module Toys
       # @param message [String] The message. Required.
       #
       def initialize(message)
-        super(message)
+        super(message, name: nil)
       end
     end
 
@@ -269,7 +269,7 @@ module Toys
     # Create an argument parser for a particular tool.
     #
     # @param cli [Toys::CLI] The CLI in effect.
-    # @param tool [Toys::Tool] The tool defining the argument format.
+    # @param tool [Toys::ToolDefinition] The tool defining the argument format.
     # @param default_data [Hash] Additional initial data (such as verbosity).
     # @param require_exact_flag_match [Boolean] Whether to require flag matches
     #     be exact (not partial). Default is false.
@@ -295,7 +295,7 @@ module Toys
 
     ##
     # The tool definition governing this parser.
-    # @return [Toys::Tool]
+    # @return [Toys::ToolDefinition]
     #
     attr_reader :tool
 
@@ -429,7 +429,7 @@ module Toys
         Context::Key::TOOL_NAME => tool.full_name,
         Context::Key::USAGE_ERRORS => [],
       }
-      Compat.merge_clones(data, tool.default_data)
+      tool.default_data.each { |k, v| data[k] = v.clone }
       default_data.each { |k, v| data[k] ||= v }
       data
     end
@@ -450,7 +450,7 @@ module Toys
       case arg
       when "--"
         @flags_allowed = false
-      when /\A(--\w[\?\w-]*)=(.*)\z/
+      when /\A(--\w[?\w-]*)=(.*)\z/
         handle_valued_flag(::Regexp.last_match(1), ::Regexp.last_match(2))
       when /\A--.+\z/
         handle_plain_flag(arg)
@@ -474,8 +474,7 @@ module Toys
       return "" unless flag_def
       @seen_flag_keys << flag_def.key
       if flag_def.flag_type == :boolean
-        add_data(flag_def.key, flag_def.handler, nil, !flag_result.unique_flag_negative?,
-                 :flag, name)
+        add_data(flag_def.key, flag_def.handler, nil, !flag_result.unique_flag_negative?, :flag, name)
       elsif following.empty?
         if flag_def.value_type == :required || flag_result.unique_flag_syntax.value_delim == " "
           @active_flag_def = flag_def

data/lib/toys/cli.rb

@@ -78,8 +78,8 @@ module Toys
     #     with different verbosity settings (since the logger cannot have
     #     multiple level settings simultaneously). In that case, do not set a
     #     global logger, but use the `logger_factory` parameter instead.
-    # @param logger_factory [Proc] A proc that takes a {Toys::Tool} as an
-    #     argument, and returns a `Logger` to use when running that tool.
+    # @param logger_factory [Proc] A proc that takes a {Toys::ToolDefinition}
+    #     as an argument, and returns a `Logger` to use when running that tool.
     #     Optional. If not provided (and no global logger is set), CLI will use
     #     a default factory that writes generates loggers writing formatted
     #     output to `STDERR`, as defined by {Toys::CLI.default_logger_factory}.
@@ -321,10 +321,22 @@ module Toys
     #     a Toys directory.
     # @param high_priority [Boolean] Add the config at the head of the priority
     #     list rather than the tail.
+    # @param source_name [String] A custom name for the root source. Optional.
+    # @param context_directory [String,nil,:path,:parent] The context directory
+    #     for tools loaded from this path. You can pass a directory path as a
+    #     string, `:path` to denote the given path, `:parent` to denote the
+    #     given path's parent directory, or `nil` to denote no context.
+    #     Defaults to `:parent`.
     # @return [self]
     #
-    def add_config_path(path, high_priority: false)
-      @loader.add_path(path, high_priority: high_priority)
+    def add_config_path(path,
+                        high_priority: false,
+                        source_name: nil,
+                        context_directory: :parent)
+      @loader.add_path(path,
+                       high_priority: high_priority,
+                       source_name: source_name,
+                       context_directory: context_directory)
       self
     end
 
@@ -336,15 +348,24 @@ module Toys
     #
     # @param high_priority [Boolean] Add the config at the head of the priority
     #     list rather than the tail.
-    # @param name [String] The source name that will be shown in documentation
-    #     for tools defined in this block. If omitted, a default unique string
-    #     will be generated.
+    # @param source_name [String] The source name that will be shown in
+    #     documentation for tools defined in this block. If omitted, a default
+    #     unique string will be generated.
     # @param block [Proc] The block of configuration, executed in the context
     #     of the tool DSL {Toys::DSL::Tool}.
+    # @param context_directory [String,nil] The context directory for tools
+    #     loaded from this block. You can pass a directory path as a string, or
+    #     `nil` to denote no context. Defaults to `nil`.
     # @return [self]
     #
-    def add_config_block(high_priority: false, name: nil, &block)
-      @loader.add_block(high_priority: high_priority, name: name, &block)
+    def add_config_block(high_priority: false,
+                         source_name: nil,
+                         context_directory: nil,
+                         &block)
+      @loader.add_block(high_priority: high_priority,
+                        source_name: source_name,
+                        context_directory: context_directory,
+                        &block)
       self
     end
 
@@ -358,19 +379,28 @@ module Toys
     # @param search_path [String] A path to search for configs.
     # @param high_priority [Boolean] Add the configs at the head of the
     #     priority list rather than the tail.
+    # @param context_directory [String,nil,:path,:parent] The context directory
+    #     for tools loaded from this path. You can pass a directory path as a
+    #     string, `:path` to denote the given path, `:parent` to denote the
+    #     given path's parent directory, or `nil` to denote no context.
+    #     Defaults to `:path`.
     # @return [self]
     #
-    def add_search_path(search_path, high_priority: false)
+    def add_search_path(search_path,
+                        high_priority: false,
+                        context_directory: :path)
       paths = []
       if @config_file_name
         file_path = ::File.join(search_path, @config_file_name)
-        paths << file_path if !::File.directory?(file_path) && ::File.readable?(file_path)
+        paths << @config_file_name if !::File.directory?(file_path) && ::File.readable?(file_path)
       end
       if @config_dir_name
         dir_path = ::File.join(search_path, @config_dir_name)
-        paths << dir_path if ::File.directory?(dir_path) && ::File.readable?(dir_path)
+        paths << @config_dir_name if ::File.directory?(dir_path) && ::File.readable?(dir_path)
       end
-      @loader.add_path(paths, high_priority: high_priority)
+      @loader.add_path_set(search_path, paths,
+                           high_priority: high_priority,
+                           context_directory: context_directory)
       self
     end
 
@@ -443,7 +473,7 @@ module Toys
     # Run the given tool with the given arguments.
     # Does not handle exceptions.
     #
-    # @param tool [Toys::Tool] The tool to run.
+    # @param tool [Toys::ToolDefinition] The tool to run.
     # @param args [Array<String>] Command line arguments passed to the tool.
     # @param default_data [Hash] Initial tool context data.
     # @return [Integer] The resulting status code

data/lib/toys/compat.rb

@@ -53,28 +53,6 @@ module Toys
       end
     end
 
-    # In Ruby < 2.4, some objects such as nil cannot be cloned.
-    if ruby_version >= 20400
-      # @private
-      def self.merge_clones(hash, orig)
-        orig.each { |k, v| hash[k] = v.clone }
-        hash
-      end
-    else
-      # @private
-      def self.merge_clones(hash, orig)
-        orig.each do |k, v|
-          hash[k] =
-            begin
-              v.clone
-            rescue ::TypeError
-              v
-            end
-        end
-        hash
-      end
-    end
-
     # The :base argument to Dir.glob requires Ruby 2.5 or later.
     if ruby_version >= 20500
       # @private
@@ -106,5 +84,24 @@ module Toys
         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
   end
 end

data/lib/toys/completion.rb

@@ -88,7 +88,7 @@ module Toys
 
       ##
       # The tool being invoked, which should control the completion.
-      # @return [Toys::Tool]
+      # @return [Toys::ToolDefinition]
       #
       def tool
         lookup_tool
@@ -236,6 +236,7 @@ module Toys
       #     prefix. Defaults to requiring the prefix be empty.
       #
       def initialize(cwd: nil, omit_files: false, omit_directories: false, prefix_constraint: "")
+        super()
         @cwd = cwd || ::Dir.pwd
         @include_files = !omit_files
         @include_directories = !omit_directories
@@ -328,6 +329,7 @@ module Toys
       #     prefix. Defaults to requiring the prefix be empty.
       #
       def initialize(values, prefix_constraint: "")
+        super()
         @values = values.flatten.map { |v| Candidate.new(v) }.sort
         @prefix_constraint = prefix_constraint
       end

data/lib/toys/context.rb

@@ -33,7 +33,7 @@ module Toys
     # This module is mixed into the runtime context. This means you can
     # reference any of these constants directly from your run method.
     #
-    # ## Example
+    # ### Example
     #
     #     tool "my-name" do
     #       def run
@@ -78,7 +78,7 @@ module Toys
       LOGGER = ::Object.new.freeze
 
       ##
-      # Context key for the {Toys::Tool} object being executed.
+      # Context key for the {Toys::ToolDefinition} object being executed.
       # @return [Object]
       #
       TOOL = ::Object.new.freeze

data/lib/toys/core.rb

@@ -9,7 +9,7 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.11.5"
+    VERSION = "0.12.0"
   end
 
   ## @private deprecated

data/lib/toys/dsl/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+##
+# Create a base class for defining a tool with a given name.
+#
+# This method returns a base class for defining a tool with a given name.
+# This is useful if the naming behavior of {Toys::Tool} is not adequate for
+# your tool.
+#
+# ### Example
+#
+#     class FooBar < Toys.Tool("Foo_Bar")
+#       desc "This is a tool called Foo_Bar"
+#
+#       def run
+#         puts "Foo_Bar called"
+#       end
+#     end
+#
+# @param name [String] Name of the tool. Defaults to a name inferred from the
+#     class name. (See {Toys::Tool}.)
+# @param base [Class] Use this tool class as the base class, and inherit helper
+#     methods from it.
+# @param args [String,Class] Any string-valued positional argument is
+#     interpreted as the name. Any class-valued positional argument is
+#     interpreted as the base class.
+#
+def Toys.Tool(*args, name: nil, base: nil) # rubocop:disable Naming/MethodName
+  args.each do |arg|
+    case arg
+    when ::Class
+      raise ::ArgumentError, "Both base keyword argument and class-valud argument received" if base
+      base = arg
+    when ::String, ::Symbol
+      raise ::ArgumentError, "Both name keyword argument and string-valud argument received" if name
+      name = arg
+    else
+      raise ::ArgumentError, "Unrecognized argument: #{arg}"
+    end
+  end
+  if base && !base.ancestors.include?(::Toys::Context)
+    raise ::ArgumentError, "Base class must itself be a tool"
+  end
+  return base || ::Toys::Tool if name.nil?
+  ::Class.new(base || ::Toys::Context) do
+    base_class = self
+    define_singleton_method(:inherited) do |tool_class|
+      ::Toys::DSL::Internal.configure_class(tool_class, base_class == self ? name.to_s : nil)
+      super(tool_class)
+      ::Toys::DSL::Internal.setup_class_dsl(tool_class)
+    end
+  end
+end
+
+module Toys
+  ##
+  # Base class for defining tools
+  #
+  # This base class provides an alternative to the {Toys::DSL::Tool#tool}
+  # directive for defining tools in the Toys DSL. Creating a subclass of
+  # `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
+  # name. Subclasses can be created only in the context of a tool configuration
+  # DSL. Furthermore, a class-defined tool can be created only at the top level
+  # of a configuration file, or within another class-defined tool. It cannot
+  # be a subtool of a tool block.
+  #
+  # ### Example
+  #
+  #     class FooBar < Toys::Tool
+  #       desc "This is a tool called foo-bar"
+  #
+  #       def run
+  #         puts "foo-bar called"
+  #       end
+  #     end
+  #
+  class Tool < Context
+    # @private
+    def self.inherited(tool_class)
+      DSL::Internal.configure_class(tool_class)
+      super
+      DSL::Internal.setup_class_dsl(tool_class)
+    end
+  end
+end