toys-core 0.14.6 → 0.15.0

data/lib/toys/dsl/tool.rb

@@ -3,7 +3,7 @@
 module Toys
   module DSL
     ##
-    # This class defines the DSL for a Toys configuration file.
+    # This module defines the DSL for a Toys configuration file.
     #
     # A Toys configuration defines one or more named tools. It provides syntax
     # for setting the description, defining flags and arguments, specifying
@@ -25,6 +25,9 @@ module Toys
     #       end
     #     end
     #
+    # The DSL directives `tool`, `desc`, `optional_arg`, and others are defined
+    # in this module.
+    #
     # Now you can execute it using:
     #
     #     toys greet
@@ -81,8 +84,8 @@ module Toys
       # ### Example
       #
       # The following example creates an acceptor named "hex" that is defined
-      # via a regular expression. It then uses it to validate values passed to
-      # a flag.
+      # via a regular expression. It uses the acceptor to validate values
+      # passed to a flag.
       #
       #     tool "example" do
       #       acceptor "hex", /[0-9a-fA-F]+/, type_desc: "hex numbers"
@@ -155,16 +158,21 @@ module Toys
       #
       # A template is an object that generates DSL directives. You can use it
       # to build "prefabricated" tools, and then instantiate them in your Toys
-      # files. Generally, a template is a class with an associated `expansion`
-      # procedure. The class defines parameters for the template expansion,
-      # and `expansion` includes DSL directives that should be run based on
-      # those parameters.
-      #
-      # Normally, you provide a block and define the template class in that
-      # block. Most templates will define an `initialize` method that takes any
-      # arguments passed into the template expansion. The template must also
-      # provide an `expansion` block showing how to use the template object to
-      # produce DSL directives.
+      # files.
+      #
+      # A template is an object that defines an `expansion` procedure. This
+      # procedure generates the DSL directives implemented by the template. The
+      # template object typically also includes attributes that are used to
+      # configure the expansion.
+      #
+      # The simplest way to define a template is to pass a block to the
+      # {#template} directive. In the block, define an `initialize` method that
+      # accepts any arguments that may be passed to the template when it is
+      # instantiated and are used to configure the template. Define
+      # `attr_reader`s or other methods to make this configuration accessible
+      # from the object. Then define an `on_expand` block that implements the
+      # template's expansion. The template object is passed as an object to the
+      # `on_expand` block.
       #
       # Alternately, you can create a template class separately and pass it
       # directly. See {Toys::Template} for details on creating a template
@@ -172,7 +180,9 @@ module Toys
       #
       # ### Example
       #
-      # The following example creates and uses a simple template.
+      # The following example creates and uses a simple template. The template
+      # defines a tool, with a configurable name, that simply prints out a
+      # configurable message.
       #
       #     template "hello-generator" do
       #       def initialize(name, message)
@@ -180,7 +190,7 @@ module Toys
       #         @message = message
       #       end
       #       attr_reader :name, :message
-      #       expansion do |template|
+      #       on_expand do |template|
       #         tool template.name do
       #           to_run do
       #             puts template.message
@@ -973,6 +983,12 @@ 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]
@@ -981,17 +997,17 @@ module Toys
                accept: nil, default: nil, handler: nil,
                complete_flags: nil, complete_values: nil,
                report_collisions: true, group: nil,
-               desc: nil, long_desc: nil, display_name: nil,
+               desc: nil, long_desc: nil, display_name: nil, add_method: nil,
                &block)
         cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
         flag_dsl = DSL::Flag.new(
           flags.flatten, accept, default, handler, complete_flags, complete_values,
-          report_collisions, group, desc, long_desc, display_name
+          report_collisions, group, desc, long_desc, display_name, add_method
         )
         flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
-        DSL::Internal.maybe_add_getter(self, key)
+        DSL::Internal.maybe_add_getter(self, key, flag_dsl._get_add_method)
         self
       end
 
@@ -1043,6 +1059,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     argument. 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 positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -1050,14 +1072,15 @@ module Toys
       #
       def required_arg(key,
                        accept: nil, complete: nil, display_name: nil,
-                       desc: nil, long_desc: nil,
+                       desc: nil, long_desc: nil, add_method: nil,
                        &block)
         cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::PositionalArg.new(accept, nil, complete, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, nil, complete, display_name,
+                                         desc, long_desc, add_method)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_required_to(cur_tool, key)
-        DSL::Internal.maybe_add_getter(self, key)
+        DSL::Internal.maybe_add_getter(self, key, arg_dsl._get_add_method)
         self
       end
       alias required required_arg
@@ -1115,6 +1138,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for this
+      #     argument. 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 positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -1122,14 +1151,15 @@ module Toys
       #
       def optional_arg(key,
                        default: nil, accept: nil, complete: nil, display_name: nil,
-                       desc: nil, long_desc: nil,
+                       desc: nil, long_desc: nil, add_method: nil,
                        &block)
         cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name,
+                                         desc, long_desc, add_method)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_optional_to(cur_tool, key)
-        DSL::Internal.maybe_add_getter(self, key)
+        DSL::Internal.maybe_add_getter(self, key, arg_dsl._get_add_method)
         self
       end
       alias optional optional_arg
@@ -1187,6 +1217,12 @@ module Toys
       #     a description of the allowed formats. (But note that this param
       #     takes an Array of description lines, rather than a series of
       #     arguments.) Defaults to the empty array.
+      # @param add_method [true,false,nil] Whether to add a method for these
+      #     arguments. 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 positional argument. See
       #     {Toys::DSL::PositionalArg} for the directives that can be called in
       #     this block.
@@ -1194,20 +1230,21 @@ module Toys
       #
       def remaining_args(key,
                          default: [], accept: nil, complete: nil, display_name: nil,
-                         desc: nil, long_desc: nil,
+                         desc: nil, long_desc: nil, add_method: nil,
                          &block)
         cur_tool = DSL::Internal.current_tool(self, true)
         return self if cur_tool.nil?
-        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name, desc, long_desc)
+        arg_dsl = DSL::PositionalArg.new(accept, default, complete, display_name,
+                                         desc, long_desc, add_method)
         arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._set_remaining_on(cur_tool, key)
-        DSL::Internal.maybe_add_getter(self, key)
+        DSL::Internal.maybe_add_getter(self, key, arg_dsl._get_add_method)
         self
       end
       alias remaining remaining_args
 
       ##
-      # Set a option values statically and create a helper method.
+      # Set option values statically and create helper methods.
       #
       # If any given key is a symbol representing a valid method name, then a
       # helper method is automatically added to retrieve the value. Otherwise,
@@ -1241,17 +1278,17 @@ module Toys
         if key.is_a?(::Hash)
           cur_tool.default_data.merge!(key)
           key.each_key do |k|
-            DSL::Internal.maybe_add_getter(self, k)
+            DSL::Internal.maybe_add_getter(self, k, true)
           end
         else
           cur_tool.default_data[key] = value
-          DSL::Internal.maybe_add_getter(self, key)
+          DSL::Internal.maybe_add_getter(self, key, true)
         end
         self
       end
 
       ##
-      # Set a option values statically without creating helper methods.
+      # Set option values statically without creating helper methods.
       #
       # ### Example
       #
@@ -1297,7 +1334,8 @@ module Toys
       # @return [self]
       #
       def enforce_flags_before_args(state = true)
-        DSL::Internal.current_tool(self, true)&.enforce_flags_before_args(state)
+        cur_tool = DSL::Internal.current_tool(self, true)
+        cur_tool&.enforce_flags_before_args(state)
         self
       end
 
@@ -1313,7 +1351,8 @@ module Toys
       # @return [self]
       #
       def require_exact_flag_match(state = true)
-        DSL::Internal.current_tool(self, true)&.require_exact_flag_match(state)
+        cur_tool = DSL::Internal.current_tool(self, true)
+        cur_tool&.require_exact_flag_match(state)
         self
       end
 
@@ -1325,10 +1364,20 @@ module Toys
       # This directive is mutually exclusive with any of the directives that
       # declare arguments or flags.
       #
+      # ### Example
+      #
+      #     tool "mytool" do
+      #       disable_argument_parsing
+      #       def run
+      #         puts "Arguments passed: #{args}"
+      #       end
+      #     end
+      #
       # @return [self]
       #
       def disable_argument_parsing
-        DSL::Internal.current_tool(self, true)&.disable_argument_parsing
+        cur_tool = DSL::Internal.current_tool(self, true)
+        cur_tool&.disable_argument_parsing
         self
       end
 
@@ -1354,7 +1403,8 @@ module Toys
       # @return [self]
       #
       def disable_flag(*flags)
-        DSL::Internal.current_tool(self, true)&.disable_flag(*flags)
+        cur_tool = DSL::Internal.current_tool(self, true)
+        cur_tool&.disable_flag(*flags)
         self
       end
 
@@ -1399,30 +1449,55 @@ module Toys
       end
 
       ##
-      # Specify how to run this tool. Typically you do this by defining a
-      # method namd `run`. Alternatively, however, you can pass a block to the
-      # `to_run` method.
+      # Specify how to run this tool.
       #
-      # You may want to do this if your method needs access to local variables
-      # in the lexical scope. However, it is often more convenient to use
-      # {#static} to set the value in the context.)
+      # Typically the entrypoint for a tool is a method named `run`. However,
+      # you can change this by passing a different method name, as a symbol, to
+      # {#to_run}.
       #
-      # ### Example
+      # You can also alternatively pass a block to {#to_run}. You might do this
+      # if your method needs access to local variables in the lexical scope.
+      # However, it is often more convenient to use {#static} to set those
+      # values in the context.
+      #
+      # ### Examples
+      #
+      #     # Set a different method name as the entrypoint:
+      #
+      #     tool "foo" do
+      #       to_run :foo
+      #       def foo
+      #         puts "The fool tool ran!"
+      #       end
+      #     end
+      #
+      #     # Use a block to retain access to the enclosing lexical scope from
+      #     # the run method:
       #
       #     tool "foo" do
-      #       cur_time = Time.new
+      #       cur_time = Time.now
       #       to_run do
       #         puts "The time at tool definition was #{cur_time}"
       #       end
       #     end
       #
-      # @param block [Proc] The run method.
+      #     # But the following is approximately equivalent:
+      #
+      #     tool "foo" do
+      #       static :cur_time, Time.now
+      #       def run
+      #         puts "The time at tool definition was #{cur_time}"
+      #       end
+      #     end
+      #
+      # @param handler [Proc,Symbol,nil] The run handler as a method name
+      #     symbol or a proc, or nil to explicitly set as non-runnable.
+      # @param block [Proc] The run handler as a block.
       # @return [self]
       #
-      def to_run(&block)
+      def to_run(handler = nil, &block)
         cur_tool = DSL::Internal.current_tool(self, true)
-        return self if cur_tool.nil?
-        cur_tool.run_handler = block
+        cur_tool&.run_handler = handler || block
         self
       end
       alias on_run to_run
@@ -1430,9 +1505,12 @@ module Toys
       ##
       # Specify how to handle interrupts.
       #
-      # You may pass a block to be called, or the name of a method to call. In
-      # either case, the block or method should take one argument, the
-      # Interrupt exception that was raised.
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the Interrupt exception that
+      # was raised.
+      #
+      # Note: this is equivalent to `on_signal("SIGINT")`.
       #
       # ### Example
       #
@@ -1440,7 +1518,7 @@ module Toys
       #       def run
       #         sleep 10
       #       end
-      #       on_interrupt do |e|
+      #       on_interrupt do
       #         puts "I was interrupted."
       #       end
       #     end
@@ -1452,23 +1530,53 @@ module Toys
       #
       def on_interrupt(handler = nil, &block)
         cur_tool = DSL::Internal.current_tool(self, true)
-        return self if cur_tool.nil?
-        cur_tool.interrupt_handler = handler || block
+        cur_tool&.interrupt_handler = handler || block
+        self
+      end
+
+      ##
+      # Specify how to handle the given signal.
+      #
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the SignalException that was
+      # raised.
+      #
+      # ### Example
+      #
+      #     tool "foo" do
+      #       def run
+      #         sleep 10
+      #       end
+      #       on_signal("QUIT") do |e|
+      #         puts "Signal caught: #{e.signm}."
+      #       end
+      #     end
+      #
+      # @param signal [Integer,String,Symbol] The signal name or number
+      # @param handler [Proc,Symbol,nil] The signal callback proc or method
+      #     name. Pass nil to disable signal handling.
+      # @param block [Proc] The signal callback as a block.
+      # @return [self]
+      #
+      def on_signal(signal, handler = nil, &block)
+        cur_tool = DSL::Internal.current_tool(self, true)
+        cur_tool&.set_signal_handler(signal, handler || block)
         self
       end
 
       ##
       # Specify how to handle usage errors.
       #
-      # You may pass a block to be called, or the name of a method to call. In
-      # either case, the block or method should take one argument, the array of
-      # usage errors reported.
+      # You can provide either a block to be called, a Proc to be called, or
+      # the name of a method to be called. In each case, the block, Proc, or
+      # method can optionally take one argument, the array of usage errors
+      # reported.
       #
       # ### Example
       #
-      # This tool runs even if a usage error is encountered. You can find info
-      # on the errors from {Toys::Context::Key::USAGE_ERRORS},
-      # {Toys::Context::Key::UNMATCHED_ARGS}, and similar keys.
+      # This tool runs even if a usage error is encountered, by setting the
+      # `run` method as the usage error handler.
       #
       #     tool "foo" do
       #       def run
@@ -1484,8 +1592,7 @@ module Toys
       #
       def on_usage_error(handler = nil, &block)
         cur_tool = DSL::Internal.current_tool(self, true)
-        return self if cur_tool.nil?
-        cur_tool.usage_error_handler = handler || block
+        cur_tool&.usage_error_handler = handler || block
         self
       end
 
@@ -1493,7 +1600,7 @@ module Toys
       # Specify that the given module should be mixed into this tool, and its
       # methods made available when running the tool.
       #
-      # You may provide either a module, the string name of a mixin that you
+      # You can provide either a module, the string name of a mixin that you
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
@@ -1528,7 +1635,7 @@ module Toys
       ##
       # Determine if the given module/mixin has already been included.
       #
-      # You may provide either a module, the string name of a mixin that you
+      # You can provide either a module, the string name of a mixin that you
       # have defined in this tool or one of its ancestors, or the symbol name
       # of a well-known mixin.
       #
@@ -1594,7 +1701,8 @@ module Toys
       # @return [nil] if there is no context.
       #
       def context_directory
-        DSL::Internal.current_tool(self, false)&.context_directory || source_info.context_directory
+        cur_tool = DSL::Internal.current_tool(self, false)
+        cur_tool&.context_directory || source_info.context_directory
       end
 
       ##
@@ -1615,8 +1723,7 @@ module Toys
       #
       def set_context_directory(dir) # rubocop:disable Naming/AccessorMethodName
         cur_tool = DSL::Internal.current_tool(self, false)
-        return self if cur_tool.nil?
-        cur_tool.custom_context_directory = dir
+        cur_tool&.custom_context_directory = dir
         self
       end
 
@@ -1655,8 +1762,7 @@ module Toys
       def subtool_apply(&block)
         cur_tool = DSL::Internal.current_tool(self, false)
         return self if cur_tool.nil?
-        cur_tool.subtool_middleware_stack.add(:apply_config,
-                                              parent_source: source_info, &block)
+        cur_tool.subtool_middleware_stack.add(:apply_config, parent_source: source_info, &block)
         self
       end
 

data/lib/toys/errors.rb

@@ -140,7 +140,7 @@ module Toys
           e = ContextualError.new(e, banner, **opts)
         end
         raise e
-      rescue ::ScriptError, ::StandardError => e
+      rescue ::ScriptError, ::StandardError, ::SignalException => e
         e = ContextualError.new(e, banner)
         add_fields_if_missing(e, opts)
         add_config_path_if_missing(e, path)
@@ -158,7 +158,7 @@ module Toys
       rescue ContextualError => e
         add_fields_if_missing(e, opts)
         raise e
-      rescue ::ScriptError, ::StandardError => e
+      rescue ::ScriptError, ::StandardError, ::SignalException => e
         raise ContextualError.new(e, banner, **opts)
       end
 

data/lib/toys/middleware.rb

@@ -21,8 +21,9 @@ module Toys
   # Generally, a middleware is a class that implements one or more of the
   # methods defined in this module: {Toys::Middleware#config}, and
   # {Toys::Middleware#run}. This module provides default implementations that
-  # do nothing, but using them is not required. Middleware objects need respond
-  # only to methods they care about.
+  # do nothing, but it is not required to include this module, or even to
+  # define both methods. Middleware objects need respond only to methods they
+  # care about.
   #
   module Middleware
     ##

data/lib/toys/settings.rb

@@ -223,7 +223,7 @@ module Toys
   #     has a parent, the parent is queried. If that parent also does not have
   #     a value for the field, it may query its parent in turn, and so forth.
   #  *  If we encounter a root settings with no parent, and still no value is
-  #     set for the field, the default is returned.
+  #     set for the field, the default for the *original* setting is returned.
   #
   # Example:
   #

data/lib/toys/standard_mixins/bundler.rb

@@ -5,6 +5,21 @@ module Toys
     ##
     # Ensures that a bundle is installed and set up when this tool is run.
     #
+    # This is the normal recommended way to use [bundler](https://bundler.io)
+    # with Toys. Including this mixin in a tool will cause Toys to ensure that
+    # the bundle is installed and available during tool execution. For example:
+    #
+    #     tool "run-rails" do
+    #       include :bundler
+    #       def run
+    #         # Note: no "bundle exec" required because Toys has already
+    #         # installed and loaded the bundle.
+    #         exec "rails s"
+    #       end
+    #     end
+    #
+    # ### Customization
+    #
     # The following parameters can be passed when including this mixin:
     #
     #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
@@ -39,7 +54,7 @@ module Toys
     #     Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
     #
     #  *  `:toys_gemfile_names` (Array\<String\>) File names that are
-    #     recognized as Gemfiles when wearching in Toys directories.
+    #     recognized as Gemfiles when searching in Toys directories.
     #     Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
     #
     #  *  `:on_missing` (Symbol) What to do if a needed gem is not installed.

data/lib/toys/standard_mixins/exec.rb

@@ -3,10 +3,10 @@
 module Toys
   module StandardMixins
     ##
-    # A set of helper methods for invoking subcommands. Provides shortcuts for
-    # common cases such as invoking Ruby in a subprocess or capturing output
-    # in a string. Also provides an interface for controlling a spawned
-    # process's streams.
+    # The `:exec` mixin provides set of helper methods for executing processes
+    # and subcommands. It provides shortcuts for common cases such as invoking
+    # a Ruby script in a subprocess or capturing output in a string. It also
+    # provides an interface for controlling a spawned process's streams.
     #
     # You can make these methods available to your tool by including the
     # following directive in your tool configuration:
@@ -16,6 +16,25 @@ module Toys
     # This is a frontend for {Toys::Utils::Exec}. More information is
     # available in that class's documentation.
     #
+    # ### Mixin overview
+    #
+    # The mixin provides a number of methods for spawning processes. The most
+    # basic are {#exec} and {#exec_proc}. The {#exec} method spawns an
+    # operating system process specified by an executable and a set of
+    # arguments. The {#exec_proc} method takes a `Proc` and forks a Ruby
+    # process. Both of these can be heavily configured with stream handling,
+    # result handling, and numerous other options described below. The mixin
+    # also provides convenience methods for common cases such as spawning a
+    # Ruby process, spawning a shell script, or capturing output.
+    #
+    # The mixin also stores default configuration that it applies to processes
+    # it spawns. You can change these defaults by calling {#configure_exec}.
+    #
+    # Underlying the mixin is a service object of type {Toys::Utils::Exec}.
+    # Normally you would use the mixin methods to access this functionality,
+    # but you can also retrieve the service object itself by calling
+    # {Toys::Context#get} with the key {Toys::StandardMixins::Exec::KEY}.
+    #
     # ### Controlling processes
     #
     # A process can be started in the *foreground* or the *background*. If you
@@ -24,7 +43,7 @@ module Toys
     # If you start a background process, its streams will be redirected to null
     # by default, and control will be returned to you immediately.
     #
-    # When a process is running, you can control it using a
+    # While a process is running, you can control it using a
     # {Toys::Utils::Exec::Controller} object. Use a controller to interact with
     # the process's input and output streams, send it signals, or wait for it
     # to complete.
@@ -44,7 +63,7 @@ module Toys
     # When running a process in the background, the controller is returned from
     # the method that starts the process:
     #
-    #     controller = exec_service.exec(["git", "init"], background: true)
+    #     controller = exec(["git", "init"], background: true)
     #
     # ### Stream handling
     #
@@ -464,7 +483,8 @@ module Toys
       #
       def exec_separate_tool(cmd, **opts, &block)
         Exec._setup_clean_process(cmd) do |clean_cmd|
-          exec(clean_cmd, **opts, &block)
+          opts = Exec._setup_exec_opts(opts, self)
+          self[KEY].exec(clean_cmd, **opts, &block)
         end
       end
 
@@ -650,7 +670,8 @@ module Toys
       #
       def capture_separate_tool(cmd, **opts, &block)
         Exec._setup_clean_process(cmd) do |clean_cmd|
-          capture(clean_cmd, **opts, &block)
+          opts = Exec._setup_exec_opts(opts, self)
+          self[KEY].capture(clean_cmd, **opts, &block)
         end
       end