toys-core 0.7.0 → 0.8.0

data/lib/toys/standard_middleware/show_help.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -125,7 +117,7 @@ module Toys
       ##
       # Create a ShowHelp middleware.
       #
-      # @param [Boolean,Array<String>,Proc] help_flags Specify flags to
+      # @param help_flags [Boolean,Array<String>,Proc] Specify flags to
       #     display help. The value may be any of the following:
       #
       #     *  An array of flags.
@@ -133,7 +125,7 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] usage_flags Specify flags to
+      # @param usage_flags [Boolean,Array<String>,Proc] Specify flags to
       #     display usage. The value may be any of the following:
       #
       #     *  An array of flags.
@@ -141,7 +133,7 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] list_flags Specify flags to
+      # @param list_flags [Boolean,Array<String>,Proc] Specify flags to
       #     display subtool list. The value may be any of the following:
       #
       #     *  An array of flags.
@@ -149,7 +141,7 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] recursive_flags Specify flags
+      # @param recursive_flags [Boolean,Array<String>,Proc] Specify flags
       #     to control recursive subtool search. The value may be any of the
       #     following:
       #
@@ -158,7 +150,7 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] search_flags Specify flags
+      # @param search_flags [Boolean,Array<String>,Proc] Specify flags
       #     to search subtools for a search term. The value may be any of
       #     the following:
       #
@@ -167,7 +159,7 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean,Array<String>,Proc] show_all_subtools_flags Specify
+      # @param show_all_subtools_flags [Boolean,Array<String>,Proc] Specify
       #     flags to show all subtools, including hidden tools and non-runnable
       #     namespaces. The value may be any of the following:
       #
@@ -176,24 +168,24 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
-      # @param [Boolean] default_recursive Whether to search recursively for
+      # @param default_recursive [Boolean] Whether to search recursively for
       #     subtools by default. Default is `false`.
-      # @param [Boolean] default_show_all_subtools Whether to show all subtools
+      # @param default_show_all_subtools [Boolean] Whether to show all subtools
       #     by default. Default is `false`.
-      # @param [Boolean] fallback_execution Cause the tool to display its own
+      # @param fallback_execution [Boolean] Cause the tool to display its own
       #     help text if it is not otherwise runnable. This is mostly useful
       #     for namespaces, which have children are not runnable. Default is
       #     `false`.
-      # @param [Boolean] allow_root_args If the root tool includes flags for
+      # @param allow_root_args [Boolean] If the root tool includes flags for
       #     help or usage, and doesn't otherwise use positional arguments,
       #     then a tool name can be passed as arguments to display help for
       #     that tool.
-      # @param [Boolean] show_source_path Show the source path section. Default
+      # @param show_source_path [Boolean] Show the source path section. Default
       #     is `false`.
-      # @param [Boolean] use_less If the `less` tool is available, and the
+      # @param use_less [Boolean] If the `less` tool is available, and the
       #     output stream is a tty, then use `less` to display help text.
-      # @param [IO] stream Output stream to write to. Default is stdout.
-      # @param [Boolean,nil] styled_output Cause the tool to display help text
+      # @param stream [IO] Output stream to write to. Default is stdout.
+      # @param styled_output [Boolean,nil] Cause the tool to display help text
       #     with ansi styles. If `nil`, display styles if the output stream is
       #     a tty. Default is `nil`.
       #
@@ -229,21 +221,21 @@ module Toys
 
       ##
       # Configure flags and default data.
+      # @private
       #
-      def config(tool_definition, loader)
-        unless tool_definition.argument_parsing_disabled?
-          StandardMiddleware.append_common_flag_group(tool_definition)
-          has_subtools = loader.has_subtools?(tool_definition.full_name)
-          help_flags = add_help_flags(tool_definition)
-          usage_flags = add_usage_flags(tool_definition)
-          list_flags = has_subtools ? add_list_flags(tool_definition) : []
-          if (!help_flags.empty? || !list_flags.empty? || @fallback_execution) && has_subtools
-            add_recursive_flags(tool_definition)
-            add_search_flags(tool_definition)
-            add_show_all_subtools_flags(tool_definition)
-          end
-          if !help_flags.empty? || !usage_flags.empty? || !list_flags.empty?
-            add_root_args(tool_definition)
+      def config(tool, loader)
+        unless tool.argument_parsing_disabled?
+          StandardMiddleware.append_common_flag_group(tool)
+          has_subtools = loader.has_subtools?(tool.full_name)
+          help_flags = add_help_flags(tool)
+          usage_flags = add_usage_flags(tool)
+          list_flags = has_subtools ? add_list_flags(tool) : []
+          can_display_help = !help_flags.empty? || !list_flags.empty? ||
+                             !usage_flags.empty? || @fallback_execution
+          if can_display_help && has_subtools
+            add_recursive_flags(tool)
+            add_search_flags(tool)
+            add_show_all_subtools_flags(tool)
           end
         end
         yield
@@ -251,39 +243,59 @@ module Toys
 
       ##
       # Display help text if requested.
+      # @private
       #
-      def run(tool) # rubocop:disable Metrics/AbcSize
-        if tool[SHOW_USAGE_KEY]
-          terminal.puts(get_help_text(tool).usage_string(wrap_width: terminal.width))
-        elsif tool[SHOW_LIST_KEY]
-          terminal.puts(get_help_text(tool).list_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
-                                                        search: tool[SEARCH_STRING_KEY],
-                                                        include_hidden: tool[SHOW_ALL_SUBTOOLS_KEY],
-                                                        wrap_width: terminal.width))
-        elsif should_show_help(tool)
-          output_help(get_help_text(tool).help_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
-                                                      search: tool[SEARCH_STRING_KEY],
-                                                      include_hidden: tool[SHOW_ALL_SUBTOOLS_KEY],
-                                                      show_source_path: @show_source_path,
-                                                      wrap_width: terminal.width))
+      def run(context)
+        if context[SHOW_USAGE_KEY]
+          show_usage(context)
+        elsif context[SHOW_LIST_KEY]
+          show_list(context)
+        elsif context[SHOW_HELP_KEY]
+          show_help(context, true)
         else
-          yield
+          begin
+            yield
+          rescue NotRunnableError => e
+            raise e unless @fallback_execution
+            show_help(context, false)
+          end
         end
       end
 
       private
 
       def terminal
+        require "toys/utils/terminal"
         @terminal ||= Utils::Terminal.new(output: @stream, styled: @styled_output)
       end
 
-      def should_show_help(tool)
-        @fallback_execution && !tool[Tool::Keys::TOOL_DEFINITION].runnable? ||
-          tool[SHOW_HELP_KEY]
+      def show_usage(context)
+        help_text = get_help_text(context, true)
+        str = help_text.usage_string(
+          recursive: context[RECURSIVE_SUBTOOLS_KEY],
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], wrap_width: terminal.width
+        )
+        terminal.puts(str)
       end
 
-      def output_help(str)
+      def show_list(context)
+        help_text = get_help_text(context, true)
+        str = help_text.list_string(
+          recursive: context[RECURSIVE_SUBTOOLS_KEY], search: context[SEARCH_STRING_KEY],
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], wrap_width: terminal.width
+        )
+        terminal.puts(str)
+      end
+
+      def show_help(context, use_extra_args)
+        help_text = get_help_text(context, use_extra_args)
+        str = help_text.help_string(
+          recursive: context[RECURSIVE_SUBTOOLS_KEY], search: context[SEARCH_STRING_KEY],
+          include_hidden: context[SHOW_ALL_SUBTOOLS_KEY], show_source_path: @show_source_path,
+          wrap_width: terminal.width
+        )
         if less_path
+          require "toys/utils/exec"
           Utils::Exec.new.exec([less_path, "-R"], in: [:string, str])
         else
           terminal.puts(str)
@@ -301,27 +313,41 @@ module Toys
         @less_path
       end
 
-      def get_help_text(tool)
-        tool_name = tool[TOOL_NAME_KEY]
-        return Utils::HelpText.from_tool(tool) if tool_name.nil? || tool_name.empty?
-        loader = tool[Tool::Keys::LOADER]
-        tool_definition, rest = loader.lookup(tool_name)
-        help_text = Utils::HelpText.new(tool_definition, loader, tool[Tool::Keys::BINARY_NAME])
-        report_usage_error(tool_name, help_text) unless rest.empty?
-        help_text
+      def get_help_text(context, use_extra_args)
+        require "toys/utils/help_text"
+        if use_extra_args && @allow_root_args && context[Context::Key::TOOL].root?
+          tool_name = Array(context[Context::Key::UNMATCHED_POSITIONAL])
+          unless tool_name.empty?
+            cli = context[Context::Key::CLI]
+            loader = cli.loader
+            tool, rest = loader.lookup(tool_name)
+            help_text = Utils::HelpText.new(tool, loader, cli.executable_name)
+            report_usage_error(help_text, loader, tool.full_name, rest.first) unless rest.empty?
+            return help_text
+          end
+        end
+        Utils::HelpText.from_context(context)
       end
 
-      def report_usage_error(tool_name, help_text)
-        terminal.puts("Tool not found: #{tool_name.join(' ')}", :bright_red, :bold)
+      def report_usage_error(help_text, loader, tool_name, next_word)
+        dict = loader.list_subtools(tool_name).map(&:simple_name)
+        suggestions = Compat.suggestions(next_word, dict)
+        tool_name = (tool_name + [next_word]).join(" ")
+        message = "Tool not found: \"#{tool_name}\"."
+        unless suggestions.empty?
+          suggestions_str = suggestions.join("\n                 ")
+          message = "#{message}\nDid you mean...  #{suggestions_str}"
+        end
+        terminal.puts(message, :bright_red, :bold)
         terminal.puts
         terminal.puts help_text.usage_string(wrap_width: terminal.width)
-        Tool.exit(1)
+        Context.exit(1)
       end
 
-      def add_help_flags(tool_definition)
-        flags = resolve_flags_spec(@help_flags, tool_definition, DEFAULT_HELP_FLAGS)
+      def add_help_flags(tool)
+        flags = resolve_flags_spec(@help_flags, tool, DEFAULT_HELP_FLAGS)
         unless flags.empty?
-          tool_definition.add_flag(
+          tool.add_flag(
             SHOW_HELP_KEY, flags,
             report_collisions: false,
             desc: "Display help for this tool",
@@ -331,10 +357,10 @@ module Toys
         flags
       end
 
-      def add_usage_flags(tool_definition)
-        flags = resolve_flags_spec(@usage_flags, tool_definition, DEFAULT_USAGE_FLAGS)
+      def add_usage_flags(tool)
+        flags = resolve_flags_spec(@usage_flags, tool, DEFAULT_USAGE_FLAGS)
         unless flags.empty?
-          tool_definition.add_flag(
+          tool.add_flag(
             SHOW_USAGE_KEY, flags,
             report_collisions: false,
             desc: "Display a brief usage string for this tool",
@@ -344,10 +370,10 @@ module Toys
         flags
       end
 
-      def add_list_flags(tool_definition)
-        flags = resolve_flags_spec(@list_flags, tool_definition, DEFAULT_LIST_FLAGS)
+      def add_list_flags(tool)
+        flags = resolve_flags_spec(@list_flags, tool, DEFAULT_LIST_FLAGS)
         unless flags.empty?
-          tool_definition.add_flag(
+          tool.add_flag(
             SHOW_LIST_KEY, flags,
             report_collisions: false,
             desc: "List the subtools under this tool",
@@ -357,12 +383,12 @@ module Toys
         flags
       end
 
-      def add_recursive_flags(tool_definition)
-        flags = resolve_flags_spec(@recursive_flags, tool_definition, DEFAULT_RECURSIVE_FLAGS)
+      def add_recursive_flags(tool)
+        flags = resolve_flags_spec(@recursive_flags, tool, DEFAULT_RECURSIVE_FLAGS)
         if flags.empty?
-          tool_definition.default_data[RECURSIVE_SUBTOOLS_KEY] = @default_recursive
+          tool.default_data[RECURSIVE_SUBTOOLS_KEY] = @default_recursive
         else
-          tool_definition.add_flag(
+          tool.add_flag(
             RECURSIVE_SUBTOOLS_KEY, flags,
             report_collisions: false, default: @default_recursive,
             desc: "List all subtools recursively when displaying help" \
@@ -373,10 +399,10 @@ module Toys
         flags
       end
 
-      def add_search_flags(tool_definition)
-        flags = resolve_flags_spec(@search_flags, tool_definition, DEFAULT_SEARCH_FLAGS)
+      def add_search_flags(tool)
+        flags = resolve_flags_spec(@search_flags, tool, DEFAULT_SEARCH_FLAGS)
         unless flags.empty?
-          tool_definition.add_flag(
+          tool.add_flag(
             SEARCH_STRING_KEY, flags,
             report_collisions: false,
             desc: "Search subtools for the given regular expression when displaying help",
@@ -386,13 +412,12 @@ module Toys
         flags
       end
 
-      def add_show_all_subtools_flags(tool_definition)
-        flags = resolve_flags_spec(@show_all_subtools_flags, tool_definition,
-                                   DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS)
+      def add_show_all_subtools_flags(tool)
+        flags = resolve_flags_spec(@show_all_subtools_flags, tool, DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS)
         if flags.empty?
-          tool_definition.default_data[SHOW_ALL_SUBTOOLS_KEY] = @default_show_all_subtools
+          tool.default_data[SHOW_ALL_SUBTOOLS_KEY] = @default_show_all_subtools
         else
-          tool_definition.add_flag(
+          tool.add_flag(
             SHOW_ALL_SUBTOOLS_KEY, flags,
             report_collisions: false, default: @default_show_all_subtools,
             desc: "List all subtools including hidden subtools and namespaces" \
@@ -403,16 +428,8 @@ module Toys
         flags
       end
 
-      def add_root_args(tool_definition)
-        if @allow_root_args && tool_definition.root? && tool_definition.arg_definitions.empty?
-          tool_definition.set_remaining_args(TOOL_NAME_KEY,
-                                             display_name: "TOOL_NAME",
-                                             desc: "The tool for which to display help")
-        end
-      end
-
-      def resolve_flags_spec(flags, tool_definition, defaults)
-        flags = flags.call(tool_definition) if flags.respond_to?(:call)
+      def resolve_flags_spec(flags, tool, defaults)
+        flags = flags.call(tool) if flags.respond_to?(:call)
         case flags
         when true, :default
           Array(defaults)

data/lib/toys/standard_middleware/show_root_version.rb

@@ -1,32 +1,24 @@
 # frozen_string_literal: true
 
-# Copyright 2018 Daniel Azuma
+# Copyright 2019 Daniel Azuma
 #
-# All rights reserved.
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
 #
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
 #
-# * 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.
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
 ;
 
 module Toys
@@ -59,11 +51,11 @@ module Toys
       ##
       # Create a ShowVersion middleware
       #
-      # @param [String] version_string The string that should be displayed.
-      # @param [Array<String>] version_flags A list of flags that should
+      # @param version_string [String] The string that should be displayed.
+      # @param version_flags [Array<String>] A list of flags that should
       #     trigger displaying the version. Default is
       #     {DEFAULT_VERSION_FLAGS}.
-      # @param [IO] stream Output stream to write to. Default is stdout.
+      # @param stream [IO] Output stream to write to. Default is stdout.
       #
       def initialize(version_string: nil,
                      version_flags: DEFAULT_VERSION_FLAGS,
@@ -72,26 +64,28 @@ module Toys
         @version_string = version_string
         @version_flags = version_flags
         @version_flag_desc = version_flag_desc
-        @terminal = Utils::Terminal.new(output: stream)
+        @output = stream
       end
 
       ##
       # Adds the version flag if requested.
+      # @private
       #
-      def config(tool_definition, _loader)
-        if @version_string && tool_definition.root?
-          tool_definition.add_flag(SHOW_VERSION_KEY, @version_flags,
-                                   report_collisions: false, desc: @version_flag_desc)
+      def config(tool, _loader)
+        if @version_string && tool.root?
+          tool.add_flag(SHOW_VERSION_KEY, @version_flags,
+                        report_collisions: false, desc: @version_flag_desc)
         end
         yield
       end
 
       ##
       # This middleware displays the version.
+      # @private
       #
-      def run(tool)
-        if tool[SHOW_VERSION_KEY]
-          @terminal.puts(@version_string)
+      def run(context)
+        if context[SHOW_VERSION_KEY]
+          @output.puts(@version_string)
         else
           yield
         end