toys-core 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd284ba44663511c6004cf0d742c4e1b5a703cbe596fd6612350be3b316ec60f
-  data.tar.gz: 9fdc655c88053d669727399c4c4c7321d4d2ececd579c9420bcddb1f0a40d65d
+  metadata.gz: 0202fa141dcee7d96aacdec2092ace8041f5498e367596d8e2a5aa893fa64d36
+  data.tar.gz: 20ea445f7ad7a5ab964ad23434e57f4acb6ee567e6dc38837751246d32940ca5
 SHA512:
-  metadata.gz: ccdfadc2660d171d39776f63e708839edfaef4b63e21a2ddc39feb6456763a0d54fa27cc611cd2c9180210c291fb1f2510fa925b9f9ebea98f7e3794d42ca00e
-  data.tar.gz: e8d68670c340ac2a2b51a83a1201334ccbbda1a69464a25b9a376badfaf891895ffcc189ad54afbd1a2901b4673ded5fcb61296065ed205e98bfd05dbf4dc810
+  metadata.gz: 704d70fc544435c23cf3d0e88550fa3a3951bbb9b3611eabdc89c3c9871d3ad67098cce21fa54ffb130aa4da6d0901729471b9e698ae78a394f8ff750392205f
+  data.tar.gz: 57d9cacc5646fd39e0399bb2729d0a936d70f5d67a1f7a7e3d4b19a5d38ab699dc6b0e5044ae455fea3cdb0d46e44406bfc898074e71e2d9b3cc7882981886d7

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 0.6.0 / 2018-10-22
+
+* CHANGED: Replaced Toys::Definition::DataFinder with Toys::Definition::SourceInfo.
+* CHANGED: Removed Toys::Definition#find_data. Use Toys::Definition#source_info and call find_data.
+* ADDED: Context directory is kept in SourceInfo and available in the DSL and the tool runtime.
+* IMPROVED: Optionally omit hidden subtools (i.e. names beginning with underscore)
+  from subtool lists.
+* IMPROVED: Optionally omit non-runnable namespaces from recursive subtool lists.
+
 ### 0.5.0 / 2018-10-07
 
 * FIXED: Template instantiation was failing if the hosting tool was priority-masked.

data/lib/toys-core.rb

@@ -68,8 +68,8 @@ 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/source_info"
 require "toys/definition/tool"
 require "toys/dsl/arg"
 require "toys/dsl/flag"

data/lib/toys/cli.rb

@@ -173,12 +173,12 @@ module Toys
     #
     # @param [Boolean] high_priority Add the config at the head of the priority
     #     list rather than the tail.
-    # @param [String] path The "path" that will be shown in documentation for
-    #     tools defined in this block. If omitted, a default unique string will
-    #     be generated.
+    # @param [String] name The source name that will be shown in documentation
+    #     for tools defined in this block. If omitted, a default unique string
+    #     will be generated.
     #
-    def add_config_block(high_priority: false, path: nil, &block)
-      @loader.add_block(high_priority: high_priority, path: path, &block)
+    def add_config_block(high_priority: false, name: nil, &block)
+      @loader.add_block(high_priority: high_priority, name: name, &block)
       self
     end
 
@@ -251,7 +251,7 @@ module Toys
         @loader.lookup(args.flatten)
       end
       ContextualError.capture_path(
-        "Error during tool execution!", tool_definition.source_path,
+        "Error during tool execution!", tool_definition.source_info&.source_path,
         tool_name: tool_definition.full_name, tool_args: remaining
       ) do
         Runner.new(self, tool_definition).run(remaining, verbosity: verbosity)

data/lib/toys/core_version.rb

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

data/lib/toys/definition/source_info.rb

@@ -0,0 +1,190 @@
+# 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
+    ##
+    # Information about source toys directories and files.
+    #
+    class SourceInfo
+      ##
+      # Create a SourceInfo.
+      # @private
+      #
+      def initialize(parent, context_directory, source, source_type, source_name, data_dir_name)
+        @parent = parent
+        @context_directory = context_directory
+        @source = source
+        @source_type = source_type
+        @source_path = source if source.is_a?(::String)
+        @source_proc = source if source.is_a?(::Proc)
+        @source_name = source_name
+        @data_dir =
+          if data_dir_name && @source_path
+            dir = ::File.join(::File.dirname(@source_path), data_dir_name)
+            dir if ::File.directory?(dir) && ::File.readable?(dir)
+          end
+      end
+
+      ##
+      # Return the parent SourceInfo, or nil if this is the root.
+      # @return [Toys::Definition::SourceInfo,nil]
+      #
+      attr_reader :parent
+
+      ##
+      # Return the context directory path (normally the directory containing
+      # the toplevel toys file or directory). May return nil if there is no
+      # context (e.g. the tool is being defined from a block).
+      # @return [String,nil]
+      #
+      attr_reader :context_directory
+
+      ##
+      # Return the source, which may be a path or a proc.
+      # @return [String,Proc]
+      #
+      attr_reader :source
+
+      ##
+      # Return the type of source.
+      # @return [:file,:directory,:proc]
+      #
+      attr_reader :source_type
+
+      ##
+      # Return the path of the current source file or directory, or nil if this
+      # source is not a file system path.
+      # @return [String,nil]
+      #
+      attr_reader :source_path
+
+      ##
+      # Return the source proc, or nil if this source is not a proc.
+      # @return [Proc,nil]
+      #
+      attr_reader :source_proc
+
+      ##
+      # Return the user-visible name of this source.
+      # @return [String]
+      #
+      attr_reader :source_name
+      alias to_s source_name
+
+      ##
+      # 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)
+        if @data_dir
+          full_path = ::File.join(@data_dir, 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
+        end
+        parent&.find_data(path, type: type)
+      end
+
+      ##
+      # Create a child SourceInfo relative to the parent path.
+      # @private
+      #
+      def relative_child(filename, data_dir_name)
+        raise "Cannot create relative child of a proc" unless source_path
+        child_path = ::File.join(source_path, filename)
+        child_path, type = SourceInfo.check_path(child_path, true)
+        return nil unless child_path
+        SourceInfo.new(self, context_directory, child_path, type, child_path, data_dir_name)
+      end
+
+      ##
+      # Create a child SourceInfo with an absolute path.
+      # @private
+      #
+      def absolute_child(child_path)
+        child_path, type = SourceInfo.check_path(child_path, false)
+        SourceInfo.new(self, context_directory, child_path, type, child_path, nil)
+      end
+
+      ##
+      # Create a root source info for a file path.
+      # @private
+      #
+      def self.create_path_root(source_path)
+        source_path, type = check_path(source_path, false)
+        context_directory = ::File.dirname(source_path)
+        new(nil, context_directory, source_path, type, source_path, nil)
+      end
+
+      ##
+      # Create a root source info for a proc.
+      # @private
+      #
+      def self.create_proc_root(source_proc, source_name)
+        new(nil, nil, source_proc, :proc, source_name, nil)
+      end
+
+      ##
+      # Check a path and determine the canonical path and type.
+      # @private
+      #
+      def self.check_path(path, lenient)
+        path = ::File.expand_path(path)
+        unless ::File.readable?(path)
+          raise LoaderError, "Cannot read: #{path}" unless lenient
+          return [nil, nil]
+        end
+        if ::File.file?(path)
+          unless ::File.extname(path) == ".rb"
+            raise LoaderError, "File is not a ruby file: #{path}" unless lenient
+            return [nil, nil]
+          end
+          [path, :file]
+        elsif ::File.directory?(path)
+          [path, :directory]
+        else
+          raise LoaderError, "Unknown type: #{path}" unless lenient
+          [nil, nil]
+        end
+      end
+    end
+  end
+end

data/lib/toys/definition/tool.rb

@@ -91,8 +91,7 @@ module Toys
       def reset_definition(loader)
         @tool_class = DSL::Tool.new_class(@full_name, @priority, loader)
 
-        @source_path = nil
-        @data_finder = nil
+        @source_info = nil
         @definition_finished = false
 
         @desc = Utils::WrappableString.new("")
@@ -109,6 +108,7 @@ module Toys
 
         @disable_argument_parsing = false
         @includes_modules = false
+        @custom_context_directory = nil
       end
 
       ##
@@ -186,10 +186,18 @@ module Toys
       attr_reader :middleware_stack
 
       ##
-      # Returns the path to the file that contains the definition of this tool.
-      # @return [String]
+      # Returns info on the source of this tool, or nil if the source is not
+      # defined.
+      # @return [Toys::Definition::SourceInfo,nil]
+      #
+      attr_reader :source_info
+
+      ##
+      # Returns the custom context directory set for this tool, or nil if none
+      # is set.
+      # @return [String,nil]
       #
-      attr_reader :source_path
+      attr_reader :custom_context_directory
 
       ##
       # Returns the local name of this tool.
@@ -366,17 +374,15 @@ module Toys
       # A tool may be defined from at most one path. If a different path is
       # already set, raises {Toys::ToolDefinitionError}
       #
-      # @param [String] path The path to the file defining this tool
-      # @param [Toys::Definition::DataFinder] data_finder Data finder
+      # @param [Toys::Definition::SourceInfo] source Source info
       #
-      def lock_source_path(path, data_finder)
-        if source_path && source_path != path
+      def lock_source(source)
+        if source_info && source_info.source != source.source
           raise ToolDefinitionError,
-                "Cannot redefine tool #{display_name.inspect} in #{path}" \
-                " (already defined in #{source_path})"
+                "Cannot redefine tool #{display_name.inspect} in #{source.source_name}" \
+                " (already defined in #{source_info.source_name})"
         end
-        @source_path = path
-        @data_finder = data_finder
+        @source_info = source
       end
 
       ##
@@ -671,15 +677,35 @@ module Toys
       end
 
       ##
-      # Find the given data file or directory in this tool's search path.
+      # Set the custom context 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.
+      # @param [String] dir
+      #
+      def custom_context_directory=(dir)
+        check_definition_state
+        @custom_context_directory = dir
+      end
+
+      ##
+      # Return the effective context directory.
+      # If there is a custom context directory, uses that. Otherwise, looks for
+      # a custom context directory up the tool ancestor chain. If none is
+      # found, uses the default context directory from the source info. It is
+      # possible for there to be no context directory at all, in which case,
+      # returns nil.
+      #
+      # @return [String,nil]
+      #
+      def context_directory
+        lookup_custom_context_directory || source_info&.context_directory
+      end
+
+      ##
+      # Lookup the custom context directory in this tool and its ancestors.
+      # @private
       #
-      def find_data(path, type: nil)
-        @data_finder ? @data_finder.find_data(path, type: type) : nil
+      def lookup_custom_context_directory
+        custom_context_directory || @parent&.lookup_custom_context_directory
       end
 
       ##

data/lib/toys/dsl/tool.rb

@@ -203,7 +203,7 @@ module Toys
           end
         end
         subtool_class = subtool.tool_class
-        DSL::Tool.prepare(subtool_class, next_remaining, @__path, @__data_finder) do
+        DSL::Tool.prepare(subtool_class, next_remaining, source_info) do
           subtool_class.class_eval(&block)
         end
         self
@@ -230,7 +230,7 @@ module Toys
       # @return [Toys::DSL::Tool] self, for chaining.
       #
       def load(path)
-        @__loader.load_path(path, @__words, @__remaining_words, @__priority)
+        @__loader.load_path(source_info, path, @__words, @__remaining_words, @__priority)
         self
       end
 
@@ -650,6 +650,15 @@ module Toys
         super(DSL::Tool.resolve_mixin(mod, cur_tool, @__loader))
       end
 
+      ##
+      # Return the current source info object.
+      #
+      # @return [Toys::Definition::SourceInfo] Source info.
+      #
+      def source_info
+        @__source.last
+      end
+
       ##
       # Find the given data path (file or directory)
       #
@@ -659,7 +668,32 @@ module Toys
       # @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
+        source_info.find_data(path, type: type)
+      end
+
+      ##
+      # Return the context directory for this tool. Generally, this defaults
+      # to the directory containing the toys config directory structure being
+      # read, but it may be changed by setting a different context directory
+      # for the tool.
+      # May return nil if there is no context.
+      #
+      # @return [String,nil] Context directory
+      #
+      def context_directory
+        DSL::Tool.current_tool(self, false)&.context_directory || source_info.context_directory
+      end
+
+      ##
+      # Set a custom context directory for this tool.
+      #
+      # @param [String] dir Context directory
+      #
+      def set_context_directory(dir)
+        cur_tool = DSL::Tool.current_tool(self, false)
+        return if cur_tool.nil?
+        cur_tool.custom_context_directory = dir
+        self
       end
 
       ## @private
@@ -670,8 +704,7 @@ module Toys
         tool_class.instance_variable_set(:@__priority, priority)
         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.instance_variable_set(:@__source, [])
         tool_class
       end
 
@@ -697,23 +730,19 @@ module Toys
           tool_class.instance_variable_set(memoize_var, cur_tool)
         end
         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)
+          source = tool_class.instance_variable_get(:@__source).last
+          cur_tool.lock_source(source)
         end
         cur_tool
       end
 
       ## @private
-      def self.prepare(tool_class, remaining_words, path, data_finder)
+      def self.prepare(tool_class, remaining_words, source)
         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)
+        tool_class.instance_variable_get(:@__source).push(source)
         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)
+        tool_class.instance_variable_get(:@__source).pop
       end
 
       ## @private

data/lib/toys/input_file.rb

@@ -40,18 +40,19 @@ module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
   end
 
   ## @private
-  def self.evaluate(tool_class, remaining_words, path, data_finder)
+  def self.evaluate(tool_class, remaining_words, source)
     namespace = ::Module.new
     namespace.module_eval do
       include ::Toys::Tool::Keys
       @tool_class = tool_class
     end
+    path = source.source_path
     basename = ::File.basename(path).tr(".-", "_").gsub(/\W/, "")
     name = "M#{namespace.object_id}_#{basename}"
     str = build_eval_string(name, ::IO.read(path))
     if str
       const_set(name, namespace)
-      ::Toys::DSL::Tool.prepare(tool_class, remaining_words, path, data_finder) do
+      ::Toys::DSL::Tool.prepare(tool_class, remaining_words, source) 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

@@ -89,7 +89,7 @@ module Toys
       @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)
+      @data_directory_name = data_directory_name
       @middleware_stack = middleware_stack
       @worklist = []
       @tool_data = {}
@@ -101,16 +101,17 @@ module Toys
     ##
     # Add a configuration file/directory to the loader.
     #
-    # @param [String,Array<String>] path One or more paths to add.
+    # @param [String,Array<String>] paths One or more paths 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)
-      paths = Array(path)
+    def add_path(paths, high_priority: false)
+      paths = Array(paths)
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-      paths.each do |p|
-        @worklist << [:file, check_path(p), [], @empty_data_finder, priority]
+      paths.each do |path|
+        source = Definition::SourceInfo.create_path_root(path)
+        @worklist << [source, [], priority]
       end
       self
     end
@@ -121,14 +122,15 @@ module Toys
     # @param [Boolean] high_priority If true, add this block at the top of the
     #     priority list. Defaults to false, indicating the block should be at
     #     the bottom of the priority list.
-    # @param [String] path The "path" that will be shown in documentation for
-    #     tools defined in this block. If omitted, a default unique string will
-    #     be generated.
+    # @param [String] name The source name that will be shown in documentation
+    #     for tools defined in this block. If omitted, a default unique string
+    #     will be generated.
     #
-    def add_block(high_priority: false, path: nil, &block)
-      path ||= "(Block #{block.object_id})"
+    def add_block(high_priority: false, name: nil, &block)
+      name ||= "(Code block #{block.object_id})"
       priority = high_priority ? (@max_priority += 1) : (@min_priority -= 1)
-      @worklist << [block, path, [], @empty_data_finder, priority]
+      source = Definition::SourceInfo.create_proc_root(block, name)
+      @worklist << [source, [], priority]
       self
     end
 
@@ -173,9 +175,11 @@ 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)
+    # @param [Boolean] include_hidden If true, include hidden subtools,
+    #     e.g. names beginning with underscores.
     # @return [Array<Toys::Definition::Tool,Toys::Definition::Alias>]
     #
-    def list_subtools(words, recursive: false)
+    def list_subtools(words, recursive: false, include_hidden: false)
       load_for_prefix(words)
       found_tools = []
       len = words.length
@@ -190,6 +194,7 @@ module Toys
         found_tools << tool unless tool.nil?
       end
       sort_tools_by_name(found_tools)
+      include_hidden ? found_tools : filter_hidden_subtools(found_tools)
     end
 
     ##
@@ -309,30 +314,14 @@ module Toys
     end
 
     ##
-    # Load configuration from the given path.
+    # Load configuration from the given path. This is called from the `load`
+    # directive in the DSL.
     #
     # @private
     #
-    def load_path(path, words, remaining_words, priority)
-      load_validated_path(check_path(path), words, remaining_words, @empty_data_finder, priority)
-    end
-
-    ##
-    # Load configuration from the given proc.
-    #
-    # @private
-    #
-    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, @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, @empty_data_finder, priority]
-      end
+    def load_path(parent_source, path, words, remaining_words, priority)
+      source = parent_source.absolute_child(path)
+      load_validated_path(source, words, remaining_words, priority)
     end
 
     ##
@@ -441,59 +430,71 @@ module Toys
     def load_for_prefix(prefix)
       cur_worklist = @worklist
       @worklist = []
-      cur_worklist.each do |source, path, words, data_finder, priority|
+      cur_worklist.each do |source, words, 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, data_finder, priority)
+        if source.source_proc
+          load_proc(source, words, remaining_words, priority)
+        elsif source.source_path
+          load_validated_path(source, words, remaining_words, priority)
+        end
+      end
+    end
+
+    def load_proc(source, words, remaining_words, priority)
+      if remaining_words
+        tool_class = get_tool_definition(words, priority).tool_class
+        DSL::Tool.prepare(tool_class, remaining_words, source) do
+          ContextualError.capture("Error while loading Toys config!") do
+            tool_class.class_eval(&source.source_proc)
+          end
         end
+      else
+        @worklist << [source, words, priority]
       end
     end
 
-    def load_validated_path(path, words, remaining_words, data_finder, priority)
+    def load_validated_path(source, words, remaining_words, priority)
       if remaining_words
-        load_relevant_path(path, words, remaining_words, data_finder, priority)
+        load_relevant_path(source, words, remaining_words, priority)
       else
-        @worklist << [:file, path, words, data_finder, priority]
+        @worklist << [source, words, priority]
       end
     end
 
-    def load_relevant_path(path, words, remaining_words, data_finder, priority)
-      if ::File.extname(path) == ".rb"
+    def load_relevant_path(source, words, remaining_words, priority)
+      if source.source_type == :file
         tool_class = get_tool_definition(words, priority).tool_class
-        InputFile.evaluate(tool_class, remaining_words, path, data_finder)
+        InputFile.evaluate(tool_class, remaining_words, source)
       else
-        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, data_finder, priority)
+        do_preload(source.source_path)
+        load_index_in(source, words, remaining_words, priority)
+        ::Dir.entries(source.source_path).each do |child|
+          load_child_in(source, child, words, remaining_words, priority)
         end
       end
     end
 
-    def load_index_in(path, words, remaining_words, data_finder, priority)
+    def load_index_in(source, words, remaining_words, 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, data_finder, priority) if index_path
+      index_source = source.relative_child(@index_file_name, @data_directory_name)
+      load_relevant_path(index_source, words, remaining_words, priority) if index_source
     end
 
-    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))
+    def load_child_in(source, child, words, remaining_words, priority)
+      return if child.start_with?(".") || child == @index_file_name ||
+                child == @preload_file_name || child == @preload_directory_name ||
+                child == @data_directory_name
+      child_source = source.relative_child(child, @data_directory_name)
       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, data_finder, priority)
+      load_validated_path(child_source, next_words, next_remaining, 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)
+        if ::File.file?(preload_file) && ::File.readable?(preload_file)
           require preload_file
         end
       end
@@ -501,37 +502,17 @@ module Toys
         preload_dir = ::File.join(path, @preload_directory_name)
         if ::File.directory?(preload_dir) && ::File.readable?(preload_dir)
           ::Dir.entries(preload_dir).each do |child|
+            next unless ::File.extname(child) == ".rb"
             preload_file = ::File.join(preload_dir, child)
-            if !::File.directory?(preload_file) && ::File.readable?(preload_file)
-              require preload_file
-            end
+            next if !::File.file?(preload_file) || !::File.readable?(preload_file)
+            require preload_file
           end
         end
       end
     end
 
-    def check_path(path, lenient: false, type: nil)
-      path = ::File.expand_path(path)
-      type ||= ::File.extname(path) == ".rb" ? :file : :dir
-      case type
-      when :file
-        if ::File.directory?(path) || !::File.readable?(path)
-          return nil if lenient
-          raise LoaderError, "Cannot read file #{path}"
-        end
-      when :dir
-        if !::File.directory?(path) || !::File.readable?(path)
-          return nil if lenient
-          raise LoaderError, "Cannot read directory #{path}"
-        end
-      else
-        raise ::ArgumentError, "Illegal type #{type}"
-      end
-      path
-    end
-
     def sort_tools_by_name(tools)
-      tools.sort do |a, b|
+      tools.sort! do |a, b|
         a = a.full_name
         b = b.full_name
         while !a.empty? && !b.empty? && a.first == b.first
@@ -542,6 +523,19 @@ module Toys
       end
     end
 
+    def filter_hidden_subtools(tools)
+      result = []
+      tools.each_with_index do |tool, index|
+        next if tool.full_name.any? { |n| n.start_with?("_") }
+        unless tool.runnable?
+          next_tool = tools[index + 1]
+          next if next_tool && next_tool.full_name.slice(0..-2) == tool.full_name
+        end
+        result << tool
+      end
+      result
+    end
+
     def calc_remaining_words(words1, words2)
       index = 0
       lengths = [words1.length, words2.length]

data/lib/toys/runner.rb

@@ -79,6 +79,7 @@ module Toys
     def create_data(args, base_verbosity)
       data = @tool_definition.default_data.dup
       data[Tool::Keys::TOOL_DEFINITION] = @tool_definition
+      data[Tool::Keys::TOOL_SOURCE] = @tool_definition.source_info
       data[Tool::Keys::TOOL_NAME] = @tool_definition.full_name
       data[Tool::Keys::VERBOSITY] = base_verbosity
       data[Tool::Keys::ARGS] = args

data/lib/toys/standard_middleware/show_help.rb

@@ -74,6 +74,12 @@ module Toys
       #
       DEFAULT_SEARCH_FLAGS = ["-s WORD", "--search=WORD"].freeze
 
+      ##
+      # Default show-all-subtools flags
+      # @return [Array<String>]
+      #
+      DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS = ["--all"].freeze
+
       ##
       # Key set when the show help flag is present
       # @return [Object]
@@ -104,6 +110,12 @@ module Toys
       #
       SEARCH_STRING_KEY = Object.new.freeze
 
+      ##
+      # Key for the show-all-subtools setting
+      # @return [Object]
+      #
+      SHOW_ALL_SUBTOOLS_KEY = Object.new.freeze
+
       ##
       # Key for the tool name
       # @return [Object]
@@ -155,8 +167,19 @@ 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] show_all_subtools_flags Specify
+      #     flags to show all subtools, including hidden tools and non-runnable
+      #     namespaces. The value may be any of the following:
+      #
+      #     *  An array of flags.
+      #     *  The `true` value to use {DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS}.
+      #     *  The `false` value for no flags. (Default)
+      #     *  A proc that takes a tool and returns any of the above.
+      #
       # @param [Boolean] default_recursive Whether to search recursively for
       #     subtools by default. Default is `false`.
+      # @param [Boolean] default_show_all_subtools Whether to show all subtools
+      #     by default. Default is `false`.
       # @param [Boolean] fallback_execution Cause the tool to display its own
       #     help text if it is not otherwise runnable. This is mostly useful
       #     for namespaces, which have children are not runnable. Default is
@@ -179,7 +202,9 @@ module Toys
                      list_flags: false,
                      recursive_flags: false,
                      search_flags: false,
+                     show_all_subtools_flags: false,
                      default_recursive: false,
+                     default_show_all_subtools: false,
                      fallback_execution: false,
                      allow_root_args: false,
                      show_source_path: false,
@@ -191,7 +216,9 @@ module Toys
         @list_flags = list_flags
         @recursive_flags = recursive_flags
         @search_flags = search_flags
+        @show_all_subtools_flags = show_all_subtools_flags
         @default_recursive = default_recursive ? true : false
+        @default_show_all_subtools = default_show_all_subtools ? true : false
         @fallback_execution = fallback_execution
         @allow_root_args = allow_root_args
         @show_source_path = show_source_path
@@ -212,6 +239,7 @@ module Toys
           if (!help_flags.empty? || !list_flags.empty? || @fallback_execution) && has_subtools
             add_recursive_flags(tool_definition)
             add_search_flags(tool_definition)
+            add_show_all_subtools_flags(tool_definition)
           end
           if !help_flags.empty? || !usage_flags.empty? || !list_flags.empty?
             add_root_args(tool_definition)
@@ -223,16 +251,18 @@ module Toys
       ##
       # Display help text if requested.
       #
-      def run(tool)
+      def run(tool) # rubocop:disable Metrics/AbcSize
         if tool[SHOW_USAGE_KEY]
           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],
+                                                        include_hidden: tool[SHOW_ALL_SUBTOOLS_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],
+                                                      include_hidden: tool[SHOW_ALL_SUBTOOLS_KEY],
                                                       show_source_path: @show_source_path,
                                                       wrap_width: terminal.width))
         else
@@ -288,67 +318,82 @@ module Toys
       end
 
       def add_help_flags(tool_definition)
-        help_flags = resolve_flags_spec(@help_flags, tool_definition, DEFAULT_HELP_FLAGS)
-        unless help_flags.empty?
+        flags = resolve_flags_spec(@help_flags, tool_definition, DEFAULT_HELP_FLAGS)
+        unless flags.empty?
           tool_definition.add_flag(
-            SHOW_HELP_KEY, help_flags,
+            SHOW_HELP_KEY, flags,
             report_collisions: false,
             desc: "Display help for this tool"
           )
         end
-        help_flags
+        flags
       end
 
       def add_usage_flags(tool_definition)
-        usage_flags = resolve_flags_spec(@usage_flags, tool_definition, DEFAULT_USAGE_FLAGS)
-        unless usage_flags.empty?
+        flags = resolve_flags_spec(@usage_flags, tool_definition, DEFAULT_USAGE_FLAGS)
+        unless flags.empty?
           tool_definition.add_flag(
-            SHOW_USAGE_KEY, usage_flags,
+            SHOW_USAGE_KEY, flags,
             report_collisions: false,
             desc: "Display a brief usage string for this tool"
           )
         end
-        usage_flags
+        flags
       end
 
       def add_list_flags(tool_definition)
-        list_flags = resolve_flags_spec(@list_flags, tool_definition, DEFAULT_LIST_FLAGS)
-        unless list_flags.empty?
+        flags = resolve_flags_spec(@list_flags, tool_definition, DEFAULT_LIST_FLAGS)
+        unless flags.empty?
           tool_definition.add_flag(
-            SHOW_LIST_KEY, list_flags,
+            SHOW_LIST_KEY, flags,
             report_collisions: false,
             desc: "List the subtools under this tool"
           )
         end
-        list_flags
+        flags
       end
 
       def add_recursive_flags(tool_definition)
-        recursive_flags = resolve_flags_spec(@recursive_flags, tool_definition,
-                                             DEFAULT_RECURSIVE_FLAGS)
-        if recursive_flags.empty?
+        flags = resolve_flags_spec(@recursive_flags, tool_definition, DEFAULT_RECURSIVE_FLAGS)
+        if flags.empty?
           tool_definition.default_data[RECURSIVE_SUBTOOLS_KEY] = @default_recursive
         else
           tool_definition.add_flag(
-            RECURSIVE_SUBTOOLS_KEY, recursive_flags,
+            RECURSIVE_SUBTOOLS_KEY, flags,
             report_collisions: false, default: @default_recursive,
             desc: "List all subtools recursively when displaying help" \
                   " (default is #{@default_recursive})"
           )
         end
-        recursive_flags
+        flags
       end
 
       def add_search_flags(tool_definition)
-        search_flags = resolve_flags_spec(@search_flags, tool_definition, DEFAULT_SEARCH_FLAGS)
-        unless search_flags.empty?
+        flags = resolve_flags_spec(@search_flags, tool_definition, DEFAULT_SEARCH_FLAGS)
+        unless flags.empty?
           tool_definition.add_flag(
-            SEARCH_STRING_KEY, search_flags,
+            SEARCH_STRING_KEY, flags,
             report_collisions: false,
             desc: "Search subtools for the given regular expression when displaying help"
           )
         end
-        search_flags
+        flags
+      end
+
+      def add_show_all_subtools_flags(tool_definition)
+        flags = resolve_flags_spec(@show_all_subtools_flags, tool_definition,
+                                   DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS)
+        if flags.empty?
+          tool_definition.default_data[SHOW_ALL_SUBTOOLS_KEY] = @default_show_all_subtools
+        else
+          tool_definition.add_flag(
+            SHOW_ALL_SUBTOOLS_KEY, flags,
+            report_collisions: false, default: @default_show_all_subtools,
+            desc: "List all subtools including hidden subtools and namespaces" \
+                  " (default is #{@default_show_all_subtools})"
+          )
+        end
+        flags
       end
 
       def add_root_args(tool_definition)

data/lib/toys/tool.rb

@@ -78,6 +78,13 @@ module Toys
       #
       TOOL_DEFINITION = ::Object.new.freeze
 
+      ##
+      # Context key for the `Toys::Definition::SourceInfo` describing the
+      # source of this tool.
+      # @return [Object]
+      #
+      TOOL_SOURCE = ::Object.new.freeze
+
       ##
       # Context key for the full name of the tool being executed. Value is an
       # array of strings.
@@ -159,6 +166,14 @@ module Toys
       @__data[Keys::TOOL_DEFINITION]
     end
 
+    ##
+    # Return the source of the tool being executed.
+    # @return [Toys::Definition::SourceInfo]
+    #
+    def tool_source
+      @__data[Keys::TOOL_SOURCE]
+    end
+
     ##
     # Return the name of the tool being executed, as an array of strings.
     # @return [Array[String]]
@@ -268,7 +283,20 @@ module Toys
     # @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)
+      @__data[Keys::TOOL_SOURCE].find_data(path, type: type)
+    end
+
+    ##
+    # Return the context directory for this tool. Generally, this defaults
+    # to the directory containing the toys config directory structure being
+    # read, but it may be changed by setting a different context directory
+    # for the tool.
+    # May return nil if there is no context.
+    #
+    # @return [String,nil] Context directory
+    #
+    def context_directory
+      @__data[Keys::TOOL_DEFINITION].context_directory
     end
 
     ##

data/lib/toys/utils/help_text.rb

@@ -83,7 +83,9 @@ module Toys
       # Generate a short usage string.
       #
       # @param [Boolean] recursive If true, and the tool is a namespace,
-      #     display all subcommands recursively. Defaults to false.
+      #     display all subtools recursively. Defaults to false.
+      # @param [Boolean] include_hidden Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
       # @param [Integer] left_column_width Width of the first column. Default
       #     is {DEFAULT_LEFT_COLUMN_WIDTH}.
       # @param [Integer] indent Indent width. Default is {DEFAULT_INDENT}.
@@ -92,10 +94,11 @@ module Toys
       #
       # @return [String] A usage string.
       #
-      def usage_string(recursive: false, left_column_width: nil, indent: nil, wrap_width: nil)
+      def usage_string(recursive: false, include_hidden: false,
+                       left_column_width: nil, indent: nil, wrap_width: nil)
         left_column_width ||= DEFAULT_LEFT_COLUMN_WIDTH
         indent ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, nil)
+        subtools = find_subtools(recursive, nil, include_hidden)
         assembler = UsageStringAssembler.new(@tool, @binary_name, subtools,
                                              indent, left_column_width, wrap_width)
         assembler.result
@@ -105,9 +108,11 @@ module Toys
       # Generate a long help string.
       #
       # @param [Boolean] recursive If true, and the tool is a namespace,
-      #     display all subcommands recursively. Defaults to false.
+      #     display all subtools recursively. Defaults to false.
       # @param [String,nil] search An optional string to search for when
-      #     listing subcommands. Defaults to `nil` which finds all subcommands.
+      #     listing subtools. Defaults to `nil` which finds all subtools.
+      # @param [Boolean] include_hidden Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
       # @param [Boolean] show_source_path If true, shows the source path
       #     section. Defaults to false.
       # @param [Integer] indent Indent width. Default is {DEFAULT_INDENT}.
@@ -119,11 +124,12 @@ module Toys
       #
       # @return [String] A usage string.
       #
-      def help_string(recursive: false, search: nil, show_source_path: false,
+      def help_string(recursive: false, search: nil, include_hidden: false,
+                      show_source_path: false,
                       indent: nil, indent2: nil, wrap_width: nil, styled: true)
         indent ||= DEFAULT_INDENT
         indent2 ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, search)
+        subtools = find_subtools(recursive, search, include_hidden)
         assembler = HelpStringAssembler.new(@tool, @binary_name, subtools, search, show_source_path,
                                             indent, indent2, wrap_width, styled)
         assembler.result
@@ -133,9 +139,11 @@ module Toys
       # Generate a subtool list string.
       #
       # @param [Boolean] recursive If true, and the tool is a namespace,
-      #     display all subcommands recursively. Defaults to false.
+      #     display all subtools recursively. Defaults to false.
       # @param [String,nil] search An optional string to search for when
-      #     listing subcommands. Defaults to `nil` which finds all subcommands.
+      #     listing subtools. Defaults to `nil` which finds all subtools.
+      # @param [Boolean] include_hidden Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
       # @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`.
@@ -143,10 +151,10 @@ module Toys
       #
       # @return [String] A usage string.
       #
-      def list_string(recursive: false, search: nil,
+      def list_string(recursive: false, search: nil, include_hidden: false,
                       indent: nil, wrap_width: nil, styled: true)
         indent ||= DEFAULT_INDENT
-        subtools = find_subtools(recursive, search)
+        subtools = find_subtools(recursive, search, include_hidden)
         assembler = ListStringAssembler.new(@tool, subtools, recursive, search,
                                             indent, wrap_width, styled)
         assembler.result
@@ -154,8 +162,9 @@ module Toys
 
       private
 
-      def find_subtools(recursive, search)
-        subtools = @loader.list_subtools(@tool.full_name, recursive: recursive)
+      def find_subtools(recursive, search, include_hidden)
+        subtools = @loader.list_subtools(@tool.full_name,
+                                         recursive: recursive, include_hidden: include_hidden)
         return subtools if search.nil? || search.empty?
         regex = ::Regexp.new(search, ::Regexp::IGNORECASE)
         subtools.find_all do |tool|
@@ -387,10 +396,10 @@ module Toys
         end
 
         def add_source_section
-          return unless @tool.source_path && @show_source_path
+          return unless @show_source_path && @tool.source_info&.source_name
           @lines << ""
           @lines << bold("SOURCE")
-          @lines << indent_str("Defined in #{@tool.source_path}")
+          @lines << indent_str("Defined in #{@tool.source_info.source_name}")
         end
 
         def add_description_section

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toys-core
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Daniel Azuma
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-10-08 00:00:00.000000000 Z
+date: 2018-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.59.1
+        version: 0.59.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.59.1
+        version: 0.59.2
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -127,8 +127,8 @@ 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/source_info.rb
 - lib/toys/definition/tool.rb
 - lib/toys/dsl/arg.rb
 - lib/toys/dsl/flag.rb

data/lib/toys/definition/data_finder.rb

@@ -1,108 +0,0 @@
-# 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