toys 0.3.0 → 0.3.1

data/lib/toys/loader.rb

@@ -29,9 +29,35 @@
 
 module Toys
   ##
-  # The lookup service that finds a tool given a set of arguments
+  # The Loader service loads tools from configuration files, and finds the
+  # appropriate tool given a set of command line arguments.
   #
   class Loader
+    ##
+    # Create a Loader
+    #
+    # @param [String,nil] config_dir_name A directory with this name that
+    #     appears in the loader path, is treated as a configuration directory
+    #     whose contents are loaded into the toys configuration. Optional.
+    #     If not provided, toplevel configuration directories are disabled.
+    # @param [String,nil] config_file_name A file with this name that appears
+    #     in the loader path, is treated as a toplevel configuration file
+    #     whose contents are loaded into the toys configuration. Optional.
+    #     If not provided, toplevel configuration files are disabled.
+    # @param [String,nil] index_file_name A file with this name that appears
+    #     in any configuration directory (not just a toplevel directory) is
+    #     loaded first as a standalone configuration file. If not provided,
+    #     standalone configuration files are disabled.
+    # @param [String,nil] preload_file_name A file with this name that appears
+    #     in any configuration directory (not just a toplevel directory) is
+    #     loaded before any configuration files. It is not treated as a
+    #     configuration file in that the configuration DSL is not honored. You
+    #     may use such a file to define auxiliary Ruby modules and classes that
+    #     used by the tools defined in that directory.
+    # @param [Array] middleware An array of middleware that will be used by
+    #     default for all tools loaded by this CLI.
+    # @param [String] root_desc The description of the root tool.
+    #
     def initialize(config_dir_name: nil, config_file_name: nil,
                    index_file_name: nil, preload_file_name: nil,
                    middleware: [], root_desc: nil)
@@ -42,12 +68,22 @@ module Toys
       @middleware = middleware
       check_init_options
       @load_worklist = []
-      root_tool = Tool.new([], middleware)
+      root_tool = Tool.new([])
+      root_tool.middleware_stack.concat(@middleware)
       root_tool.long_desc = root_desc if root_desc
       @tools = {[] => [root_tool, nil]}
       @max_priority = @min_priority = 0
     end
 
+    ##
+    # Add one or more configuration files/directories to the loader.
+    # This might point to a directory that defines a default set of tools.
+    #
+    # @param [String,Array<String>] paths One or more paths to add.
+    # @param [Boolean] high_priority If true, add these paths at the top of
+    #     the priority list. Defaults to false, indicating new paths should
+    #     be at the bottom of the priority list.
+    #
     def add_config_paths(paths, high_priority: false)
       paths = Array(paths)
       paths = paths.reverse if high_priority
@@ -57,6 +93,15 @@ module Toys
       self
     end
 
+    ##
+    # Add a single configuration file/directory to the loader.
+    # This might point to a directory that defines a default set of tools.
+    #
+    # @param [String] path A path to add.
+    # @param [Boolean] high_priority If true, add this path at the top of the
+    #     priority list. Defaults to false, indicating the new path should be
+    #     at the bottom of the priority list.
+    #
     def add_config_path(path, high_priority: false)
       path = check_path(path)
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
@@ -64,6 +109,15 @@ module Toys
       self
     end
 
+    ##
+    # Add one or more path directories to the loader. These directories are
+    # searched for toplevel config directories and files.
+    #
+    # @param [String,Array<String>] paths One or more paths to add.
+    # @param [Boolean] high_priority If true, add these paths at the top of
+    #     the priority list. Defaults to false, indicating new paths should
+    #     be at the bottom of the priority list.
+    #
     def add_paths(paths, high_priority: false)
       paths = Array(paths)
       paths = paths.reverse if high_priority
@@ -73,6 +127,15 @@ module Toys
       self
     end
 
+    ##
+    # Add a single path directory to the loader. This directory is searched
+    # for toplevel config directories and files.
+    #
+    # @param [String] path A path to add.
+    # @param [Boolean] high_priority If true, add this path at the top of the
+    #     priority list. Defaults to false, indicating the new path should be
+    #     at the bottom of the priority list.
+    #
     def add_path(path, high_priority: false)
       path = check_path(path, type: :dir)
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
@@ -91,6 +154,16 @@ module Toys
       self
     end
 
+    ##
+    # Given a list of command line arguments, find the appropriate tool to
+    # handle the command, loading it from the configuration if necessary.
+    # This always returns a tool. If the specific tool path is not defined and
+    # cannot be found in any configuration, it returns the nearest group that
+    # _would_ contain that tool, up to the root tool.
+    #
+    # @param [String] args Command line arguments
+    # @return [Toys::Tool]
+    #
     def lookup(args)
       orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
       cur_prefix = orig_prefix.dup
@@ -105,59 +178,119 @@ module Toys
       end
     end
 
+    ##
+    # Returns a list of subtools for the given path, loading from the
+    # configuration if necessary.
+    #
+    # @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::Tool>]
+    #
+    def list_subtools(words, recursive: false)
+      load_for_prefix(words)
+      found_tools = []
+      len = words.length
+      @tools.each do |n, tp|
+        next if n.empty?
+        if recursive
+          next if n.length <= len || n.slice(0, len) != words
+        else
+          next unless n.slice(0..-2) == words
+        end
+        found_tools << tp.first
+      end
+      sort_tools_by_name(found_tools)
+    end
+
+    ##
+    # Execute the tool given by the given arguments, in the given context.
+    #
+    # @param [Toys::Context::Base] context_base The context in which to
+    #     execute.
+    # @param [String] args Command line arguments
+    # @param [Integer] verbosity Starting verbosity. Defaults to 0.
+    # @return [Integer] The exit code
+    #
+    # @private
+    #
     def execute(context_base, args, verbosity: 0)
       tool = lookup(args)
       tool.execute(context_base, args.slice(tool.full_name.length..-1), verbosity: verbosity)
     end
 
-    def exact_tool(words)
-      return nil unless tool_defined?(words)
-      @tools[words].first
-    end
-
-    def get_tool(words, priority, assume_parent: false)
+    ##
+    # 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.
+    #
+    # @param [Array<String>] words The name of the tool.
+    # @param [Integer] priority The priority of the request.
+    # @param [Boolean] assume_parent If true, does not check the parent tool's
+    #     priority.
+    # @return [Toys::Tool,nil] The tool, or `nil` if the given priority is
+    #     insufficient.
+    #
+    # @private
+    #
+    def get_or_create_tool(words, priority, assume_parent: false)
       if tool_defined?(words)
         tool, tool_priority = @tools[words]
         return tool if priority.nil? || tool_priority.nil? || tool_priority == priority
         return nil if tool_priority > priority
       end
       unless assume_parent
-        parent = get_tool(words[0..-2], priority)
+        parent = get_or_create_tool(words[0..-2], priority)
         return nil if parent.nil?
       end
-      tool = Tool.new(words, @middleware)
+      prune_from(words)
+      tool = Tool.new(words)
+      tool.middleware_stack.concat(@middleware)
       @tools[words] = [tool, priority]
       tool
     end
 
+    ##
+    # Adds a tool directly to the loader.
+    # This should be used only for testing, as it overrides normal priority
+    # checking.
+    #
+    # @param [Toys::Tool] tool Tool to add.
+    # @param [Integer,nil] priority Priority for the tool.
+    #
+    # @private
+    #
     def put_tool!(tool, priority = nil)
       @tools[tool.full_name] = [tool, priority]
       self
     end
 
+    ##
+    # Returns true if the given tool name currently exists in the loader.
+    # Does not load the tool if not found.
+    #
+    # @param [Array<String>] words The name of the tool.
+    # @return [Boolean]
+    #
+    # @private
+    #
     def tool_defined?(words)
       @tools.key?(words)
     end
 
-    def list_subtools(words, recursive)
-      found_tools = []
-      len = words.length
-      @tools.each do |n, tp|
-        next if n.empty?
-        if recursive
-          next if n.length <= len || n.slice(0, len) != words
-        else
-          next unless n.slice(0..-2) == words
-        end
-        found_tools << tp.first
-      end
-      sort_tools_by_name(found_tools)
-    end
-
+    ##
+    # Load configuration from the given path.
+    #
+    # @private
+    #
     def include_path(path, words, remaining_words, priority)
       handle_path(check_path(path), words, remaining_words, priority)
     end
 
+    ##
+    # Determine the next setting for remaining_words, given a word.
+    #
+    # @private
+    #
     def self.next_remaining_words(remaining_words, word)
       if remaining_words.nil?
         nil
@@ -185,6 +318,11 @@ module Toys
       end
     end
 
+    def prune_from(words)
+      return unless @tools.key?(words)
+      @tools.delete_if { |k, _v| k[0, words.size] == words }
+    end
+
     def load_for_prefix(prefix)
       cur_worklist = @load_worklist
       @load_worklist = []
@@ -203,9 +341,9 @@ module Toys
 
     def load_path(path, words, remaining_words, priority)
       if ::File.extname(path) == ".rb"
-        tool = get_tool(words, priority)
+        tool = get_or_create_tool(words, priority)
         if tool
-          Builder.build(path, tool, remaining_words, priority, self, ::IO.read(path), :tool)
+          ConfigDSL.evaluate(path, tool, remaining_words, priority, self, :tool, ::IO.read(path))
         end
       else
         require_preload_in(path)

data/lib/toys/middleware.rb

@@ -34,6 +34,20 @@ module Toys
   # Namespace for common middleware
   #
   module Middleware
+    ##
+    # Return a middleware class by name.
+    #
+    # Currently recognized middleware names are:
+    #
+    # *  `:group_default` : Provides a default implementation for a group.
+    # *  `:set_verbosity` : Switches for affecting log verbosity.
+    # *  `:show_tool_help` : A switch that causes a tool to print its usage
+    #    documentation.
+    # *  `:show_usage_errors` : Displays the usage error if one occurs.
+    #
+    # @param [String,Symbol] name Name of the middleware class to return
+    # @return [Class,nil] The class, or `nil` if not found
+    #
     def self.lookup(name)
       Utils::ModuleLookup.lookup(:middleware, name)
     end

data/lib/toys/middleware/base.rb

@@ -30,13 +30,19 @@
 module Toys
   module Middleware
     ##
-    # A base middleware with a no-op implementation
+    # 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

data/lib/toys/middleware/set_verbosity.rb

@@ -35,6 +35,9 @@ module Toys
     # A middleware that provides switches for editing the verbosity
     #
     class SetVerbosity < Base
+      ##
+      # This middleware adds `--verbose` and `--quiet` flags.
+      #
       def config(tool)
         tool.add_switch(Context::VERBOSITY, "-v", "--verbose",
                         doc: "Increase verbosity",

data/lib/toys/middleware/{group_default.rb → show_group_usage.rb}

@@ -33,23 +33,34 @@ require "toys/utils/usage"
 module Toys
   module Middleware
     ##
-    # A middleware that provides a default implementation for groups
+    # A middleware that provides a default implementation for groups. If a
+    # tool has no executor, this middleware assumes it to be a group, and it
+    # provides a default executor that displays group usage documentation.
     #
-    class GroupDefault < Base
+    class ShowGroupUsage < Base
+      ##
+      # This middleware adds a "--no-recursive" flag to groups. This flag, when
+      # set, shows only immediate subcommands rather than all recursively.
+      #
       def config(tool)
         if tool.includes_executor?
           yield
         else
-          tool.add_switch(:_recursive, "-r", "--[no-]recursive",
-                          doc: "Show all subcommands recursively")
+          tool.add_switch(:_no_recursive, "--no-recursive",
+                          doc: "Show immediate rather than all subcommands",
+                          only_unique: true)
         end
       end
 
+      ##
+      # This middleware displays the usage documentation for groups. It has
+      # no effect on tools that have their own executor.
+      #
       def execute(context)
         if context[Context::TOOL].includes_executor?
           yield
         else
-          puts(Utils::Usage.from_context(context).string(recursive: context[:_recursive]))
+          puts(Utils::Usage.from_context(context).string(recursive: !context[:_no_recursive]))
         end
       end
     end

data/lib/toys/middleware/{show_tool_help.rb → show_tool_usage.rb}

@@ -35,7 +35,10 @@ module Toys
     ##
     # A middleware that shows usage documentation
     #
-    class ShowToolHelp < Base
+    class ShowToolUsage < Base
+      ##
+      # This middleware adds a `--help` flag that triggers display of help.
+      #
       def config(tool)
         if tool.includes_executor?
           tool.add_switch(:_help, "-?", "--help",
@@ -45,6 +48,10 @@ module Toys
         yield
       end
 
+      ##
+      # If the `--help` flag is present, this middleware causes the tool to
+      # display its usage documentation and exit, rather than executing.
+      #
       def execute(context)
         if context[:_help]
           puts(Utils::Usage.from_context(context).string(recursive: context[:_recursive]))

data/lib/toys/middleware/show_usage_errors.rb

@@ -36,6 +36,12 @@ module Toys
     # A middleware that shows usage errors
     #
     class ShowUsageErrors < Base
+      ##
+      # If a usage error happens, e.g. an unrecognized switch or an unfulfilled
+      # required argument, this middleware causes the tool to display the error
+      # and usage documentation and exit with a nonzero result. Otherwise, it
+      # does nothing.
+      #
       def execute(context)
         if context[Context::USAGE_ERROR]
           puts(context[Context::USAGE_ERROR])

data/lib/toys/template.rb

@@ -31,7 +31,73 @@ module Toys
   ##
   # A template definition. Template classes should include this module.
   #
+  # A template is a configurable set of DSL code that can be run in a toys
+  # configuration to automate tool defintion. For example, toys provides a
+  # "minitest" template that generates a "test" tool that invokes minitest.
+  # Templates will often support configuration; for example the minitest
+  # template lets you configure the paths to the test files.
+  #
+  # ## Usage
+  #
+  # To create a template, define a class and include this module.
+  # The class defines the "configuration" of the template. If your template
+  # has options/parameters, you should provide a constructor, and methods
+  # appropriate to edit those options. The arguments given to the
+  # {Toys::ConfigDSL#expand} method are passed to your constructor, and your
+  # template object is passed to any block given to {Toys::ConfigDSL#expand}.
+  #
+  # Next, in your template class, call the `to_expand` method, which is defined
+  # in {Toys::Template::ClassMethods#to_expand}. Pass this a block which
+  # defines the implementation of the template. Effectively, the contents of
+  # this block are "inserted" into the user's configuration. The template
+  # object is passed to the block so you have access to the template options.
+  #
+  # ## Example
+  #
+  # This is a simple template that generates a "hello" tool. The tool simply
+  # prints a `"Hello, #{name}!"` greeting. The name is set as a template
+  # option; it is defined when the template is expanded in a toys
+  # configuration.
+  #
+  #     # Define a template by creating a class that includes Toys::Template.
+  #     class MyHelloTemplate
+  #       include Toys::Template
+  #
+  #       # A user of the template may pass an optional name as a parameter to
+  #       # `expand`, or leave it as the default of "world".
+  #       def initialize(name: "world")
+  #         @name = name
+  #       end
+  #
+  #       # The template is passed to the expand block, so a user of the
+  #       # template may also call this method to set the name.
+  #       attr_accessor :name
+  #
+  #       # The following block is inserted when the template is expanded.
+  #       to_expand do |template|
+  #         desc "Prints a greeting to #{template.name}"
+  #         tool "templated-greeting" do
+  #           execute do
+  #             puts "Hello, #{template.name}!"
+  #           end
+  #         end
+  #       end
+  #     end
+  #
+  # Now you can use the template in your `.toys.rb` file like this:
+  #
+  #     expand(MyHelloTemplate, name: "rubyists")
+  #
+  # or alternately:
+  #
+  #     expand(MyHelloTemplate) do |template|
+  #       template.name = "rubyists"
+  #     end
+  #
+  # And it will create a tool called "templated-greeting".
+  #
   module Template
+    ## @private
     def self.included(mod)
       mod.extend(ClassMethods)
     end
@@ -40,10 +106,17 @@ module Toys
     # Class methods that will be added to a template class.
     #
     module ClassMethods
+      ##
+      # Provide the block that implements the template.
+      #
       def to_expand(&block)
         @expander = block
       end
 
+      ##
+      # You may alternately set the expander block using this accessor.
+      # @return [Proc]
+      #
       attr_accessor :expander
     end
   end