toys-core 0.3.3 → 0.3.4

data/lib/toys/middleware/base.rb

@@ -36,7 +36,7 @@ module Toys
       ##
       # The base middleware does not affect tool configuration.
       #
-      def config(_tool)
+      def config(_tool, _loader)
         yield
       end
 

data/lib/toys/middleware/handle_usage_errors.rb

@@ -30,15 +30,16 @@
 require "highline"
 
 require "toys/middleware/base"
-require "toys/utils/usage"
+require "toys/utils/help_text"
+require "toys/utils/line_output"
 
 module Toys
   module Middleware
     ##
     # This middleware handles the case of a usage error. If a usage error, such
-    # as an unrecognized switch or an unfulfilled required argument, is
-    # detected, this middleware intercepts execution and displays the error
-    # along with the usage string, and terminates execution with an error code.
+    # as an unrecognized flag or an unfulfilled required argument, is detected,
+    # this middleware intercepts execution and displays the error along with
+    # the short help string, and terminates execution with an error code.
     #
     class HandleUsageErrors < Base
       ##
@@ -46,9 +47,14 @@ module Toys
       #
       # @param [Intgeer] exit_code The exit code to return if a usage error
       #     occurs. Default is -1.
+      # @param [IO] stream Output stream to write to. Default is stderr.
+      # @param [Boolean,nil] styled_output Cause the tool to display help text
+      #     with ansi styles. If `nil`, display styles if the output stream is
+      #     a tty. Default is `nil`.
       #
-      def initialize(exit_code: -1)
+      def initialize(exit_code: -1, stream: $stderr, styled_output: nil)
         @exit_code = exit_code
+        @output = Utils::LineOutput.new(stream, styled: styled_output)
       end
 
       ##
@@ -57,10 +63,10 @@ module Toys
       def execute(context)
         if context[Context::USAGE_ERROR]
           width = ::HighLine.new.output_cols
-          usage = Utils::Usage.from_context(context)
-          puts(context[Context::USAGE_ERROR])
-          puts("")
-          puts(usage.string(show_path: true, wrap_width: width))
+          help_text = Utils::HelpText.from_context(context)
+          @output.puts(context[Context::USAGE_ERROR], :bright_red, :bold)
+          @output.puts("")
+          @output.puts(help_text.usage_string(wrap_width: width))
           context.exit(@exit_code)
         else
           yield

data/lib/toys/middleware/set_default_descriptions.rb

@@ -41,89 +41,166 @@ module Toys
       # The default description for tools.
       # @return [String]
       #
-      DEFAULT_TOOL_DESC = "(No description available)".freeze
+      DEFAULT_TOOL_DESC = "(No tool description available)".freeze
 
       ##
       # The default description for groups.
       # @return [String]
       #
-      DEFAULT_GROUP_DESC = "(A group of commands)".freeze
+      DEFAULT_GROUP_DESC = "(A group of tools)".freeze
 
       ##
       # The default description for the root tool.
       # @return [String]
       #
-      DEFAULT_ROOT_DESC =
-        "This command line tool was built using the toys-core gem." \
-        " See https://www.rubydoc.info/gems/toys-core for more info." \
-        " To replace this message, configure the SetDefaultDescriptions" \
-        " middleware.".freeze
+      DEFAULT_ROOT_DESC = "Command line tool built using the toys-core gem.".freeze
+
+      ##
+      # The default long description for the root tool.
+      # @return [String]
+      #
+      DEFAULT_ROOT_LONG_DESC =
+        "This command line tool was built using the toys-core gem. See" \
+        " https://www.rubydoc.info/gems/toys-core for more info. To replace this message," \
+        " configure the SetDefaultDescriptions middleware.".freeze
+
+      ##
+      # The default description for flags.
+      # @return [String]
+      #
+      DEFAULT_FLAG_DESC = "(No flag description available)".freeze
+
+      ##
+      # The default description for required args.
+      # @return [String]
+      #
+      DEFAULT_REQUIRED_ARG_DESC = "(Required argument - no description available)".freeze
+
+      ##
+      # The default description for optional args.
+      # @return [String]
+      #
+      DEFAULT_OPTIONAL_ARG_DESC = "(Optional argument - no description available)".freeze
+
+      ##
+      # The default description for remaining args.
+      # @return [String]
+      #
+      DEFAULT_REMAINING_ARG_DESC = "(Remaining arguments - no description available)".freeze
 
       ##
       # Create a SetDefaultDescriptions middleware given default descriptions.
       #
-      # @param [String] default_tool_desc The default short description for
-      #     tools with an eecutor. Defaults to {DEFAULT_TOOL_DESC}.
+      # @param [String,nil] default_tool_desc The default short description for
+      #     tools with an executor, or `nil` not to set one. Defaults to
+      #     {DEFAULT_TOOL_DESC}.
       # @param [String,nil] default_tool_long_desc The default long description
-      #     for tools with an eecutor. If `nil` (the default), falls back to
-      #     the value of the `default_tool_desc` parameter.
-      # @param [String] default_group_desc The default short description for
-      #     tools with no eecutor. Defaults to {DEFAULT_GROUP_DESC}.
+      #     for tools with an executor, or `nil` not to set one. Defaults to
+      #     `nil`.
+      # @param [String,nil] default_group_desc The default short description
+      #     for tools with no executor, or `nil` not to set one. Defaults to
+      #     {DEFAULT_TOOL_DESC}.
       # @param [String,nil] default_group_long_desc The default long
-      #     description for tools with no eecutor. If `nil` (the default),
-      #     falls back to the value of the `default_group_desc` parameter.
-      # @param [String] default_root_desc The default long description for the
-      #     root tool. Defaults to {DEFAULT_ROOT_DESC}.
+      #     description for tools with no executor, or `nil` not to set one.
+      #     Defaults to `nil`.
+      # @param [String,nil] default_root_desc The default short description for
+      #     the root tool, or `nil` not to set one. Defaults to
+      #     {DEFAULT_ROOT_DESC}.
+      # @param [String,nil] default_root_long_desc The default long description
+      #     for the root tool, or `nil` not to set one. Defaults to
+      #     {DEFAULT_ROOT_LONG_DESC}.
+      # @param [String,nil] default_flag_desc The default short description for
+      #     flags, or `nil` not to set one. Defaults to {DEFAULT_FLAG_DESC}.
+      # @param [String,nil] default_flag_long_desc The default long description
+      #     for flags, or `nil` not to set one. Defaults to `nil`.
+      # @param [String,nil] default_required_arg_desc The default short
+      #     description for required args, or `nil` not to set one. Defaults to
+      #     {DEFAULT_REQUIRED_ARG_DESC}.
+      # @param [String,nil] default_required_arg_long_desc The default long
+      #     description for required args, or `nil` not to set one. Defaults to
+      #     `nil`.
+      # @param [String,nil] default_optional_arg_desc The default short
+      #     description for optional args, or `nil` not to set one. Defaults to
+      #     {DEFAULT_OPTIONAL_ARG_DESC}.
+      # @param [String,nil] default_optional_arg_long_desc The default long
+      #     description for optional args, or `nil` not to set one. Defaults to
+      #     `nil`.
+      # @param [String,nil] default_remaining_arg_desc The default short
+      #     description for remaining args, or `nil` not to set one. Defaults
+      #     to {DEFAULT_REMAINING_ARG_DESC}.
+      # @param [String,nil] default_remaining_arg_long_desc The default long
+      #     description for remaining args, or `nil` not to set one. Defaults
+      #     to `nil`.
       #
       def initialize(default_tool_desc: DEFAULT_TOOL_DESC,
                      default_tool_long_desc: nil,
                      default_group_desc: DEFAULT_GROUP_DESC,
                      default_group_long_desc: nil,
-                     default_root_desc: DEFAULT_ROOT_DESC)
+                     default_root_desc: DEFAULT_ROOT_DESC,
+                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
+                     default_flag_desc: DEFAULT_FLAG_DESC,
+                     default_flag_long_desc: nil,
+                     default_required_arg_desc: DEFAULT_REQUIRED_ARG_DESC,
+                     default_required_arg_long_desc: nil,
+                     default_optional_arg_desc: DEFAULT_OPTIONAL_ARG_DESC,
+                     default_optional_arg_long_desc: nil,
+                     default_remaining_arg_desc: DEFAULT_REMAINING_ARG_DESC,
+                     default_remaining_arg_long_desc: nil)
         @default_tool_desc = default_tool_desc
         @default_tool_long_desc = default_tool_long_desc
         @default_group_desc = default_group_desc
         @default_group_long_desc = default_group_long_desc
         @default_root_desc = default_root_desc
+        @default_root_long_desc = default_root_long_desc
+        @default_flag_desc = default_flag_desc
+        @default_flag_long_desc = default_flag_long_desc
+        @default_required_arg_desc = default_required_arg_desc
+        @default_required_arg_long_desc = default_required_arg_long_desc
+        @default_optional_arg_desc = default_optional_arg_desc
+        @default_optional_arg_long_desc = default_optional_arg_long_desc
+        @default_remaining_arg_desc = default_remaining_arg_desc
+        @default_remaining_arg_long_desc = default_remaining_arg_long_desc
       end
 
       ##
       # Add default description text to tools.
       #
-      def config(tool)
+      def config(tool, _loader)
         if tool.root?
-          config_root_desc(tool)
+          config_descs(tool, @default_root_desc, @default_root_long_desc)
         elsif tool.includes_executor?
-          config_tool_desc(tool)
+          config_descs(tool, @default_tool_desc, @default_tool_long_desc)
         else
-          config_group_desc(tool)
+          config_descs(tool, @default_group_desc, @default_group_long_desc)
+        end
+        tool.flag_definitions.each do |flag|
+          config_descs(flag, @default_flag_desc, @default_flag_long_desc)
         end
+        config_args(tool)
         yield
       end
 
       private
 
-      def config_root_desc(tool)
-        if @default_root_desc && tool.effective_long_desc.empty?
-          tool.long_desc = @default_root_desc
+      def config_args(tool)
+        tool.required_arg_definitions.each do |arg|
+          config_descs(arg, @default_required_arg_desc, @default_required_arg_long_desc)
         end
-      end
-
-      def config_tool_desc(tool)
-        if @default_tool_long_desc && tool.effective_long_desc.empty?
-          tool.long_desc = @default_tool_long_desc
+        tool.optional_arg_definitions.each do |arg|
+          config_descs(arg, @default_optional_arg_desc, @default_optional_arg_long_desc)
         end
-        if @default_tool_desc && tool.effective_desc.empty?
-          tool.desc = @default_tool_desc
+        if tool.remaining_args_definition
+          config_descs(tool.remaining_args_definition,
+                       @default_remaining_arg_desc, @default_remaining_arg_long_desc)
         end
       end
 
-      def config_group_desc(tool)
-        if @default_group_long_desc && tool.effective_long_desc.empty?
-          tool.long_desc = @default_group_long_desc
+      def config_descs(object, default_desc, default_long_desc)
+        if default_desc && object.desc.empty?
+          object.desc = default_desc
         end
-        if @default_group_desc && tool.effective_desc.empty?
-          tool.desc = @default_group_desc
+        if default_long_desc && object.long_desc.empty?
+          object.long_desc = default_long_desc
         end
       end
     end

data/lib/toys/middleware/show_help.rb

@@ -0,0 +1,245 @@
+# 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 "highline"
+
+require "toys/middleware/base"
+require "toys/utils/help_text"
+require "toys/utils/line_output"
+
+module Toys
+  module Middleware
+    ##
+    # A middleware that shows help text for the tool when a flag (typically
+    # `--help`) is provided. It can also be configured to show help by
+    # default if the tool is a group with no executor.
+    #
+    # If a tool has no executor, this middleware can also add a
+    # `--[no-]recursive` flag, which, when set to `true` (the default), shows
+    # all subtools recursively rather than only immediate subtools. This
+    # middleware can also search for keywords in its subtools.
+    #
+    class ShowHelp < Base
+      ##
+      # Default help flags
+      # @return [Array<String>]
+      #
+      DEFAULT_HELP_FLAGS = ["-?", "--help"].freeze
+
+      ##
+      # Default usage flags
+      # @return [Array<String>]
+      #
+      DEFAULT_USAGE_FLAGS = ["--usage"].freeze
+
+      ##
+      # Default recursive flags
+      # @return [Array<String>]
+      #
+      DEFAULT_RECURSIVE_FLAGS = ["-r", "--[no-]recursive"].freeze
+
+      ##
+      # Default search flags
+      # @return [Array<String>]
+      #
+      DEFAULT_SEARCH_FLAGS = ["-s WORD", "--search=WORD"].freeze
+
+      ##
+      # Create a ShowHelp middleware.
+      #
+      # @param [Boolean,Array<String>,Proc] help_flags Specify flags to
+      #     display help. The value may be any of the following:
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_HELP_FLAGS}.
+      #     *  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
+      #     display usage. The value may be any of the following:
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_USAGE_FLAGS}.
+      #     *  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
+      #     to control recursive subtool search. The value may be any of the
+      #     following:
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_RECURSIVE_FLAGS}.
+      #     *  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
+      #     to search subtools for a search term. The value may be any of
+      #     the following:
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_SEARCH_FLAGS}.
+      #     *  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
+      #     subtools by default. Default is `false`.
+      # @param [Boolean] fallback_execution Cause the tool to display its own
+      #     help text if it does not otherwise have an executor. This is
+      #     mostly useful for groups, which have children but no executor.
+      #     Default is `false`.
+      # @param [Boolean] allow_root_args 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 [IO] stream Output stream to write to. Default is stdout.
+      # @param [Boolean,nil] styled_output Cause the tool to display help text
+      #     with ansi styles. If `nil`, display styles if the output stream is
+      #     a tty. Default is `nil`.
+      #
+      def initialize(help_flags: false,
+                     usage_flags: false,
+                     recursive_flags: false,
+                     search_flags: false,
+                     default_recursive: false,
+                     fallback_execution: false,
+                     allow_root_args: false,
+                     stream: $stdout,
+                     styled_output: nil)
+        @help_flags = help_flags
+        @usage_flags = usage_flags
+        @recursive_flags = recursive_flags
+        @search_flags = search_flags
+        @default_recursive = default_recursive ? true : false
+        @fallback_execution = fallback_execution
+        @allow_root_args = allow_root_args
+        @stream = stream
+        @styled_output = styled_output
+      end
+
+      ##
+      # Configure flags and default data.
+      #
+      def config(tool, loader)
+        help_flags = add_help_flags(tool)
+        usage_flags = add_usage_flags(tool)
+        if @allow_root_args && (!help_flags.empty? || !usage_flags.empty?)
+          if tool.root? && tool.arg_definitions.empty?
+            tool.set_remaining_args(:_tool_name, display_name: "TOOL_NAME",
+                                                 desc: "The tool for which to display help")
+          end
+        end
+        if (!help_flags.empty? || @fallback_execution) && loader.has_subtools?(tool.full_name)
+          add_recursive_flags(tool)
+          add_search_flags(tool)
+        end
+        yield
+      end
+
+      ##
+      # Display help text if requested.
+      #
+      def execute(context)
+        if context[:_show_usage]
+          help_text = get_help_text(context)
+          str = help_text.usage_string(wrap_width: output_cols)
+          output.puts(str)
+        elsif @fallback_execution && !context[Context::TOOL].includes_executor? ||
+              context[:_show_help]
+          help_text = get_help_text(context)
+          str = help_text.help_string(recursive: context[:_recursive_subtools],
+                                      search: context[:_search_subtools],
+                                      wrap_width: output_cols)
+          output.puts(str)
+        else
+          yield
+        end
+      end
+
+      private
+
+      def output_cols
+        @output_cols ||= ::HighLine.new(nil, @stream).output_cols
+      end
+
+      def output
+        @output ||= Utils::LineOutput.new(@stream, styled: @styled_output)
+      end
+
+      def get_help_text(context)
+        tool_name = context[:_tool_name]
+        return Utils::HelpText.from_context(context) if tool_name.nil? || tool_name.empty?
+        loader = context[Context::LOADER]
+        tool, rest = loader.lookup(tool_name)
+        help_text = Utils::HelpText.new(tool, loader, context[Context::BINARY_NAME])
+        report_usage_error(context, tool_name, help_text) unless rest.empty?
+        help_text
+      end
+
+      def report_usage_error(context, tool_name, help_text)
+        output.puts("Tool not found: #{tool_name.join(' ')}", :bright_red, :bold)
+        output.puts
+        output.puts help_text.usage_string(wrap_width: output_cols)
+        context.exit(1)
+      end
+
+      def add_help_flags(tool)
+        help_flags = Middleware.resolve_flags_spec(@help_flags, tool,
+                                                   DEFAULT_HELP_FLAGS)
+        unless help_flags.empty?
+          tool.add_flag(:_show_help, *help_flags,
+                        desc: "Display help for this tool", only_unique: true)
+        end
+        help_flags
+      end
+
+      def add_usage_flags(tool)
+        usage_flags = Middleware.resolve_flags_spec(@usage_flags, tool,
+                                                    DEFAULT_USAGE_FLAGS)
+        unless usage_flags.empty?
+          tool.add_flag(:_show_usage, *usage_flags,
+                        desc: "Display a brief usage string for this tool", only_unique: true)
+        end
+        usage_flags
+      end
+
+      def add_recursive_flags(tool)
+        recursive_flags = Middleware.resolve_flags_spec(@recursive_flags, tool,
+                                                        DEFAULT_RECURSIVE_FLAGS)
+        unless recursive_flags.empty?
+          tool.add_flag(:_recursive_subtools, *recursive_flags,
+                        default: @default_recursive,
+                        desc: "Show all subtools recursively (default is #{@default_recursive})",
+                        only_unique: true)
+        end
+      end
+
+      def add_search_flags(tool)
+        search_flags = Middleware.resolve_flags_spec(@search_flags, tool,
+                                                     DEFAULT_SEARCH_FLAGS)
+        unless search_flags.empty?
+          tool.add_flag(:_search_subtools, *search_flags,
+                        desc: "Search subtools for the given regular expression",
+                        only_unique: true)
+        end
+      end
+    end
+  end
+end