toys 0.13.1 → 0.14.2

data/core-docs/toys/errors.rb

@@ -51,6 +51,19 @@ module Toys
   # thrown during tool execution.
   #
   class ContextualError < ::StandardError
+    ##
+    # Construct a ContextualError. This exception type is thrown from
+    # {ContextualError.capture} and {ContextualError.capture_path} and should
+    # not be constructed directly.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def initialize(cause, banner,
+                   config_path: nil, config_line: nil,
+                   tool_name: nil, tool_args: nil)
+      # Source available in the toys-core gem
+    end
+
     ##
     # The underlying exception
     # @return [::StandardError]
@@ -88,6 +101,26 @@ module Toys
     attr_reader :tool_args
 
     class << self
+      ##
+      # Execute the given block, and wrap any exceptions thrown with a
+      # ContextualError. This is intended for loading a config file from the
+      # given path, and wraps any Ruby parsing errors.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def capture_path(banner, path, **opts)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Execute the given block, and wrap any exceptions thrown with a
+      # ContextualError.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def capture(banner, **opts)
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/core-docs/toys/flag.rb

@@ -77,6 +77,7 @@ module Toys
       # The type of flag (`:boolean` or `:value`)
       # @return [:boolean] if this is a boolean flag (i.e. no value)
       # @return [:value] if this flag takes a value (even if optional)
+      # @return [nil] if this flag is indeterminate
       #
       attr_reader :flag_type
 
@@ -111,6 +112,16 @@ module Toys
       # @return [String]
       #
       attr_reader :canonical_str
+
+      ##
+      # This method is accessible for testing only.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def configure_canonical(canonical_flag_type, canonical_value_type,
+                              canonical_value_label, canonical_value_delim)
+        # Source available in the toys-core gem
+      end
     end
 
     ##

data/core-docs/toys/input_file.rb

@@ -5,4 +5,10 @@
 # is parsed, a module is created under this parent for that file's constants.
 #
 module Toys::InputFile # rubocop:disable Style/ClassAndModuleChildren
+  ##
+  # @private This interface is internal and subject to change without warning.
+  #
+  def self.evaluate(tool_class, words, priority, remaining_words, source, loader)
+    # Source available in the toys-core gem
+  end
 end

data/core-docs/toys/loader.rb

@@ -183,22 +183,31 @@ module Toys
 
     ##
     # Returns a list of subtools for the given path, loading from the
-    # configuration if necessary.
+    # configuration if necessary. The list will be sorted by name.
     #
     # @param words [Array<String>] The name of the parent tool
     # @param recursive [Boolean] If true, return all subtools recursively
     #     rather than just the immediate children (the default)
     # @param include_hidden [Boolean] If true, include hidden subtools,
-    #     e.g. names beginning with underscores.
+    #     i.e. names beginning with underscores. Defaults to false.
+    # @param include_namespaces [Boolean] If true, include namespaces,
+    #     i.e. tools that are not runnable but have descendents that would have
+    #     been listed by the current filters. Defaults to false.
+    # @param include_non_runnable [Boolean] If true, include tools that have
+    #     no children and are not runnable. Defaults to false.
     # @return [Array<Toys::ToolDefinition>] An array of subtools.
     #
-    def list_subtools(words, recursive: false, include_hidden: false)
+    def list_subtools(words,
+                      recursive: false,
+                      include_hidden: false,
+                      include_namespaces: false,
+                      include_non_runnable: false)
       # Source available in the toys-core gem
     end
 
     ##
-    # Returns true if the given path has at least one subtool. Loads from the
-    # configuration if necessary.
+    # Returns true if the given path has at least one subtool, even if they are
+    # hidden or non-runnable. Loads from the configuration if necessary.
     #
     # @param words [Array<String>] The name of the parent tool
     # @return [Boolean]
@@ -218,5 +227,137 @@ module Toys
     def split_path(str)
       # Source available in the toys-core gem
     end
+
+    #### INTERNAL METHODS ####
+
+    ##
+    # Get or create the tool definition for the given name and priority.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def get_tool(words, priority, tool_class = nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # 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.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def activate_tool(words, priority)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Returns true if the given tool name currently exists in the loader.
+    # Does not load the tool if not found.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def tool_defined?(words)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Build a new tool.
+    # Called only from ToolData.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def build_tool(words, priority, tool_class = nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Stop search at the given priority. Returns true if successful.
+    # Called only from the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def stop_loading_at_priority(priority)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Loads the subtree under the given prefix.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def load_for_prefix(prefix)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Attempt to get a well-known mixin module for the given symbolic name.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def resolve_standard_mixin(name)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Attempt to get a well-known template class for the given symbolic name.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def resolve_standard_template(name)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Load configuration from the given path. This is called from the `load`
+    # directive in the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def load_path(parent_source, path, words, remaining_words, priority)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Load configuration from the given git remote. This is called from the
+    # `load_git` directive in the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def load_git(parent_source, git_remote, git_path, git_commit, words, remaining_words, priority,
+                 update: false)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Load a subtool block. Called from the `tool` directive in the DSL.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def load_block(parent_source, block, words, remaining_words, priority)
+      # Source available in the toys-core gem
+    end
+
+    @git_cache_mutex = ::Monitor.new
+    @default_git_cache = nil
+
+    ##
+    # Get a global default GitCache.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.default_git_cache
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Determine the next setting for remaining_words, given a word.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.next_remaining_words(remaining_words, word)
+      # Source available in the toys-core gem
+    end
   end
 end

data/core-docs/toys/middleware.rb

@@ -123,12 +123,21 @@ module Toys
       def stack(input)
         # Source available in the toys-core gem
       end
+
+      ##
+      # Create a spec from an array specification.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def spec_from_array(array)
+        # Source available in the toys-core gem
+      end
     end
 
     ##
     # **_Defined in the toys-core gem_**
     #
-    # A base class that provides default NOP implementations of the middleware
+    # A base class that provides default no-op implementation of the middleware
     # interface. This base class may optionally be subclassed by a middleware
     # implementation.
     #
@@ -214,12 +223,34 @@ module Toys
       def hash
         # Source available in the toys-core gem
       end
+
+      ##
+      # Internal constructor. Use {Toys::Middleware.spec} instead.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def initialize(object, name, args, kwargs, block)
+        # Source available in the toys-core gem
+      end
     end
 
     ##
     # **_Defined in the toys-core gem_**
     #
-    # A stack of middleware specs.
+    # A stack of middleware specs, which can be applied in order to a tool.
+    #
+    # A middleware stack is separated into three groups:
+    #
+    #  *  {#pre_specs}, which are applied first.
+    #  *  {#default_specs}, which are applied next. The default specs are set
+    #     when the stack is created and are generally not modified.
+    #  *  {#post_specs}, which are applied third.
+    #
+    # When adding middleware to a stack, you should normally add them to the
+    # pre or post specs. By default, {Stack#add} appends to the pre specs,
+    # inserting new middleware just before the defaults.
+    #
+    # Use {Toys::Middleware.stack} to create a middleware stack.
     #
     class Stack
       ##
@@ -290,6 +321,15 @@ module Toys
       def hash
         # Source available in the toys-core gem
       end
+
+      ##
+      # Internal constructor. Use {Toys::Middleware.stack} instead.
+      #
+      # @private This interface is internal and subject to change without warning.
+      #
+      def initialize(default_specs: nil, pre_specs: nil, post_specs: nil)
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/core-docs/toys/settings.rb

@@ -332,6 +332,13 @@ module Toys
       # @return [String, nil]
       #
       attr_reader :type_description
+
+      ##
+      # @private This interface is internal and subject to change without warning.
+      #
+      def initialize(value, settings_class, field_name, type_description)
+        # Source available in the toys-core gem
+      end
     end
 
     ##
@@ -502,6 +509,16 @@ module Toys
       def settings_group(name, klass = nil, &block)
         # Source available in the toys-core gem
       end
+
+      ##
+      # @private This interface is internal and subject to change without warning.
+      #
+      # Returns the fields hash. This is shared between the settings class and
+      # all its instances.
+      #
+      def fields
+        # Source available in the toys-core gem
+      end
     end
   end
 end

data/core-docs/toys/source_info.rb

@@ -123,5 +123,100 @@ module Toys
     def apply_lib_paths
       # Source available in the toys-core gem
     end
+
+    ##
+    # Create a SourceInfo.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def initialize(parent, priority, context_directory, source_type, source_path, source_proc,
+                   git_remote, git_path, git_commit, source_name, data_dir_name, lib_dir_name)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a child SourceInfo relative to the parent path.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def relative_child(filename, source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a child SourceInfo with an absolute path.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def absolute_child(child_path, source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a child SourceInfo with a git source.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def git_child(child_git_remote, child_git_path, child_git_commit, child_path,
+                  source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a proc child SourceInfo
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def proc_child(child_proc, source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a root source info for a file path.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.create_path_root(source_path, priority,
+                              context_directory: nil,
+                              data_dir_name: nil,
+                              lib_dir_name: nil,
+                              source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a root source info for a cached git repo.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.create_git_root(git_remote, git_path, git_commit, source_path, priority,
+                             context_directory: nil,
+                             data_dir_name: nil,
+                             lib_dir_name: nil,
+                             source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Create a root source info for a proc.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.create_proc_root(source_proc, priority,
+                              context_directory: nil,
+                              data_dir_name: nil,
+                              lib_dir_name: nil,
+                              source_name: nil)
+      # Source available in the toys-core gem
+    end
+
+    ##
+    # Check a path and determine the canonical path and type.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.check_path(path, lenient)
+      # Source available in the toys-core gem
+    end
   end
 end

data/core-docs/toys/standard_mixins/exec.rb

@@ -8,7 +8,7 @@ module Toys
     # in a string. Also provides an interface for controlling a spawned
     # process's streams.
     #
-    # You may make these methods available to your tool by including the
+    # You can make these methods available to your tool by including the
     # following directive in your tool configuration:
     #
     #     include :exec
@@ -54,54 +54,88 @@ module Toys
     # options.
     #
     # Three general strategies are available for custom stream handling. First,
-    # you may redirect to other streams such as files, IO objects, or Ruby
+    # you can redirect to other streams such as files, IO objects, or Ruby
     # strings. Some of these options map directly to options provided by the
-    # `Process#spawn` method. Second, you may use a controller to manipulate
-    # the streams programmatically. Third, you may capture output stream data
+    # `Process#spawn` method. Second, you can use a controller to manipulate
+    # the streams programmatically. Third, you can capture output stream data
     # and make it available in the result.
     #
     # Following is a full list of the stream handling options, along with how
     # to specify them using the `:in`, `:out`, and `:err` options.
     #
-    #  *  **Inherit parent stream:** You may inherit the corresponding stream
+    #  *  **Inherit parent stream:** You can inherit the corresponding stream
     #     in the parent process by passing `:inherit` as the option value. This
     #     is the default if the subprocess is *not* run in the background.
-    #  *  **Redirect to null:** You may redirect to a null stream by passing
+    #
+    #  *  **Redirect to null:** You can redirect to a null stream by passing
     #     `:null` as the option value. This connects to a stream that is not
     #     closed but contains no data, i.e. `/dev/null` on unix systems. This
     #     is the default if the subprocess is run in the background.
-    #  *  **Close the stream:** You may close the stream by passing `:close` as
+    #
+    #  *  **Close the stream:** You can close the stream by passing `:close` as
     #     the option value. This is the same as passing `:close` to
     #     `Process#spawn`.
-    #  *  **Redirect to a file:** You may redirect to a file. This reads from
+    #
+    #  *  **Redirect to a file:** You can redirect to a file. This reads from
     #     an existing file when connected to `:in`, and creates or appends to a
     #     file when connected to `:out` or `:err`. To specify a file, use the
-    #     setting `[:file, "/path/to/file"]`. You may also, when writing a
+    #     setting `[:file, "/path/to/file"]`. You can also, when writing a
     #     file, append an optional mode and permission code to the array. For
     #     example, `[:file, "/path/to/file", "a", 0644]`.
-    #  *  **Redirect to an IO object:** You may redirect to an IO object in the
-    #     parent process, by passing the IO object as the option value. You may
+    #
+    #  *  **Redirect to an IO object:** You can redirect to an IO object in the
+    #     parent process, by passing the IO object as the option value. You can
     #     use any IO object. For example, you could connect the child's output
     #     to the parent's error using `out: $stderr`, or you could connect to
     #     an existing File stream. Unlike `Process#spawn`, this works for IO
     #     objects that do not have a corresponding file descriptor (such as
     #     StringIO objects). In such a case, a thread will be spawned to pipe
     #     the IO data through to the child process.
-    #  *  **Combine with another child stream:** You may redirect one child
+    #
+    #  *  **Redirect to a pipe:** You can redirect to a pipe created using
+    #     `IO.pipe` (i.e. a two-element array of read and write IO objects) by
+    #     passing the array as the option value. This will connect the
+    #     appropriate IO (either read or write), and close it in the parent.
+    #     Thus, you can connect only one process to each end. If you want more
+    #     direct control over IO closing behavior, pass the IO object (i.e. the
+    #     element of the pipe array) directly.
+    #
+    #  *  **Combine with another child stream:** You can redirect one child
     #     output stream to another, to combine them. To merge the child's error
     #     stream into its output stream, use `err: [:child, :out]`.
-    #  *  **Read from a string:** You may pass a string to the input stream by
+    #
+    #  *  **Read from a string:** You can pass a string to the input stream by
     #     setting `[:string, "the string"]`. This works only for `:in`.
-    #  *  **Capture output stream:** You may capture a stream and make it
+    #
+    #  *  **Capture output stream:** You can capture a stream and make it
     #     available on the {Toys::Utils::Exec::Result} object, using the
     #     setting `:capture`. This works only for the `:out` and `:err`
     #     streams.
-    #  *  **Use the controller:** You may hook a stream to the controller using
+    #
+    #  *  **Use the controller:** You can hook a stream to the controller using
     #     the setting `:controller`. You can then manipulate the stream via the
     #     controller. If you pass a block to {Toys::StandardMixins::Exec#exec},
     #     it yields the {Toys::Utils::Exec::Controller}, giving you access to
     #     streams.
     #
+    #  *  **Make copies of an output stream:** You can "tee," or duplicate the
+    #     `:out` or `:err` stream and redirect those copies to various
+    #     destinations. To specify a tee, use the setting `[:tee, ...]` where
+    #     the additional array elements include two or more of the following.
+    #     See the corresponding documentation above for more detail.
+    #      *  `:inherit` to direct to the parent process's stream.
+    #      *  `:capture` to capture the stream and store it in the result.
+    #      *  `:controller` to direct the stream to the controller.
+    #      *  `[:file, "/path/to/file"]` to write to a file.
+    #      *  An `IO` or `StringIO` object.
+    #      *  An array of two `IO` objects representing a pipe
+    #
+    #     Additionally, the last element of the array can be a hash of options.
+    #     Supported options include:
+    #      *  `:buffer_size` The size of the memory buffer for each element of
+    #         the tee. Larger buffers may allow higher throughput. The default
+    #         is 65536.
+    #
     # ### Result handling
     #
     # A subprocess result is represented by a {Toys::Utils::Exec::Result}
@@ -191,7 +225,7 @@ module Toys
     #     not present, the command is not logged.
     #
     #  *  `:log_level` (Integer,false) Level for logging the actual command.
-    #     Defaults to Logger::INFO if not present. You may also pass `false` to
+    #     Defaults to Logger::INFO if not present. You can also pass `false` to
     #     disable logging of the command.
     #
     #  *  `:log_cmd` (String) The string logged for the actual command.
@@ -243,7 +277,7 @@ module Toys
       end
 
       ##
-      # Execute a command. The command may be given as a single string to pass
+      # Execute a command. The command can be given as a single string to pass
       # to a shell, or an array of strings indicating a posix command.
       #
       # If the process is not set to run in the background, and a block is
@@ -347,7 +381,7 @@ module Toys
       ##
       # Execute a tool in the current CLI in a forked process.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If the process is not set to run in the background, and a block is
@@ -382,7 +416,7 @@ module Toys
       ##
       # Execute a tool in a separately spawned process.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If the process is not set to run in the background, and a block is
@@ -425,7 +459,7 @@ module Toys
       end
 
       ##
-      # Execute a command. The command may be given as a single string to pass
+      # Execute a command. The command can be given as a single string to pass
       # to a shell, or an array of strings indicating a posix command.
       #
       # Captures standard out and returns it as a string.
@@ -527,7 +561,7 @@ module Toys
       # Captures standard out and returns it as a string.
       # Cannot be run in the background.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
@@ -563,7 +597,7 @@ module Toys
       # Captures standard out and returns it as a string.
       # Cannot be run in the background.
       #
-      # The command may be given as a single string or an array of strings,
+      # The command can be given as a single string or an array of strings,
       # representing the tool to run and the arguments to pass.
       #
       # If a block is provided, a {Toys::Utils::Exec::Controller} will be
@@ -640,6 +674,19 @@ module Toys
       def exit_on_nonzero_status(status)
         # Source available in the toys-core gem
       end
+
+      ##
+      # Returns an array of standard verbosity flags needed to replicate the
+      # current verbosity level. This is useful when you want to spawn tools
+      # with the same verbosity level as the current tool.
+      #
+      # @param short [Boolean] Whether to emit short rather than long flags.
+      #     Default is false.
+      # @return [Array<String>]
+      #
+      def verbosity_flags(short: false)
+        # Source available in the toys-core gem
+      end
     end
   end
 end