toys 0.17.1 → 0.17.2

data/core-docs/toys/source_info.rb

@@ -0,0 +1,321 @@
+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 file or directory loaded from a gem
+  # * 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
+
+    ##
+    # The gem name. This is set if the source, or one of its ancestors, comes
+    # from a gem.
+    #
+    # @return [String] The gem name.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_name
+
+    ##
+    # The gem version. This is set if the source, or one of its ancestors,
+    # comes from a gem.
+    #
+    # @return [Gem::Version] The gem version.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_version
+
+    ##
+    # The path within the gem, including the toys root directory in the gem.
+    #
+    # @return [String] The path.
+    # @return [nil] if this source is not from a gem.
+    #
+    attr_reader :gem_path
+
+    ##
+    # 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, gem_name, gem_version, gem_path,
+                   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 child SourceInfo with a gem source.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def gem_child(child_gem_name, child_gem_version, child_gem_path, 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 loaded gem.
+    #
+    # @private This interface is internal and subject to change without warning.
+    #
+    def self.create_gem_root(gem_name, gem_version, gem_path, 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

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

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

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

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