toys-core 0.3.2

data/lib/toys/middleware/add_verbosity_switches.rb

@@ -0,0 +1,99 @@
+# 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 "toys/middleware/base"
+
+module Toys
+  module Middleware
+    ##
+    # A middleware that provides switches for editing the verbosity.
+    #
+    # This middleware adds `-v`, `--verbose`, `-q`, and `--quiet` switches, if
+    # not already defined by the tool. These switches affect the setting of
+    # {Toys::Context::VERBOSITY}, and, thus, the logger level.
+    #
+    class AddVerbositySwitches < Base
+      ##
+      # Default verbose switches
+      # @return [Array<String>]
+      #
+      DEFAULT_VERBOSE_SWITCHES = ["-v", "--verbose"].freeze
+
+      ##
+      # Default quiet switches
+      # @return [Array<String>]
+      #
+      DEFAULT_QUIET_SWITCHES = ["-q", "--quiet"].freeze
+
+      ##
+      # Create a AddVerbositySwitches middleware.
+      #
+      # @param [Boolean,Array<String>,Proc] verbose_switches Specify switches
+      #     to increase verbosity. The value may be any of the following:
+      #     *  An array of switches that increase verbosity.
+      #     *  The `true` value to use {DEFAULT_VERBOSE_SWITCHES}. (Default)
+      #     *  The `false` value to disable verbose switches.
+      #     *  A proc that takes a tool and returns any of the above.
+      # @param [Boolean,Array<String>,Proc] quiet_switches Specify switches
+      #     to decrease verbosity. The value may be any of the following:
+      #     *  An array of switches that decrease verbosity.
+      #     *  The `true` value to use {DEFAULT_QUIET_SWITCHES}. (Default)
+      #     *  The `false` value to disable quiet switches.
+      #     *  A proc that takes a tool and returns any of the above.
+      #
+      def initialize(verbose_switches: true, quiet_switches: true)
+        @verbose_switches = verbose_switches
+        @quiet_switches = quiet_switches
+      end
+
+      ##
+      # Configure the tool switches.
+      #
+      def config(tool)
+        verbose_switches = Middleware.resolve_switches_spec(@verbose_switches, tool,
+                                                            DEFAULT_VERBOSE_SWITCHES)
+        unless verbose_switches.empty?
+          tool.add_switch(Context::VERBOSITY, *verbose_switches,
+                          doc: "Increase verbosity",
+                          handler: ->(_val, cur) { cur + 1 },
+                          only_unique: true)
+        end
+        quiet_switches = Middleware.resolve_switches_spec(@quiet_switches, tool,
+                                                          DEFAULT_QUIET_SWITCHES)
+        unless quiet_switches.empty?
+          tool.add_switch(Context::VERBOSITY, *quiet_switches,
+                          doc: "Decrease verbosity",
+                          handler: ->(_val, cur) { cur - 1 },
+                          only_unique: true)
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/toys/middleware/base.rb

@@ -0,0 +1,51 @@
+# 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
+  module Middleware
+    ##
+    # A base middleware with a no-op implementation.
+    #
+    class Base
+      ##
+      # The base middleware does not affect tool configuration.
+      #
+      def config(_tool)
+        yield
+      end
+
+      ##
+      # The base middleware does not affect tool execution.
+      #
+      def execute(_context)
+        yield
+      end
+    end
+  end
+end

data/lib/toys/middleware/handle_usage_errors.rb

@@ -0,0 +1,67 @@
+# 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 "toys/middleware/base"
+require "toys/utils/usage"
+
+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.
+    #
+    class HandleUsageErrors < Base
+      ##
+      # Create a HandleUsageErrors middleware.
+      #
+      # @param [Intgeer] exit_code The exit code to return if a usage error
+      #     occurs. Default is -1.
+      #
+      def initialize(exit_code: -1)
+        @exit_code = exit_code
+      end
+
+      ##
+      # Intercept and handle usage errors during execution.
+      #
+      def execute(context)
+        if context[Context::USAGE_ERROR]
+          puts(context[Context::USAGE_ERROR])
+          puts("")
+          puts(Utils::Usage.from_context(context).string(show_path: true))
+          context.exit(@exit_code)
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/toys/middleware/set_default_descriptions.rb

@@ -0,0 +1,131 @@
+# 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 "toys/middleware/base"
+
+module Toys
+  module Middleware
+    ##
+    # This middleware sets default description fields for tools that do not
+    # have them set otherwise. You can set separate descriptions for tools,
+    # groups, and the root.
+    #
+    class SetDefaultDescriptions < Base
+      ##
+      # The default description for tools.
+      # @return [String]
+      #
+      DEFAULT_TOOL_DESC = "(No description available)".freeze
+
+      ##
+      # The default description for groups.
+      # @return [String]
+      #
+      DEFAULT_GROUP_DESC = "(A group of commands)".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
+
+      ##
+      # 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_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}.
+      # @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}.
+      #
+      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_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
+      end
+
+      ##
+      # Add default description text to tools.
+      #
+      def config(tool)
+        if tool.root?
+          config_root_desc(tool)
+        elsif tool.includes_executor?
+          config_tool_desc(tool)
+        else
+          config_group_desc(tool)
+        end
+        yield
+      end
+
+      private
+
+      def config_root_desc(tool)
+        if @default_root_desc && tool.effective_long_desc.empty?
+          tool.long_desc = @default_root_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
+        end
+        if @default_tool_desc && tool.effective_desc.empty?
+          tool.desc = @default_tool_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
+        end
+        if @default_group_desc && tool.effective_desc.empty?
+          tool.desc = @default_group_desc
+        end
+      end
+    end
+  end
+end

data/lib/toys/middleware/show_usage.rb

@@ -0,0 +1,170 @@
+# 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 "toys/middleware/base"
+require "toys/utils/usage"
+
+module Toys
+  module Middleware
+    ##
+    # A middleware that shows usage documentation.
+    #
+    # This can be configured to display usage text when a switch (typically
+    # `--help`) is provided. It can also be configured to display usage text
+    # automatically for tools that do not have an 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 subcommands recursively rather than only immediate subcommands.
+    #
+    class ShowUsage < Base
+      ##
+      # Default help switches
+      # @return [Array<String>]
+      #
+      DEFAULT_HELP_SWITCHES = ["-?", "--help"].freeze
+
+      ##
+      # Default recursive switches
+      # @return [Array<String>]
+      #
+      DEFAULT_RECURSIVE_SWITCHES = ["-r", "--[no-]recursive"].freeze
+
+      ##
+      # Default search switches
+      # @return [Array<String>]
+      #
+      DEFAULT_SEARCH_SWITCHES = ["-s WORD", "--search=WORD"].freeze
+
+      ##
+      # Create a ShowUsage middleware.
+      #
+      # @param [Boolean,Array<String>,Proc] help_switches Specify switches to
+      #     activate help. The value may be any of the following:
+      #     *  An array of switches.
+      #     *  The `true` value to use {DEFAULT_HELP_SWITCHES}. (Default)
+      #     *  The `false` value for no switches.
+      #     *  A proc that takes a tool and returns any of the above.
+      # @param [Boolean,Array<String>,Proc] recursive_switches Specify switches
+      #     to control recursive subcommand search. The value may be any of the
+      #     following:
+      #     *  An array of switches.
+      #     *  The `true` value to use {DEFAULT_RECURSIVE_SWITCHES}. (Default)
+      #     *  The `false` value for no switches.
+      #     *  A proc that takes a tool and returns any of the above.
+      # @param [Boolean,Array<String>,Proc] search_switches Specify switches
+      #     to search subcommands for a search term. The value may be any of
+      #     the following:
+      #     *  An array of switches.
+      #     *  The `true` value to use {DEFAULT_SEARCH_SWITCHES}. (Default)
+      #     *  The `false` value for no switches.
+      #     *  A proc that takes a tool and returns any of the above.
+      # @param [Boolean] default_recursive Whether to search recursively for
+      #     subcommands by default. Default is `true`.
+      # @param [Boolean] fallback_execution Cause the tool to display its own
+      #     usage text if it does not otherwise have an executor. This is
+      #     mostly useful for groups, which have children but no executor.
+      #     Default is `true`.
+      #
+      def initialize(help_switches: true,
+                     recursive_switches: true,
+                     search_switches: true,
+                     default_recursive: true,
+                     fallback_execution: true)
+        @help_switches = help_switches
+        @recursive_switches = recursive_switches
+        @search_switches = search_switches
+        @default_recursive = default_recursive ? true : false
+        @fallback_execution = fallback_execution
+      end
+
+      ##
+      # Configure switches and default data.
+      #
+      def config(tool)
+        help_switches = Middleware.resolve_switches_spec(@help_switches, tool,
+                                                         DEFAULT_HELP_SWITCHES)
+        is_default = !tool.includes_executor? && @fallback_execution
+        if !help_switches.empty?
+          doc = "Show help message"
+          doc << " (default for groups)" if is_default
+          tool.add_switch(:_help, *help_switches,
+                          doc: doc,
+                          default: is_default,
+                          only_unique: true)
+        elsif is_default
+          tool.default_data[:_help] = true
+        end
+        if !tool.includes_executor? && (!help_switches.empty? || @fallback_execution)
+          add_recursive_switches(tool)
+          add_search_switches(tool)
+        end
+        yield
+      end
+
+      ##
+      # Display usage text if requested.
+      #
+      def execute(context)
+        if context[:_help]
+          usage = Utils::Usage.from_context(context)
+          puts(usage.string(recursive: context[:_recursive_subcommands],
+                            search: context[:_search_subcommands],
+                            show_path: context.verbosity > 0))
+        else
+          yield
+        end
+      end
+
+      private
+
+      def add_recursive_switches(tool)
+        recursive_switches = Middleware.resolve_switches_spec(@recursive_switches, tool,
+                                                              DEFAULT_RECURSIVE_SWITCHES)
+        unless recursive_switches.empty?
+          tool.add_switch(:_recursive_subcommands, *recursive_switches,
+                          default: @default_recursive,
+                          doc: "Show all subcommands recursively" \
+                               " (default is #{@default_recursive})",
+                          only_unique: true)
+        end
+      end
+
+      def add_search_switches(tool)
+        search_switches = Middleware.resolve_switches_spec(@search_switches, tool,
+                                                           DEFAULT_SEARCH_SWITCHES)
+        unless search_switches.empty?
+          tool.add_switch(:_search_subcommands, *search_switches,
+                          doc: "Search subcommands for the given term",
+                          only_unique: true)
+        end
+      end
+    end
+  end
+end