toys-core 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5faba9107743469c7a7092eb483b103136dda81252fb7dbf4ed9d2abadc0c9cb
-  data.tar.gz: 7c5898c2f6c5de58c73cc99b38a00537164ceeb7575b944df857ddbed75a8d86
+  metadata.gz: 68a552244c25e03216c7bf958a7ccd2a35bb7fb3795a02e77c4a839b7720e258
+  data.tar.gz: 58513ce7d5d60646a1b9e51235d04df470ee5d9317a9a72048a8e95872227da0
 SHA512:
-  metadata.gz: 5d6552a6c22d948d28e90ccbd6690b8eafe82c1157f1b6fea3c8eec75b22e0b3e5d81862f93cb994ae63bbfdf234e6bcf97618da4835848c3a25ada8ca76dd80
-  data.tar.gz: f2843e6e542612b0f22b1619a02d5a9b153bf85584065dce49f520d1e190b0e81bb071378a92f296bf6fb5d1768a1489ba97c856a0757b45ea89873fb30ab504
+  metadata.gz: 299c193de07d0802046029c7b305a1e4cecac715eee32d259a917b6ecc2505975ba10a2aca90b510036076d9f32b58849a02381ae61837336eee5361cd2126ea
+  data.tar.gz: b42a4d81db4a71a136deafd4a62f0e7087325097a1c3e7473a5b7edda699b08ee1c8d81377765a70d8a18fd0a2693874781418f9953ca52f92cced670bec1421

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Release History
 
+### v0.13.0 / 2022-02-08
+
+Toys-Core 0.13.0 is a major release with significant improvements to the git cache, along with compatibility improvements and bug fixes.
+
+New functionality:
+
+* The `load_git` directive and the underlying `Toys::Utils::GitCache` class now support updating from git based on cache age.
+* The `Toys::Utils::GitCache` class supports copying git content into a provided directory, querying repo information, and deleting cache data.
+* The `Toys::Utils::GitCache` class makes files read-only, to help prevent clients from interfering with one another.
+* The `:terminal` mixin and the underlying `Toys::Utils::Terminal` class now honor the `NO_COLOR` environment variable.
+* Added `Toys::CLI#load_tool`, which is useful for testing tools.
+
+Fixes and compatibility updates:
+
+* Bundler install/updates are now spawned in subprocesses for compatibility with bundler 2.3. The bundler integration also now requires bundler 2.2 or later.
+* The `exec_tool` and `exec_proc` methods in the `:exec` mixin now log their execution in the same way as other exec functions.
+* Minor compatibility fixes to provide partial support for TruffleRuby.
+
+Other notes:
+
+* The internal GitCache representation has changed significantly to support additional features and improve robustness and performance. This will force existing caches to update, but should not break existing usage.
+
 ### v0.12.2 / 2021-08-30
 
 * FIXED: Tool context inspect string is no longer overwhelmingly long

data/LICENSE.md

@@ -1,6 +1,6 @@
 # License
 
-Copyright 2019-2020 Daniel Azuma and the Toys contributors
+Copyright 2019-2022 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/README.md

@@ -39,6 +39,9 @@ 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.
 
+Most parts of Toys-Core work on TruffleRuby. However, TruffleRuby is not
+recommended because it has a few known bugs that affect Toys.
+
 ### Create a new executable
 
 We'll start by creating an executable Ruby script. Using your favorite text
@@ -338,7 +341,7 @@ templates, and middleware, in the
 
 ## License
 
-Copyright 2019-2020 Daniel Azuma and the Toys contributors
+Copyright 2019-2022 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

@@ -31,7 +31,7 @@ sophisticated command line tools.
 
 Toys-Core is a command line *framework* in the traditional sense. It is
 intended to be used to write custom command line executables in Ruby. The
-framework provides common facilities such as argumentparsing and online help,
+framework provides common facilities such as argument parsing and online help,
 while your executable chooses and configures those facilities, and implements
 the actual behavior.
 

data/lib/toys/acceptor.rb

@@ -178,6 +178,7 @@ module Toys
 
       ##
       # Overrides {Toys::Acceptor::Base#match} to use the given function.
+      #
       # @private
       #
       def match(str)
@@ -188,6 +189,7 @@ module Toys
       ##
       # Overrides {Toys::Acceptor::Base#convert} to use the given function's
       # result.
+      #
       # @private
       #
       def convert(_str, result)
@@ -234,6 +236,7 @@ module Toys
 
       ##
       # Overrides {Toys::Acceptor::Base#match} to use the given regex.
+      #
       # @private
       #
       def match(str)
@@ -242,6 +245,7 @@ module Toys
 
       ##
       # Overrides {Toys::Acceptor::Base#convert} to use the given converter.
+      #
       # @private
       #
       def convert(str, *extra)
@@ -285,6 +289,7 @@ module Toys
 
       ##
       # Overrides {Toys::Acceptor::Base#match} to find the value.
+      #
       # @private
       #
       def match(str)
@@ -294,6 +299,7 @@ module Toys
       ##
       # Overrides {Toys::Acceptor::Base#convert} to return the actual enum
       # element.
+      #
       # @private
       #
       def convert(_str, elem)
@@ -303,6 +309,7 @@ module Toys
       ##
       # Overrides {Toys::Acceptor::Base#suggestions} to return close matches
       # from the enum.
+      #
       # @private
       #
       def suggestions(str)
@@ -513,7 +520,9 @@ module Toys
         internal_create(spec, options, block)
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def scalarize_spec(spec, options, block)
         spec ||= block
         if options.empty?

data/lib/toys/arg_parser.rb

@@ -417,6 +417,7 @@ module Toys
 
     REMAINING_HANDLER = ->(val, prev) { prev.is_a?(::Array) ? prev << val : [val] }
     ARG_HANDLER = ->(val, _prev) { val }
+    private_constant :REMAINING_HANDLER, :ARG_HANDLER
 
     def initial_data(cli, tool, default_data)
       data = {

data/lib/toys/cli.rb

@@ -175,26 +175,24 @@ module Toys
     #     Optional. If not provided, lib directories are disabled.
     #     Note: the standard toys executable sets this to `".lib"`.
     #
-    def initialize( # rubocop:disable Metrics/MethodLength
-      executable_name: nil,
-      middleware_stack: nil,
-      extra_delimiters: "",
-      config_dir_name: nil,
-      config_file_name: nil,
-      index_file_name: nil,
-      preload_file_name: nil,
-      preload_dir_name: nil,
-      data_dir_name: nil,
-      lib_dir_name: nil,
-      mixin_lookup: nil,
-      middleware_lookup: nil,
-      template_lookup: nil,
-      logger_factory: nil,
-      logger: nil,
-      base_level: nil,
-      error_handler: nil,
-      completion: nil
-    )
+    def initialize(executable_name: nil, # rubocop:disable Metrics/MethodLength
+                   middleware_stack: nil,
+                   extra_delimiters: "",
+                   config_dir_name: nil,
+                   config_file_name: nil,
+                   index_file_name: nil,
+                   preload_file_name: nil,
+                   preload_dir_name: nil,
+                   data_dir_name: nil,
+                   lib_dir_name: nil,
+                   mixin_lookup: nil,
+                   middleware_lookup: nil,
+                   template_lookup: nil,
+                   logger_factory: nil,
+                   logger: nil,
+                   base_level: nil,
+                   error_handler: nil,
+                   completion: nil)
       @executable_name = executable_name || ::File.basename($PROGRAM_NAME)
       @middleware_stack = middleware_stack || CLI.default_middleware_stack
       @mixin_lookup = mixin_lookup || CLI.default_mixin_lookup
@@ -446,6 +444,9 @@ module Toys
     #     run and what arguments to pass to it. You may pass either a single
     #     array of strings, or a series of string arguments.
     # @param verbosity [Integer] Initial verbosity. Default is 0.
+    # @param delegated_from [Toys::Context] The context from which this
+    #     execution is delegated. Optional. Should be set only if this is a
+    #     delegated execution.
     #
     # @return [Integer] The resulting process status code (i.e. 0 for success).
     #
@@ -457,101 +458,32 @@ module Toys
         "Error during tool execution!", tool.source_info&.source_path,
         tool_name: tool.full_name, tool_args: remaining
       ) do
-        default_data = {
-          Context::Key::VERBOSITY => verbosity,
-          Context::Key::DELEGATED_FROM => delegated_from,
-        }
-        run_tool(tool, remaining, default_data)
+        context = build_context(tool, remaining,
+                                verbosity: verbosity,
+                                delegated_from: delegated_from)
+        execute_tool(tool, context, &:run)
       end
     rescue ContextualError, ::Interrupt => e
       @error_handler.call(e).to_i
     end
 
-    private
-
     ##
-    # Run the given tool with the given arguments.
-    # Does not handle exceptions.
+    # Prepare a tool to be run, but just execute the given block rather than
+    # performing a full run of the tool. This is intended for testing tools.
+    # Unlike {#run}, this does not catch errors and perform error handling.
     #
-    # @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
+    # @param args [String...] Command line arguments specifying which tool to
+    #     run and what arguments to pass to it. You may pass either a single
+    #     array of strings, or a series of string arguments.
+    # @yieldparam context [Toys::Context] Yields the tool context.
     #
-    def run_tool(tool, args, default_data)
-      arg_parser = ArgParser.new(self, tool,
-                                 default_data: default_data,
-                                 require_exact_flag_match: tool.exact_flag_match_required?)
-      arg_parser.parse(args).finish
-      context = tool.tool_class.new(arg_parser.data)
-      tool.source_info&.apply_lib_paths
-      tool.run_initializers(context)
-
-      cur_logger = context[Context::Key::LOGGER]
-      if cur_logger
-        original_level = cur_logger.level
-        cur_logger.level = (base_level || original_level) - context[Context::Key::VERBOSITY].to_i
-      end
-      begin
-        execute_tool_in_context(context, tool)
-      ensure
-        cur_logger.level = original_level if cur_logger
-      end
-    end
-
-    def execute_tool_in_context(context, tool)
-      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
-            context.run
-          end
-        rescue ::Interrupt => e
-          raise e unless tool.handles_interrupts?
-          handle_interrupt(context, tool.interrupt_handler, e)
-        end
-      end
-      tool.built_middleware.reverse_each do |middleware|
-        executor = make_executor(middleware, context, executor)
-      end
-      catch(:result) do
-        executor.call
-        0
-      end
-    end
-
-    def handle_usage_errors(context, tool)
-      usage_errors = context[Context::Key::USAGE_ERRORS]
-      handler = tool.usage_error_handler
-      raise ArgParsingError, usage_errors if handler.nil?
-      handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
-      if handler.arity.zero?
-        context.instance_exec(&handler)
-      else
-        context.instance_exec(usage_errors, &handler)
-      end
-    end
-
-    def handle_interrupt(context, handler, exception)
-      handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
-      if handler.arity.zero?
-        context.instance_exec(&handler)
-      else
-        context.instance_exec(exception, &handler)
-      end
-    rescue ::Interrupt => e
-      raise e if e.equal?(exception)
-      handle_interrupt(context, handler, e)
-    end
-
-    def make_executor(middleware, context, next_executor)
-      if middleware.respond_to?(:run)
-        proc { middleware.run(context, &next_executor) }
-      else
-        next_executor
+    # @return [Object] The value returned from the block.
+    #
+    def load_tool(*args)
+      tool, remaining = @loader.lookup(args.flatten)
+      context = build_context(tool, remaining)
+      execute_tool(tool, context) do |ctx|
+        ctx.exit(yield ctx)
       end
     end
 
@@ -757,5 +689,93 @@ module Toys
         "#{styled_header}  #{msg}\n"
       end
     end
+
+    private
+
+    def build_context(tool, args, verbosity: 0, delegated_from: nil)
+      default_data = {
+        Context::Key::VERBOSITY => verbosity,
+        Context::Key::DELEGATED_FROM => delegated_from,
+      }
+      arg_parser = ArgParser.new(self, tool,
+                                 default_data: default_data,
+                                 require_exact_flag_match: tool.exact_flag_match_required?)
+      arg_parser.parse(args).finish
+      tool.tool_class.new(arg_parser.data)
+    end
+
+    def execute_tool(tool, context)
+      tool.source_info&.apply_lib_paths
+      tool.run_initializers(context)
+      cur_logger = context[Context::Key::LOGGER]
+      if cur_logger
+        original_level = cur_logger.level
+        cur_logger.level = (base_level || original_level) - context[Context::Key::VERBOSITY].to_i
+      end
+      begin
+        executor = build_executor(tool, context) do
+          yield context
+        end
+        catch(:result) do
+          executor.call
+          0
+        end
+      ensure
+        cur_logger.level = original_level if cur_logger
+      end
+    end
+
+    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
+          end
+        rescue ::Interrupt => e
+          raise e unless tool.handles_interrupts?
+          handle_interrupt(context, tool.interrupt_handler, e)
+        end
+      end
+      tool.built_middleware.reverse_each do |middleware|
+        executor = make_executor(middleware, context, executor)
+      end
+      executor
+    end
+
+    def handle_usage_errors(context, tool)
+      usage_errors = context[Context::Key::USAGE_ERRORS]
+      handler = tool.usage_error_handler
+      raise ArgParsingError, usage_errors if handler.nil?
+      handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
+      if handler.arity.zero?
+        context.instance_exec(&handler)
+      else
+        context.instance_exec(usage_errors, &handler)
+      end
+    end
+
+    def handle_interrupt(context, handler, exception)
+      handler = context.method(handler).to_proc if handler.is_a?(::Symbol)
+      if handler.arity.zero?
+        context.instance_exec(&handler)
+      else
+        context.instance_exec(exception, &handler)
+      end
+    rescue ::Interrupt => e
+      raise e if e.equal?(exception)
+      handle_interrupt(context, handler, e)
+    end
+
+    def make_executor(middleware, context, next_executor)
+      if middleware.respond_to?(:run)
+        proc { middleware.run(context, &next_executor) }
+      else
+        next_executor
+      end
+    end
   end
 end

data/lib/toys/compat.rb

@@ -5,28 +5,44 @@ require "rbconfig"
 module Toys
   ##
   # Compatibility wrappers for older Ruby versions.
+  #
   # @private
   #
   module Compat
     parts = ::RUBY_VERSION.split(".")
     ruby_version = parts[0].to_i * 10000 + parts[1].to_i * 100 + parts[2].to_i
 
+    ##
     # @private
+    #
     def self.jruby?
-      ::RUBY_PLATFORM == "java"
+      ::RUBY_ENGINE == "jruby"
+    end
+
+    ##
+    # @private
+    #
+    def self.truffleruby?
+      ::RUBY_ENGINE == "truffleruby"
     end
 
+    ##
     # @private
+    #
     def self.windows?
       ::RbConfig::CONFIG["host_os"] =~ /mswin|msys|mingw|cygwin|bccwin|wince|emc/
     end
 
+    ##
     # @private
+    #
     def self.allow_fork?
-      !jruby? && !windows?
+      !jruby? && !truffleruby? && !windows?
     end
 
+    ##
     # @private
+    #
     def self.supports_suggestions?
       unless defined?(@supports_suggestions)
         begin
@@ -44,7 +60,9 @@ module Toys
       @supports_suggestions
     end
 
+    ##
     # @private
+    #
     def self.suggestions(word, list)
       if supports_suggestions?
         ::DidYouMean::SpellChecker.new(dictionary: list).correct(word)
@@ -55,26 +73,53 @@ module Toys
 
     # 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.
-    if ruby_version >= 20700
+    # 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 }
@@ -88,17 +133,23 @@ module Toys
     # 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

data/lib/toys/completion.rb

@@ -116,7 +116,9 @@ module Toys
         @arg_parser ||= ArgParser.new(@cli, @tool).parse(@args)
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def inspect
         "<Toys::Completion::Context previous=#{previous_words.inspect}" \
           " prefix=#{fragment_prefix.inspect} fragment=#{fragment.inspect}>"
@@ -175,17 +177,23 @@ module Toys
         !@partial
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def eql?(other)
         other.is_a?(Candidate) && other.string.eql?(string) && other.partial? == @partial
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def <=>(other)
         string <=> other.string
       end
 
-      ## @private
+      ##
+      # @private
+      #
       def hash
         string.hash ^ (partial? ? 1 : 0)
       end
@@ -426,7 +434,9 @@ module Toys
       end
     end
 
-    ## @private
+    ##
+    # @private
+    #
     def self.scalarize_spec(spec, options, block)
       spec ||= block
       if options.empty?

data/lib/toys/context.rb

@@ -133,26 +133,6 @@ module Toys
       VERBOSITY = ::Object.new.freeze
     end
 
-    ##
-    # Create a Context object. Applications generally will not need to create
-    # these objects directly; they are created by the tool when it is preparing
-    # for execution.
-    #
-    # @private
-    #
-    # @param data [Hash]
-    #
-    def initialize(data)
-      @__data = data
-    end
-
-    # @private
-    def inspect
-      name = Array(@__data[Key::TOOL_NAME]).join(" ")
-      id = object_id.to_s(16)
-      "#<Toys::Context id=0x#{id} #{name}>"
-    end
-
     ##
     # The raw arguments passed to the tool, as an array of strings.
     # This does not include the tool name itself.
@@ -342,5 +322,27 @@ module Toys
     def self.exit(code = 0)
       throw :result, code
     end
+
+    ##
+    # Create a Context object. Applications generally will not need to create
+    # these objects directly; they are created by the tool when it is preparing
+    # for execution.
+    #
+    # @param data [Hash]
+    #
+    # @private
+    #
+    def initialize(data)
+      @__data = data
+    end
+
+    ##
+    # @private
+    #
+    def inspect
+      name = Array(@__data[Key::TOOL_NAME]).join(" ")
+      id = object_id.to_s(16)
+      "#<Toys::Context id=0x#{id} #{name}>"
+    end
   end
 end

data/lib/toys/core.rb

@@ -9,9 +9,13 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.12.2"
+    VERSION = "0.13.0"
   end
 
-  ## @private deprecated
+  ##
+  # Deprecated
+  #
+  # @private
+  #
   CORE_VERSION = Core::VERSION
 end

data/lib/toys/dsl/base.rb

@@ -75,7 +75,9 @@ module Toys
   #     end
   #
   class Tool < Context
+    ##
     # @private
+    #
     def self.inherited(tool_class)
       DSL::Internal.configure_class(tool_class)
       super