toys 0.2.1 → 0.2.2

data/lib/toys/templates/gem_build.rb

@@ -1,58 +1,90 @@
+# 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 "rubygems/package"
 
-module Toys
-  module Templates
-    GemBuild = Toys::Template.new
-
-    GemBuild.to_init_opts do |opts|
-      {
-        name: "build",
-        gem_name: nil,
-        push_gem: false,
-        tag: false,
-        push_tag: false
-      }.merge(opts)
+module Toys::Templates
+  ##
+  # A template for tools that build and release gems
+  #
+  class GemBuild
+    include ::Toys::Template
+
+    def initialize(opts = {})
+      @name = opts[:name] || "build"
+      @gem_name = opts[:gem_name]
+      @push_gem = opts[:push_gem]
+      @tag = opts[:tag]
+      @push_tag = opts[:push_tag]
     end
 
-    GemBuild.to_expand do |opts|
-      toy_name = opts[:name] || "build"
-      gem_name = opts[:gem_name]
-      unless gem_name
+    attr_accessor :name
+    attr_accessor :gem_name
+    attr_accessor :push_gem
+    attr_accessor :tag
+    attr_accessor :push_tag
+
+    to_expand do |template|
+      unless template.gem_name
         candidates = ::Dir.glob("*.gemspec")
-        if candidates.size > 0
-          gem_name = candidates.first.sub(/\.gemspec$/, "")
-        else
-          raise Toys::ToysDefinitionError, "Could not find a gemspec"
+        if candidates.empty?
+          raise ::Toys::ToolDefinitionError, "Could not find a gemspec"
         end
+        template.gem_name = candidates.first.sub(/\.gemspec$/, "")
       end
-      push_gem = opts[:push_gem]
-      tag = opts[:tag]
-      push_tag = opts[:push_tag]
+      task_type = template.push_gem ? "Release" : "Build"
 
-      name toy_name do
-        short_desc "#{push_gem ? 'Release' : 'Build'} the gem: #{gem_name}"
+      name(template.name) do
+        short_desc "#{task_type} the gem: #{template.gem_name}"
 
         use :file_utils
         use :exec
 
         execute do
-          gemspec = Gem::Specification.load "#{gem_name}.gemspec"
+          configure_exec(exit_on_nonzero_status: true)
+          gemspec = ::Gem::Specification.load "#{template.gem_name}.gemspec"
           version = gemspec.version
-          gemfile = "#{gem_name}-#{version}.gem"
-          Gem::Package.build gemspec
+          gemfile = "#{template.gem_name}-#{version}.gem"
+          ::Gem::Package.build gemspec
           mkdir_p "pkg"
           mv gemfile, "pkg"
-          if push_gem
-            if File.directory?(".git") && capture("git status -s").strip != ""
+          if template.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
-            sh "gem push pkg/#{gemfile}", report_subprocess_errors: true
-            if tag
-              sh "git tag v#{version}", report_subprocess_errors: true
-              if push_tag
-                push_tag = "origin" if push_tag == true
-                sh "git push #{push_tag} v#{version}", report_subprocess_errors: true
+            sh "gem push pkg/#{gemfile}"
+            if template.tag
+              sh "git tag v#{version}"
+              if template.push_tag
+                template.push_tag = "origin" if template.push_tag == true
+                sh "git push #{template.push_tag} v#{version}"
               end
             end
           end

data/lib/toys/templates/minitest.rb

@@ -1,39 +1,85 @@
-require "shellwords"
-
-module Toys
-  module Templates
-    Minitest = Toys::Template.new
-
-    Minitest.to_init_opts do |opts|
-      {
-        name: "test",
-        libs: ["lib", "test"],
-        test_files: [],
-        warning: true
-      }.merge(opts)
+# 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.
+;
+
+module Toys::Templates
+  ##
+  # A template for tools that run minitest
+  #
+  class Minitest
+    include ::Toys::Template
+
+    def initialize(opts = {})
+      @name = opts[:name] || "test"
+      @libs = opts[:libs] || ["lib"]
+      @files = opts[:files] || ["test/test*.rb"]
+      @warnings = opts.include?(:warnings) ? opts[:warnings] : true
     end
 
-    Minitest.to_expand do |opts|
-      toy_name = opts[:name] || "build"
-      libs = opts[:libs] || []
-      warning = opts[:warning]
-      test_files = opts[:test_files] || []
-      lib_path = libs.join(File::PATH_SEPARATOR)
-      cmd = []
-      cmd << File.join(RbConfig::CONFIG["bindir"], RbConfig::CONFIG["ruby_install_name"])
-      cmd << "-I#{lib_path}" unless libs.empty?
-      cmd << "-w" if warning
-      cmd << "-e" << "ARGV.each{|f| load f}"
-      cmd << "--"
-      cmd = Shellwords.join(cmd + test_files)
-
-      name toy_name do
+    attr_accessor :name
+    attr_accessor :libs
+    attr_accessor :files
+    attr_accessor :warnings
+
+    to_expand do |template|
+      name(template.name) do
         short_desc "Run minitest"
 
         use :exec
 
+        switch(
+          :warnings, "-w", "--[no-]warnings",
+          default: template.warnings,
+          doc: "Turn on Ruby warnings (defaults to #{template.warnings})"
+        )
+        remaining_args(:tests, doc: "Paths to the tests to run (defaults to all tests)")
+
         execute do
-          sh(cmd, report_subprocess_errors: true)
+          ruby_args = []
+          unless template.libs.empty?
+            lib_path = template.libs.join(::File::PATH_SEPARATOR)
+            ruby_args << "-I#{lib_path}"
+          end
+          ruby_args << "-w" if self[:warnings]
+
+          tests = self[:tests]
+          if tests.empty?
+            Array(template.files).each do |pattern|
+              tests.concat(::Dir.glob(pattern))
+            end
+            tests.uniq!
+          end
+
+          ruby(ruby_args, in_from: :controller, exit_on_nonzero_status: true) do |controller|
+            tests.each do |file|
+              controller.in.puts("load '#{file}'")
+            end
+          end
         end
       end
     end

data/lib/toys/templates/rubocop.rb

@@ -0,0 +1,66 @@
+# 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.
+;
+
+module Toys::Templates
+  ##
+  # A template for tools that run rubocop
+  #
+  class Rubocop
+    include ::Toys::Template
+
+    def initialize(opts = {})
+      @name = opts[:name] || "rubocop"
+      @fail_on_error = opts.include?(:fail_on_error) ? opts[:fail_on_error] : true
+      @options = opts[:options] || []
+    end
+
+    attr_accessor :name
+    attr_accessor :fail_on_error
+    attr_accessor :options
+
+    to_expand do |template|
+      name(template.name) do
+        short_desc "Run RuboCop"
+
+        use :exec
+
+        execute do
+          require "rubocop"
+          cli = ::RuboCop::CLI.new
+          logger.info "Running RuboCop..."
+          result = cli.run(template.options)
+          if result.nonzero?
+            logger.error "RuboCop failed!"
+            exit(1) if template.fail_on_error
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toys/templates/yardoc.rb

@@ -0,0 +1,79 @@
+# 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.
+;
+
+module Toys::Templates
+  ##
+  # A template for tools that run yardoc
+  #
+  class Yardoc
+    include ::Toys::Template
+
+    def initialize(opts = {})
+      @name = opts[:name] || "yardoc"
+      @files = opts[:files] || []
+      @options = opts[:options] || []
+      @stats_options = opts[:stats_options] || []
+    end
+
+    attr_accessor :name
+    attr_accessor :files
+    attr_accessor :options
+    attr_accessor :stats_options
+
+    to_expand do |template|
+      name(template.name) do
+        short_desc "Run yardoc"
+
+        use :exec
+
+        execute do
+          require "yard"
+          files = []
+          patterns = Array(template.files)
+          patterns = ["lib/**/*.rb"] if patterns.empty?
+          patterns.each do |pattern|
+            files.concat(::Dir.glob(pattern))
+          end
+          files.uniq!
+
+          unless template.stats_options.empty?
+            template.options << "--no-stats"
+            template.stats_options << "--use-cache"
+          end
+
+          yardoc = ::YARD::CLI::Yardoc.new
+          yardoc.run(*(template.options + files))
+          unless template.stats_options.empty?
+            ::YARD::CLI::Stats.run(*template.stats_options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toys/tool.rb

@@ -1,14 +1,42 @@
-require "logger"
+# 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
+  ##
+  # A tool definition
+  #
   class Tool
-
-    def initialize(parent, name)
-      @parent = parent
-      @simple_name = name
-      @full_name = name ? [name] : []
-      @full_name = parent.full_name + @full_name if parent
+    def initialize(lookup, full_name)
+      @lookup = lookup
+      @full_name = full_name
 
       @definition_path = nil
       @cur_path = nil
@@ -23,22 +51,53 @@ module Toys
       @required_args = []
       @optional_args = []
       @remaining_args = nil
+
       @helpers = {}
       @modules = []
       @executor = nil
     end
 
-    attr_reader :simple_name
+    attr_reader :lookup
     attr_reader :full_name
-
-    def root?
-      @parent.nil?
+    attr_reader :switches
+    attr_reader :required_args
+    attr_reader :optional_args
+    attr_reader :remaining_args
+    attr_reader :default_data
+    attr_reader :modules
+    attr_reader :helpers
+    attr_reader :executor
+    attr_reader :alias_target
+
+    def simple_name
+      full_name.last
     end
 
     def display_name
       full_name.join(" ")
     end
 
+    def root?
+      full_name.empty?
+    end
+
+    def leaf?
+      @executor.is_a?(::Proc)
+    end
+
+    def alias?
+      !alias_target.nil?
+    end
+
+    def only_collection?
+      @executor == false
+    end
+
+    def parent
+      return nil if root?
+      @lookup.exact_tool(full_name.slice(0..-2))
+    end
+
     def effective_short_desc
       @short_desc || default_desc
     end
@@ -47,28 +106,24 @@ module Toys
       @long_desc || @short_desc || default_desc
     end
 
-    def has_description?
+    def includes_description?
       !@long_desc.nil? || !@short_desc.nil?
     end
 
-    def has_definition?
+    def includes_definition?
       !@default_data.empty? || !@switches.empty? ||
         !@required_args.empty? || !@optional_args.empty? ||
-        !@remaining_args.nil? || !!@executor ||
+        !@remaining_args.nil? || leaf? ||
         !@helpers.empty? || !@modules.empty?
     end
 
-    def only_collection?
-      @executor == false
-    end
-
     def defining_from(path)
       raise ToolDefinitionError, "Already being defined" if @cur_path
       @cur_path = path
       begin
         yield
       ensure
-        @definition_path = @cur_path if has_description? || has_definition?
+        @definition_path = @cur_path if includes_description? || includes_definition?
         @cur_path = nil
       end
     end
@@ -83,24 +138,21 @@ module Toys
       end
     end
 
-    def set_alias_target(target_tool)
-      unless target_tool.is_a?(Toys::Tool)
-        raise ArgumentError, "Illegal target type"
+    def make_alias_of(target_word)
+      if root?
+        raise ToolDefinitionError, "Cannot make the root tool an alias"
       end
       if only_collection?
         raise ToolDefinitionError, "Tool #{display_name.inspect} is already" \
           " a collection and cannot be made an alias"
       end
-      if has_description? || has_definition?
+      if includes_description? || includes_definition?
         raise ToolDefinitionError, "Tool #{display_name.inspect} already has" \
           " a definition and cannot be made an alias"
       end
-      if @executor == false
-        raise ToolDefinitionError, "Cannot make tool #{display_name.inspect}" \
-          " an alias because a descendant is already executable"
-      end
-      @parent.ensure_collection_only(full_name) if @parent
-      @alias_target = target_tool
+      parent.ensure_collection_only(full_name) unless root?
+      @alias_target = target_word
+      self
     end
 
     def short_desc=(str)
@@ -122,17 +174,20 @@ module Toys
       @helpers[name.to_sym] = block
     end
 
-    def use_helper_module(mod)
+    def use_module(mod)
       check_definition_state(true)
       case mod
-      when Module
+      when ::Module
         @modules << mod
-      when Symbol
+      when ::Symbol
         mod = mod.to_s
-        file_name = mod.gsub(/([a-zA-Z])([A-Z])/){ |m| "#{$1}_#{$2.downcase}" }.downcase
+        file_name =
+          mod
+          .gsub(/([a-zA-Z])([A-Z])/) { |_m| "#{$1}_#{$2.downcase}" }
+          .downcase
         require "toys/helpers/#{file_name}"
-        const_name = mod.gsub(/(^|_)([a-zA-Z0-9])/){ |m| $2.upcase }
-        @modules << Toys::Helpers.const_get(const_name)
+        const_name = mod.gsub(/(^|_)([a-zA-Z0-9])/) { |_m| $2.upcase }
+        @modules << Helpers.const_get(const_name)
       else
         raise ToolDefinitionError, "Illegal helper module name: #{mod.inspect}"
       end
@@ -141,28 +196,28 @@ module Toys
     def add_switch(key, *switches, accept: nil, default: nil, doc: nil)
       check_definition_state(true)
       @default_data[key] = default
-      switches << "--#{canonical_switch(key)}=VALUE" if switches.empty?
+      switches << "--#{Tool.canonical_switch(key)}=VALUE" if switches.empty?
       switches << accept unless accept.nil?
       switches += Array(doc)
-      @switches << [key, switches]
+      @switches << SwitchInfo.new(key, switches)
     end
 
     def add_required_arg(key, accept: nil, doc: nil)
       check_definition_state(true)
       @default_data[key] = nil
-      @required_args << [key, accept, Array(doc)]
+      @required_args << ArgInfo.new(key, accept, Array(doc))
     end
 
     def add_optional_arg(key, accept: nil, default: nil, doc: nil)
       check_definition_state(true)
       @default_data[key] = default
-      @optional_args << [key, accept, Array(doc)]
+      @optional_args << ArgInfo.new(key, accept, Array(doc))
     end
 
     def set_remaining_args(key, accept: nil, default: [], doc: nil)
       check_definition_state(true)
       @default_data[key] = default
-      @remaining_args = [key, accept, Array(doc)]
+      @remaining_args = ArgInfo.new(key, accept, Array(doc))
     end
 
     def executor=(executor)
@@ -170,243 +225,373 @@ module Toys
       @executor = executor
     end
 
-    def execute(context, args)
-      return @alias_target.execute(context, args) if @alias_target
-      execution_data = parse_args(args, context.binary_name)
-      context = create_child_context(context, args, execution_data)
-      if execution_data[:usage_error]
-        puts(execution_data[:usage_error])
-        puts("")
-        show_usage(context, execution_data[:optparse])
-        -1
-      elsif execution_data[:show_help]
-        show_usage(context, execution_data[:optparse],
-                   recursive: execution_data[:recursive])
-        0
-      else
-        catch(:result) do
-          context.instance_eval(&@executor)
-          0
-        end
-      end
+    def execute(context_base, args)
+      Execution.new(self).execute(context_base, args)
     end
 
     protected
 
     def ensure_collection_only(source_name)
-      if has_definition?
+      if includes_definition?
         raise ToolDefinitionError, "Cannot create tool #{source_name.inspect}" \
           " because #{display_name.inspect} is already a tool."
       end
-      if @executor != false
+      unless @executor == false
         @executor = false
-        @parent.ensure_collection_only(source_name) if @parent
+        parent.ensure_collection_only(source_name) unless root?
       end
     end
 
     private
 
-    SPECIAL_FLAGS = ["-q", "--quiet", "-v", "--verbose", "-?", "-h", "--help"]
-
     def default_desc
-      if @alias_target
-        "(Alias of #{@alias_target.display_name.inspect})"
-      elsif @executor
+      if alias?
+        "(Alias of #{@alias_target.inspect})"
+      elsif leaf?
         "(No description available)"
       else
         "(A collection of commands)"
       end
     end
 
-    def check_definition_state(execution_field=false)
-      if @alias_target
+    def check_definition_state(execution_field = false)
+      if alias?
         raise ToolDefinitionError, "Tool #{display_name.inspect} is an alias"
       end
       if @definition_path
         in_clause = @cur_path ? "in #{@cur_path} " : ""
         raise ToolDefinitionError,
-          "Cannot redefine tool #{display_name.inspect} #{in_clause}" \
-          "(already defined in #{@definition_path})"
+              "Cannot redefine tool #{display_name.inspect} #{in_clause}" \
+              "(already defined in #{@definition_path})"
       end
       if execution_field
-        if @executor == false
+        if only_collection?
           raise ToolDefinitionError,
-            "Cannot make tool #{display_name.inspect} executable because a" \
-            " descendant is already executable"
+                "Cannot make tool #{display_name.inspect} executable because" \
+                " a descendant is already executable"
         end
-        @parent.ensure_collection_only(full_name) if @parent
+        parent.ensure_collection_only(full_name) unless root?
       end
     end
 
-    def leaf_option_parser(execution_data, binary_name)
-      optparse = OptionParser.new
-      banner = ["Usage:", binary_name] + full_name
-      banner << "[<options...>]" unless @switches.empty?
-      @required_args.each do |key, opts|
-        banner << "<#{canonical_switch(key)}>"
+    class << self
+      def canonical_switch(name)
+        name.to_s.downcase.tr("_", "-").gsub(/[^a-z0-9-]/, "")
       end
-      @optional_args.each do |key, opts|
-        banner << "[<#{canonical_switch(key)}>]"
+    end
+
+    ##
+    # Representation of a formal switch
+    #
+    class SwitchInfo
+      def initialize(key, optparse_info)
+        @key = key
+        @optparse_info = optparse_info
+      end
+
+      attr_reader :key
+      attr_reader :optparse_info
+    end
+
+    ##
+    # Representation of a formal argument
+    #
+    class ArgInfo
+      def initialize(key, accept, doc)
+        @key = key
+        @accept = accept
+        @doc = doc
       end
-      if @remaining_args
-        banner << "[<#{canonical_switch(@remaining_args.first)}...>]"
+
+      attr_reader :key
+      attr_reader :accept
+      attr_reader :doc
+
+      def process_value(val)
+        return val unless accept
+        n = canonical_switch(key)
+        result = val
+        optparse = ::OptionParser.new
+        optparse.on("--#{n}=VALUE", accept) { |v| result = v }
+        optparse.parse(["--#{n}", val])
+        result
       end
-      optparse.banner = banner.join(" ")
-      desc = @long_desc || @short_desc || default_desc
-      unless desc.empty?
-        optparse.separator("")
-        optparse.separator(desc)
-      end
-      optparse.separator("")
-      optparse.separator("Options:")
-      found_special_flags = []
-      @switches.each do |key, opts|
-        found_special_flags |= (opts & SPECIAL_FLAGS)
-        optparse.on(*opts) do |val|
-          execution_data[:options][key] = val
+
+      def canonical_name
+        Tool.canonical_switch(key)
+      end
+    end
+
+    ##
+    # An internal class that manages execution of a tool
+    # @private
+    #
+    class Execution
+      def initialize(tool)
+        @tool = tool
+      end
+
+      def execute(context_base, args)
+        return execute_alias(context_base, args) if @tool.alias?
+
+        parsed_args = ParsedArgs.new(@tool, context_base.binary_name, args)
+        context = create_child_context(context_base, parsed_args, args)
+
+        if parsed_args.usage_error
+          puts(parsed_args.usage_error)
+          puts("")
+          show_usage(parsed_args.optparse)
+          -1
+        elsif parsed_args.show_help
+          show_usage(parsed_args.optparse, recursive: parsed_args.recursive)
+          0
+        else
+          catch(:result) do
+            context.instance_eval(&@tool.executor)
+            0
+          end
         end
       end
-      flags = ["-v", "--verbose"] - found_special_flags
-      unless flags.empty?
-        optparse.on(*(flags + ["Increase verbosity"])) do
-          execution_data[:delta_severity] -= 1
+
+      private
+
+      def create_child_context(context_base, parsed_args, args)
+        context = context_base.create_context(@tool.full_name, args, parsed_args.data)
+        context.logger.level += parsed_args.delta_severity
+        @tool.modules.each do |mod|
+          context.extend(mod)
         end
+        @tool.helpers.each do |name, block|
+          context.define_singleton_method(name, &block)
+        end
+        context
       end
-      flags = ["-q", "--quiet"] - found_special_flags
-      unless flags.empty?
-        optparse.on(*(flags + ["Decrease verbosity"])) do
-          execution_data[:delta_severity] += 1
+
+      def show_usage(optparse, recursive: false)
+        puts(optparse.to_s)
+        if @tool.leaf?
+          required_args = @tool.required_args
+          optional_args = @tool.optional_args
+          remaining_args = @tool.remaining_args
+          if !required_args.empty? || !optional_args.empty? || remaining_args
+            show_positional_arguments(required_args, optional_args, remaining_args)
+          end
+        else
+          show_command_list(recursive)
         end
       end
-      flags = ["-?", "-h", "--help"] - found_special_flags
-      unless flags.empty?
-        optparse.on(*(flags + ["Show help message"])) do
-          execution_data[:show_help] = true
+
+      def show_positional_arguments(required_args, optional_args, remaining_args)
+        puts("")
+        puts("Positional arguments:")
+        args_to_display = required_args + optional_args
+        args_to_display << remaining_args if remaining_args
+        args_to_display.each do |arg_info|
+          puts("    #{arg_info.canonical_name.ljust(31)}  #{arg_info.doc.first}")
+          next if arg_info.doc.empty?
+          arg_info.doc[1..-1].each do |d|
+            puts("                                     #{d}")
+          end
+        end
+      end
+
+      def show_command_list(recursive)
+        puts("")
+        puts("Commands:")
+        name_len = @tool.full_name.length
+        @tool.lookup.list_subtools(@tool.full_name, recursive).each do |subtool|
+          desc = subtool.effective_short_desc
+          tool_name = subtool.full_name.slice(name_len..-1).join(" ").ljust(31)
+          puts("    #{tool_name}  #{desc}")
+        end
+      end
+
+      def execute_alias(context_base, args)
+        target_name = @tool.full_name.slice(0..-2) + [@tool.alias_target]
+        target_tool = @tool.lookup.lookup(target_name)
+        if target_tool.full_name == target_name
+          target_tool.execute(context_base, args)
+        else
+          logger.fatal("Alias target #{@tool.alias_target.inspect} not found")
+          -1
         end
       end
-      optparse
     end
 
-    def collection_option_parser(execution_data, binary_name)
-      optparse = OptionParser.new
-      optparse.banner = (["Usage:", binary_name] + full_name + ["<command>", "[<options...>]"]).join(" ")
-      desc = @long_desc || @short_desc || default_desc
-      unless desc.empty?
-        optparse.separator("")
-        optparse.separator(desc)
-      end
-      optparse.separator("")
-      optparse.separator("Options:")
-      optparse.on("-?", "--help", "Show help message")
-      optparse.on("-r", "--[no-]recursive", "Show all subcommands recursively") do |val|
-        execution_data[:recursive] = val
-      end
-      execution_data[:show_help] = true
-      optparse
-    end
-
-    def parse_args(args, binary_name)
-      optdata = @default_data.dup
-      execution_data = {
-        show_help: false,
-        usage_error: nil,
-        delta_severity: 0,
-        recursive: false,
-        options: optdata
-      }
-      begin
-        binary_name ||= File.basename($0)
-        option_parser = @executor ?
-          leaf_option_parser(execution_data, binary_name) :
-          collection_option_parser(execution_data, binary_name)
-        execution_data[:optparse] = option_parser
-        remaining = option_parser.parse(args)
-        @required_args.each do |key, accept, doc|
-          if !execution_data[:show_help] && remaining.empty?
-            error = OptionParser::ParseError.new(*args)
-            error.reason = "No value given for required argument named <#{canonical_switch(key)}>"
-            raise error
+    ##
+    # An internal class that manages parsing of tool arguments
+    # @private
+    #
+    class ParsedArgs
+      def initialize(tool, binary_name, args)
+        binary_name ||= ::File.basename($PROGRAM_NAME)
+        @show_help = !tool.leaf?
+        @usage_error = nil
+        @delta_severity = 0
+        @recursive = false
+        @data = tool.default_data.dup
+        @optparse = create_option_parser(tool, binary_name)
+        parse_args(args, tool)
+      end
+
+      attr_reader :show_help
+      attr_reader :usage_error
+      attr_reader :delta_severity
+      attr_reader :recursive
+      attr_reader :data
+      attr_reader :optparse
+
+      private
+
+      ##
+      # Well-known flags
+      # @private
+      #
+      SPECIAL_FLAGS = %w[
+        -q
+        --quiet
+        -v
+        --verbose
+        -?
+        -h
+        --help
+      ].freeze
+
+      def parse_args(args, tool)
+        remaining = @optparse.parse(args)
+        remaining = parse_required_args(remaining, tool, args)
+        remaining = parse_optional_args(remaining, tool)
+        parse_remaining_args(remaining, tool, args)
+      rescue ::OptionParser::ParseError => e
+        @usage_error = e
+      end
+
+      def create_option_parser(tool, binary_name)
+        optparse = ::OptionParser.new
+        optparse.banner =
+          if tool.leaf?
+            leaf_banner(tool, binary_name)
+          else
+            collection_banner(tool, binary_name)
           end
-          optdata[key] = process_value(key, remaining.shift, accept)
+        unless tool.effective_long_desc.empty?
+          optparse.separator("")
+          optparse.separator(tool.effective_long_desc)
         end
-        @optional_args.each do |key, accept, doc|
-          break if remaining.empty?
-          optdata[key] = process_value(key, remaining.shift, accept)
+        optparse.separator("")
+        optparse.separator("Options:")
+        if tool.leaf?
+          leaf_switches(tool, optparse)
+        else
+          collection_switches(optparse)
+        end
+        optparse
+      end
+
+      def leaf_banner(tool, binary_name)
+        banner = ["Usage:", binary_name] + tool.full_name
+        banner << "[<options...>]" unless tool.switches.empty?
+        tool.required_args.each do |arg_info|
+          banner << "<#{arg_info.canonical_name}>"
+        end
+        tool.optional_args.each do |arg_info|
+          banner << "[<#{arg_info.canonical_name}>]"
+        end
+        if tool.remaining_args
+          banner << "[<#{tool.remaining_args.canonical_name}...>]"
+        end
+        banner.join(" ")
+      end
+
+      def collection_banner(tool, binary_name)
+        (["Usage:", binary_name] + tool.full_name + ["<command>", "[<options...>]"]).join(" ")
+      end
+
+      def leaf_switches(tool, optparse)
+        found_special_flags = []
+        leaf_normal_switches(tool.switches, optparse, found_special_flags)
+        leaf_verbose_switch(optparse, found_special_flags)
+        leaf_quiet_switch(optparse, found_special_flags)
+        leaf_help_switch(optparse, found_special_flags)
+      end
+
+      def collection_switches(optparse)
+        optparse.on("-?", "--help", "Show help message")
+        optparse.on("-r", "--[no-]recursive", "Show all subcommands recursively") do |val|
+          @recursive = val
         end
-        unless remaining.empty?
-          if !@remaining_args
-            if @executor
-              error = OptionParser::ParseError.new(*remaining)
-              error.reason = "Extra arguments provided"
-              raise error
-            else
-              error = OptionParser::ParseError.new(*(full_name + args))
-              error.reason = "Tool not found"
-              raise error
-            end
+      end
+
+      def leaf_normal_switches(switches, optparse, found_special_flags)
+        switches.each do |switch|
+          found_special_flags |= (switch.optparse_info & SPECIAL_FLAGS)
+          optparse.on(*switch.optparse_info) do |val|
+            @data[switch.key] = val
           end
-          key = @remaining_args[0]
-          accept = @remaining_args[1]
-          optdata[key] = remaining.map{ |arg| process_value(key, arg, accept) }
         end
-      rescue OptionParser::ParseError => e
-        execution_data[:usage_error] = e
       end
-      execution_data
-    end
 
-    def create_child_context(parent_context, args, execution_data)
-      context = parent_context._create_child(
-        full_name, args, execution_data[:options])
-      context.logger.level += execution_data[:delta_severity]
-      @modules.each do |mod|
-        context.extend(mod)
+      def leaf_verbose_switch(optparse, found_special_flags)
+        flags = ["-v", "--verbose"] - found_special_flags
+        return if flags.empty?
+        optparse.on(*(flags + ["Increase verbosity"])) do
+          @delta_severity -= 1
+        end
       end
-      @helpers.each do |name, block|
-        context.define_singleton_method(name, &block)
+
+      def leaf_quiet_switch(optparse, found_special_flags)
+        flags = ["-q", "--quiet"] - found_special_flags
+        return if flags.empty?
+        optparse.on(*(flags + ["Decrease verbosity"])) do
+          @delta_severity += 1
+        end
       end
-      context
-    end
 
-    def show_usage(context, optparse, recursive: false)
-      puts(optparse.to_s)
-      if @executor
-        if !@required_args.empty? || !@optional_args.empty? || @remaining_args
-          puts("")
-          puts("Positional arguments:")
-          args_to_display = @required_args + @optional_args
-          args_to_display << @remaining_args if @remaining_args
-          args_to_display.each do |key, accept, doc|
-            puts("    #{canonical_switch(key).ljust(31)}  #{doc.first}")
-            doc[1..-1].each do |d|
-              puts("                                     #{d}")
-            end unless doc.empty?
+      def leaf_help_switch(optparse, found_special_flags)
+        flags = ["-?", "-h", "--help"] - found_special_flags
+        return if flags.empty?
+        optparse.on(*(flags + ["Show help message"])) do
+          @show_help = true
+        end
+      end
+
+      def parse_required_args(remaining, tool, args)
+        tool.required_args.each do |arg_info|
+          if !@show_help && remaining.empty?
+            reason = "No value given for required argument named <#{arg_info.canonical_name}>"
+            raise create_parse_error(args, reason)
           end
+          @data[arg_info.key] = arg_info.process_value(remaining.shift)
         end
-      else
-        puts("")
-        puts("Commands:")
-        name_len = full_name.length
-        context._lookup.list_subtools(full_name, recursive).each do |tool|
-          desc = tool.effective_short_desc
-          tool_name = tool.full_name.slice(name_len..-1).join(' ').ljust(31)
-          puts("    #{tool_name}  #{desc}")
+        remaining
+      end
+
+      def parse_optional_args(remaining, tool)
+        tool.optional_args.each do |arg_info|
+          break if remaining.empty?
+          @data[arg_info.key] = arg_info.process_value(remaining.shift)
         end
+        remaining
       end
-    end
 
-    def canonical_switch(name)
-      name.to_s.downcase.gsub("_", "-").gsub(/[^a-z0-9-]/, "")
-    end
+      def parse_remaining_args(remaining, tool, args)
+        return if remaining.empty?
+        unless tool.remaining_args
+          if tool.leaf?
+            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.key] =
+          remaining.map { |arg| tool.remaining_args.process_value(arg) }
+      end
 
-    def process_value(key, val, accept)
-      return val unless accept
-      n = canonical_switch(key)
-      result = val
-      optparse = OptionParser.new
-      optparse.on("--#{n}=VALUE", accept){ |v| result = v }
-      optparse.parse(["--#{n}", val])
-      result
+      def create_parse_error(path, reason)
+        OptionParser::ParseError.new(*path).tap do |e|
+          e.reason = reason
+        end
+      end
     end
   end
 end