toys-core 0.3.7.1 → 0.3.8

data/lib/toys/dsl/flag.rb

@@ -33,6 +33,9 @@ module Toys
     # DSL for a flag definition block. Lets you set flag attributes in a block
     # instead of a long series of keyword arguments.
     #
+    # These directives are available inside a block passed to
+    # {Toys::DSL::Tool#flag}.
+    #
     class Flag
       ## @private
       def initialize(flags, accept, default, handler, report_collisions, desc, long_desc)
@@ -75,14 +78,15 @@ module Toys
 
       ##
       # Set the optional handler for setting/updating the value when a flag is
-      # parsed. It should be a Proc taking two arguments, the new given value
-      # and the previous value, and it should return the new value that should
-      # be set.
+      # parsed. A handler should be a Proc taking two arguments, the new given
+      # value and the previous value, and it should return the new value that
+      # should be set. You may pass the handler as a Proc (or an object
+      # responding to the `call` method) or you may pass a block.
       #
       # @param [Proc] handler
       #
-      def handler(handler)
-        @handler = handler
+      def handler(handler = nil, &block)
+        @handler = handler || block
         self
       end
 

data/lib/toys/dsl/tool.rb

@@ -30,16 +30,13 @@
 module Toys
   module DSL
     ##
-    # This class defines the DSL for a toys configuration file.
+    # This class defines the DSL for a Toys configuration file.
     #
-    # A toys configuration defines one or more named tools. It provides syntax
+    # A Toys configuration defines one or more named tools. It provides syntax
     # for setting the description, defining flags and arguments, specifying
-    # how to execute the tool, and requesting helper modules and other services.
+    # how to execute the tool, and requesting mixin modules and other services.
     # It also lets you define subtools, nested arbitrarily deep, using blocks.
     #
-    # Generally the DSL is invoked from the {Loader}. Applications should not
-    # need to create instances of DSL::Tool directly.
-    #
     # ## Simple example
     #
     # Create a file called `.toys.rb` in the current directory, with the
@@ -50,8 +47,8 @@ module Toys
     #
     #       optional_arg :recipient, default: "world"
     #
-    #       script do
-    #         puts "Hello, #{self[:recipient]}!"
+    #       def run
+    #         puts "Hello, #{option(:recipient)}!"
     #       end
     #     end
     #
@@ -129,16 +126,16 @@ module Toys
       end
 
       ##
-      # Create a named helper module.
+      # Create a named mixin module.
       # This module may be included by name in this tool or any subtool.
       #
       # You should pass a block and define methods in that block.
       #
-      # @param [String] name Name of the helper
+      # @param [String] name Name of the mixin
       #
-      def helper(name, &block)
+      def mixin(name, &block)
         cur_tool = DSL::Tool.activate_tool(self)
-        cur_tool.add_helper(name, ::Module.new(&block)) if cur_tool
+        cur_tool.add_mixin(name, ::Module.new(&block)) if cur_tool
         self
       end
 
@@ -209,7 +206,10 @@ module Toys
       def expand(template_class, *args)
         unless template_class.is_a?(::Class)
           name = template_class.to_s
-          template_class = Templates.lookup!(name)
+          template_class = @__loader.resolve_standard_template(name)
+          if template_class.nil?
+            raise ToolDefinitionError, "Template name not found: #{name.inspect}"
+          end
         end
         template = template_class.new(*args)
         yield template if block_given?
@@ -281,7 +281,7 @@ module Toys
       ##
       # Add a flag to the current tool. Each flag must specify a key which
       # the script may use to obtain the flag value from the context.
-      # You may then provide the flags themselves in `OptionParser` form.
+      # You may then provide the flags themselves in OptionParser form.
       #
       # Attributes of the flag may be passed in as arguments to this method, or
       # set in a block passed to this method.
@@ -318,12 +318,13 @@ module Toys
       def flag(key, *flags,
                accept: nil, default: nil, handler: nil,
                report_collisions: true,
-               desc: nil, long_desc: nil)
+               desc: nil, long_desc: nil,
+               &block)
         cur_tool = DSL::Tool.activate_tool(self)
         return self if cur_tool.nil?
         flag_dsl = DSL::Flag.new(flags, accept, default, handler, report_collisions,
                                  desc, long_desc)
-        yield flag_dsl if block_given?
+        flag_dsl.instance_exec(flag_dsl, &block) if block
         flag_dsl._add_to(cur_tool, key)
         self
       end
@@ -352,11 +353,13 @@ module Toys
       # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
       #     this argument in a block.
       #
-      def required_arg(key, accept: nil, display_name: nil, desc: nil, long_desc: nil)
+      def required_arg(key,
+                       accept: nil, display_name: nil, desc: nil, long_desc: nil,
+                       &block)
         cur_tool = DSL::Tool.activate_tool(self)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, nil, display_name, desc, long_desc)
-        yield arg_dsl if block_given?
+        arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_required_to(cur_tool, key)
         self
       end
@@ -390,12 +393,14 @@ module Toys
       # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
       #     this argument in a block.
       #
-      def optional_arg(key, default: nil, accept: nil, display_name: nil,
-                       desc: nil, long_desc: nil)
+      def optional_arg(key,
+                       default: nil, accept: nil, display_name: nil,
+                       desc: nil, long_desc: nil,
+                       &block)
         cur_tool = DSL::Tool.activate_tool(self)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
-        yield arg_dsl if block_given?
+        arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._add_optional_to(cur_tool, key)
         self
       end
@@ -428,12 +433,14 @@ module Toys
       # @yieldparam arg_dsl [Toys::DSL::Arg] An object that lets you configure
       #     this argument in a block.
       #
-      def remaining_args(key, default: [], accept: nil, display_name: nil,
-                         desc: nil, long_desc: nil)
+      def remaining_args(key,
+                         default: [], accept: nil, display_name: nil,
+                         desc: nil, long_desc: nil,
+                         &block)
         cur_tool = DSL::Tool.activate_tool(self)
         return self if cur_tool.nil?
         arg_dsl = DSL::Arg.new(accept, default, display_name, desc, long_desc)
-        yield arg_dsl if block_given?
+        arg_dsl.instance_exec(arg_dsl, &block) if block
         arg_dsl._set_remaining_on(cur_tool, key)
         self
       end
@@ -452,9 +459,9 @@ module Toys
       # Specify that the given module should be mixed into this tool, and its
       # methods made available when running the tool.
       #
-      # You may provide either a module, the string name of a helper that you
+      # You may provide either a module, the string name of a mixin that you
       # have defined in this tool or one of its ancestors, or the symbol name
-      # of a well-known helper.
+      # of a well-known mixin.
       #
       # @param [Module,Symbol,String] mod Module or module name.
       #
@@ -463,9 +470,9 @@ module Toys
         return if cur_tool.nil?
         name = mod.to_s
         if mod.is_a?(::String)
-          mod = cur_tool.resolve_helper(mod)
+          mod = cur_tool.resolve_mixin(mod)
         elsif mod.is_a?(::Symbol)
-          mod = Helpers.lookup!(name)
+          mod = @__loader.resolve_standard_mixin(name)
         end
         if mod.nil?
           raise ToolDefinitionError, "Module not found: #{name.inspect}"

data/lib/toys/input_file.rb

@@ -28,7 +28,8 @@
 ;
 
 ##
-# Internal modules providing constant namespaces for config files.
+# This module is a namespace for constant scopes. Whenever a configuration file
+# is parsed, a module is created under this parent for that file's constants.
 #
 module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
   ## @private

data/lib/toys/loader.rb

@@ -59,14 +59,24 @@ module Toys
     #     used by the tools defined in that directory.
     # @param [Array] middleware_stack An array of middleware that will be used
     #     by default for all tools loaded by this loader.
-    #
-    def initialize(index_file_name: nil, preload_file_name: nil, middleware_stack: [])
+    # @param [Toys::Utils::ModuleLookup] mixin_lookup A lookup for well-known
+    #     mixin modules. Defaults to an empty lookup.
+    # @param [Toys::Utils::ModuleLookup] middleware_lookup A lookup for
+    #     well-known middleware classes. Defaults to an empty lookup.
+    # @param [Toys::Utils::ModuleLookup] template_lookup A lookup for
+    #     well-known template classes. Defaults to an empty lookup.
+    #
+    def initialize(index_file_name: nil, preload_file_name: nil, middleware_stack: [],
+                   mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil)
       if index_file_name && ::File.extname(index_file_name) != ".rb"
         raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
       end
       if preload_file_name && ::File.extname(preload_file_name) != ".rb"
         raise ::ArgumentError, "Illegal preload file name #{preload_file_name.inspect}"
       end
+      @mixin_lookup = mixin_lookup || Utils::ModuleLookup.new
+      @middleware_lookup = middleware_lookup || Utils::ModuleLookup.new
+      @template_lookup = template_lookup || Utils::ModuleLookup.new
       @index_file_name = index_file_name
       @preload_file_name = preload_file_name
       @middleware_stack = middleware_stack
@@ -133,7 +143,7 @@ module Toys
     # @param [Array<String>] words The name of the parent tool
     # @param [Boolean] recursive If true, return all subtools recursively
     #     rather than just the immediate children (the default)
-    # @return [Array<Toys::Definition::Tool,Tool::Definition::Alias>]
+    # @return [Array<Toys::Definition::Tool,Toys::Definition::Alias>]
     #
     def list_subtools(words, recursive: false)
       load_for_prefix(words)
@@ -168,23 +178,6 @@ module Toys
       false
     end
 
-    ##
-    # Finishes all tool definitions under the given path. This generally means
-    # installing middleware.
-    #
-    # @param [Array<String>] words The path to the tool under which all
-    #     definitions should be finished.
-    #
-    def finish_definitions_in_tree(words)
-      load_for_prefix(words)
-      len = words.length
-      @tool_data.each do |n, td|
-        next if n.length < len || n.slice(0, len) != words
-        tool = td.active_definition || td.top_definition
-        tool.finish_definition(self) if tool.is_a?(Definition::Tool)
-      end
-    end
-
     ##
     # Returns a tool specified by the given words, with the given priority.
     # Does not do any loading. If the tool is not present, creates it.
@@ -241,36 +234,8 @@ module Toys
     end
 
     ##
-    # Returns a tool given a name. Resolves any aliases.
-    #
-    # @param [Array<String>] words Name of the tool
-    # @param [Array<Array<String>>] looked_up List of names that have already
-    #     been traversed during alias resolution. Used to detect circular
-    #     alias references.
-    # @return [Toys::Definition::Tool,nil] The tool, or `nil` if not found
-    #
-    # @private
-    #
-    def get_active_tool(words, looked_up = [])
-      tool_data = get_tool_data(words)
-      result = tool_data.active_definition
-      case result
-      when Definition::Alias
-        words = result.target_name
-        if looked_up.include?(words)
-          raise ToolDefinitionError, "Circular alias references: #{looked_up.inspect}"
-        end
-        looked_up << words
-        get_active_tool(words, looked_up)
-      when Definition::Tool
-        result
-      else
-        tool_data.top_definition
-      end
-    end
-
-    ##
-    # Get the tool definition for the given name and priority.
+    # Get or create the tool definition for the given name and priority.
+    # May return either a tool or alias definition.
     #
     # @private
     #
@@ -284,8 +249,29 @@ module Toys
       if tool_data.top_priority.nil? || tool_data.top_priority < priority
         tool_data.top_priority = priority
       end
+      middlewares = @middleware_stack.map { |m| resolve_middleware(m) }
       tool_data.definitions[priority] ||=
-        Definition::Tool.new(self, parent, words, priority, @middleware_stack)
+        Definition::Tool.new(self, parent, words, priority, middlewares)
+    end
+
+    ##
+    # Attempt to get a well-known mixin module for the given symbolic name.
+    #
+    # @param [Symbol] name Mixin name
+    # @return [Module,nil] The mixin, or `nil` if not found.
+    #
+    def resolve_standard_mixin(name)
+      @mixin_lookup.lookup(name)
+    end
+
+    ##
+    # Attempt to get a well-known template class for the given symbolic name.
+    #
+    # @param [Symbol] name Template name
+    # @return [Class,nil] The template, or `nil` if not found.
+    #
+    def resolve_standard_template(name)
+      @template_lookup.lookup(name)
     end
 
     ##
@@ -318,6 +304,66 @@ module Toys
       @tool_data[words] ||= ToolData.new({}, nil, nil)
     end
 
+    ##
+    # Returns the current effective tool given a name. Resolves any aliases.
+    #
+    # If there is an active tool, returns it; otherwise, returns the highest
+    # priority tool that has been defined. If no tool has been defined with
+    # the given name, returns `nil`.
+    #
+    # @private
+    #
+    def get_active_tool(words, looked_up = [])
+      tool_data = get_tool_data(words)
+      result = tool_data.active_definition
+      case result
+      when Definition::Alias
+        words = result.target_name
+        if looked_up.include?(words)
+          raise ToolDefinitionError, "Circular alias references: #{looked_up.inspect}"
+        end
+        looked_up << words
+        get_active_tool(words, looked_up)
+      when Definition::Tool
+        result
+      else
+        tool_data.top_definition
+      end
+    end
+
+    def resolve_middleware(input)
+      input = Array(input)
+      cls = input.first
+      args = input[1..-1]
+      if cls.is_a?(::String) || cls.is_a?(::Symbol)
+        cls = @middleware_lookup.lookup(cls)
+        if cls.nil?
+          raise ::ArgumentError, "Unrecognized middleware name #{input.first.inspect}"
+        end
+      end
+      if cls.is_a?(::Class)
+        cls.new(*args)
+      elsif !args.empty?
+        raise ::ArgumentError, "Unrecognized middleware object of class #{cls.class}"
+      else
+        cls
+      end
+    end
+
+    ##
+    # Finishes all tool definitions under the given path. This generally means
+    # installing middleware.
+    #
+    def finish_definitions_in_tree(words)
+      load_for_prefix(words)
+      len = words.length
+      @tool_data.each do |n, td|
+        next if n.length < len || n.slice(0, len) != words
+        tool = td.active_definition || td.top_definition
+        tool.finish_definition(self) if tool.is_a?(Definition::Tool)
+      end
+    end
+
     def load_for_prefix(prefix)
       cur_worklist = @load_worklist
       @load_worklist = []

data/lib/toys/middleware.rb

@@ -27,98 +27,72 @@
 # POSSIBILITY OF SUCH DAMAGE.
 ;
 
-require "toys/utils/module_lookup"
-
 module Toys
   ##
-  # Middleware lets you define common behavior across many tools.
+  # 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.
+  #
+  # Generally, a middleware is a class that implements the two methods defined
+  # in this module: {Toys::Middleware#config} and {Toys::Middleware#run}. A
+  # middleware can include this module to get default implementations that do
+  # nothing, but this is not required.
   #
   module Middleware
-    class << self
-      ##
-      # Return a well-known middleware class by name.
-      #
-      # Currently recognized middleware names are:
-      #
-      # *  `:add_verbosity_flags` : Adds flags for affecting verbosity.
-      # *  `:handle_usage_errors` : Displays the usage error if one occurs.
-      # *  `:set_default_descriptions` : Sets default descriptions for tools
-      #    that do not have them set explicitly.
-      # *  `:show_help` : Teaches tools to print their usage documentation.
-      # *  `:show_version` : Teaches tools to print their version.
-      #
-      # @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)
-      end
-
-      ##
-      # Resolves a single middleware. You may pass an instance already
-      # constructed, a middleware class, the name of a well-known middleware
-      # class, or an array where the first element is the lookup name or class,
-      # and subsequent elements are arguments to be passed to the constructor.
-      #
-      # @param [String,Symbol,Array,Object] input The middleware spec
-      # @return [Object] Constructed middleware
-      #
-      def resolve(input)
-        input = Array(input)
-        raise "No middleware found" if input.empty?
-        cls = input.first
-        args = input[1..-1]
-        if cls.is_a?(::String) || cls.is_a?(::Symbol)
-          cls = lookup!(cls)
-        end
-        if cls.is_a?(::Class)
-          cls.new(*args)
-        else
-          raise "Unrecognized middleware class #{cls.class}" unless args.empty?
-          cls
-        end
-      end
-
-      ##
-      # Resolves an array of middleware specs. See {Toys::Middleware.resolve}.
-      #
-      # @param [Array] input An array of middleware specs
-      # @return [Array] An array of constructed middleware
-      #
-      def resolve_stack(input)
-        input.map { |e| resolve(e) }
-      end
+    ##
+    # 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.
+    #
+    # This basic implementation does nothing and simply yields to the next
+    # middleware.
+    #
+    # @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
 
-      ##
-      # Resolves a typical flags specification. Used often in middleware.
-      #
-      # You may provide any of the following for the `flags` parameter:
-      # *  A string, which becomes the single flag
-      # *  An array of strings
-      # *  The value `false` or `nil` which resolves to no flags
-      # *  The value `true` or `:default` which resolves to the given defaults
-      # *  A proc that takes a tool as argument and returns any of the above.
-      #
-      # Always returns an array of flag strings, even if empty.
-      #
-      # @param [Boolean,String,Array<String>,Proc] flags Flag spec
-      # @param [Toys::Tool] tool The tool
-      # @param [Array<String>] defaults The defaults to use for `true`.
-      # @return [Array<String>] An array of flags
-      #
-      def resolve_flags_spec(flags, tool, defaults)
-        flags = flags.call(tool) if flags.respond_to?(:call)
-        case flags
-        when true, :default
-          Array(defaults)
-        when ::String
-          [flags]
-        when ::Array
-          flags
-        else
-          []
-        end
-      end
+    ##
+    # 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.
+    #
+    # This basic implementation does nothing and simply yields to the next
+    # middleware.
+    #
+    # @param [Toys::Tool] _tool The tool execution instance.
+    #
+    def run(_tool)
+      yield
     end
   end
 end