toys-core 0.3.6 → 0.3.7

data/lib/toys/middleware.rb

@@ -50,8 +50,8 @@ module Toys
       # @param [String,Symbol] name Name of the middleware class to return
       # @return [Class,nil] The class, or `nil` if not found
       #
-      def lookup(name)
-        Utils::ModuleLookup.lookup(:middleware, name)
+      def lookup!(name)
+        Utils::ModuleLookup.lookup!(:middleware, name)
       end
 
       ##
@@ -69,7 +69,7 @@ module Toys
         cls = input.first
         args = input[1..-1]
         if cls.is_a?(::String) || cls.is_a?(::Symbol)
-          cls = lookup(cls)
+          cls = lookup!(cls)
         end
         if cls.is_a?(::Class)
           cls.new(*args)

data/lib/toys/middleware/add_verbosity_flags.rb

@@ -36,7 +36,7 @@ module Toys
     #
     # This middleware adds `-v`, `--verbose`, `-q`, and `--quiet` flags, if
     # not already defined by the tool. These flags affect the setting of
-    # {Toys::Context::VERBOSITY}, and, thus, the logger level.
+    # {Toys::Tool::Keys::VERBOSITY}, and, thus, the logger level.
     #
     class AddVerbosityFlags < Base
       ##
@@ -75,37 +75,39 @@ module Toys
       ##
       # Configure the tool flags.
       #
-      def config(tool, _loader)
-        add_verbose_flags(tool)
-        add_quiet_flags(tool)
+      def config(tool_definition, _loader)
+        add_verbose_flags(tool_definition)
+        add_quiet_flags(tool_definition)
         yield
       end
 
       private
 
-      def add_verbose_flags(tool)
-        verbose_flags = Middleware.resolve_flags_spec(@verbose_flags, tool,
+      def add_verbose_flags(tool_definition)
+        verbose_flags = Middleware.resolve_flags_spec(@verbose_flags, tool_definition,
                                                       DEFAULT_VERBOSE_FLAGS)
         unless verbose_flags.empty?
-          long_desc = "Increase verbosity, causing additional logging levels to display."
-          tool.add_flag(Context::VERBOSITY, verbose_flags,
-                        report_collisions: false,
-                        handler: ->(_val, cur) { cur + 1 },
-                        desc: "Increase verbosity",
-                        long_desc: long_desc)
+          tool_definition.add_flag(
+            Tool::Keys::VERBOSITY, verbose_flags,
+            report_collisions: false,
+            handler: ->(_val, cur) { cur + 1 },
+            desc: "Increase verbosity",
+            long_desc: "Increase verbosity, causing additional logging levels to display."
+          )
         end
       end
 
-      def add_quiet_flags(tool)
-        quiet_flags = Middleware.resolve_flags_spec(@quiet_flags, tool,
+      def add_quiet_flags(tool_definition)
+        quiet_flags = Middleware.resolve_flags_spec(@quiet_flags, tool_definition,
                                                     DEFAULT_QUIET_FLAGS)
         unless quiet_flags.empty?
-          long_desc = "Decrease verbosity, causing fewer logging levels to display."
-          tool.add_flag(Context::VERBOSITY, quiet_flags,
-                        report_collisions: false,
-                        handler: ->(_val, cur) { cur - 1 },
-                        desc: "Decrease verbosity",
-                        long_desc: long_desc)
+          tool_definition.add_flag(
+            Tool::Keys::VERBOSITY, quiet_flags,
+            report_collisions: false,
+            handler: ->(_val, cur) { cur - 1 },
+            desc: "Decrease verbosity",
+            long_desc: "Decrease verbosity, causing fewer logging levels to display."
+          )
         end
       end
     end

data/lib/toys/middleware/base.rb

@@ -30,20 +30,68 @@
 module Toys
   module Middleware
     ##
-    # A base middleware with a no-op implementation.
+    # This is a base middleware with a no-op implementation.
+    #
+    # A middleware is an object that has the opportunity to alter the
+    # configuration and runtime behavior of each tool in a Toys CLI. A CLI
+    # contains an ordered list of middleware, known as the *middleware stack*,
+    # that together define the CLI's default behavior.
+    #
+    # Specifically, a middleware can perform two functions.
+    #
+    # First, it can modify the configuration of a tool. After tools are defined
+    # from configuration, the middleware stack can make modifications to each
+    # tool. A middleware can add flags and arguments to the tool, modify the
+    # description, or make any other changes to how the tool is set up.
+    #
+    # Second, a middleware can intercept and change tool execution. Like a Rack
+    # middleware, a Toys middleware can wrap execution with its own code,
+    # replace it outright, or leave it unmodified.
     #
     class Base
       ##
-      # The base middleware does not affect tool configuration.
+      # This method is called after a tool has been defined, and gives this
+      # middleware the opportunity to modify the tool definition. It is passed
+      # the tool definition object and the loader, and can make any changes to
+      # the tool definition. In most cases, this method should also call
+      # `yield`, which passes control to the next middleware in the stack. A
+      # middleware can disable modifications done by subsequent middleware by
+      # omitting the `yield` call, but this is uncommon.
+      #
+      # The base middleware implementation does nothing and simply yields to
+      # the next middleware. Subclasses should override this if they want to
+      # alter the tool definition.
       #
-      def config(_tool, _loader)
+      # @param [Toys::Definition::Tool] _tool_definition The tool definition
+      #     to modify.
+      # @param [Toys::Loader] _loader The loader that loaded this tool.
+      #
+      def config(_tool_definition, _loader)
         yield
       end
 
       ##
-      # The base middleware does not affect tool execution.
+      # This method is called when the tool is run. It gives the middleware an
+      # opportunity to modify the runtime behavior of the tool. It is passed
+      # the tool instance (i.e. the object that hosts a tool's `run` method),
+      # and you can use this object to access the tool's options and other
+      # context data. In most cases, this method should also call `yield`,
+      # which passes control to the next middleware in the stack. A middleware
+      # can "wrap" normal execution by calling `yield` somewhere in its
+      # implementation of this method, or it can completely replace the
+      # execution behavior by not calling `yield` at all.
+      #
+      # Like a tool's `run` method, this method's return value is unused. If
+      # you want to output from a tool, write to stdout or stderr. If you want
+      # to set the exit status code, call {Toys::Tool#exit} on the tool object.
+      #
+      # The base middleware implementation does nothing and simply yields to
+      # the next middleware. Subclasses should override this if they want to
+      # alter the tool execution.
+      #
+      # @param [Toys::Tool] _tool The tool execution instance.
       #
-      def execute(_context)
+      def run(_tool)
         yield
       end
     end

data/lib/toys/middleware/handle_usage_errors.rb

@@ -27,11 +27,9 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "highline"
-
 require "toys/middleware/base"
 require "toys/utils/help_text"
-require "toys/utils/line_output"
+require "toys/utils/terminal"
 
 module Toys
   module Middleware
@@ -54,20 +52,19 @@ module Toys
       #
       def initialize(exit_code: -1, stream: $stderr, styled_output: nil)
         @exit_code = exit_code
-        @output = Utils::LineOutput.new(stream, styled: styled_output)
+        @terminal = Utils::Terminal.new(output: stream, styled: styled_output)
       end
 
       ##
       # Intercept and handle usage errors during execution.
       #
-      def execute(context)
-        if context[Context::USAGE_ERROR]
-          width = ::HighLine.new.output_cols
-          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)
+      def run(tool)
+        if tool[Tool::Keys::USAGE_ERROR]
+          help_text = Utils::HelpText.from_tool(tool)
+          @terminal.puts(tool[Tool::Keys::USAGE_ERROR], :bright_red, :bold)
+          @terminal.puts("")
+          @terminal.puts(help_text.usage_string(wrap_width: @terminal.width))
+          tool.exit(@exit_code)
         else
           yield
         end

data/lib/toys/middleware/set_default_descriptions.rb

@@ -86,16 +86,15 @@ module Toys
       # Create a SetDefaultDescriptions middleware given default descriptions.
       #
       # @param [String,nil] default_tool_desc The default short description for
-      #     tools with an script, or `nil` not to set one. Defaults to
+      #     runnable tools, 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 script, or `nil` not to set one. Defaults to
-      #     `nil`.
+      #     for runnable tools, or `nil` not to set one. Defaults to `nil`.
       # @param [String,nil] default_namespace_desc The default short
-      #     description for tools with no script, or `nil` not to set one.
+      #     description for non-runnable tools, or `nil` not to set one.
       #     Defaults to {DEFAULT_TOOL_DESC}.
       # @param [String,nil] default_namespace_long_desc The default long
-      #     description for tools with no script, or `nil` not to set one.
+      #     description for non-runnable tools, 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
@@ -151,7 +150,7 @@ module Toys
       def generate_tool_desc(tool, data)
         if tool.root?
           @default_root_desc
-        elsif !tool.includes_script? && data[:loader].has_subtools?(tool.full_name)
+        elsif !tool.runnable? && data[:loader].has_subtools?(tool.full_name)
           @default_namespace_desc
         else
           @default_tool_desc
@@ -174,7 +173,7 @@ module Toys
       def generate_tool_long_desc(tool, data)
         if tool.root?
           @default_root_long_desc
-        elsif !tool.includes_script? && data[:loader].has_subtools?(tool.full_name)
+        elsif !tool.runnable? && data[:loader].has_subtools?(tool.full_name)
           @default_namespace_long_desc
         else
           @default_tool_long_desc

data/lib/toys/middleware/show_help.rb

@@ -27,21 +27,19 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "highline"
-
 require "toys/middleware/base"
 require "toys/utils/exec"
 require "toys/utils/help_text"
-require "toys/utils/line_output"
+require "toys/utils/terminal"
 
 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 namespace with no script.
+    # default if the tool is a namespace that is not runnable.
     #
-    # If a tool has no script, this middleware can also add a
+    # If a tool is not runnable, 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.
@@ -103,9 +101,9 @@ module Toys
       # @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 script. This is mostly
-      #     useful for namespaces, which have children but no script. Default
-      #     is `false`.
+      #     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
       #     help or usage, and doesn't otherwise use positional arguments,
       #     then a tool name can be passed as arguments to display help for
@@ -146,18 +144,20 @@ module Toys
       ##
       # Configure flags and default data.
       #
-      def config(tool, loader)
-        help_flags = add_help_flags(tool)
-        usage_flags = add_usage_flags(tool)
+      def config(tool_definition, loader)
+        help_flags = add_help_flags(tool_definition)
+        usage_flags = add_usage_flags(tool_definition)
         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")
+          if tool_definition.root? && tool_definition.arg_definitions.empty?
+            tool_definition.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)
+        if (!help_flags.empty? || @fallback_execution) &&
+           loader.has_subtools?(tool_definition.full_name)
+          add_recursive_flags(tool_definition)
+          add_search_flags(tool_definition)
         end
         yield
       end
@@ -165,18 +165,18 @@ module Toys
       ##
       # 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_script? ||
-              context[:_show_help]
-          help_text = get_help_text(context)
-          str = help_text.help_string(recursive: context[:_recursive_subtools],
-                                      search: context[:_search_subtools],
+      def run(tool)
+        if tool[:_show_usage]
+          help_text = get_help_text(tool)
+          str = help_text.usage_string(wrap_width: terminal.width)
+          terminal.puts(str)
+        elsif @fallback_execution && !tool[Tool::Keys::TOOL_DEFINITION].runnable? ||
+              tool[:_show_help]
+          help_text = get_help_text(tool)
+          str = help_text.help_string(recursive: tool[:_recursive_subtools],
+                                      search: tool[:_search_subtools],
                                       show_source_path: @show_source_path,
-                                      wrap_width: output_cols)
+                                      wrap_width: terminal.width)
           output_help(str)
         else
           yield
@@ -185,19 +185,15 @@ module Toys
 
       private
 
-      def output_cols
-        @output_cols ||= ::HighLine.new(nil, @stream).output_cols
-      end
-
-      def output
-        @output ||= Utils::LineOutput.new(@stream, styled: @styled_output)
+      def terminal
+        @terminal ||= Utils::Terminal.new(output: @stream, styled: @styled_output)
       end
 
       def output_help(str)
         if less_path
           Utils::Exec.new.exec([less_path, "-R"], in_from: str)
         else
-          output.puts(str)
+          terminal.puts(str)
         end
       end
 
@@ -212,62 +208,70 @@ module Toys
         @less_path
       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?
+      def get_help_text(tool)
+        tool_name = tool[:_tool_name]
+        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, 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)
+      def report_usage_error(tool, tool_name, help_text)
+        terminal.puts("Tool not found: #{tool_name.join(' ')}", :bright_red, :bold)
+        terminal.puts
+        terminal.puts help_text.usage_string(wrap_width: terminal.width)
+        tool.exit(1)
       end
 
-      def add_help_flags(tool)
-        help_flags = Middleware.resolve_flags_spec(@help_flags, tool,
+      def add_help_flags(tool_definition)
+        help_flags = Middleware.resolve_flags_spec(@help_flags, tool_definition,
                                                    DEFAULT_HELP_FLAGS)
         unless help_flags.empty?
-          tool.add_flag(:_show_help, help_flags,
-                        report_collisions: false, desc: "Display help for this tool")
+          tool_definition.add_flag(
+            :_show_help, help_flags,
+            report_collisions: false,
+            desc: "Display help for this tool"
+          )
         end
         help_flags
       end
 
-      def add_usage_flags(tool)
-        usage_flags = Middleware.resolve_flags_spec(@usage_flags, tool,
+      def add_usage_flags(tool_definition)
+        usage_flags = Middleware.resolve_flags_spec(@usage_flags, tool_definition,
                                                     DEFAULT_USAGE_FLAGS)
         unless usage_flags.empty?
-          tool.add_flag(:_show_usage, usage_flags,
-                        report_collisions: false,
-                        desc: "Display a brief usage string for this tool")
+          tool_definition.add_flag(
+            :_show_usage, usage_flags,
+            report_collisions: false,
+            desc: "Display a brief usage string for this tool"
+          )
         end
         usage_flags
       end
 
-      def add_recursive_flags(tool)
-        recursive_flags = Middleware.resolve_flags_spec(@recursive_flags, tool,
+      def add_recursive_flags(tool_definition)
+        recursive_flags = Middleware.resolve_flags_spec(@recursive_flags, tool_definition,
                                                         DEFAULT_RECURSIVE_FLAGS)
         unless recursive_flags.empty?
-          tool.add_flag(:_recursive_subtools, recursive_flags,
-                        report_collisions: false,
-                        default: @default_recursive,
-                        desc: "Show all subtools recursively (default is #{@default_recursive})")
+          tool_definition.add_flag(
+            :_recursive_subtools, recursive_flags,
+            report_collisions: false, default: @default_recursive,
+            desc: "Show all subtools recursively (default is #{@default_recursive})"
+          )
         end
       end
 
-      def add_search_flags(tool)
-        search_flags = Middleware.resolve_flags_spec(@search_flags, tool,
+      def add_search_flags(tool_definition)
+        search_flags = Middleware.resolve_flags_spec(@search_flags, tool_definition,
                                                      DEFAULT_SEARCH_FLAGS)
         unless search_flags.empty?
-          tool.add_flag(:_search_subtools, search_flags,
-                        report_collisions: false,
-                        desc: "Search subtools for the given regular expression")
+          tool_definition.add_flag(
+            :_search_subtools, search_flags,
+            report_collisions: false,
+            desc: "Search subtools for the given regular expression"
+          )
         end
       end
     end