toys 0.14.7 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dff2ae40b96b0233329db81e892e66e4a32d3784d02a41e748ed27911a33b485
-  data.tar.gz: 1a5fb082570d1811a17de821ed996c763b354db7e2bf6d2663d7f2f73fdd5769
+  metadata.gz: 4cb07f9df7100f093730bc4029f1ae244f4417a353af98afe09e00981778ae78
+  data.tar.gz: 87d3c3ca9a0062190abf4070e223db59bfd61a2124739dcdbd61bceece277acb
 SHA512:
-  metadata.gz: 4c46b28e9de47f61c4fb10a368b235c327e43979bac1b85e399c86709d3145ce478f1ce78d5dc1e493d77c02ea5d6149b52a5f71ecf070746279b5776ec7e09c
-  data.tar.gz: ee9c59b7ccdc02db6ccdf55889a42d408714f4523c55a2f477a673551baf7d7de3c94c3ef12ef5cfa16fb5b2c75c0394f09e14e1387c0136afe6b716dccb253b
+  metadata.gz: e35f19f001aa9148439f2b9584d8e83d6b745dcd81a674f8994a4384754c6dfd4345812857f9670884696de0e6394fe0cf60fc40c5c8ab1426fa321c39e46276
+  data.tar.gz: e10c2526cb2c4c600512db26c65befc65f41257d275d89fe5b620a3b985bc36cbad489ebe5cae77ea6efbe49f93a940e22b5313b3fe6e80b8fa214d01a179539

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Release History
 
+### v0.15.0 / 2023-10-12
+
+Toys 0.15.0 is a major release that adds arbitrary signal handling, cleans up some warts around entrypoint and method definition, and fixes a few long-standing issues.
+
+Breaking changes:
+
+* If a missing delegate or a delegation loop is detected, ToolDefinitionError is raised instead of RuntimeError.
+* Passing a block to the to_run directive no longer defines the "run" method, but simply uses the block as the run entrypoint.
+* The default algorithm for determining whether flags and arguments add methods now allows overriding of methods of Toys::Context and any other included modules, but prevents collisions with private methods defined in the tool. (It continues to prevent overriding of public methods of Object and BasicObject.)
+
+New functionality:
+
+* New DSL directive on_signal lets tools provide signal handlers.
+* You can pass a symbol to the to_run directive to set the entrypoint to a method other than "run".
+* Flags and arguments can be configured explicitly to add methods or not add methods, overriding the default behavior.
+* The minitest template has a configuration argument that defines MT_COMPAT.
+
+Fixes and documentation:
+
+* The Bundler integration prevents Bundler from attempting to self-update to the version specified in a lockfile (which would often cause problems when Bundler is called from Toys).
+* Tools generated by the minitest and rspec standard templates can now interact properly with stdin (e.g. so you can invoke pry temporarily from a test.)
+* Some cleanup of varioius mixins to prevent issues if their methods ever get overridden.
+* Various improvements and clarifications in the reference documentation and user guide.
+
 ### v0.14.7 / 2023-07-19
 
 * FIXED: Fixed an exception when passing a non-string to puts in the terminal mixin

data/LICENSE.md

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

@@ -249,7 +249,7 @@ you can often rewrite an entire Rakefile as a Toys file and get quite a bit of
 benefit in readability and maintainability. For an example, see the
 [Toys file for the Toys gem itself](https://github.com/dazuma/toys/blob/main/toys/.toys/.toys.rb).
 It contains Toys scripts that I use to develop, test, and release Toys itself.
-Yes, Toys is self-hosted. You'll notice most of this Toys file consists of
+Yes, Toys is self-hosted. You'll notice much of this Toys file consists of
 template expansions. Toys provides templates for a lot of common build, test,
 and release tasks for Ruby projects.
 
@@ -276,6 +276,9 @@ separate files. Such directories are versatile, letting you organize your tool
 definitions, along with shared code, normal Ruby classes, tests, and even data
 files for use by tools.
 
+You can find detailed usage information, including the entire DSL, in the
+[class reference documentation](https://dazuma.github.io/toys/gems/toys/latest/Toys.html)
+
 Unlike most command line frameworks, Toys is *not primarily* designed to help
 you build and ship a custom command line executable written in Ruby. However,
 you *can* use it in that way with the "toys-core" API, available as a separate
@@ -323,7 +326,7 @@ because it has a few known bugs that affect Toys.
 
 ## License
 
-Copyright 2019-2022 Daniel Azuma and the Toys contributors
+Copyright 2019-2023 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/builtins/system/test.rb

@@ -23,36 +23,18 @@ flag :minitest_focus, "--minitest-focus[=VERSION]",
      desc: "Make minitest-focus available during the run"
 flag :minitest_rg, "--minitest-rg[=VERSION]",
      desc: "Make minitest-rg available during the run"
+flag :minitest_compat, "--[no-]minitest-compat",
+     desc: "Set MT_COMPAT to retain compatibility with certain old plugins"
 
 include :exec
 include :gems
 include :terminal
 
 def run
+  env = ruby_env
+  ENV["MT_COMPAT"] = env["MT_COMPAT"] if env.key?("MT_COMPAT")
   load_minitest_gems
-  test_files = find_test_files
-  result = exec_ruby(ruby_args, in: :controller, log_cmd: "Starting minitest...") do |controller|
-    controller.in.puts("gem 'minitest', '= #{::Minitest::VERSION}'")
-    controller.in.puts("require 'minitest/autorun'")
-    if minitest_focus
-      controller.in.puts("gem 'minitest-focus', '= #{::Minitest::Test::Focus::VERSION}'")
-      controller.in.puts("require 'minitest/focus'")
-    end
-    if minitest_rg
-      controller.in.puts("gem 'minitest-rg', '= #{::MiniTest::RG::VERSION}'")
-      controller.in.puts("require 'minitest/rg'")
-    end
-    controller.in.puts("require 'toys'")
-    controller.in.puts("require 'toys/testing'")
-    if directory
-      dir_str = ::File.absolute_path(directory).inspect
-      controller.in.puts("Toys::Testing.toys_custom_paths(#{dir_str})")
-      controller.in.puts("Toys::Testing.toys_include_builtins(false)")
-    end
-    test_files.each do |file|
-      controller.in.puts("load '#{file}'")
-    end
-  end
+  result = exec_ruby(ruby_args, log_cmd: "Starting minitest...", env: env)
   if result.error?
     logger.error("Minitest failed!")
     exit(result.exit_code)
@@ -74,6 +56,54 @@ def load_minitest_gems
   end
 end
 
+def ruby_env
+  case minitest_compat
+  when true
+    { "MT_COMPAT" => "true" }
+  when false
+    { "MT_COMPAT" => nil }
+  else
+    {}
+  end
+end
+
+def ruby_args
+  args = []
+  args << "-w" if warnings
+  args << "-I#{::Toys::CORE_LIB_PATH}#{::File::PATH_SEPARATOR}#{::Toys::LIB_PATH}"
+  args << "-e" << ruby_code.join("\n")
+  args << "--"
+  args << "--seed" << seed if seed
+  args << "--verbose" if verbosity.positive?
+  args << "--name" << name if name
+  args << "--exclude" << exclude if exclude
+  args
+end
+
+def ruby_code
+  code = []
+  code << "gem 'minitest', '= #{::Minitest::VERSION}'"
+  code << "require 'minitest/autorun'"
+  if minitest_focus
+    code << "gem 'minitest-focus', '= #{::Minitest::Test::Focus::VERSION}'"
+    code << "require 'minitest/focus'"
+  end
+  if minitest_rg
+    code << "gem 'minitest-rg', '= #{::MiniTest::RG::VERSION}'"
+    code << "require 'minitest/rg'"
+  end
+  code << "require 'toys'"
+  code << "require 'toys/testing'"
+  if directory
+    code << "Toys::Testing.toys_custom_paths(#{::File.absolute_path(directory).inspect})"
+    code << "Toys::Testing.toys_include_builtins(false)"
+  end
+  find_test_files.each do |file|
+    code << "load '#{file}'"
+  end
+  code
+end
+
 def find_test_files
   glob = ".test/**/test_*.rb"
   glob = "**/#{glob}" if recursive
@@ -116,15 +146,3 @@ def base_dir
     dir = parent
   end
 end
-
-def ruby_args
-  args = []
-  args << "-w" if warnings
-  args << "-I#{::Toys::CORE_LIB_PATH}#{::File::PATH_SEPARATOR}#{::Toys::LIB_PATH}"
-  args << "-"
-  args << "--seed" << seed if seed
-  args << "--verbose" if verbosity.positive?
-  args << "--name" << name if name
-  args << "--exclude" << exclude if exclude
-  args
-end

data/core-docs/toys/cli.rb

@@ -68,7 +68,7 @@ module Toys
     #      *  `preload_dir_name`: Name of preload directories in tool directories
     #      *  `data_dir_name`: Name of data directories in tool directories
     #
-    # @param logger [Logger] A global logger to use for all tools. This may be
+    # @param logger [Logger] A global logger to use for all tools. This can be
     #     set if the CLI will call at most one tool at a time. However, it will
     #     behave incorrectly if CLI might run multiple tools at the same time
     #     with different verbosity settings (since the logger cannot have
@@ -76,19 +76,21 @@ module Toys
     #     global logger, but use the `logger_factory` parameter instead.
     # @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}.
+    #     Optional. If not provided (and no global logger is set),
+    #     {Toys::CLI.default_logger_factory} is called to get a basic default.
     # @param base_level [Integer] The logger level that should correspond
     #     to zero verbosity.
     #     Optional. If not provided, defaults to the current level of the
     #     logger (which is often `Logger::WARN`).
-    # @param error_handler [Proc,nil] A proc that is called when an error is
-    #     caught. The proc should take a {Toys::ContextualError} argument and
-    #     report the error. It should return an exit code (normally nonzero).
-    #     Optional. If not provided, defaults to an instance of
-    #     {Toys::CLI::DefaultErrorHandler}, which displays an error message to
-    #     `STDERR`.
+    # @param error_handler [Proc,nil] A proc that is called when an unhandled
+    #     exception (a normal exception subclassing `StandardError`, an error
+    #     loading a toys config file subclassing `SyntaxError`, or an unhandled
+    #     signal subclassing `SignalException`) is detected. The proc should
+    #     take a {Toys::ContextualError}, whose cause is the unhandled
+    #     exception, as the sole argument, and report the error. It should
+    #     return an exit code (normally nonzero) appropriate to the error.
+    #     Optional. If not provided, {Toys::CLI.default_error_handler} is
+    #     called to get a basic default handler.
     # @param executable_name [String] The executable name displayed in help
     #     text. Optional. Defaults to the ruby program name.
     #
@@ -97,9 +99,8 @@ module Toys
     #     characters are period, colon, and slash.
     # @param completion [Toys::Completion::Base] A specifier for shell tab
     #     completion for the CLI as a whole.
-    #     Optional. If not provided, defaults to an instance of
-    #     {Toys::CLI::DefaultCompletion}, which delegates completion to the
-    #     relevant tool.
+    #     Optional. If not provided, {Toys::CLI.default_completion} is called
+    #     to get a default completion that delegates to the tool.
     #
     # @param middleware_stack [Array<Toys::Middleware::Spec>] An array of
     #     middleware that will be used by default for all tools.
@@ -382,53 +383,6 @@ module Toys
       # Source available in the toys-core gem
     end
 
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A basic error handler that prints out captured errors to a stream or
-    # a logger.
-    #
-    class DefaultErrorHandler
-      ##
-      # Create an error handler.
-      #
-      # @param output [IO,nil] Where to write errors. Default is `$stderr`.
-      #
-      def initialize(output: $stderr)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The error handler routine. Prints out the error message and backtrace,
-      # and returns the correct result code.
-      #
-      # @param error [Exception] The error that occurred.
-      # @return [Integer] The result code for the execution.
-      #
-      def call(error)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A Completion that implements the default algorithm for a CLI. This
-    # algorithm simply determines the tool and uses its completion.
-    #
-    class DefaultCompletion < Completion::Base
-      ##
-      # Returns candidates for the current completion.
-      #
-      # @param context [Toys::Completion::Context] the current completion
-      #     context including the string fragment.
-      # @return [Array<Toys::Completion::Candidate>] an array of candidates
-      #
-      def call(context)
-        # Source available in the toys-core gem
-      end
-    end
-
     class << self
       ##
       # Returns a default set of middleware that may be used as a starting
@@ -478,16 +432,35 @@ module Toys
       end
 
       ##
-      # Returns a logger factory that generates loggers that write to stderr.
-      # All loggers generated by this factory share a single
-      # {Toys::Utils::Terminal}, so log entries may interleave but will not
-      # interrupt one another.
+      # Returns a bare-bones error handler that takes simply reraises the
+      # error. If the original error (the cause of the {Toys::ContextualError})
+      # was a `SignalException` (or a subclass such as `Interrupted`), that
+      # `SignalException` itself is reraised so that the Ruby VM has a chance
+      # to handle it. Otherwise, for any other error, the
+      # {Toys::ContextualError} is reraised.
+      #
+      # @return [Proc]
+      #
+      def default_error_handler
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Returns a default logger factory that generates simple loggers that
+      # write to STDERR.
       #
       # @return [Proc]
       #
       def default_logger_factory
         # Source available in the toys-core gem
       end
+
+      ##
+      # Returns a default Completion that simply uses the tool's completion.
+      #
+      def default_completion
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/core-docs/toys/context.rb

@@ -141,22 +141,30 @@ module Toys
     #
     # This is a convenience getter for {Toys::Context::Key::ARGS}.
     #
+    # If the `args` method is overridden by the tool, you can still access it
+    # using the name `__args`.
+    #
     # @return [Array<String>]
     #
     def args
       # Source available in the toys-core gem
     end
+    alias __args args
 
     ##
     # The currently running CLI.
     #
     # This is a convenience getter for {Toys::Context::Key::CLI}.
     #
+    # If the `cli` method is overridden by the tool, you can still access it
+    # using the name `__cli`.
+    #
     # @return [Toys::CLI]
     #
     def cli
       # Source available in the toys-core gem
     end
+    alias __cli cli
 
     ##
     # Return the context directory for this tool. Generally, this defaults
@@ -166,71 +174,98 @@ module Toys
     #
     # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
     #
+    # If the `context_directory` method is overridden by the tool, you can
+    # still access it using the name `__context_directory`.
+    #
     # @return [String] Context directory path
     # @return [nil] if there is no context.
     #
     def context_directory
       # Source available in the toys-core gem
     end
+    alias __context_directory context_directory
 
     ##
     # The logger for this execution.
     #
     # This is a convenience getter for {Toys::Context::Key::LOGGER}.
     #
+    # If the `logger` method is overridden by the tool, you can still access it
+    # using the name `__logger`.
+    #
     # @return [Logger]
     #
     def logger
       # Source available in the toys-core gem
     end
+    alias __logger logger
 
     ##
     # The full name of the tool being executed, as an array of strings.
     #
     # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
     #
+    # If the `tool_name` method is overridden by the tool, you can still access
+    # it using the name `__tool_name`.
+    #
     # @return [Array<String>]
     #
     def tool_name
       # Source available in the toys-core gem
     end
+    alias __tool_name tool_name
 
     ##
     # The source of the tool being executed.
     #
     # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
     #
+    # If the `tool_source` method is overridden by the tool, you can still
+    # access it using the name `__tool_source`.
+    #
     # @return [Toys::SourceInfo]
     #
     def tool_source
       # Source available in the toys-core gem
     end
+    alias __tool_source tool_source
 
     ##
     # The (possibly empty) array of errors detected during argument parsing.
     #
     # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
     #
+    # If the `usage_errors` method is overridden by the tool, you can still
+    # access it using the name `__usage_errors`.
+    #
     # @return [Array<Toys::ArgParser::UsageError>]
     #
     def usage_errors
       # Source available in the toys-core gem
     end
+    alias __usage_errors usage_errors
 
     ##
     # The current verbosity setting as an integer.
     #
     # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
     #
+    # If the `verbosity` method is overridden by the tool, you can still access
+    # it using the name `__verbosity`.
+    #
     # @return [Integer]
     #
     def verbosity
       # Source available in the toys-core gem
     end
+    alias __verbosity verbosity
 
     ##
     # Fetch an option or other piece of data by key.
     #
+    # If the `get` method is overridden by the tool, you can still access it
+    # using the name `__get` or the `[]` operator.
+    #
     # @param key [Symbol]
     # @return [Object]
     #
@@ -253,6 +288,9 @@ module Toys
     ##
     # Set one or more options or other context data by key.
     #
+    # If the `set` method is overridden by the tool, you can still access it
+    # using the name `__set`.
+    #
     # @return [self]
     #
     # @overload set(key, value)
@@ -269,6 +307,7 @@ module Toys
     def set(key, value = nil)
       # Source available in the toys-core gem
     end
+    alias __set set
 
     ##
     # The subset of the context that uses string or symbol keys. By convention,
@@ -276,15 +315,22 @@ module Toys
     # include well-known context values such as verbosity or private context
     # values used by middleware or mixins.
     #
+    # If the `options` method is overridden by the tool, you can still access
+    # it using the name `__options`.
+    #
     # @return [Hash]
     #
     def options
       # Source available in the toys-core gem
     end
+    alias __options options
 
     ##
     # Find the given data file or directory in this tool's search path.
     #
+    # If the `find_data` method is overridden by the tool, you can still access
+    # it using the name `__find_data`.
+    #
     # @param path [String] The path to find
     # @param type [nil,:file,:directory] Type of file system object to find,
     #     or nil to return any type.
@@ -295,10 +341,14 @@ module Toys
     def find_data(path, type: nil)
       # Source available in the toys-core gem
     end
+    alias __find_data find_data
 
     ##
     # Exit immediately with the given status code.
     #
+    # If the `exit` method is overridden by the tool, you can still access it
+    # using the name `__exit` or by calling {Context.exit}.
+    #
     # @param code [Integer] The status code, which should be 0 for no error,
     #     or nonzero for an error condition. Default is 0.
     # @return [void]
@@ -306,6 +356,7 @@ module Toys
     def exit(code = 0)
       # Source available in the toys-core gem
     end
+    alias __exit exit
 
     ##
     # Exit immediately with the given status code. This class method can be

data/core-docs/toys/core.rb

@@ -9,6 +9,6 @@ module Toys
     # Current version of Toys core.
     # @return [String]
     #
-    VERSION = "0.14.7"
+    VERSION = "0.15.0"
   end
 end

data/core-docs/toys/dsl/flag.rb

@@ -117,7 +117,14 @@ module Toys
       # 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.
       #
-      # @param handler [Proc]
+      # 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
+      # "multi-valued" flags.
+      #
+      # @param handler [Proc,:set,:push]
       # @param block [Proc]
       # @return [self]
       #
@@ -256,6 +263,22 @@ module Toys
       def display_name(display_name)
         # Source available in the toys-core gem
       end
+
+      ##
+      # Specify whether to add a method for this flag.
+      #
+      # Recognized values are true to force creation of a method, false to
+      # disable method creation, and nil for the default behavior. The default
+      # checks the name and adds a method if the name is a symbol representing
+      # a legal method name that starts with a letter and does not override any
+      # public method in the Ruby Object class or collide with any method
+      # directly defined in the tool class.
+      #
+      # @param value [true,false,nil]
+      #
+      def add_method(value)
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/core-docs/toys/dsl/flag_group.rb

@@ -181,13 +181,21 @@ module Toys
       #     arguments.) Defaults to the empty array.
       # @param display_name [String] A display name for this flag, used in help
       #     text and error messages.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     flag. If omitted or set to nil, uses the default behavior, which
+      #     adds the method if the key is a symbol representing a legal method
+      #     name that starts with a letter and does not override any public
+      #     method in the Ruby Object class or collide with any method directly
+      #     defined in the tool class.
       # @param block [Proc] Configures the flag. See {Toys::DSL::Flag} for the
       #     directives that can be called in this block.
       # @return [self]
       #
       def flag(key, *flags,
-               accept: nil, default: nil, handler: nil, complete_flags: nil, complete_values: nil,
-               report_collisions: true, desc: nil, long_desc: nil, display_name: nil,
+               accept: nil, default: nil, handler: nil,
+               complete_flags: nil, complete_values: nil,
+               report_collisions: true, desc: nil, long_desc: nil,
+               display_name: nil, add_method: nil,
                &block)
         # Source available in the toys-core gem
       end

data/core-docs/toys/dsl/positional_arg.rb

@@ -134,6 +134,22 @@ module Toys
       def long_desc(*long_desc)
         # Source available in the toys-core gem
       end
+
+      ##
+      # Specify whether to add a method for this argument.
+      #
+      # Recognized values are true to force creation of a method, false to
+      # disable method creation, and nil for the default behavior. The default
+      # checks the name and adds a method if the name is a symbol representing
+      # a legal method name that starts with a letter and does not override any
+      # public method in the Ruby Object class or collide with any method
+      # directly defined in the tool class.
+      #
+      # @param value [true,false,nil]
+      #
+      def add_method(value)
+        # Source available in the toys-core gem
+      end
     end
   end
 end