toys-core 0.4.5 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e238ba243a2e72d0c04df73414040baf052dae6179f6f81030e5bf96b1bc06a
-  data.tar.gz: 4b711336fca9d960390e523741ddf800674e7657da1677a884679e28fbe9c6f1
+  metadata.gz: bd284ba44663511c6004cf0d742c4e1b5a703cbe596fd6612350be3b316ec60f
+  data.tar.gz: 9fdc655c88053d669727399c4c4c7321d4d2ececd579c9420bcddb1f0a40d65d
 SHA512:
-  metadata.gz: 470b8f9c78917c60db54df07c54f43a14b7626cf31f22ab7810756103af41482f34a66a92b09d82587e5ac09f3774f7446275a0f2f131fab5f4a7a0eec6903dc
-  data.tar.gz: 0eb481163a3476ad7fd94146f09ee0b8acc4a02b1a0aadd95d559100756e6793e913091588e35523073e41152b464a5dbb48aba37c86613a34a483afbb50cbe3
+  metadata.gz: ccdfadc2660d171d39776f63e708839edfaef4b63e21a2ddc39feb6456763a0d54fa27cc611cd2c9180210c291fb1f2510fa925b9f9ebea98f7e3794d42ca00e
+  data.tar.gz: e8d68670c340ac2a2b51a83a1201334ccbbda1a69464a25b9a376badfaf891895ffcc189ad54afbd1a2901b4673ded5fcb61296065ed205e98bfd05dbf4dc810

data/.yardopts

@@ -1,6 +1,7 @@
 --no-private
 --title=Toys Core
 --markup=markdown
+--markup-provider redcarpet
 --main=README.md
 ./lib/**/*.rb
 -

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 0.5.0 / 2018-10-07
+
+* FIXED: Template instantiation was failing if the hosting tool was priority-masked.
+* ADDED: Several additional characters can optionally be used as tool path delimiters.
+* ADDED: Support for preloaded files and directories
+* ADDED: Support for data directories
+* ADDED: Ability to display just the list of subtools of a tool
+* IMPROVED: The tool directive can now take an array as the tool name.
+* IMPROVED: The tool directive can now take an `if_defined` argument.
+
 ### 0.4.5 / 2018-08-05
 
 * CHANGED: Dropped preload file feature

data/lib/toys-core.rb

@@ -68,6 +68,7 @@ require "toys/core_version"
 require "toys/definition/acceptor"
 require "toys/definition/alias"
 require "toys/definition/arg"
+require "toys/definition/data_finder"
 require "toys/definition/flag"
 require "toys/definition/tool"
 require "toys/dsl/arg"

data/lib/toys/cli.rb

@@ -58,9 +58,25 @@ module Toys
     #     loaded first as a standalone configuration file. If not provided,
     #     standalone configuration files are disabled.
     #     The default toys CLI sets this to `".toys.rb"`.
+    # @param [String,nil] preload_file_name A file with this name that appears
+    #     in any configuration directory is preloaded before any tools in that
+    #     configuration directory are defined.
+    #     The default toys CLI sets this to `".preload.rb"`.
+    # @param [String,nil] preload_directory_name A directory with this name
+    #     that appears in any configuration directory is searched for Ruby
+    #     files, which are preloaded before any tools in that configuration
+    #     directory are defined.
+    #     The default toys CLI sets this to `".preload"`.
+    # @param [String,nil] data_directory_name A directory with this name that
+    #     appears in any configuration directory is added to the data directory
+    #     search path for any tool file in that directory.
+    #     The default toys CLI sets this to `".data"`.
     # @param [Array] middleware_stack An array of middleware that will be used
     #     by default for all tools loaded by this CLI. If not provided, uses
     #     {Toys::CLI.default_middleware_stack}.
+    # @param [String] extra_delimiters A string containing characters that can
+    #     function as delimiters in a tool name. Defaults to empty. Allowed
+    #     characters are period, colon, and slash.
     # @param [Toys::Utils::ModuleLookup] mixin_lookup A lookup for well-known
     #     mixin modules. If not provided, uses
     #     {Toys::CLI.default_mixin_lookup}.
@@ -81,23 +97,30 @@ module Toys
     #     Default is a {Toys::CLI::DefaultErrorHandler} writing to the logger.
     #
     def initialize(
-      binary_name: nil, middleware_stack: nil,
+      binary_name: nil, middleware_stack: nil, extra_delimiters: "",
       config_dir_name: nil, config_file_name: nil, index_file_name: nil,
+      preload_file_name: nil, preload_directory_name: nil, data_directory_name: nil,
       mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil,
       logger: nil, base_level: nil, error_handler: nil
     )
       @logger = logger || self.class.default_logger
       @base_level = base_level || @logger.level
       @middleware_stack = middleware_stack || self.class.default_middleware_stack
+      @extra_delimiters = extra_delimiters
       @binary_name = binary_name || ::File.basename($PROGRAM_NAME)
       @config_dir_name = config_dir_name
       @config_file_name = config_file_name
       @index_file_name = index_file_name
+      @preload_file_name = preload_file_name
+      @preload_directory_name = preload_directory_name
+      @data_directory_name = data_directory_name
       @mixin_lookup = mixin_lookup || self.class.default_mixin_lookup
       @middleware_lookup = middleware_lookup || self.class.default_middleware_lookup
       @template_lookup = template_lookup || self.class.default_template_lookup
       @loader = Loader.new(
-        index_file_name: index_file_name,
+        index_file_name: index_file_name, extra_delimiters: @extra_delimiters,
+        preload_directory_name: @preload_directory_name, preload_file_name: @preload_file_name,
+        data_directory_name: @data_directory_name,
         mixin_lookup: @mixin_lookup, template_lookup: @template_lookup,
         middleware_lookup: @middleware_lookup, middleware_stack: @middleware_stack
       )
@@ -251,7 +274,11 @@ module Toys
                     config_dir_name: @config_dir_name,
                     config_file_name: @config_file_name,
                     index_file_name: @index_file_name,
+                    preload_directory_name: @preload_directory_name,
+                    preload_file_name: @preload_file_name,
+                    data_directory_name: @data_directory_name,
                     middleware_stack: @middleware_stack,
+                    extra_delimiters: @extra_delimiters,
                     mixin_lookup: @mixin_lookup,
                     middleware_lookup: @middleware_lookup,
                     template_lookup: @template_lookup,

data/lib/toys/core_version.rb

@@ -34,5 +34,5 @@ module Toys
   # Current version of Toys core
   # @return [String]
   #
-  CORE_VERSION = "0.4.5"
+  CORE_VERSION = "0.5.0"
 end

data/lib/toys/definition/data_finder.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# 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 Definition
+    ##
+    # Finds data files.
+    #
+    class DataFinder
+      ##
+      # Create a new finder.
+      #
+      # @param [String,nil] data_name Name of the data directory, or nil if
+      #     data directories are disabled.
+      # @param [Toys::Definition::DataFinder,nil] parent The parent, or nil if
+      #     this is the root.
+      # @param [String,nil] directory The data directory, or nil for none.
+      # @private
+      #
+      def initialize(data_name, parent, directory)
+        @data_name = data_name
+        @parent = parent
+        @directory = directory
+      end
+
+      ##
+      # Create a new finder for the given directory.
+      #
+      # @param [String] directory Toys directory path
+      # @return [Toys::Definition::DataFinder] The finder
+      #
+      def finder_for(directory)
+        return self if @data_name.nil?
+        directory = ::File.join(directory, @data_name)
+        return self unless ::File.directory?(directory)
+        DataFinder.new(@data_name, self, directory)
+      end
+
+      ##
+      # Return the absolute path to the given data file or directory.
+      #
+      # @param [String] path The relative path to find
+      # @param [nil,:file,:directory] type Type of file system object to find,
+      #     or nil to return any type.
+      # @return [String,nil] Absolute path of the result, or nil if not found.
+      #
+      def find_data(path, type: nil)
+        return nil if @directory.nil?
+        full_path = ::File.join(@directory, path)
+        case type
+        when :file
+          return full_path if ::File.file?(full_path)
+        when :directory
+          return full_path if ::File.directory?(full_path)
+        else
+          return full_path if ::File.readable?(full_path)
+        end
+        @parent.find_data(path, type: type)
+      end
+
+      ##
+      # Create an empty finder.
+      #
+      # @param [String,nil] data_name Name of the data directory, or nil if
+      #     data directories are disabled.
+      # @return [Toys::Definition::DataFinder]
+      #
+      def self.create_empty(data_name)
+        new(data_name, nil, nil)
+      end
+
+      ##
+      # A default empty finder.
+      #
+      # @return [Toys::Definition::DataFinder]
+      #
+      EMPTY = create_empty(nil)
+    end
+  end
+end

data/lib/toys/definition/tool.rb

@@ -72,11 +72,27 @@ module Toys
       def initialize(loader, parent, full_name, priority, middleware_stack)
         @parent = parent
         @full_name = full_name.dup.freeze
-        @tool_class = DSL::Tool.new_class(@full_name, priority, loader)
         @priority = priority
         @middleware_stack = middleware_stack
 
+        @acceptors = {}
+        @mixins = {}
+        @templates = {}
+
+        reset_definition(loader)
+      end
+
+      ##
+      # Reset the definition of this tool, deleting all definition data but
+      # leaving named acceptors, mixins, and templates intact.
+      # Should be called only from the DSL.
+      # @private
+      #
+      def reset_definition(loader)
+        @tool_class = DSL::Tool.new_class(@full_name, @priority, loader)
+
         @source_path = nil
+        @data_finder = nil
         @definition_finished = false
 
         @desc = Utils::WrappableString.new("")
@@ -86,17 +102,13 @@ module Toys
         @used_flags = []
         @initializers = []
 
-        @acceptors = {}
-        @mixins = {}
-        @templates = {}
-
         @flag_definitions = []
         @required_arg_definitions = []
         @optional_arg_definitions = []
         @remaining_args_definition = nil
 
         @disable_argument_parsing = false
-        @runnable = false
+        @includes_modules = false
       end
 
       ##
@@ -209,7 +221,15 @@ module Toys
       # @return [Boolean]
       #
       def runnable?
-        @runnable
+        tool_class.public_instance_methods(false).include?(:run)
+      end
+
+      ##
+      # Returns true if this tool has at least one included module.
+      # @return [Boolean]
+      #
+      def includes_modules?
+        @includes_modules
       end
 
       ##
@@ -236,7 +256,8 @@ module Toys
       # @return [Boolean]
       #
       def includes_definition?
-        includes_arguments? || runnable?
+        includes_arguments? || runnable? || argument_parsing_disabled? ||
+          includes_modules? || includes_description?
       end
 
       ##
@@ -346,14 +367,16 @@ module Toys
       # already set, raises {Toys::ToolDefinitionError}
       #
       # @param [String] path The path to the file defining this tool
+      # @param [Toys::Definition::DataFinder] data_finder Data finder
       #
-      def lock_source_path(path)
+      def lock_source_path(path, data_finder)
         if source_path && source_path != path
           raise ToolDefinitionError,
                 "Cannot redefine tool #{display_name.inspect} in #{path}" \
                 " (already defined in #{source_path})"
         end
         @source_path = path
+        @data_finder = data_finder
       end
 
       ##
@@ -648,12 +671,24 @@ module Toys
       end
 
       ##
-      # Mark this tool as runnable. Should be called from the DSL only.
+      # Find the given data file or directory in this tool's search path.
+      #
+      # @param [String] path The path to find
+      # @param [nil,:file,:directory] type Type of file system object to find,
+      #     or nil to return any type.
+      # @return [String,nil] Absolute path of the result, or nil if not found.
+      #
+      def find_data(path, type: nil)
+        @data_finder ? @data_finder.find_data(path, type: type) : nil
+      end
+
+      ##
+      # Mark this tool as having at least one module included
       # @private
       #
-      def mark_runnable
+      def mark_includes_modules
         check_definition_state
-        @runnable = true
+        @includes_modules = true
         self
       end
 
@@ -687,12 +722,11 @@ module Toys
         end
       end
 
-      private
-
-      def make_config_proc(middleware, loader, next_config)
-        proc { middleware.config(self, loader, &next_config) }
-      end
-
+      ##
+      # Check that the tool can still be defined. Should be called internally
+      # or from the DSL only.
+      # @private
+      #
       def check_definition_state(is_arg: false)
         if @definition_finished
           raise ToolDefinitionError,
@@ -704,6 +738,12 @@ module Toys
         end
         self
       end
+
+      private
+
+      def make_config_proc(middleware, loader, next_config)
+        proc { middleware.config(self, loader, &next_config) }
+      end
     end
   end
 end

data/lib/toys/dsl/tool.rb

@@ -64,9 +64,8 @@ module Toys
     #
     module Tool
       ## @private
-      def method_added(meth)
-        cur_tool = DSL::Tool.current_tool(self, true)
-        cur_tool.mark_runnable if cur_tool && meth == :run
+      def method_added(_meth)
+        DSL::Tool.current_tool(self, true)&.check_definition_state
       end
 
       ##
@@ -177,18 +176,34 @@ module Toys
       ##
       # Create a subtool. You must provide a block defining the subtool.
       #
-      # If the subtool is already defined (either as a tool or a namespace), the
-      # old definition is discarded and replaced with the new definition.
-      #
-      # @param [String] word The name of the subtool
+      # @param [String,Array<String>] words The name of the subtool
+      # @param [:combine,:reset,:ignore] if_defined What to do if a definition
+      #     already exists for this tool. Possible values are `:combine` (the
+      #     default) indicating the definition should be combined with the
+      #     existing definition, `:reset` indicating the earlier definition
+      #     should be reset and the new definition applied instead, or
+      #     `:ignore` indicating the new definition should be ignored.
       # @return [Toys::DSL::Tool] self, for chaining.
       #
-      def tool(word, &block)
-        word = word.to_s
-        subtool_words = @__words + [word]
-        next_remaining = Loader.next_remaining_words(@__remaining_words, word)
-        subtool_class = @__loader.get_tool_definition(subtool_words, @__priority).tool_class
-        DSL::Tool.prepare(subtool_class, next_remaining, @__path) do
+      def tool(words, if_defined: :combine, &block)
+        subtool_words = @__words
+        next_remaining = @__remaining_words
+        Array(words).each do |word|
+          word = word.to_s
+          subtool_words += [word]
+          next_remaining = Loader.next_remaining_words(next_remaining, word)
+        end
+        subtool = @__loader.get_tool_definition(subtool_words, @__priority)
+        if subtool.includes_definition?
+          case if_defined
+          when :ignore
+            return self
+          when :reset
+            subtool.reset_definition(@__loader)
+          end
+        end
+        subtool_class = subtool.tool_class
+        DSL::Tool.prepare(subtool_class, next_remaining, @__path, @__data_finder) do
           subtool_class.class_eval(&block)
         end
         self
@@ -231,8 +246,7 @@ module Toys
       # @return [Toys::DSL::Tool] self, for chaining.
       #
       def expand(template_class, *args)
-        cur_tool = DSL::Tool.current_tool(self, true)
-        return self if cur_tool.nil?
+        cur_tool = DSL::Tool.current_tool(self, false)
         name = template_class.to_s
         if template_class.is_a?(::String)
           template_class = cur_tool.resolve_template(template_class)
@@ -607,11 +621,14 @@ module Toys
         if included_modules.include?(mod)
           raise ToolDefinitionError, "Mixin already included: #{mod.name}"
         end
-        if mod.respond_to?(:initialization_callback) && mod.initialization_callback
-          cur_tool.add_initializer(mod.initialization_callback, *args)
+        cur_tool.mark_includes_modules
+        if mod.respond_to?(:initialization_callback)
+          callback = mod.initialization_callback
+          cur_tool.add_initializer(callback, *args) if callback
         end
-        if mod.respond_to?(:inclusion_callback) && mod.inclusion_callback
-          class_exec(*args, &mod.inclusion_callback)
+        if mod.respond_to?(:inclusion_callback)
+          callback = mod.inclusion_callback
+          class_exec(*args, &callback) if callback
         end
         super(mod)
       end
@@ -633,6 +650,18 @@ module Toys
         super(DSL::Tool.resolve_mixin(mod, cur_tool, @__loader))
       end
 
+      ##
+      # Find the given data path (file or directory)
+      #
+      # @param [String] path The path to find
+      # @param [nil,:file,:directory] type Type of file system object to find,
+      #     or nil to return any type.
+      # @return [String,nil] Absolute path of the result, or nil if not found.
+      #
+      def find_data(path, type: nil)
+        @__data_finder ? @__data_finder.find_data(path, type: type) : nil
+      end
+
       ## @private
       def self.new_class(words, priority, loader)
         tool_class = ::Class.new(::Toys::Tool)
@@ -642,13 +671,13 @@ module Toys
         tool_class.instance_variable_set(:@__loader, loader)
         tool_class.instance_variable_set(:@__remaining_words, nil)
         tool_class.instance_variable_set(:@__path, nil)
+        tool_class.instance_variable_set(:@__data_finder, nil)
         tool_class
       end
 
       ## @private
       def self.current_tool(tool_class, activate)
         memoize_var = activate ? :@__active_tool : :@__cur_tool
-        path = tool_class.instance_variable_get(:@__path)
         if tool_class.instance_variable_defined?(memoize_var)
           cur_tool = tool_class.instance_variable_get(memoize_var)
         else
@@ -667,18 +696,24 @@ module Toys
           end
           tool_class.instance_variable_set(memoize_var, cur_tool)
         end
-        cur_tool.lock_source_path(path) if cur_tool && activate
+        if cur_tool && activate
+          path = tool_class.instance_variable_get(:@__path)
+          data_finder = tool_class.instance_variable_get(:@__data_finder)
+          cur_tool.lock_source_path(path, data_finder)
+        end
         cur_tool
       end
 
       ## @private
-      def self.prepare(tool_class, remaining_words, path)
+      def self.prepare(tool_class, remaining_words, path, data_finder)
         tool_class.instance_variable_set(:@__remaining_words, remaining_words)
         tool_class.instance_variable_set(:@__path, path)
+        tool_class.instance_variable_set(:@__data_finder, data_finder)
         yield
       ensure
         tool_class.instance_variable_set(:@__remaining_words, nil)
         tool_class.instance_variable_set(:@__path, nil)
+        tool_class.instance_variable_set(:@__data_finder, nil)
       end
 
       ## @private

data/lib/toys/input_file.rb

@@ -40,7 +40,7 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
   end
 
   ## @private
-  def self.evaluate(tool_class, remaining_words, path)
+  def self.evaluate(tool_class, remaining_words, path, data_finder)
     namespace = ::Module.new
     namespace.module_eval do
       include ::Toys::Tool::Keys
@@ -51,7 +51,7 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
     str = build_eval_string(name, ::IO.read(path))
     if str
       const_set(name, namespace)
-      ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path) do
+      ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path, data_finder) do
         ::Toys::ContextualError.capture_path("Error while loading Toys config!", path) do
           # rubocop:disable Security/Eval
           eval(str, __binding, path, 0)

data/lib/toys/loader.rb

@@ -34,6 +34,8 @@ module Toys
   # The Loader service loads tools from configuration files, and finds the
   # appropriate tool given a set of command line arguments.
   #
+  # This class is not thread-safe.
+  #
   class Loader
     ## @private
     ToolData = ::Struct.new(:definitions, :top_priority, :active_priority) do
@@ -53,8 +55,21 @@ module Toys
     #     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 is preloaded before any tools in that
+    #     configuration directory are defined.
+    # @param [String,nil] preload_directory_name A directory with this name
+    #     that appears in any configuration directory is searched for Ruby
+    #     files, which are preloaded before any tools in that configuration
+    #     directory are defined.
+    # @param [String,nil] data_directory_name A directory with this name that
+    #     appears in any configuration directory is added to the data directory
+    #     search path for any tool file in that directory.
     # @param [Array] middleware_stack An array of middleware that will be used
     #     by default for all tools loaded by this loader.
+    # @param [String] extra_delimiters A string containing characters that can
+    #     function as delimiters in a tool name. Defaults to empty. Allowed
+    #     characters are period, colon, and slash.
     # @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
@@ -62,7 +77,8 @@ module Toys
     # @param [Toys::Utils::ModuleLookup] template_lookup A lookup for
     #     well-known template classes. Defaults to an empty lookup.
     #
-    def initialize(index_file_name: nil, middleware_stack: [],
+    def initialize(index_file_name: nil, preload_directory_name: nil, preload_file_name: nil,
+                   data_directory_name: nil, middleware_stack: [], extra_delimiters: "",
                    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}"
@@ -71,10 +87,14 @@ module Toys
       @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
+      @preload_directory_name = preload_directory_name
+      @empty_data_finder = Definition::DataFinder.create_empty(data_directory_name)
       @middleware_stack = middleware_stack
       @worklist = []
       @tool_data = {}
       @max_priority = @min_priority = 0
+      @extra_delimiters = process_extra_delimiters(extra_delimiters)
       get_tool_definition([], -999_999)
     end
 
@@ -90,7 +110,7 @@ module Toys
       paths = Array(path)
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
       paths.each do |p|
-        @worklist << [:file, check_path(p), [], priority]
+        @worklist << [:file, check_path(p), [], @empty_data_finder, priority]
       end
       self
     end
@@ -108,7 +128,7 @@ module Toys
     def add_block(high_priority: false, path: nil, &block)
       path ||= "(Block #{block.object_id})"
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-      @worklist << [block, path, [], priority]
+      @worklist << [block, path, [], @empty_data_finder, priority]
       self
     end
 
@@ -123,23 +143,23 @@ module Toys
     # Returns a tuple of the found tool, and the array of remaining arguments
     # that are not part of the tool name and should be passed as tool args.
     #
-    # @param [String] args Command line arguments
+    # @param [Array<String>] args Command line arguments
     # @return [Array(Toys::Definition::Tool,Array<String>)]
     #
     def lookup(args)
-      orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
+      orig_prefix, args = find_orig_prefix(args)
       cur_prefix = orig_prefix
       loop do
         load_for_prefix(cur_prefix)
-        p = orig_prefix
+        prefix = orig_prefix
         loop do
-          tool_definition = get_active_tool(p, [])
+          tool_definition = get_active_tool(prefix, [])
           if tool_definition
             finish_definitions_in_tree(tool_definition.full_name)
-            return [tool_definition, args.slice(p.length..-1)]
+            return [tool_definition, args.slice(prefix.length..-1)]
           end
-          break if p.empty? || p.length <= cur_prefix.length
-          p = p.slice(0..-2)
+          break if prefix.empty? || prefix.length <= cur_prefix.length
+          prefix = prefix.slice(0..-2)
         end
         raise "Unexpected error" if cur_prefix.empty?
         cur_prefix = cur_prefix.slice(0..-2)
@@ -189,13 +209,16 @@ module Toys
     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.
+    # Returns the active tool specified by the given words, with the given
+    # priority, without doing any loading. If the given priority matches the
+    # currently active tool, returns it. If the given priority is lower than
+    # the active priority, returns `nil`. If the given priority is higher than
+    # the active priority, returns and activates a new tool.
     #
     # @param [Array<String>] words The name of the tool.
     # @param [Integer] priority The priority of the request.
     # @return [Toys::Definition::Tool,Toys::Definition::Alias,nil] The tool or
-    #     alias, or `nil` if the given priority is insufficient
+    #     alias, or `nil` if the given priority is insufficient.
     #
     # @private
     #
@@ -259,9 +282,10 @@ 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] ||=
+      tool_data.definitions[priority] ||= begin
+        middlewares = @middleware_stack.map { |m| resolve_middleware(m) }
         Definition::Tool.new(self, parent, words, priority, middlewares)
+      end
     end
 
     ##
@@ -290,7 +314,7 @@ module Toys
     # @private
     #
     def load_path(path, words, remaining_words, priority)
-      load_validated_path(check_path(path), words, remaining_words, priority)
+      load_validated_path(check_path(path), words, remaining_words, @empty_data_finder, priority)
     end
 
     ##
@@ -301,13 +325,13 @@ module Toys
     def load_proc(proc, words, remaining_words, priority, path)
       if remaining_words
         tool_class = get_tool_definition(words, priority).tool_class
-        ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path) do
+        ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path, @empty_data_finder) do
           ::Toys::ContextualError.capture("Error while loading Toys config!") do
             tool_class.class_eval(&proc)
           end
         end
       else
-        @worklist << [proc, path, words, priority]
+        @worklist << [proc, path, words, @empty_data_finder, priority]
       end
     end
 
@@ -328,6 +352,28 @@ module Toys
 
     private
 
+    ALLOWED_DELIMITERS = %r{^[\./:]*$}
+
+    def process_extra_delimiters(input)
+      unless ALLOWED_DELIMITERS =~ input
+        raise ::ArgumentError, "Illegal delimiters in #{input.inspect}"
+      end
+      chars = ::Regexp.escape(input.chars.uniq.join)
+      chars.empty? ? nil : ::Regexp.new("[#{chars}]")
+    end
+
+    def find_orig_prefix(args)
+      if @extra_delimiters
+        first_split = (args.first || "").split(@extra_delimiters)
+        if first_split.size > 1
+          args = first_split + args.slice(1..-1)
+          return [first_split, args]
+        end
+      end
+      orig_prefix = args.take_while { |arg| !arg.start_with?("-") }
+      [orig_prefix, args]
+    end
+
     def get_tool_data(words)
       @tool_data[words] ||= ToolData.new({}, nil, nil)
     end
@@ -395,51 +441,73 @@ module Toys
     def load_for_prefix(prefix)
       cur_worklist = @worklist
       @worklist = []
-      cur_worklist.each do |source, path, words, priority|
+      cur_worklist.each do |source, path, words, data_finder, priority|
         remaining_words = calc_remaining_words(prefix, words)
         if source.respond_to?(:call)
           load_proc(source, words, remaining_words, priority, path)
         elsif source == :file
-          load_validated_path(path, words, remaining_words, priority)
+          load_validated_path(path, words, remaining_words, data_finder, priority)
         end
       end
     end
 
-    def load_validated_path(path, words, remaining_words, priority)
+    def load_validated_path(path, words, remaining_words, data_finder, priority)
       if remaining_words
-        load_relevant_path(path, words, remaining_words, priority)
+        load_relevant_path(path, words, remaining_words, data_finder, priority)
       else
-        @worklist << [:file, path, words, priority]
+        @worklist << [:file, path, words, data_finder, priority]
       end
     end
 
-    def load_relevant_path(path, words, remaining_words, priority)
+    def load_relevant_path(path, words, remaining_words, data_finder, priority)
       if ::File.extname(path) == ".rb"
         tool_class = get_tool_definition(words, priority).tool_class
-        Toys::InputFile.evaluate(tool_class, remaining_words, path)
+        InputFile.evaluate(tool_class, remaining_words, path, data_finder)
       else
-        load_index_in(path, words, remaining_words, priority)
+        do_preload(path)
+        data_finder = data_finder.finder_for(path)
+        load_index_in(path, words, remaining_words, data_finder, priority)
         ::Dir.entries(path).each do |child|
-          load_child_in(path, child, words, remaining_words, priority)
+          load_child_in(path, child, words, remaining_words, data_finder, priority)
         end
       end
     end
 
-    def load_index_in(path, words, remaining_words, priority)
+    def load_index_in(path, words, remaining_words, data_finder, priority)
       return unless @index_file_name
       index_path = ::File.join(path, @index_file_name)
       index_path = check_path(index_path, type: :file, lenient: true)
-      load_relevant_path(index_path, words, remaining_words, priority) if index_path
+      load_relevant_path(index_path, words, remaining_words, data_finder, priority) if index_path
     end
 
-    def load_child_in(path, child, words, remaining_words, priority)
+    def load_child_in(path, child, words, remaining_words, data_finder, priority)
       return if child.start_with?(".")
       return if child == @index_file_name
       child_path = check_path(::File.join(path, child))
       child_word = ::File.basename(child, ".rb")
       next_words = words + [child_word]
       next_remaining = Loader.next_remaining_words(remaining_words, child_word)
-      load_validated_path(child_path, next_words, next_remaining, priority)
+      load_validated_path(child_path, next_words, next_remaining, data_finder, priority)
+    end
+
+    def do_preload(path)
+      if @preload_file_name
+        preload_file = ::File.join(path, @preload_file_name)
+        if !::File.directory?(preload_file) && ::File.readable?(preload_file)
+          require preload_file
+        end
+      end
+      if @preload_directory_name
+        preload_dir = ::File.join(path, @preload_directory_name)
+        if ::File.directory?(preload_dir) && ::File.readable?(preload_dir)
+          ::Dir.entries(preload_dir).each do |child|
+            preload_file = ::File.join(preload_dir, child)
+            if !::File.directory?(preload_file) && ::File.readable?(preload_file)
+              require preload_file
+            end
+          end
+        end
+      end
     end
 
     def check_path(path, lenient: false, type: nil)

data/lib/toys/standard_middleware/show_help.rb

@@ -56,6 +56,12 @@ module Toys
       #
       DEFAULT_USAGE_FLAGS = ["--usage"].freeze
 
+      ##
+      # Default list subtools flags
+      # @return [Array<String>]
+      #
+      DEFAULT_LIST_FLAGS = ["--tools"].freeze
+
       ##
       # Default recursive flags
       # @return [Array<String>]
@@ -80,6 +86,12 @@ module Toys
       #
       SHOW_USAGE_KEY = Object.new.freeze
 
+      ##
+      # Key set when the show subtool list flag is present
+      # @return [Object]
+      #
+      SHOW_LIST_KEY = Object.new.freeze
+
       ##
       # Key for the recursive setting
       # @return [Object]
@@ -117,6 +129,14 @@ module Toys
       #     *  The `false` value for no flags. (Default)
       #     *  A proc that takes a tool and returns any of the above.
       #
+      # @param [Boolean,Array<String>,Proc] list_flags Specify flags to
+      #     display subtool list. The value may be any of the following:
+      #
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_LIST_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:
@@ -156,6 +176,7 @@ module Toys
       #
       def initialize(help_flags: false,
                      usage_flags: false,
+                     list_flags: false,
                      recursive_flags: false,
                      search_flags: false,
                      default_recursive: false,
@@ -167,6 +188,7 @@ module Toys
                      styled_output: nil)
         @help_flags = help_flags
         @usage_flags = usage_flags
+        @list_flags = list_flags
         @recursive_flags = recursive_flags
         @search_flags = search_flags
         @default_recursive = default_recursive ? true : false
@@ -183,20 +205,17 @@ module Toys
       #
       def config(tool_definition, loader)
         unless tool_definition.argument_parsing_disabled?
+          has_subtools = loader.has_subtools?(tool_definition.full_name)
           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_definition.root? && tool_definition.arg_definitions.empty?
-              tool_definition.set_remaining_args(TOOL_NAME_KEY,
-                                                 display_name: "TOOL_NAME",
-                                                 desc: "The tool for which to display help")
-            end
-          end
-          if (!help_flags.empty? || @fallback_execution) &&
-             loader.has_subtools?(tool_definition.full_name)
+          list_flags = has_subtools ? add_list_flags(tool_definition) : []
+          if (!help_flags.empty? || !list_flags.empty? || @fallback_execution) && has_subtools
             add_recursive_flags(tool_definition)
             add_search_flags(tool_definition)
           end
+          if !help_flags.empty? || !usage_flags.empty? || !list_flags.empty?
+            add_root_args(tool_definition)
+          end
         end
         yield
       end
@@ -206,17 +225,16 @@ module Toys
       #
       def run(tool)
         if tool[SHOW_USAGE_KEY]
-          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_KEY]
-          help_text = get_help_text(tool)
-          str = help_text.help_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
-                                      search: tool[SEARCH_STRING_KEY],
-                                      show_source_path: @show_source_path,
-                                      wrap_width: terminal.width)
-          output_help(str)
+          terminal.puts(get_help_text(tool).usage_string(wrap_width: terminal.width))
+        elsif tool[SHOW_LIST_KEY]
+          terminal.puts(get_help_text(tool).list_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
+                                                        search: tool[SEARCH_STRING_KEY],
+                                                        wrap_width: terminal.width))
+        elsif should_show_help(tool)
+          output_help(get_help_text(tool).help_string(recursive: tool[RECURSIVE_SUBTOOLS_KEY],
+                                                      search: tool[SEARCH_STRING_KEY],
+                                                      show_source_path: @show_source_path,
+                                                      wrap_width: terminal.width))
         else
           yield
         end
@@ -228,6 +246,11 @@ module Toys
         @terminal ||= Utils::Terminal.new(output: @stream, styled: @styled_output)
       end
 
+      def should_show_help(tool)
+        @fallback_execution && !tool[Tool::Keys::TOOL_DEFINITION].runnable? ||
+          tool[SHOW_HELP_KEY]
+      end
+
       def output_help(str)
         if less_path
           Utils::Exec.new.exec([less_path, "-R"], in: [:string, str])
@@ -288,6 +311,18 @@ module Toys
         usage_flags
       end
 
+      def add_list_flags(tool_definition)
+        list_flags = resolve_flags_spec(@list_flags, tool_definition, DEFAULT_LIST_FLAGS)
+        unless list_flags.empty?
+          tool_definition.add_flag(
+            SHOW_LIST_KEY, list_flags,
+            report_collisions: false,
+            desc: "List the subtools under this tool"
+          )
+        end
+        list_flags
+      end
+
       def add_recursive_flags(tool_definition)
         recursive_flags = resolve_flags_spec(@recursive_flags, tool_definition,
                                              DEFAULT_RECURSIVE_FLAGS)
@@ -297,7 +332,8 @@ module Toys
           tool_definition.add_flag(
             RECURSIVE_SUBTOOLS_KEY, recursive_flags,
             report_collisions: false, default: @default_recursive,
-            desc: "Show all subtools recursively (default is #{@default_recursive})"
+            desc: "List all subtools recursively when displaying help" \
+                  " (default is #{@default_recursive})"
           )
         end
         recursive_flags
@@ -309,12 +345,20 @@ module Toys
           tool_definition.add_flag(
             SEARCH_STRING_KEY, search_flags,
             report_collisions: false,
-            desc: "Search subtools for the given regular expression"
+            desc: "Search subtools for the given regular expression when displaying help"
           )
         end
         search_flags
       end
 
+      def add_root_args(tool_definition)
+        if @allow_root_args && tool_definition.root? && tool_definition.arg_definitions.empty?
+          tool_definition.set_remaining_args(TOOL_NAME_KEY,
+                                             display_name: "TOOL_NAME",
+                                             desc: "The tool for which to display help")
+        end
+      end
+
       def resolve_flags_spec(flags, tool_definition, defaults)
         flags = flags.call(tool_definition) if flags.respond_to?(:call)
         case flags

data/lib/toys/tool.rb

@@ -259,6 +259,18 @@ module Toys
       end
     end
 
+    ##
+    # Find the given data file or directory in this tool's search path.
+    #
+    # @param [String] path The path to find
+    # @param [nil,:file,:directory] type Type of file system object to find,
+    #     or nil to return any type.
+    # @return [String,nil] Absolute path of the result, or nil if not found.
+    #
+    def find_data(path, type: nil)
+      @__data[Keys::TOOL_DEFINITION].find_data(path, type: type)
+    end
+
     ##
     # Exit immediately with the given status code
     #

data/lib/toys/utils/help_text.rb

@@ -129,6 +129,29 @@ module Toys
         assembler.result
       end
 
+      ##
+      # Generate a subtool list string.
+      #
+      # @param [Boolean] recursive If true, and the tool is a namespace,
+      #     display all subcommands recursively. Defaults to false.
+      # @param [String,nil] search An optional string to search for when
+      #     listing subcommands. Defaults to `nil` which finds all subcommands.
+      # @param [Integer] indent Indent width. Default is {DEFAULT_INDENT}.
+      # @param [Integer,nil] wrap_width Wrap width of the column, or `nil` to
+      #     disable wrap. Default is `nil`.
+      # @param [Boolean] styled Output ansi styles. Default is `true`.
+      #
+      # @return [String] A usage string.
+      #
+      def list_string(recursive: false, search: nil,
+                      indent: nil, wrap_width: nil, styled: true)
+        indent ||= DEFAULT_INDENT
+        subtools = find_subtools(recursive, search)
+        assembler = ListStringAssembler.new(@tool, subtools, recursive, search,
+                                            indent, wrap_width, styled)
+        assembler.result
+      end
+
       private
 
       def find_subtools(recursive, search)
@@ -493,6 +516,86 @@ module Toys
           "#{' ' * (@indent + @indent2)}#{str}"
         end
       end
+
+      ## @private
+      class ListStringAssembler
+        def initialize(tool, subtools, recursive, search_term, indent, wrap_width, styled)
+          @tool = tool
+          @subtools = subtools
+          @recursive = recursive
+          @search_term = search_term
+          @indent = indent
+          @wrap_width = wrap_width
+          assemble(styled)
+        end
+
+        attr_reader :result
+
+        private
+
+        def assemble(styled)
+          @lines = Utils::Terminal.new(output: ::StringIO.new, styled: styled)
+          add_header
+          add_list
+          @result = @lines.output.string
+        end
+
+        def add_header
+          top_line = @recursive ? "Recursive list of tools" : "List of tools"
+          @lines <<
+            if @tool.root?
+              "#{top_line}:"
+            else
+              "#{top_line} under #{bold(@tool.display_name)}:"
+            end
+          @lines << ""
+          if @search_term
+            @lines << "Showing search results for \"#{@search_term}\""
+            @lines << ""
+          end
+        end
+
+        def add_list
+          name_len = @tool.full_name.length
+          @subtools.each do |subtool|
+            tool_name = subtool.full_name.slice(name_len..-1).join(" ")
+            desc =
+              if subtool.is_a?(Definition::Alias)
+                "(Alias of #{subtool.display_target})"
+              else
+                subtool.desc
+              end
+            add_prefix_with_desc(bold(tool_name), desc)
+          end
+        end
+
+        def add_prefix_with_desc(prefix, desc)
+          if desc.empty?
+            @lines << prefix
+          elsif !desc.is_a?(Utils::WrappableString)
+            @lines << "#{prefix} - #{desc}"
+          else
+            desc = wrap_indent(Utils::WrappableString.new(["#{prefix} -"] + desc.fragments))
+            @lines << desc[0]
+            desc[1..-1].each do |line|
+              @lines << indent_str(line)
+            end
+          end
+        end
+
+        def wrap_indent(input)
+          return Utils::WrappableString.wrap_lines(input, nil) unless @wrap_width
+          Utils::WrappableString.wrap_lines(input, @wrap_width, @wrap_width - @indent)
+        end
+
+        def bold(str)
+          @lines.apply_styles(str, :bold)
+        end
+
+        def indent_str(str)
+          "#{' ' * @indent}#{str}"
+        end
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.4.5
+  version: 0.5.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-06 00:00:00.000000000 Z
+date: 2018-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -66,34 +66,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.58.2
+        version: 0.59.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.58.2
+        version: 0.59.1
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 0.9.16
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.14
+        version: 0.9.16
 description: Toys-Core is the command line tool framework underlying Toys. It can
   be used to create command line binaries using the internal Toys APIs.
 email:
@@ -113,6 +127,7 @@ files:
 - lib/toys/definition/acceptor.rb
 - lib/toys/definition/alias.rb
 - lib/toys/definition/arg.rb
+- lib/toys/definition/data_finder.rb
 - lib/toys/definition/flag.rb
 - lib/toys/definition/tool.rb
 - lib/toys/dsl/arg.rb
@@ -145,7 +160,11 @@ files:
 homepage: https://github.com/dazuma/toys
 licenses:
 - BSD-3-Clause
-metadata: {}
+metadata:
+  changelog_uri: https://github.com/dazuma/toys/blob/master/toys-core/CHANGELOG.md
+  source_code_uri: https://github.com/dazuma/toys
+  bug_tracker_uri: https://github.com/dazuma/toys/issues
+  documentation_uri: https://www.rubydoc.info/gems/toys-core
 post_install_message: 
 rdoc_options: []
 require_paths: