toys 0.14.6 → 0.15.0

data/docs/guide.md

@@ -399,10 +399,11 @@ argument is omitted, e.g.
 
 Then the option `:whom` is set to the default value `"world"`.
 
-If the option name is a valid method name, Toys will provide a method that you
-can use to retrieve the value. In the above example, we retrieve the value for
-the option `:whom` by calling the method `whom`. If the option name cannot be
-made into a method, you can retrieve the value by calling {Toys::Context#get}.
+If the option name is symbol representing a valid method name (that doesn't
+collide with a method already present), Toys will provide a method that you can
+use to retrieve the value. In the above example, we retrieve the value for the
+option `:whom` by calling the method `whom`. If the option name cannot be made
+into a method, you can retrieve the value by calling {Toys::Context#get}.
 
 An argument can also be **required**, which means it must be provided on the
 command line; otherwise the tool will report a usage error. You can declare a
@@ -418,7 +419,7 @@ first, in order, followed by the optional arguments. For example:
       required_arg :arg1
 
       def run
-        puts "options data is #{options.inspect}"
+        puts "Options data is #{options.inspect}"
       end
     end
 
@@ -457,7 +458,7 @@ not provided on the command line. For example:
       optional_arg :arg2, default: "the-default"
 
       def run
-        puts "options data is #{options.inspect}"
+        puts "Options data is #{options.inspect}"
       end
     end
 
@@ -594,10 +595,12 @@ arguments passed to the tool. In the case above, the `:shout` option is set to
 it remains falsy. The two flags `-s` and `--shout` are effectively synonyms and
 have the same effect. A flag declaration can include any number of synonyms.
 
-As with arguments, Toys will provide a method that you can call to retrieve the
-option value set by a flag. In this case, a method called `shout` will be
-available, and will return either true or false. If the option name cannot be
-made into a method, you can retrieve the value by calling {Toys::Context#get}.
+As with arguments, Toys can provide a method that you can call to retrieve the
+option value set by a flag. This method is provided if the flag name is a
+symbol representing a valid method name that does not collide with a method
+already present. In our example, Toys provides a method called `shout` that
+returns either true or false. If the option name cannot be made into a method,
+you can retrieve the value by calling {Toys::Context#get}.
 
 #### Flag types
 
@@ -820,10 +823,11 @@ like this:
          default: 0,
          handler: proc { |_val, prev| prev - 1 }
 
-Note that both flags affect the same option name, `VERBOSITY`. The first
-increments it each time it appears, and the second decrements it. A tool can
-query this option and get an integer telling the requested verbosity level, as
-you will see [below](#Logging_and_verbosity).
+Note that both flags affect the same option name,
+{Toys::Context::Key::VERBOSITY}. The first increments it each time it appears,
+and the second decrements it. A tool can query this option and get an integer
+telling the requested verbosity level, as you will see
+[below](#Logging_and_verbosity).
 
 Toys provides a few built-in handlers that can be specified by name. We already
 discussed the default handler that can be specified by its name `:set` or by
@@ -1400,6 +1404,10 @@ chance of problems, if you need to use `truncate_load_path!`, locate it as
 early as possible in your Toys files, typically at the top of the
 [index file](#Index_files).
 
+### Loading remote files
+
+(TODO)
+
 ## The execution environment
 
 This section describes the context and resources available to your tool when it
@@ -1871,8 +1879,11 @@ Following is a simple template example:
       on_expand do |template|
         tool template.name do
           desc "A greeting tool generated from a template"
-          to_run do
-            puts "Hello, #{template.whom}!"
+
+          static :whom, template.whom
+
+          def run
+            puts "Hello, #{whom}!"
           end
         end
       end
@@ -1893,15 +1904,12 @@ passed to the block, so it can access the template configuration when
 generating directives. The "greet" template in the above example generates a
 tool whose name is set by the template's `name` property.
 
-Notice that in the above example, we used `to_run do`, providing a *block* for
-the tool's execution, rather than `def run`, providing a method. Both forms are
-valid and will work in a template (as well as in a normal Toys file), but the
-block form is often useful in a template because you can access the `template`
-variable inside the block, whereas it would not be accessible if you defined a
-method. Similarly, if your template generates helper methods, and the body of
-those methods need access to the `template` variable, you can use
-[Module#define_method](http://ruby-doc.org/core/Module.html#method-i-define_method)
-instead of `def`.
+Notice in the above example, we used the {Toys::DSL::Tool#static} directive to
+create a "static" option for `template.whom`. A "static" option is an option
+whose value is set directly in code rather than via a flag or argument. We use
+it here because we can't access the `template` local variable from within the
+`run` method. Static options are a common technique for accessing template
+configuration properties from inside tool methods.
 
 By convention, it is a good idea for configuration options for your template to
 be settable *both* as arguments to the constructor, *and* as `attr_accessor`
@@ -1927,8 +1935,9 @@ class by including the {Toys::Template} module in your class definition.
       on_expand do |template|
         tool template.name do
           desc "A greeting tool generated from a template"
-          to_run do
-            puts "Hello, #{template.whom}!"
+          static :whom, template.whom
+          def run
+            puts "Hello, #{whom}!"
           end
         end
       end
@@ -3045,9 +3054,9 @@ themselves.
 
     # This file is .toys.rb
 
-    # A "clean" tool that cleans out gem builds (from the pkg directory), and
-    # documentation builds (from doc and .yardoc)
-    expand :clean, paths: ["pkg", "doc", ".yardoc"]
+    # A "clean" tool that cleans out anything matched by the gitignore. You can
+    # also configure it to clean specific files and directories.
+    expand :clean, paths: :gitignore
 
     # This is the "test" tool.
     expand :minitest, libs: ["lib", "test"]
@@ -3397,44 +3406,49 @@ Here is an example that wraps calls to git:
       end
     end
 
-### Handling interrupts
+### Handling signals
 
-If you interrupt a running tool, say, by hitting `CTRL`-`C`, Toys will normally
-terminate execution and display the message `INTERRUPTED` on the standard error
-stream.
+If you interrupt a running tool by hitting `CTRL`-`C` or sending it a signal,
+Toys will normally terminate execution and display the message `INTERRUPTED` on
+the standard error stream.
 
-If your tool needs to handle interrupts itself, you have several options. You
-can rescue the `Interrupt` exception or call `Signal.trap`. Or you can provide
-an *interrupt handler* in your tool using the `on_interrupt` directive. This
-directive either provides a block to handle interrupts, or designates a named
-method as the handler. If an interrupt handler is present, Toys will handle
-interrupts as follows:
+If your tool needs to handle signals or inerrupts itself, you have several
+options. You can rescue the `SignalException` or call `Signal.trap`. Or you can
+provide a *signal handler* in your tool using the `on_signal` or `on_interrupt`
+directive. These directives either provide a block or designate a named method
+to handle a given signal received by the process. A separate handler must be
+provided for each signal type. (The `on_interrupt` directive is simply
+shorthand for registering a handler for `SIGINT`.)
 
-1.  Toys will terminate the tool's `run` method by raising an `Interrupt`
-    exception. Any `ensure` blocks will be called.
-2.  Toys will call the interrupt handler. If this method or block takes an
-    argument, Toys will pass it the `Interrupt` exception object.
-3.  The interrupt handler is then responsible for tool execution from that
+If a signal or interrupt is received and is not caught via `Signal.trap`, the
+following takes place:
+
+1.  Ruby will terminate the tool's `run` method by raising a `SignalException`
+    Any `ensure` blocks in the tool will be called.
+2.  Toys will call the signal handler, either a method or a block. If the
+    handler takes an argument, Toys will pass it the `SignalException` object.
+3.  The signal handler is then responsible for tool execution from that
     point. It can terminate execution by returning or calling `exit`, or it can
     restart or resume processing (perhaps by calling the `run` method again).
-    Or it can invoke the normal Toys interrupt handling (i.e. terminating
-    execution, displaying the message `INTERRUPTED`) by re-raising *the same*
-    interrupt exception object.
-4.  If another interrupt takes place during the execution of the interrupt
-    handler, Toys will terminate it by raising a *second* `Interrupt` exception
-    (calling any `ensure` blocks). Then, the interrupt handler will be called
-    *again* and passed the new exception. Any additional interrupts will be
-    handled similarly.
-
-Because the interrupt handler is called again even if it is itself interrupted,
-you might consider detecting this case if your interrupt handler might be
-long-running. You can tell how many interrupts have taken place by looking at
-the `Exception#cause` property of the exception. The first interrupt will have
-a cause of `nil`. The second interrupt (i.e. the interrupt raised the first
-time the interrupt handler is itself interrupted) will have its cause point to
-the first interrupt (which in turn has a `nil` cause.) The third interrupt's
-cause will point to the second interrupt, and so on. So you can determine the
-interrupt "depth" by counting the length of the cause chain.
+    Or it can invoke the normal Toys signal handling (i.e. terminating
+    execution and displaying the message `INTERRUPTED` or `SIGNAL RECEIVED`) by
+    re-raising *the same* `SignalException` object.
+4.  If another signal is received or interrupt takes place during the execution
+    of the handler, Toys will terminate the handler by raising a *second*
+    `SignalException` (again calling any `ensure` blocks). Then, any matching
+    signal handler will be called *again* for the new signal and passed the new
+    exception. Any further signals will be handled similarly.
+
+It is possible for a signal handler itself to receive signals. For example, if
+you have a long-running `CTRL`-`C` interrupt handler, it itself could get
+interrupted. You can tell how many signals have taken place by looking at the
+`Exception#cause` property of the `SignalException`. The first signal will have
+a cause of `nil`. The second signal (i.e. the first time a signal handler
+itself receives a signal) will have a cause pointing to the first
+`SignalException` (which in turn has a `nil` cause). The third signal's cause
+points at the second, and so forth. Hence, you can determine the signal "depth"
+by counting the length of the cause chain, which could be important to prevent
+"infinite" signals.
 
 Here is an example that performs a long-running task. The first two times the
 task is interrupted, it is restarted. The third time, it is terminated.
@@ -3496,6 +3510,81 @@ failed.
       end
     end
 
+### Changing the entrypoint
+
+The normal entrypoint for a tool is the `run` method. However, you can change
+it using the {Toys::DSL::Tool#to_run} directive, providing either a different
+method name as a symbol, or a block that will be called instead of a method to
+run the tool.
+
+One reason to change which method is called, is if you need to modify a tool
+that was already defined by some other means (like a template expansion). For
+example, the tests for the Toys gems include a number of longer-running
+"integration" tests that run only when the `TOYS_TEST_INTEGRATION` environment
+variable is set. The Toys gems provide standard `test` tools using the
+`:minitest` template, but then modify those tools to add an `--integration`
+flag. When this flag is set, the `TOYS_TEST_INTEGRATION` environment variable
+gets set, causing the integration tests to run. Here's what that looks like:
+
+    # Use the minitest template to generate the normal test tool with the
+    # normal "run" method as the entrypoint
+    expand :minitest, libs: ["lib", "test"], bundler: true
+
+    # Reopen the "test" tool generated above
+    tool "test" do
+      # Add a flag to the tool
+      flag :integration
+
+      # Create a new run method that "wraps" the existing one
+      def run_with_integration
+        # First set the environment variable to activate integration tests
+        # if requested
+        ENV["TOYS_TEST_INTEGRATION"] = "true" if integration
+
+        # Invoke the original run method that was defined in the template
+        run
+      end
+
+      # Now set the entrypoint to our new method
+      to_run :run_with_integration
+    end
+
+Passing a block to {Toys::DSL::Tool#to_run} is less common. One reason you
+might do it is if you need to access variables from an outer scope. (Normally,
+defining a method isolates your variables from any enclosing scopes.) Here is
+an example that prints out the time that the tool was *defined* (rather than
+executed).
+
+    tool "def-time" do
+      # Grab the time during tool definition
+      time = Time.now
+
+      # Define the entrypoint using a block rather than a method.
+      # The block is still called in the same object context, but now has
+      # access to variables from enclosing scopes.
+      to_run do
+        puts "Defined at #{time}"
+      end
+    end
+
+The downside of this technique is that the entrypoint is not a method, and
+can't be called like one. Which means, among other things, you can't "wrap" it
+like we did with the test tool above.
+
+If you need to access information from enclosing scopes, consider instead
+setting options using the {Toys::DSL::Tool#static} directive, as illustrated
+earlier when we discussed [defining templates](#Defining_templates).
+
+    tool "def-time" do
+      # Grab the time during tool definition and set it as a static option. 
+      static :time, Time.now
+
+      # Now you can access it from a run method like any other option
+      def run
+        puts "Defined at #{time}"
+      end
+    end
+
 ### Data files
 
 If your tools require images, archives, keys, or other such static data, Toys

data/lib/toys/standard_cli.rb

@@ -3,7 +3,19 @@
 module Toys
   ##
   # Subclass of `Toys::CLI` configured for the behavior of the standard Toys
-  # executable.
+  # executable. Specifically, this subclass:
+  #
+  # * Configures the standard names of files and directories, such as the
+  #   `.toys.rb` file for an "index" tool, and the `.data` and `.lib` directory
+  #   names.
+  # * Configures default descriptions for the root tool.
+  # * Configures a default error handler and logger that provide ANSI-colored
+  #   formatted output.
+  # * Configures a set of middleware that implement online help, verbosity
+  #   flags, and other features.
+  # * Provides a set of standard templates for typical project build and
+  #   maintenance scripts (suh as clean, test, and rubocop).
+  # * Finds tool definitions in the standard Toys search path.
   #
   class StandardCLI < CLI
     ##
@@ -103,6 +115,8 @@ module Toys
     def initialize(custom_paths: nil,
                    include_builtins: true,
                    cur_dir: nil)
+      require "toys/utils/standard_ui"
+      ui = Toys::Utils::StandardUI.new
       super(
         executable_name: EXECUTABLE_NAME,
         config_dir_name: CONFIG_DIR_NAME,
@@ -114,7 +128,8 @@ module Toys
         lib_dir_name: LIB_DIR_NAME,
         extra_delimiters: EXTRA_DELIMITERS,
         middleware_stack: default_middleware_stack,
-        template_lookup: default_template_lookup
+        template_lookup: default_template_lookup,
+        **ui.cli_args
       )
       if custom_paths
         Array(custom_paths).each { |path| add_config_path(path) }

data/lib/toys/templates/gem_build.rb

@@ -237,15 +237,21 @@ module Toys
             end
           end
 
+          static :gem_name, template.gem_name(context_directory || ::Dir.getwd)
+          static :install_gem, template.install_gem
+          static :push_gem, template.push_gem
+          static :tag, template.tag
+          static :push_tag, template.push_tag
+
           include :exec, exit_on_nonzero_status: true
           include :fileutils
           include :terminal
 
-          to_run do
+          # @private
+          def run # rubocop:disable all
             require "rubygems"
             require "rubygems/package"
             ::Dir.chdir(context_directory || ::Dir.getwd) do
-              gem_name = template.gem_name
               gemspec = ::Gem::Specification.load("#{gem_name}.gemspec")
               ::Gem::Package.build(gemspec)
               version = gemspec.version
@@ -255,21 +261,21 @@ module Toys
                 mkdir_p(::File.dirname(archive_path))
                 mv(archive_name, archive_path)
               end
-              if template.install_gem
+              if install_gem
                 exit(1) unless yes || confirm("Install #{gem_name} #{version}? ", default: true)
                 exec ["gem", "install", archive_path]
               end
-              if template.push_gem
+              if push_gem
                 if ::File.directory?(".git") && capture("git status -s").strip != ""
                   logger.error "Cannot push the gem when there are uncommited changes"
                   exit(1)
                 end
                 exit(1) unless yes || confirm("Release #{gem_name} #{version}? ", default: true)
                 exec(["gem", "push", archive_path])
-                if template.tag
+                if tag
                   exec(["git", "tag", "v#{version}"])
-                  if template.push_tag
-                    exec(["git", "push", template.push_tag, "v#{version}"])
+                  if push_tag
+                    exec(["git", "push", push_tag, "v#{version}"])
                   end
                 end
               end

data/lib/toys/templates/minitest.rb

@@ -55,6 +55,10 @@ module Toys
       #     enabled. See the documentation for the
       #     [bundler mixin](https://dazuma.github.io/toys/gems/toys-core/latest/Toys/StandardMixins/Bundler)
       #     for information on available options.
+      # @param mt_compat [boolean] If set to `true` or `false`, sets the
+      #     `MT_COMPAT` environment variable accordingly. This may be required
+      #     for certain older Minitest plugins. Optional. If not present, keeps
+      #     any current setting.
       # @param context_directory [String] A custom context directory to use
       #     when executing this tool.
       #
@@ -66,6 +70,7 @@ module Toys
                      verbose: false,
                      warnings: true,
                      bundler: false,
+                     mt_compat: nil,
                      context_directory: nil)
         @name = name
         @gem_version = gem_version
@@ -75,6 +80,7 @@ module Toys
         @verbose = verbose
         @warnings = warnings
         @bundler = bundler
+        @mt_compat = mt_compat
         @context_directory = context_directory
       end
 
@@ -160,6 +166,18 @@ module Toys
       #
       attr_writer :bundler
 
+      ##
+      # Adjust the `MT_COMPAT` environment variable when running tests. This
+      # setting may be necessary for certain older Minitest plugins.
+      #
+      # Pass `true` to enable compat mode, `false` to disable it, or `nil` to
+      # use any ambient setting from the current environment.
+      #
+      # @param value [true,false,nil]
+      # @return [true,false,nil]
+      #
+      attr_writer :mt_compat
+
       ##
       # Use bundler for this tool.
       #
@@ -195,6 +213,11 @@ module Toys
       #
       attr_reader :context_directory
 
+      ##
+      # @private
+      #
+      attr_reader :mt_compat
+
       ##
       # @private
       #
@@ -261,35 +284,42 @@ module Toys
                          complete: :file_system,
                          desc: "Paths to the tests to run (defaults to all tests)"
 
-          to_run do
-            gem "minitest", *template.gem_version
+          static :gem_version, template.gem_version
+          static :libs, template.libs
+          static :files, template.files
+          static :template_verbose, template.verbose
+          static :mt_compat, template.mt_compat
+
+          # @private
+          def run # rubocop:disable all
+            gem "minitest", *gem_version
 
             ::Dir.chdir(context_directory || ::Dir.getwd) do
               ruby_args = []
-              libs = Array(template.libs)
               ruby_args << "-I#{libs.join(::File::PATH_SEPARATOR)}" unless libs.empty?
               ruby_args << "-w" if warnings
-              ruby_args << "-"
-              ruby_args << "--seed" << seed if seed
-              vv = verbosity
-              vv += 1 if template.verbose
-              ruby_args << "--verbose" if vv.positive?
-              ruby_args << "--name" << name if name
-              ruby_args << "--exclude" << exclude if exclude
 
               if tests.empty?
-                Array(template.files).each do |pattern|
+                files.each do |pattern|
                   tests.concat(::Dir.glob(pattern))
                 end
                 tests.uniq!
               end
+              code = ["require 'minitest/autorun'"] + tests.map { |file| "load '#{file}'" }
+              ruby_args << "-e" << code.join("\n")
 
-              result = exec_ruby(ruby_args, in: :controller) do |controller|
-                controller.in.puts("require 'minitest/autorun'")
-                tests.each do |file|
-                  controller.in.puts("load '#{file}'")
-                end
-              end
+              ruby_args << "--"
+              ruby_args << "--seed" << seed if seed
+              vv = verbosity
+              vv += 1 if template_verbose
+              ruby_args << "--verbose" if vv.positive?
+              ruby_args << "--name" << name if name
+              ruby_args << "--exclude" << exclude if exclude
+
+              env = {}
+              env["MT_COMPAT"] = mt_compat ? "true" : nil unless mt_compat.nil?
+
+              result = exec_ruby(ruby_args, env: env)
               if result.error?
                 logger.error("Minitest failed!")
                 exit(result.exit_code)

data/lib/toys/templates/rake.rb

@@ -163,31 +163,41 @@ module Toys
       on_expand do |template|
         gem "rake", *template.gem_version
         require "rake"
+
         rakefile_path = Templates::Rake.find_rakefile(
           template.rakefile_path, template.context_directory || context_directory
         )
         raise "Cannot find #{template.rakefile_path}" unless rakefile_path
-        context_dir = ::File.dirname(rakefile_path)
-        rake = Templates::Rake.prepare_rake(rakefile_path, context_dir)
+        rake_context_dir = ::File.dirname(rakefile_path)
+        rake = Templates::Rake.prepare_rake(rakefile_path, rake_context_dir)
+
         rake.tasks.each do |task|
           comments = task.full_comment.to_s.split("\n")
           next if comments.empty? && template.only_described
+
           tool(task.name.split(":"), if_defined: :ignore) do
+            static :task, task
+            static :rake_context_dir, rake_context_dir
+
             bundler_settings = template.bundler_settings
             include :bundler, **bundler_settings if bundler_settings
+
             unless comments.empty?
               desc(comments.first)
               comments << "" << "Defined as a Rake task in #{rakefile_path}"
               long_desc(*comments)
             end
+
             if template.use_flags
               task.arg_names.each do |arg|
                 specs = Templates::Rake.flag_specs(arg)
                 flag(arg, *specs) unless specs.empty?
               end
-              to_run do
+
+              # @private
+              def run
                 args = task.arg_names.map { |arg| self[arg] }
-                ::Dir.chdir(context_dir) do
+                ::Dir.chdir(rake_context_dir) do
                   task.invoke(*args)
                 end
               end
@@ -195,8 +205,10 @@ module Toys
               task.arg_names.each do |arg|
                 optional_arg(arg)
               end
-              to_run do
-                ::Dir.chdir(context_dir) do
+
+              # @private
+              def run
+                ::Dir.chdir(rake_context_dir) do
                   task.invoke(*args)
                 end
               end

data/lib/toys/templates/rdoc.rb

@@ -297,36 +297,47 @@ module Toys
 
           set_context_directory template.context_directory if template.context_directory
 
+          static :gem_version, template.gem_version
+          static :template_files, template.files
+          static :rdoc_options, template.options
+          static :output_dir, template.output_dir
+          static :rdoc_markup, template.markup
+          static :rdoc_main, template.main
+          static :rdoc_title, template.title
+          static :rdoc_template, template.template
+          static :rdoc_generator, template.generator
+
           include :exec, exit_on_nonzero_status: true
           include :gems
 
           bundler_settings = template.bundler_settings
           include :bundler, **bundler_settings if bundler_settings
 
-          to_run do
-            gem_requirements = template.gem_version
-            gem "rdoc", *gem_requirements
+          # @private
+          def run # rubocop:disable all
+            gem "rdoc", *gem_version
 
             ::Dir.chdir(context_directory || ::Dir.getwd) do
               files = []
-              template.files.each do |pattern|
+              template_files.each do |pattern|
                 files.concat(::Dir.glob(pattern))
               end
               files.uniq!
 
-              args = template.options.dup
-              args << "-o" << template.output_dir
-              args << "--markup" << template.markup if template.markup
-              args << "--main" << template.main if template.main
-              args << "--title" << template.title if template.title
-              args << "-T" << template.template if template.template
-              args << "-f" << template.generator if template.generator
-
-              exec_ruby([], in: :controller) do |controller|
-                controller.in.puts("gem 'rdoc', *#{gem_requirements.inspect}")
-                controller.in.puts("require 'rdoc'")
-                controller.in.puts("::RDoc::RDoc.new.document(#{(args + files).inspect})")
-              end
+              args = rdoc_options.dup
+              args << "-o" << output_dir
+              args << "--markup" << rdoc_markup if rdoc_markup
+              args << "--main" << rdoc_main if rdoc_main
+              args << "--title" << rdoc_title if rdoc_title
+              args << "-T" << rdoc_template if rdoc_template
+              args << "-f" << rdoc_generator if rdoc_generator
+
+              code = <<~CODE
+                gem 'rdoc', *#{gem_version.inspect}
+                require 'rdoc'
+                ::RDoc::RDoc.new.document(#{(args + files).inspect})
+              CODE
+              exec_ruby(["-e", code])
             end
           end
         end