toys 0.15.6 → 0.16.0

data/core-docs/toys/source_info.rb

@@ -1,271 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Information about the source of a tool, such as the file, git repository,
-  # or block that defined it.
-  #
-  # This object represents a source of tool information and definitions. Such a
-  # source could include:
-  #
-  # * A toys directory
-  # * A single toys file
-  # * A file or directory loaded from git
-  # * A config block passed directly to the CLI
-  # * A tool block within a toys file
-  #
-  # The SourceInfo provides information such as the tool's context directory,
-  # and locates data and lib directories appropriate to the tool. It also
-  # locates the tool's source code so it can be reported when an error occurs.
-  #
-  # Each tool has a unique SourceInfo with all the information specific to that
-  # tool. Additionally, SourceInfo objects are arranged in a containment
-  # hierarchy. For example, a SourceInfo object representing a toys files could
-  # have a parent representing a toys directory, and an object representing a
-  # tool block could have a parent representing an enclosing block or a file.
-  #
-  # Child SourceInfo objects generally inherit some attributes of their parent.
-  # For example, the `.toys` directory in a project directory defines the
-  # context directory as that project directory. Then all tools defined under
-  # that directory will share that context directory, so all SourceInfo objects
-  # descending from that root will inherit that value (unless it's changed
-  # explicitly).
-  #
-  # SourceInfo objects can be obtained in the DSL from
-  # {Toys::DSL::Tool#source_info} or at runtime by getting the
-  # {Toys::Context::Key::TOOL_SOURCE} key. However, they are created internally
-  # by the Loader and should not be created manually.
-  #
-  class SourceInfo
-    ##
-    # The parent of this SourceInfo.
-    #
-    # @return [Toys::SourceInfo] The parent.
-    # @return [nil] if this SourceInfo is a root.
-    #
-    attr_reader :parent
-
-    ##
-    # The root ancestor of this SourceInfo. This generally represents a source
-    # that was added directly to a CLI in code.
-    #
-    # @return [Toys::SourceInfo] The root ancestor.
-    #
-    attr_reader :root
-
-    ##
-    # The priority of tools defined by this source. Higher values indicate a
-    # higher priority. Lower priority values could be negative.
-    #
-    # @return [Integer] The priority.
-    #
-    attr_reader :priority
-
-    ##
-    # The context directory path (normally the directory containing the
-    # toplevel toys file or directory).
-    #
-    # This is not affected by setting a custom context directory for a tool.
-    #
-    # @return [String] The context directory path.
-    # @return [nil] if there is no context directory (perhaps because the root
-    #     source was a block)
-    #
-    attr_reader :context_directory
-
-    ##
-    # The source, which may be a path or a proc depending on the {#source_type}.
-    #
-    # @return [String] Path to the source file or directory.
-    # @return [Proc] The block serving as the source.
-    #
-    attr_reader :source
-
-    ##
-    # The type of source. This could be:
-    #
-    # * `:file`, representing a single toys file. The {#source} will be the
-    #   filesystem path to that file.
-    # * `:directory`, representing a toys directory. The {#source} will be the
-    #   filesystem path to that directory.
-    # * `:proc`, representing a proc, which could be a toplevel block added
-    #   directly to a CLI, a `tool` block within a toys file, or a block within
-    #   another block. The {#source} will be the proc itself.
-    #
-    # @return [:file,:directory,:proc]
-    #
-    attr_reader :source_type
-
-    ##
-    # The path of the current source file or directory.
-    #
-    # This could be set even if {#source_type} is `:proc`, if that proc is
-    # defined within a toys file. The only time this is not set is if the
-    # source is added directly to a CLI in a code block.
-    #
-    # @return [String] The source path
-    # @return [nil] if this source has no file system path.
-    #
-    attr_reader :source_path
-
-    ##
-    # The source proc. This is set if {#source_type} is `:proc`.
-    #
-    # @return [Proc] The source proc
-    # @return [nil] if this source has no proc.
-    #
-    attr_reader :source_proc
-
-    ##
-    # The git remote. This is set if the source, or one of its ancestors, comes
-    # from git.
-    #
-    # @return [String] The git remote
-    # @return [nil] if this source is not fron git.
-    #
-    attr_reader :git_remote
-
-    ##
-    # The git path. This is set if the source, or one of its ancestors, comes
-    # from git.
-    #
-    # @return [String] The git path. This could be the empty string.
-    # @return [nil] if this source is not fron git.
-    #
-    attr_reader :git_path
-
-    ##
-    # The git commit. This is set if the source, or one of its ancestors, comes
-    # from git.
-    #
-    # @return [String] The git commit.
-    # @return [nil] if this source is not fron git.
-    #
-    attr_reader :git_commit
-
-    ##
-    # A user-visible name of this source.
-    #
-    # @return [String]
-    #
-    attr_reader :source_name
-    alias to_s source_name
-
-    ##
-    # Locate the given data file or directory and return an absolute path.
-    #
-    # @param path [String] The relative path to find
-    # @param type [nil,:file,:directory] Type of file system object to find,
-    #     or nil (the default) to return any type.
-    # @return [String] Absolute path of the resulting data.
-    # @return [nil] if the data was not found.
-    #
-    def find_data(path, type: nil)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Apply all lib paths in order from high to low priority
-    #
-    # @return [self]
-    #
-    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_middleware/add_verbosity_flags.rb

@@ -1,49 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A middleware that provides flags for editing the verbosity.
-    #
-    # This middleware adds `-v`, `--verbose`, `-q`, and `--quiet` flags, if
-    # not already defined by the tool. These flags affect the setting of
-    # {Toys::Context::Key::VERBOSITY}, and, thus, the logger level.
-    #
-    class AddVerbosityFlags
-      ##
-      # Default verbose flags
-      # @return [Array<String>]
-      #
-      DEFAULT_VERBOSE_FLAGS = ["-v", "--verbose"].freeze
-
-      ##
-      # Default quiet flags
-      # @return [Array<String>]
-      #
-      DEFAULT_QUIET_FLAGS = ["-q", "--quiet"].freeze
-
-      ##
-      # Create a AddVerbosityFlags middleware.
-      #
-      # @param verbose_flags [Boolean,Array<String>,Proc] Specify flags
-      #     to increase verbosity. The value may be any of the following:
-      #
-      #     *  An array of flags that increase verbosity.
-      #     *  The `true` value to use {DEFAULT_VERBOSE_FLAGS}. (Default)
-      #     *  The `false` value to disable verbose flags.
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param quiet_flags [Boolean,Array<String>,Proc] Specify flags
-      #     to decrease verbosity. The value may be any of the following:
-      #
-      #     *  An array of flags that decrease verbosity.
-      #     *  The `true` value to use {DEFAULT_QUIET_FLAGS}. (Default)
-      #     *  The `false` value to disable quiet flags.
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      def initialize(verbose_flags: true, quiet_flags: true)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/standard_middleware/apply_config.rb

@@ -1,24 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A middleware that applies the given block to all tool configurations.
-    #
-    class ApplyConfig
-      ##
-      # Create an ApplyConfig middleware
-      #
-      # @param parent_source [Toys::SourceInfo] The SourceInfo corresponding to
-      #     the source where this block is provided, or `nil` (the default) if
-      #     the block does not come from a Toys file.
-      # @param source_name [String] A user-visible name for the source, or
-      #     `nil` to use the default.
-      # @param block [Proc] The configuration to apply.
-      #
-      def initialize(parent_source: nil, source_name: nil, &block)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/standard_middleware/handle_usage_errors.rb

@@ -1,33 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # This middleware handles the case of a usage error. If a usage error, such
-    # as an unrecognized flag or an unfulfilled required argument, is detected,
-    # this middleware intercepts execution and displays the error along with
-    # the short help string, and terminates execution with an error code.
-    #
-    class HandleUsageErrors
-      ##
-      # Exit code for usage error. (2 by convention)
-      # @return [Integer]
-      #
-      USAGE_ERROR_EXIT_CODE = 2
-
-      ##
-      # Create a HandleUsageErrors middleware.
-      #
-      # @param exit_code [Integer] The exit code to return if a usage error
-      #     occurs. Default is {USAGE_ERROR_EXIT_CODE}.
-      # @param stream [IO] Output stream to write to. Default is stderr.
-      # @param styled_output [Boolean,nil] Cause the tool to display help text
-      #     with ansi styles. If `nil`, display styles if the output stream is
-      #     a tty. Default is `nil`.
-      #
-      def initialize(exit_code: nil, stream: $stderr, styled_output: nil)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/standard_middleware/set_default_descriptions.rb

@@ -1,222 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # This middleware sets default description fields for tools and command
-    # line arguments and flags that do not have them set otherwise.
-    #
-    # You can modify the static descriptions for tools, namespaces, and the
-    # root tool by passing parameters to this middleware. For finer control,
-    # you can override methods to modify the description generation logic.
-    #
-    class SetDefaultDescriptions
-      ##
-      # The default description for tools.
-      # @return [String]
-      #
-      DEFAULT_TOOL_DESC = "(No tool description available)"
-
-      ##
-      # The default description for delegating tools.
-      # @return [String]
-      #
-      DEFAULT_DELEGATE_DESC = '(Delegates to "%<target>s")'
-
-      ##
-      # The default description for namespaces.
-      # @return [String]
-      #
-      DEFAULT_NAMESPACE_DESC = "(A namespace of tools)"
-
-      ##
-      # The default description for the root tool.
-      # @return [String]
-      #
-      DEFAULT_ROOT_DESC = "Command line tool built using the toys-core gem."
-
-      ##
-      # The default long description for the root tool.
-      # @return [String]
-      #
-      DEFAULT_ROOT_LONG_DESC = [
-        "This command line tool was built using the toys-core gem. See" \
-          " https://dazuma.github.io/toys/gems/toys-core for more info.",
-        "To replace this message, set the description and long description" \
-          " of the root tool, or configure the SetDefaultDescriptions" \
-          " middleware.",
-      ].freeze
-
-      ##
-      # Create a SetDefaultDescriptions middleware given default descriptions.
-      #
-      # @param default_tool_desc [String,nil] The default short description for
-      #     runnable tools, or `nil` not to set one. Defaults to
-      #     {DEFAULT_TOOL_DESC}.
-      # @param default_tool_long_desc [Array<String>,nil] The default long
-      #     description for runnable tools, or `nil` not to set one. Defaults
-      #     to `nil`.
-      # @param default_namespace_desc [String,nil] The default short
-      #     description for non-runnable tools, or `nil` not to set one.
-      #     Defaults to {DEFAULT_TOOL_DESC}.
-      # @param default_namespace_long_desc [Array<String>,nil] The default long
-      #     description for non-runnable tools, or `nil` not to set one.
-      #     Defaults to `nil`.
-      # @param default_root_desc [String,nil] The default short description for
-      #     the root tool, or `nil` not to set one. Defaults to
-      #     {DEFAULT_ROOT_DESC}.
-      # @param default_root_long_desc [Array<String>,nil] The default long
-      #     description for the root tool, or `nil` not to set one. Defaults to
-      #     {DEFAULT_ROOT_LONG_DESC}.
-      # @param default_delegate_desc [String,nil] The default short description
-      #     for delegate tools, or `nil` not to set one. May include an sprintf
-      #     field for the `target` name. Defaults to {DEFAULT_DELEGATE_DESC}.
-      #
-      def initialize(default_tool_desc: DEFAULT_TOOL_DESC,
-                     default_tool_long_desc: nil,
-                     default_namespace_desc: DEFAULT_NAMESPACE_DESC,
-                     default_namespace_long_desc: nil,
-                     default_root_desc: DEFAULT_ROOT_DESC,
-                     default_root_long_desc: DEFAULT_ROOT_LONG_DESC,
-                     default_delegate_desc: DEFAULT_DELEGATE_DESC)
-        # Source available in the toys-core gem
-      end
-
-      protected
-
-      ##
-      # This method implements the logic for generating a tool description.
-      # By default, it uses the parameters given to the middleware object.
-      # Override this method to provide different logic.
-      #
-      # @param tool [Toys::ToolDefinition] The tool to document.
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Loader} is passed with key `:loader`. Future versions
-      #     of Toys may provide additional information.
-      # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::DSL::Tool#desc} for info on the format.
-      # @return [nil] if this middleware should not set the description.
-      #
-      def generate_tool_desc(tool, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements logic for generating a tool long description.
-      # By default, it uses the parameters given to the middleware object.
-      # Override this method to provide different logic.
-      #
-      # @param tool [Toys::ToolDefinition] The tool to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::Loader} is passed with key `:loader`. Future versions of
-      #     Toys may provide additional information.
-      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
-      #     format.
-      # @return [nil] if this middleware should not set the long description.
-      #
-      def generate_tool_long_desc(tool, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements the logic for generating a flag description.
-      # Override this method to provide different logic.
-      #
-      # @param flag [Toys::Flag] The flag to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::DSL::Tool#desc} for info on the format.
-      # @return [nil] if this middleware should not set the description.
-      #
-      def generate_flag_desc(flag, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements logic for generating a flag long description.
-      # Override this method to provide different logic.
-      #
-      # @param flag [Toys::Flag] The flag to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
-      #     format.
-      # @return [nil] if this middleware should not set the long description.
-      #
-      def generate_flag_long_desc(flag, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements the logic for generating an arg description.
-      # Override this method to provide different logic.
-      #
-      # @param arg [Toys::PositionalArg] The arg to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::DSL::Tool#desc} for info on the format.
-      # @return [nil] if this middleware should not set the description.
-      #
-      def generate_arg_desc(arg, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements logic for generating an arg long description.
-      # Override this method to provide different logic.
-      #
-      # @param arg [Toys::PositionalArg] The arg to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
-      #     format.
-      # @return [nil] if this middleware should not set the long description.
-      #
-      def generate_arg_long_desc(arg, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements the logic for generating a flag group
-      # description. Override this method to provide different logic.
-      #
-      # @param group [Toys::FlagGroup] The flag group to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [String,Array<String>,Toys::WrappableString] The default
-      #     description. See {Toys::DSL::Tool#desc} for info on the format.
-      # @return [nil] if this middleware should not set the description.
-      #
-      def generate_flag_group_desc(group, data)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # This method implements the logic for generating a flag group long
-      # description. Override this method to provide different logic.
-      #
-      # @param group [Toys::FlagGroup] The flag group to document
-      # @param data [Hash] Additional data that might be useful. Currently,
-      #     the {Toys::ToolDefinition} is passed with key `:tool`. Future
-      #     versions of Toys may provide additional information.
-      # @return [Array<Toys::WrappableString,String,Array<String>>] The default
-      #     long description. See {Toys::DSL::Tool#long_desc} for info on the
-      #     format.
-      # @return [nil] if this middleware should not set the long description.
-      #
-      def generate_flag_group_long_desc(group, data)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end