toys-core 0.3.6 → 0.3.7

data/lib/toys/middleware/show_root_version.rb

@@ -28,7 +28,7 @@
 ;
 
 require "toys/middleware/base"
-require "toys/utils/line_output"
+require "toys/utils/terminal"
 
 module Toys
   module Middleware
@@ -65,16 +65,16 @@ module Toys
         @version_string = version_string
         @version_flags = version_flags
         @version_flag_desc = version_flag_desc
-        @output = Utils::LineOutput.new(stream)
+        @terminal = Utils::Terminal.new(output: stream)
       end
 
       ##
       # Adds the version flag if requested.
       #
-      def config(tool, _loader)
-        if @version_string && tool.root?
-          tool.add_flag(:_show_version, @version_flags,
-                        report_collisions: false, desc: @version_flag_desc)
+      def config(tool_definition, _loader)
+        if @version_string && tool_definition.root?
+          tool_definition.add_flag(:_show_version, @version_flags,
+                                   report_collisions: false, desc: @version_flag_desc)
         end
         yield
       end
@@ -82,9 +82,9 @@ module Toys
       ##
       # This middleware displays the version.
       #
-      def execute(context)
-        if context[:_show_version]
-          @output.puts(@version_string)
+      def run(tool)
+        if tool[:_show_version]
+          @terminal.puts(@version_string)
         else
           yield
         end

data/lib/toys/runner.rb

@@ -0,0 +1,157 @@
+# Copyright 2018 Daniel Azuma
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the copyright holder, nor the names of any other
+#   contributors to this software, may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+;
+
+require "optparse"
+
+module Toys
+  ##
+  # An internal class that manages execution of a tool
+  # @private
+  #
+  class Runner
+    def initialize(cli, tool_definition)
+      @cli = cli
+      @tool_definition = tool_definition
+    end
+
+    def run(args, verbosity: 0)
+      data = create_data(args, verbosity)
+      parse_args(args, data)
+      tool = @tool_definition.tool_class.new(@cli, data)
+
+      original_level = @cli.logger.level
+      @cli.logger.level = @cli.base_level - data[Tool::Keys::VERBOSITY]
+      begin
+        perform_execution(tool)
+      ensure
+        @cli.logger.level = original_level
+      end
+    end
+
+    private
+
+    def create_data(args, base_verbosity)
+      data = @tool_definition.default_data.dup
+      data[Tool::Keys::TOOL_DEFINITION] = @tool_definition
+      data[Tool::Keys::TOOL_NAME] = @tool_definition.full_name
+      data[Tool::Keys::VERBOSITY] = base_verbosity
+      data[Tool::Keys::ARGS] = args
+      data[Tool::Keys::USAGE_ERROR] = nil
+      data
+    end
+
+    def parse_args(args, data)
+      optparse = create_option_parser(data)
+      remaining = optparse.parse(args)
+      remaining = parse_required_args(remaining, args, data)
+      remaining = parse_optional_args(remaining, data)
+      parse_remaining_args(remaining, args, data)
+    rescue ::OptionParser::ParseError => e
+      data[Tool::Keys::USAGE_ERROR] = e.message
+    end
+
+    def create_option_parser(data)
+      optparse = ::OptionParser.new
+      # The following clears out the Officious (hidden default flags).
+      optparse.remove
+      optparse.remove
+      optparse.new
+      optparse.new
+      @tool_definition.flag_definitions.each do |flag|
+        optparse.on(*flag.optparser_info) do |val|
+          data[flag.key] = flag.handler.call(val, data[flag.key])
+        end
+      end
+      @tool_definition.custom_acceptors do |accept|
+        optparse.accept(accept)
+      end
+      optparse
+    end
+
+    def parse_required_args(remaining, args, data)
+      @tool_definition.required_arg_definitions.each do |arg_info|
+        if remaining.empty?
+          reason = "No value given for required argument #{arg_info.display_name}"
+          raise create_parse_error(args, reason)
+        end
+        data[arg_info.key] = arg_info.process_value(remaining.shift)
+      end
+      remaining
+    end
+
+    def parse_optional_args(remaining, data)
+      @tool_definition.optional_arg_definitions.each do |arg_info|
+        break if remaining.empty?
+        data[arg_info.key] = arg_info.process_value(remaining.shift)
+      end
+      remaining
+    end
+
+    def parse_remaining_args(remaining, args, data)
+      return if remaining.empty?
+      unless @tool_definition.remaining_args_definition
+        if @tool_definition.runnable?
+          raise create_parse_error(remaining, "Extra arguments provided")
+        else
+          raise create_parse_error(@tool_definition.full_name + args, "Tool not found")
+        end
+      end
+      data[@tool_definition.remaining_args_definition.key] =
+        remaining.map { |arg| @tool_definition.remaining_args_definition.process_value(arg) }
+    end
+
+    def create_parse_error(path, reason)
+      OptionParser::ParseError.new(*path).tap do |e|
+        e.reason = reason
+      end
+    end
+
+    def perform_execution(tool)
+      executor = proc do
+        if @tool_definition.runnable?
+          tool.run
+        else
+          @cli.logger.fatal("No implementation for tool #{@tool_definition.display_name.inspect}")
+          tool.exit(-1)
+        end
+      end
+      @tool_definition.middleware_stack.reverse.each do |middleware|
+        executor = make_executor(middleware, tool, executor)
+      end
+      catch(:result) do
+        executor.call
+        0
+      end
+    end
+
+    def make_executor(middleware, tool, next_executor)
+      proc { middleware.run(tool, &next_executor) }
+    end
+  end
+end

data/lib/toys/template.rb

@@ -43,8 +43,8 @@ module Toys
   # The class defines the "configuration" of the template. If your template
   # has options/parameters, you should provide a constructor, and methods
   # appropriate to edit those options. The arguments given to the
-  # {Toys::ConfigDSL#expand} method are passed to your constructor, and your
-  # template object is passed to any block given to {Toys::ConfigDSL#expand}.
+  # {Toys::DSL::Tool#expand} method are passed to your constructor, and your
+  # template object is passed to any block given to {Toys::DSL::Tool#expand}.
   #
   # Next, in your template class, call the `to_expand` method, which is defined
   # in {Toys::Template::ClassMethods#to_expand}. Pass this a block which
@@ -77,7 +77,7 @@ module Toys
   #       to_expand do |template|
   #         desc "Prints a greeting to #{template.name}"
   #         tool "templated-greeting" do
-  #           script do
+  #           run do
   #             puts "Hello, #{template.name}!"
   #           end
   #         end
@@ -100,6 +100,7 @@ module Toys
     ## @private
     def self.included(mod)
       mod.extend(ClassMethods)
+      mod.include(Tool::Keys)
     end
 
     ##

data/lib/toys/templates.rb

@@ -48,8 +48,8 @@ module Toys
     # @param [String,Symbol] name Name of the template class to return
     # @return [Class,nil] The class, or `nil` if not found
     #
-    def self.lookup(name)
-      Utils::ModuleLookup.lookup(:templates, name)
+    def self.lookup!(name)
+      Utils::ModuleLookup.lookup!(:templates, name)
     end
   end
 end

data/lib/toys/templates/clean.rb

@@ -61,9 +61,9 @@ module Toys
         tool(template.name) do
           desc "Clean built files and directories."
 
-          use :fileutils
+          include :fileutils
 
-          script do
+          run do
             files = []
             patterns = Array(template.paths)
             patterns.each do |pattern|

data/lib/toys/templates/gem_build.rb

@@ -90,11 +90,11 @@ module Toys
 
           flag :yes, "-y", "--yes", desc: "Do not ask for interactive confirmation"
 
-          use :exec
-          use :fileutils
-          use :highline
+          include :exec
+          include :fileutils
+          include :terminal
 
-          script do
+          run do
             configure_exec(exit_on_nonzero_status: true)
             gemspec = ::Gem::Specification.load "#{template.gem_name}.gemspec"
             version = gemspec.version
@@ -107,7 +107,7 @@ module Toys
                 logger.error "Cannot push the gem when there are uncommited changes"
                 exit(1)
               end
-              exit(1) unless options[:yes] || agree("Release #{gemfile}? (y/n) ")
+              exit(1) unless option(:yes) || confirm("Release #{gemfile}?")
               sh "gem push pkg/#{gemfile}"
               if template.tag
                 sh "git tag v#{version}"

data/lib/toys/templates/minitest.rb

@@ -84,7 +84,7 @@ module Toys
         tool(template.name) do
           desc "Run minitest on the current project."
 
-          use :exec
+          include :exec
 
           flag :warnings, "-w", "--[no-]warnings",
                default: template.warnings,
@@ -92,7 +92,7 @@ module Toys
 
           remaining_args :tests, desc: "Paths to the tests to run (defaults to all tests)"
 
-          script do
+          run do
             ruby_args = []
             unless template.libs.empty?
               lib_path = template.libs.join(::File::PATH_SEPARATOR)

data/lib/toys/templates/rubocop.rb

@@ -67,9 +67,9 @@ module Toys
         tool(template.name) do
           desc "Run rubocop on the current project."
 
-          use :exec
+          include :exec
 
-          script do
+          run do
             require "rubocop"
             cli = ::RuboCop::CLI.new
             logger.info "Running RuboCop..."

data/lib/toys/templates/yardoc.rb

@@ -71,9 +71,9 @@ module Toys
         tool(template.name) do
           desc "Run yardoc on the current project."
 
-          use :exec
+          include :exec
 
-          script do
+          run do
             require "yard"
             files = []
             patterns = Array(template.files)

data/lib/toys/tool.rb

@@ -27,712 +27,255 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "optparse"
-
-require "toys/utils/wrappable_string"
+require "logger"
 
 module Toys
   ##
-  # A Tool is a single command that can be invoked using Toys.
-  # It has a name, a series of one or more words that you use to identify
-  # the tool on the command line. It also has a set of formal flags and
-  # command line arguments supported, and a block that gets run when the
-  # tool is executed.
+  # This class manages the object context in effect during the execution of a
+  # tool. The context is a hash of key-value pairs.
+  #
+  # Flags and arguments defined by your tool normally report their values in
+  # the context, using keys that are strings or symbols.
+  #
+  # Keys that are neither strings nor symbols are by convention used for other
+  # context information, including:
+  # *   Common information such as the {Toys::Definition::Tool} object being
+  #     executed, the arguments originally passed to it, or the usage error
+  #     string. These well-known keys can be accessed via constants in the
+  #     {Toys::Tool::Keys} module.
+  # *   Common settings such as the verbosity level, and whether to exit
+  #     immediately if a subprocess exits with a nonzero result. These keys are
+  #     also present as {Toys::Context} constants.
+  # *   Private information used internally by middleware and helpers.
+  #
+  # This class provides convenience accessors for common keys and settings, and
+  # you can retrieve argument-set keys using the {#options} hash.
   #
   class Tool
     ##
-    # Built-in acceptors (i.e. those recognized by OptionParser).
-    # You can reference these acceptors directly. Otherwise, you have to add
-    # one explicitly to the tool using {Tool#add_acceptor}.
-    #
-    OPTPARSER_ACCEPTORS = [
-      ::Object,
-      ::NilClass,
-      ::String,
-      ::Integer,
-      ::Float,
-      ::Numeric,
-      ::TrueClass,
-      ::FalseClass,
-      ::Array,
-      ::Regexp,
-      ::OptionParser::DecimalInteger,
-      ::OptionParser::OctalInteger,
-      ::OptionParser::DecimalNumeric
-    ].freeze
-
-    ##
-    # Create a new tool.
-    #
-    # @param [Array<String>] full_name The name of the tool
-    #
-    def initialize(full_name)
-      @full_name = full_name.dup.freeze
-      @middleware_stack = []
-
-      @definition_path = nil
-      @definition_finished = false
-
-      @desc = Toys::Utils::WrappableString.new("")
-      @long_desc = []
-
-      @default_data = {}
-      @acceptors = {}
-      OPTPARSER_ACCEPTORS.each { |a| @acceptors[a] = a }
-      @used_flags = []
-
-      @flag_definitions = []
-      @required_arg_definitions = []
-      @optional_arg_definitions = []
-      @remaining_args_definition = nil
-
-      @helpers = {}
-      @modules = []
-      @script = nil
+    # Well-known context keys.
+    #
+    module Keys
+      ##
+      # Context key for the currently running CLI.
+      # @return [Object]
+      #
+      CLI = ::Object.new.freeze
+
+      ##
+      # Context key for the verbosity value. Verbosity is an integer defaulting
+      # to 0, with higher values meaning more verbose and lower meaning quieter.
+      # @return [Object]
+      #
+      VERBOSITY = ::Object.new.freeze
+
+      ##
+      # Context key for the `Toys::Definition::Tool` object being executed.
+      # @return [Object]
+      #
+      TOOL_DEFINITION = ::Object.new.freeze
+
+      ##
+      # Context key for the full name of the tool being executed. Value is an
+      # array of strings.
+      # @return [Object]
+      #
+      TOOL_NAME = ::Object.new.freeze
+
+      ##
+      # Context key for the active `Toys::Loader` object.
+      # @return [Object]
+      #
+      LOADER = ::Object.new.freeze
+
+      ##
+      # Context key for the active `Logger` object.
+      # @return [Object]
+      #
+      LOGGER = ::Object.new.freeze
+
+      ##
+      # Context key for the name of the toys binary. Value is a string.
+      # @return [Object]
+      #
+      BINARY_NAME = ::Object.new.freeze
+
+      ##
+      # Context key for the argument list passed to the current tool. Value is
+      # an array of strings.
+      # @return [Object]
+      #
+      ARGS = ::Object.new.freeze
+
+      ##
+      # Context key for the usage error raised. Value is a string if there was
+      # an error, or nil if there was no error.
+      # @return [Object]
+      #
+      USAGE_ERROR = ::Object.new.freeze
     end
 
     ##
-    # Return the name of the tool as an array of strings.
-    # This array may not be modified.
-    # @return [Array<String>]
-    #
-    attr_reader :full_name
-
-    ##
-    # Returns the short description string.
-    # @return [Toys::Utils::WrappableString]
-    #
-    attr_reader :desc
-
-    ##
-    # Returns the long description strings as an array.
-    # @return [Array<Toys::Utils::WrappableString>]
-    #
-    attr_reader :long_desc
-
-    ##
-    # Return a list of all defined flags.
-    # @return [Array<Toys::Tool::FlagDefinition>]
-    #
-    attr_reader :flag_definitions
-
-    ##
-    # Return a list of all defined required positional arguments.
-    # @return [Array<Toys::Tool::ArgDefinition>]
-    #
-    attr_reader :required_arg_definitions
-
-    ##
-    # Return a list of all defined optional positional arguments.
-    # @return [Array<Toys::Tool::ArgDefinition>]
-    #
-    attr_reader :optional_arg_definitions
-
-    ##
-    # Return the remaining arguments specification, or `nil` if remaining
-    # arguments are currently not supported by this tool.
-    # @return [Toys::Tool::ArgDefinition,nil]
-    #
-    attr_reader :remaining_args_definition
-
-    ##
-    # Return a list of flags that have been used in the flag definitions.
-    # @return [Array<String>]
-    #
-    attr_reader :used_flags
-
-    ##
-    # Return the default argument data.
-    # @return [Hash]
-    #
-    attr_reader :default_data
-
-    ##
-    # Return a list of modules that will be available during execution.
-    # @return [Array<Module>]
-    #
-    attr_reader :modules
-
-    ##
-    # Return a list of helper methods that will be available during execution.
-    # @return [Hash{Symbol => Proc}]
-    #
-    attr_reader :helpers
-
-    ##
-    # Return the script block, or `nil` if not present.
-    # @return [Proc,nil]
-    #
-    attr_reader :script
-
-    ##
-    # Returns the middleware stack
-    # @return [Array<Object>]
-    #
-    attr_reader :middleware_stack
-
-    ##
-    # Returns the path to the file that contains the definition of this tool.
-    # @return [String]
-    #
-    attr_reader :definition_path
-
-    ##
-    # Returns the local name of this tool.
-    # @return [String]
-    #
-    def simple_name
-      full_name.last
-    end
-
-    ##
-    # Returns a displayable name of this tool, generally the full name
-    # delimited by spaces.
-    # @return [String]
-    #
-    def display_name
-      full_name.join(" ")
-    end
-
-    ##
-    # Returns true if this tool is a root tool.
-    # @return [Boolean]
+    # 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
     #
-    def root?
-      full_name.empty?
-    end
-
-    ##
-    # Returns true if this tool has an script defined.
-    # @return [Boolean]
+    # @param [Toys::CLI] cli
+    # @param [Hash] data
     #
-    def includes_script?
-      script.is_a?(::Proc)
+    def initialize(cli, data)
+      @__data = data
+      @__data[Keys::CLI] = cli
+      @__data[Keys::LOADER] = cli.loader
+      @__data[Keys::BINARY_NAME] = cli.binary_name
+      @__data[Keys::LOGGER] = cli.logger
     end
 
     ##
-    # Returns true if there is a specific description set for this tool.
-    # @return [Boolean]
+    # Return the currently running CLI.
+    # @return [Toys::CLI]
     #
-    def includes_description?
-      !long_desc.empty? || !desc.empty?
+    def cli
+      @__data[Keys::CLI]
     end
 
     ##
-    # Returns true if at least one flag or positional argument is defined
-    # for this tool.
-    # @return [Boolean]
+    # Return the current verbosity setting as an integer.
+    # @return [Integer]
     #
-    def includes_arguments?
-      !default_data.empty? || !flag_definitions.empty? ||
-        !required_arg_definitions.empty? || !optional_arg_definitions.empty? ||
-        !remaining_args_definition.nil?
+    def verbosity
+      @__data[Keys::VERBOSITY]
     end
 
     ##
-    # Returns true if at least one helper method or module is added to this
-    # tool.
-    # @return [Boolean]
+    # Return the tool being executed.
+    # @return [Toys::Definition::Tool]
     #
-    def includes_helpers?
-      !helpers.empty? || !modules.empty?
+    def tool_definition
+      @__data[Keys::TOOL_DEFINITION]
     end
 
     ##
-    # Returns true if this tool has any definition information.
-    # @return [Boolean]
+    # Return the name of the tool being executed, as an array of strings.
+    # @return [Array[String]]
     #
-    def includes_definition?
-      includes_arguments? || includes_script? || includes_helpers?
+    def tool_name
+      @__data[Keys::TOOL_NAME]
     end
 
     ##
-    # Returns true if this tool's definition has been finished and is locked.
-    # @return [Boolean]
+    # Return the raw arguments passed to the tool, as an array of strings.
+    # This does not include the tool name itself.
+    # @return [Array[String]]
     #
-    def definition_finished?
-      @definition_finished
+    def args
+      @__data[Keys::ARGS]
     end
 
     ##
-    # Returns all arg definitions in order: required, optional, remaining.
-    # @return [Array<Toys::Tool::ArgDefinition>]
+    # Return any usage error detected during argument parsing, or `nil` if
+    # no error was detected.
+    # @return [String,nil]
     #
-    def arg_definitions
-      result = required_arg_definitions + optional_arg_definitions
-      result << remaining_args_definition if remaining_args_definition
-      result
+    def usage_error
+      @__data[Keys::USAGE_ERROR]
     end
 
     ##
-    # Returns a list of all custom acceptors used by this tool.
-    # @return [Array<Toys::Tool::Acceptor>]
+    # Return the logger for this execution.
+    # @return [Logger]
     #
-    def custom_acceptors
-      result = []
-      flag_definitions.each do |f|
-        result << f.accept if f.accept.is_a?(Acceptor)
-      end
-      arg_definitions.each do |a|
-        result << a.accept if a.accept.is_a?(Acceptor)
-      end
-      result.uniq
+    def logger
+      @__data[Keys::LOGGER]
     end
 
     ##
-    # Sets the path to the file that defines this tool.
-    # A tool may be defined from at most one path. If a different path is
-    # already set, raises {Toys::ToolDefinitionError}
+    # Return the active loader that can be used to get other tools.
+    # @return [Toys::Loader]
     #
-    # @param [String] path The path to the file defining this tool
-    #
-    def lock_definition_path(path)
-      if definition_path && definition_path != path
-        raise ToolDefinitionError,
-              "Cannot redefine tool #{display_name.inspect} in #{path}" \
-              " (already defined in #{definition_path})"
-      end
-      @definition_path = path
+    def loader
+      @__data[Keys::LOADER]
     end
 
     ##
-    # Set the short description string.
-    #
-    # The description may be provided as a {Toys::Utils::WrappableString}, a
-    # single string (which will be wrapped), or an array of strings, which will
-    # be interpreted as string fragments that will be concatenated and wrapped.
-    #
-    # @param [Toys::Utils::WrappableString,String,Array<String>] desc
+    # Return the name of the binary that was executed.
+    # @return [String]
     #
-    def desc=(desc)
-      check_definition_state
-      @desc = Utils::WrappableString.make(desc)
+    def binary_name
+      @__data[Keys::BINARY_NAME]
     end
 
     ##
-    # Set the long description strings.
+    # Return an option or other piece of data by key.
     #
-    # Each string may be provided as a {Toys::Utils::WrappableString}, a single
-    # string (which will be wrapped), or an array of strings, which will be
-    # interpreted as string fragments that will be concatenated and wrapped.
+    # @param [Symbol] key
+    # @return [Object]
     #
-    # @param [Array<Toys::Utils::WrappableString,String,Array<String>>] descs
-    #
-    def long_desc=(descs)
-      check_definition_state
-      @long_desc = Utils::WrappableString.make_array(descs)
+    def [](key)
+      @__data[key]
     end
+    alias get []
 
     ##
-    # Define a helper method that will be available during execution.
-    # Pass the name of the method in the argument, and provide a block with
-    # the method body. Note the method name may not start with an underscore.
+    # Set an option or other piece of context data by key.
     #
-    # @param [String] name The method name
+    # @param [Symbol] key
+    # @param [Object] value
     #
-    def add_helper(name, &block)
-      check_definition_state
-      name_str = name.to_s
-      unless name_str =~ /^[a-z]\w+$/
-        raise ToolDefinitionError, "Illegal helper name: #{name_str.inspect}"
-      end
-      @helpers[name.to_sym] = block
-      self
+    def []=(key, value)
+      @__data[key] = value
     end
 
     ##
-    # Mix in the given module during execution. You may provide the module
-    # itself, or the name of a well-known module under {Toys::Helpers}.
+    # Set an option or other piece of context data by key.
     #
-    # @param [Module,String] name The module or module name.
+    # @param [Symbol] key
+    # @param [Object] value
     #
-    def use_module(name)
-      check_definition_state
-      case name
-      when ::Module
-        @modules << name
-      when ::Symbol
-        mod = Helpers.lookup(name.to_s)
-        if mod.nil?
-          raise ToolDefinitionError, "Module not found: #{name.inspect}"
-        end
-        @modules << mod
+    def set(key, value = nil)
+      if key.is_a?(::Hash)
+        @__data.merge!(key)
       else
-        raise ToolDefinitionError, "Illegal helper module name: #{name.inspect}"
+        @__data[key] = value
       end
       self
     end
 
     ##
-    # Add an acceptor to the tool. This acceptor may be refereneced by name
-    # when adding a flag or an arg.
-    #
-    # @param [Toys::Tool::Acceptor] acceptor The acceptor to add.
+    # Returns the subset of the context that uses string or symbol keys. By
+    # convention, this includes keys that are set by tool flags and arguments,
+    # but does not include well-known context values such as verbosity or
+    # private context values used by middleware or helpers.
     #
-    def add_acceptor(acceptor)
-      @acceptors[acceptor.name] = acceptor
-      self
-    end
-
-    ##
-    # Add a flag to the current tool. Each flag must specify a key which
-    # the script may use to obtain the flag value from the context.
-    # You may then provide the flags themselves in `OptionParser` form.
-    #
-    # @param [Symbol] key The key to use to retrieve the value from the
-    #     execution context.
-    # @param [Array<String>] flags The flags in OptionParser format.
-    # @param [Object] accept An acceptor that validates and/or converts the
-    #     value. You may provide either the name of an acceptor you have
-    #     defined, or one of the default acceptors provided by OptionParser.
-    #     Optional. If not specified, accepts any value as a string.
-    # @param [Object] default The default value. This is the value that will
-    #     be set in the context if this flag is not provided on the command
-    #     line. Defaults to `nil`.
-    # @param [Proc,nil] handler An optional handler for setting/updating the
-    #     value. If given, it should take two arguments, the new given value
-    #     and the previous value, and it should return the new value that
-    #     should be set. The default handler simply replaces the previous
-    #     value. i.e. the default is effectively `-> (val, _prev) { val }`.
-    # @param [Boolean] report_collisions Raise an exception if a flag is
-    #     requested that is already in use or marked as disabled. Default is
-    #     true.
-    # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-    #     description for the flag. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
-    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-    #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
-    #
-    def add_flag(key, flags = [],
-                 accept: nil, default: nil, handler: nil,
-                 report_collisions: true,
-                 desc: nil, long_desc: nil)
-      check_definition_state
-      accept = resolve_acceptor(accept)
-      flag_def = FlagDefinition.new(key, flags, @used_flags, report_collisions,
-                                    accept, handler, default)
-      flag_def.desc = desc if desc
-      flag_def.long_desc = long_desc if long_desc
-      @flag_definitions << flag_def if flag_def.active?
-      @default_data[key] = default
-      self
-    end
-
-    ##
-    # Mark one or more flags as disabled, preventing their use by any
-    # subsequent flag definition. This may be used to prevent middleware from
-    # defining a particular flag.
-    #
-    # @param [String...] flags The flags to disable
+    # @return [Hash]
     #
-    def disable_flag(*flags)
-      flags = flags.uniq
-      intersection = @used_flags & flags
-      unless intersection.empty?
-        raise ToolDefinitionError, "Cannot disable flags already used: #{intersection.inspect}"
+    def options
+      @__data.select do |k, _v|
+        k.is_a?(::Symbol) || k.is_a?(::String)
       end
-      @used_flags.concat(flags)
-      self
     end
 
     ##
-    # Add a required positional argument to the current tool. You must specify
-    # a key which the script may use to obtain the argument value from the
-    # context.
+    # Returns the value of the given option. Returns only options with string
+    # or symbol keys; returns `nil` if passed other well-known context keys
+    # such as verbosity.
     #
-    # @param [Symbol] key The key to use to retrieve the value from the
-    #     execution context.
-    # @param [Object] accept An acceptor that validates and/or converts the
-    #     value. You may provide either the name of an acceptor you have
-    #     defined, or one of the default acceptors provided by OptionParser.
-    #     Optional. If not specified, accepts any value as a string.
-    # @param [String] display_name A name to use for display (in help text and
-    #     error reports). Defaults to the key in upper case.
-    # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-    #     description for the flag. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
-    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-    #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
+    # @param [String,Symbol] key
+    # @return [Object]
     #
-    def add_required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
-      check_definition_state
-      accept = resolve_acceptor(accept)
-      arg_def = ArgDefinition.new(key, :required, accept, nil, desc, long_desc, display_name)
-      @required_arg_definitions << arg_def
-      self
+    def option(key)
+      key.is_a?(::Symbol) || key.is_a?(::String) ? @__data[key] : nil
     end
 
     ##
-    # Add an optional positional argument to the current tool. You must specify
-    # a key which the script may use to obtain the argument value from the
-    # context. If an optional argument is not given on the command line, the
-    # value is set to the given default.
+    # Exit immediately with the given status code
     #
-    # @param [Symbol] key The key to use to retrieve the value from the
-    #     execution context.
-    # @param [Object] default The default value. This is the value that will
-    #     be set in the context if this argument is not provided on the command
-    #     line. Defaults to `nil`.
-    # @param [Object] accept An acceptor that validates and/or converts the
-    #     value. You may provide either the name of an acceptor you have
-    #     defined, or one of the default acceptors provided by OptionParser.
-    #     Optional. If not specified, accepts any value as a string.
-    # @param [String] display_name A name to use for display (in help text and
-    #     error reports). Defaults to the key in upper case.
-    # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-    #     description for the flag. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
-    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-    #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
+    # @param [Integer] code The status code, which should be 0 for no error,
+    #     or nonzero for an error condition.
     #
-    def add_optional_arg(key, default: nil, accept: nil, display_name: nil,
-                         desc: nil, long_desc: nil)
-      check_definition_state
-      accept = resolve_acceptor(accept)
-      arg_def = ArgDefinition.new(key, :optional, accept, default, desc, long_desc, display_name)
-      @optional_arg_definitions << arg_def
-      @default_data[key] = default
-      self
-    end
-
-    ##
-    # Specify what should be done with unmatched positional arguments. You must
-    # specify a key which the script may use to obtain the remaining args
-    # from the context.
-    #
-    # @param [Symbol] key The key to use to retrieve the value from the
-    #     execution context.
-    # @param [Object] default The default value. This is the value that will
-    #     be set in the context if no unmatched arguments are provided on the
-    #     command line. Defaults to the empty array `[]`.
-    # @param [Object] accept An acceptor that validates and/or converts the
-    #     value. You may provide either the name of an acceptor you have
-    #     defined, or one of the default acceptors provided by OptionParser.
-    #     Optional. If not specified, accepts any value as a string.
-    # @param [String] display_name A name to use for display (in help text and
-    #     error reports). Defaults to the key in upper case.
-    # @param [String,Array<String>,Toys::Utils::WrappableString] desc Short
-    #     description for the flag. See {Toys::Tool#desc=} for a description of
-    #     allowed formats. Defaults to the empty string.
-    # @param [Array<String,Array<String>,Toys::Utils::WrappableString>] long_desc
-    #     Long description for the flag. See {Toys::Tool#long_desc=} for a
-    #     description of allowed formats. Defaults to the empty array.
-    #
-    def set_remaining_args(key, default: [], accept: nil, display_name: nil,
-                           desc: nil, long_desc: nil)
-      check_definition_state
-      accept = resolve_acceptor(accept)
-      arg_def = ArgDefinition.new(key, :remaining, accept, default, desc, long_desc, display_name)
-      @remaining_args_definition = arg_def
-      @default_data[key] = default
-      self
-    end
-
-    ##
-    # Set the script for this tool. This is a proc that will be called,
-    # with `self` set to a {Toys::Context}.
-    #
-    # @param [Proc] script The script for this tool.
-    #
-    def script=(script)
-      check_definition_state
-      @script = script
-    end
-
-    ##
-    # Execute this tool in the given context.
-    #
-    # @param [Toys::CLI] cli The CLI execution context
-    # @param [Array<String>] args The arguments to pass to the tool. Should
-    #     not include the tool name.
-    # @param [Integer] verbosity The starting verbosity. Defaults to 0.
-    #
-    # @return [Integer] The result code.
-    #
-    def execute(cli, args, verbosity: 0)
-      ContextualError.capture_path(
-        "Error during tool execution!", definition_path,
-        tool_name: full_name, tool_args: args
-      ) do
-        Execution.new(self).execute(cli, args, verbosity: verbosity)
-      end
-    end
-
-    ##
-    # Complete definition and run middleware configs
-    # @param [Toys::Loader] loader
-    #
-    # @private
-    #
-    def finish_definition(loader)
-      unless @definition_finished
-        ContextualError.capture("Error installing tool middleware!", tool_name: full_name) do
-          config_proc = proc {}
-          middleware_stack.reverse.each do |middleware|
-            config_proc = make_config_proc(middleware, loader, config_proc)
-          end
-          config_proc.call
-        end
-        @definition_finished = true
-      end
-      self
-    end
-
-    private
-
-    def make_config_proc(middleware, loader, next_config)
-      proc { middleware.config(self, loader, &next_config) }
-    end
-
-    def check_definition_state
-      if @definition_finished
-        raise ToolDefinitionError,
-              "Defintion of tool #{display_name.inspect} is already finished"
-      end
-    end
-
-    def resolve_acceptor(accept)
-      return accept if accept.nil? || accept.is_a?(Acceptor)
-      unless @acceptors.key?(accept)
-        raise ToolDefinitionError, "Unknown acceptor: #{accept.inspect}"
-      end
-      @acceptors[accept]
-    end
-
-    ##
-    # An internal class that manages execution of a tool
-    # @private
-    #
-    class Execution
-      def initialize(tool)
-        @tool = tool
-        @data = @tool.default_data.dup
-        @data[Context::TOOL] = tool
-        @data[Context::TOOL_NAME] = tool.full_name
-      end
-
-      def execute(cli, args, verbosity: 0)
-        parse_args(args, verbosity)
-        context = create_child_context(cli)
-
-        original_level = context.logger.level
-        context.logger.level = cli.base_level - @data[Context::VERBOSITY]
-        begin
-          perform_execution(context)
-        ensure
-          context.logger.level = original_level
-        end
-      end
-
-      private
-
-      def parse_args(args, base_verbosity)
-        optparse = create_option_parser
-        @data[Context::VERBOSITY] = base_verbosity
-        @data[Context::ARGS] = args
-        @data[Context::USAGE_ERROR] = nil
-        remaining = optparse.parse(args)
-        remaining = parse_required_args(remaining, args)
-        remaining = parse_optional_args(remaining)
-        parse_remaining_args(remaining, args)
-      rescue ::OptionParser::ParseError => e
-        @data[Context::USAGE_ERROR] = e.message
-      end
-
-      def create_option_parser
-        optparse = ::OptionParser.new
-        # The following clears out the Officious (hidden default flags).
-        optparse.remove
-        optparse.remove
-        optparse.new
-        optparse.new
-        @tool.flag_definitions.each do |flag|
-          optparse.on(*flag.optparser_info) do |val|
-            @data[flag.key] = flag.handler.call(val, @data[flag.key])
-          end
-        end
-        @tool.custom_acceptors do |accept|
-          optparse.accept(accept)
-        end
-        optparse
-      end
-
-      def parse_required_args(remaining, args)
-        @tool.required_arg_definitions.each do |arg_info|
-          if remaining.empty?
-            reason = "No value given for required argument #{arg_info.display_name}"
-            raise create_parse_error(args, reason)
-          end
-          @data[arg_info.key] = arg_info.process_value(remaining.shift)
-        end
-        remaining
-      end
-
-      def parse_optional_args(remaining)
-        @tool.optional_arg_definitions.each do |arg_info|
-          break if remaining.empty?
-          @data[arg_info.key] = arg_info.process_value(remaining.shift)
-        end
-        remaining
-      end
-
-      def parse_remaining_args(remaining, args)
-        return if remaining.empty?
-        unless @tool.remaining_args_definition
-          if @tool.includes_script?
-            raise create_parse_error(remaining, "Extra arguments provided")
-          else
-            raise create_parse_error(@tool.full_name + args, "Tool not found")
-          end
-        end
-        @data[@tool.remaining_args_definition.key] =
-          remaining.map { |arg| @tool.remaining_args_definition.process_value(arg) }
-      end
-
-      def create_parse_error(path, reason)
-        OptionParser::ParseError.new(*path).tap do |e|
-          e.reason = reason
-        end
-      end
-
-      def create_child_context(cli)
-        context = Context.new(cli, @data)
-        modules = @tool.modules
-        context.extend(*modules) unless modules.empty?
-        @tool.helpers.each do |name, block|
-          context.define_singleton_method(name, &block)
-        end
-        context
-      end
-
-      def perform_execution(context)
-        executor = proc do
-          if @tool.includes_script?
-            context.instance_eval(&@tool.script)
-          else
-            context.logger.fatal("No implementation for tool #{@tool.display_name.inspect}")
-            context.exit(-1)
-          end
-        end
-        @tool.middleware_stack.reverse.each do |middleware|
-          executor = make_executor(middleware, context, executor)
-        end
-        catch(:result) do
-          executor.call
-          0
-        end
-      end
-
-      def make_executor(middleware, context, next_executor)
-        proc { middleware.execute(context, &next_executor) }
-      end
+    def exit(code)
+      throw :result, code
     end
   end
 end
-
-require "toys/tool/acceptor"
-require "toys/tool/arg_definition"
-require "toys/tool/flag_definition"