toys 0.12.2 → 0.13.0

data/core-docs/toys/utils/gems.rb

@@ -0,0 +1,185 @@
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A helper class that activates and installs gems and sets up bundler.
+    #
+    # This class is not loaded by default. Before using it directly, you should
+    # `require "toys/utils/gems"`
+    #
+    class Gems
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Failed to activate a gem.
+      #
+      class ActivationFailedError < ::StandardError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Failed to install a gem.
+      #
+      class InstallFailedError < ActivationFailedError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Need to add a gem to the bundle.
+      #
+      class GemfileUpdateNeededError < ActivationFailedError
+        ##
+        # Create a GemfileUpdateNeededError.
+        #
+        # @param requirements_text [String] Gems and versions missing.
+        # @param gemfile_path [String] Path to the offending Gemfile.
+        #
+        def initialize(requirements_text, gemfile_path)
+          # Source available in the toys-core gem
+        end
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Failed to run Bundler
+      #
+      class BundlerFailedError < ::StandardError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Could not find a Gemfile
+      #
+      class GemfileNotFoundError < BundlerFailedError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # The bundle is not and could not be installed
+      #
+      class BundleNotInstalledError < BundlerFailedError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Bundler has already been run; cannot do so again
+      #
+      class AlreadyBundledError < BundlerFailedError
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # The bundle contained a toys or toys-core dependency that is
+      # incompatible with the currently running version.
+      #
+      class IncompatibleToysError < BundlerFailedError
+      end
+
+      ##
+      # The gemfile names that are searched by default.
+      # @return [Array<String>]
+      #
+      DEFAULT_GEMFILE_NAMES = [".gems.rb", "gems.rb", "Gemfile"].freeze
+
+      ##
+      # Activate the given gem. If it is not present, attempt to install it (or
+      # inform the user to update the bundle).
+      #
+      # @param name [String] Name of the gem
+      # @param requirements [String...] Version requirements
+      # @return [void]
+      #
+      def self.activate(name, *requirements)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Create a new gem activator.
+      #
+      # @param on_missing [:confirm,:error,:install] What to do if a needed gem
+      #     is not installed. Possible values:
+      #
+      #      *  `:confirm` - prompt the user on whether to install
+      #      *  `:error` - raise an exception
+      #      *  `:install` - just install the gem
+      #
+      #     The default is `:confirm`.
+      #
+      # @param on_conflict [:error,:warn,:ignore] What to do if bundler has
+      #     already been run with a different Gemfile. Possible values:
+      #
+      #      *  `:error` - raise an exception
+      #      *  `:ignore` - just silently proceed without bundling again
+      #      *  `:warn` - print a warning and proceed without bundling again
+      #
+      #     The default is `:error`.
+      #
+      # @param terminal [Toys::Utils::Terminal] Terminal to use (optional)
+      # @param input [IO] Input IO (optional, defaults to STDIN)
+      # @param output [IO] Output IO (optional, defaults to STDOUT)
+      # @param suppress_confirm [Boolean] Deprecated. Use `on_missing` instead.
+      # @param default_confirm [Boolean] Deprecated. Use `on_missing` instead.
+      #
+      def initialize(on_missing: nil,
+                     on_conflict: nil,
+                     terminal: nil,
+                     input: nil,
+                     output: nil,
+                     suppress_confirm: nil,
+                     default_confirm: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Activate the given gem. If it is not present, attempt to install it (or
+      # inform the user to update the bundle).
+      #
+      # @param name [String] Name of the gem
+      # @param requirements [String...] Version requirements
+      # @return [void]
+      #
+      def activate(name, *requirements)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Search for an appropriate Gemfile, and set up the bundle.
+      #
+      # @param groups [Array<String>] The groups to include in setup.
+      #
+      # @param gemfile_path [String] The path to the Gemfile to use. If `nil`
+      #     or not given, the `:search_dirs` will be searched for a Gemfile.
+      #
+      # @param search_dirs [String,Array<String>] Directories in which to
+      #     search for a Gemfile, if gemfile_path is not given. You can provide
+      #     a single directory or an array of directories.
+      #
+      # @param gemfile_names [String,Array<String>] File names that are
+      #     recognized as Gemfiles, when searching because gemfile_path is not
+      #     given. Defaults to {DEFAULT_GEMFILE_NAMES}.
+      #
+      # @param retries [Integer] Number of times to retry bundler operations.
+      #     Optional.
+      #
+      # @return [void]
+      #
+      def bundle(groups: nil,
+                 gemfile_path: nil,
+                 search_dirs: nil,
+                 gemfile_names: nil,
+                 retries: nil)
+        # Source available in the toys-core gem
+      end
+
+      @global_mutex = ::Monitor.new
+    end
+  end
+end

data/core-docs/toys/utils/git_cache.rb

@@ -0,0 +1,353 @@
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # This object provides cached access to remote git data. Given a remote
+    # repository, a path, and a commit, it makes the files availble in the
+    # local filesystem. Access is cached, so repeated requests for the same
+    # commit and path in the same repo do not hit the remote repository again.
+    #
+    # This class is used by the Loader to load tools from git. Tools can also
+    # use the `:git_cache` mixin for direct access to this class.
+    #
+    class GitCache
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # GitCache encountered a failure
+      #
+      class Error < ::StandardError
+        ##
+        # Create a GitCache::Error.
+        #
+        # @param message [String] The error message
+        # @param result [Toys::Utils::Exec::Result] The result of a git
+        #     command execution, or `nil` if this error was not due to a git
+        #     command error.
+        #
+        def initialize(message, result)
+          # Source available in the toys-core gem
+        end
+
+        ##
+        # @return [Toys::Utils::Exec::Result] The result of a git command
+        #     execution, or `nil` if this error was not due to a git command
+        #     error.
+        #
+        attr_reader :exec_result
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Information about a remote git repository in the cache.
+      #
+      # This object is returned from {GitCache#repo_info}.
+      #
+      class RepoInfo
+        include ::Comparable
+
+        ##
+        # The base directory of this git repository's cache entry. This
+        # directory contains all cached data related to this repo. Deleting it
+        # effectively removes the repo from the cache.
+        #
+        # @return [String]
+        #
+        attr_reader :base_dir
+
+        ##
+        # The git remote, usually a file system path or URL.
+        #
+        # @return [String]
+        #
+        attr_reader :remote
+
+        ##
+        # The last time any cached data from this repo was accessed, or `nil`
+        # if the information is unavailable.
+        #
+        # @return [Time,nil]
+        #
+        attr_reader :last_accessed
+
+        ##
+        # A list of git refs (branches, tags, shas) that have been accessed
+        # from this repo.
+        #
+        # @return [Array<RefInfo>]
+        #
+        attr_reader :refs
+
+        ##
+        # A list of shared source files and directories accessed for this repo.
+        #
+        # @return [Array<SourceInfo>]
+        #
+        attr_reader :sources
+
+        ##
+        # Convert this RepoInfo to a hash suitable for JSON output
+        #
+        # @return [Hash]
+        #
+        def to_h
+          # Source available in the toys-core gem
+        end
+
+        ##
+        # Comparison function
+        #
+        # @param other [RepoInfo]
+        # @return [Integer]
+        #
+        def <=>(other)
+          # Source available in the toys-core gem
+        end
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Information about a git ref used in a cache.
+      #
+      class RefInfo
+        include ::Comparable
+
+        ##
+        # The git ref
+        #
+        # @return [String]
+        #
+        attr_reader :ref
+
+        ##
+        # The git sha last associated with the ref
+        #
+        # @return [String]
+        #
+        attr_reader :sha
+
+        ##
+        # The timestamp when this ref was last accessed
+        #
+        # @return [Time]
+        #
+        attr_reader :last_accessed
+
+        ##
+        # The timestamp when this ref was last updated
+        #
+        # @return [Time]
+        #
+        attr_reader :last_updated
+
+        ##
+        # Convert this RefInfo to a hash suitable for JSON output
+        #
+        # @return [Hash]
+        #
+        def to_h
+          # Source available in the toys-core gem
+        end
+
+        ##
+        # Comparison function
+        #
+        # @param other [RefInfo]
+        # @return [Integer]
+        #
+        def <=>(other)
+          # Source available in the toys-core gem
+        end
+      end
+
+      ##
+      # **_Defined in the toys-core gem_**
+      #
+      # Information about shared source files provided from the cache.
+      #
+      class SourceInfo
+        include ::Comparable
+
+        ##
+        # The git sha the source comes from
+        #
+        # @return [String]
+        #
+        attr_reader :sha
+
+        ##
+        # The path within the git repo
+        #
+        # @return [String]
+        #
+        attr_reader :git_path
+
+        ##
+        # The path to the source file or directory
+        #
+        # @return [String]
+        #
+        attr_reader :source
+
+        ##
+        # The timestamp when this ref was last accessed
+        #
+        # @return [Time]
+        #
+        attr_reader :last_accessed
+
+        ##
+        # Convert this SourceInfo to a hash suitable for JSON output
+        #
+        # @return [Hash]
+        #
+        def to_h
+          # Source available in the toys-core gem
+        end
+
+        ##
+        # Comparison function
+        #
+        # @param other [SourceInfo]
+        # @return [Integer]
+        #
+        def <=>(other)
+          # Source available in the toys-core gem
+        end
+      end
+
+      ##
+      # Access a git cache.
+      #
+      # @param cache_dir [String] The path to the cache directory. Defaults to
+      #     a specific directory in the user's XDG cache.
+      #
+      def initialize(cache_dir: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # The cache directory.
+      #
+      # @return [String]
+      #
+      attr_reader :cache_dir
+
+      ##
+      # Get the given git-based files from the git cache, loading from the
+      # remote repo if necessary.
+      #
+      # The resulting files are either copied into a directory you provide in
+      # the `:into` parameter, or populated into a _shared_ source directory if
+      # you omit the `:info` parameter. In the latter case, it is important
+      # that you do not modify the returned files or directories, nor add or
+      # remove any files from the directories returned, to avoid confusing
+      # callers that could be given the same directory. If you need to make any
+      # modifications to the returned files, use `:into` to provide your own
+      # private directory.
+      #
+      # @param remote [String] The URL of the git repo. Required.
+      # @param path [String] The path to the file or directory within the repo.
+      #     Optional. Defaults to the entire repo.
+      # @param commit [String] The commit reference, which may be a SHA or any
+      #     git ref such as a branch or tag. Optional. Defaults to `HEAD`.
+      # @param into [String] If provided, copies the specified files into the
+      #     given directory path. If omitted or `nil`, populates and returns a
+      #     shared source file or directory.
+      # @param update [Boolean,Integer] Whether to update of non-SHA commit
+      #     references if they were previously loaded. This is useful, for
+      #     example, if the commit is `HEAD` or a branch name. Pass `true` or
+      #     `false` to specify whether to update, or an integer to update if
+      #     last update was done at least that many seconds ago. Default is
+      #     `false`.
+      #
+      # @return [String] The full path to the cached files. The returned path
+      #     will correspod to the path given. For example, if you provide the
+      #     path `Gemfile` representing a single file in the repository, the
+      #     returned path will point directly to the cached copy of that file.
+      #
+      def get(remote, path: nil, commit: nil, into: nil, update: false, timestamp: nil)
+        # Source available in the toys-core gem
+      end
+      alias find get
+
+      ##
+      # Returns an array of the known remote names.
+      #
+      # @return [Array<String>]
+      #
+      def remotes
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Returns a {RepoInfo} describing the cache for the given remote, or
+      # `nil` if the given remote has never been cached.
+      #
+      # @param remote [String] Remote name for a repo
+      # @return [RepoInfo,nil]
+      #
+      def repo_info(remote)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Removes caches for the given repos, or all repos if specified.
+      #
+      # Removes all cache information for the specified repositories, including
+      # local clones and shared source directories. The next time these
+      # repositories are requested, they will be reloaded from the remote
+      # repository from scratch.
+      #
+      # Be careful not to remove repos that are currently in use by other
+      # GitCache clients.
+      #
+      # @param remotes [Array<String>,:all] The remotes to remove.
+      # @return [Array<String>] The remotes actually removed.
+      #
+      def remove_repos(remotes)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Remove records of the given refs (i.e. branches, tags, or `HEAD`) from
+      # the given repository's cache. The next time those refs are requested,
+      # they will be pulled from the remote repo.
+      #
+      # If you provide the `refs:` argument, only those refs are removed.
+      # Otherwise, all refs are removed.
+      #
+      # @param remote [String] The repository
+      # @param refs [Array<String>] The refs to remove. Optional.
+      # @return [Array<RefInfo>,nil] The refs actually forgotten, or `nil` if
+      #     the given repo is not in the cache.
+      #
+      def remove_refs(remote, refs: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Removes shared sources for the given cache. The next time a client
+      # requests them, the removed sources will be recopied from the repo.
+      #
+      # If you provide the `commits:` argument, only sources associated with
+      # those commits are removed. Otherwise, all sources are removed.
+      #
+      # Be careful not to remove sources that are currently in use by other
+      # GitCache clients.
+      #
+      # @param remote [String] The repository
+      # @param commits [Array<String>] Remove only the sources for the given
+      #     commits. Optional.
+      # @return [Array<SourceInfo>,nil] The sources actually removed, or `nil`
+      #     if the given repo is not in the cache.
+      #
+      def remove_sources(remote, commits: nil)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end

data/core-docs/toys/utils/help_text.rb

@@ -0,0 +1,134 @@
+module Toys
+  module Utils
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A helper class that generates usage documentation for a tool.
+    #
+    # This class generates full usage documentation, including description,
+    # flags, and arguments. It is used by middleware that implements help
+    # and related options.
+    #
+    # This class is not loaded by default. Before using it directly, you should
+    # `require "toys/utils/help_text"`
+    #
+    class HelpText
+      ##
+      # Default width of first column
+      # @return [Integer]
+      #
+      DEFAULT_LEFT_COLUMN_WIDTH = 32
+
+      ##
+      # Default indent
+      # @return [Integer]
+      #
+      DEFAULT_INDENT = 4
+
+      ##
+      # Create a usage helper given an execution context.
+      #
+      # @param context [Toys::Context] The current context.
+      # @return [Toys::Utils::HelpText]
+      #
+      def self.from_context(context)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Create a usage helper.
+      #
+      # @param tool [Toys::ToolDefinition] The tool to document.
+      # @param loader [Toys::Loader] A loader that can provide subcommands.
+      # @param executable_name [String] The name of the executable.
+      #     e.g. `"toys"`.
+      # @param delegates [Array<Toys::ToolDefinition>] The delegation path to
+      #     the tool.
+      #
+      # @return [Toys::Utils::HelpText]
+      #
+      def initialize(tool, loader, executable_name, delegates: [])
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # The ToolDefinition being documented.
+      # @return [Toys::ToolDefinition]
+      #
+      attr_reader :tool
+
+      ##
+      # Generate a short usage string.
+      #
+      # @param recursive [Boolean] If true, and the tool is a namespace,
+      #     display all subtools recursively. Defaults to false.
+      # @param include_hidden [Boolean] Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
+      # @param left_column_width [Integer] Width of the first column. Default
+      #     is {DEFAULT_LEFT_COLUMN_WIDTH}.
+      # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
+      # @param wrap_width [Integer,nil] Overall width to wrap to. Default is
+      #     `nil` indicating no wrapping.
+      #
+      # @return [String] A usage string.
+      #
+      def usage_string(recursive: false, include_hidden: false, separate_sources: false,
+                       left_column_width: nil, indent: nil, wrap_width: nil)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Generate a long help string.
+      #
+      # @param recursive [Boolean] If true, and the tool is a namespace,
+      #     display all subtools recursively. Defaults to false.
+      # @param search [String,nil] An optional string to search for when
+      #     listing subtools. Defaults to `nil` which finds all subtools.
+      # @param include_hidden [Boolean] Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
+      # @param show_source_path [Boolean] If true, shows the source path
+      #     section. Defaults to false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
+      # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
+      # @param indent2 [Integer] Second indent width. Default is
+      #     {DEFAULT_INDENT}.
+      # @param wrap_width [Integer,nil] Wrap width of the column, or `nil` to
+      #     disable wrap. Default is `nil`.
+      # @param styled [Boolean] Output ansi styles. Default is `true`.
+      #
+      # @return [String] A usage string.
+      #
+      def help_string(recursive: false, search: nil, include_hidden: false,
+                      show_source_path: false, separate_sources: false,
+                      indent: nil, indent2: nil, wrap_width: nil, styled: true)
+        # Source available in the toys-core gem
+      end
+
+      ##
+      # Generate a subtool list string.
+      #
+      # @param recursive [Boolean] If true, and the tool is a namespace,
+      #     display all subtools recursively. Defaults to false.
+      # @param search [String,nil] An optional string to search for when
+      #     listing subtools. Defaults to `nil` which finds all subtools.
+      # @param include_hidden [Boolean] Include hidden subtools (i.e. whose
+      #     names begin with underscore.) Default is false.
+      # @param separate_sources [Boolean] Split up tool list by source root.
+      #     Defaults to false.
+      # @param indent [Integer] Indent width. Default is {DEFAULT_INDENT}.
+      # @param wrap_width [Integer,nil] Wrap width of the column, or `nil` to
+      #     disable wrap. Default is `nil`.
+      # @param styled [Boolean] Output ansi styles. Default is `true`.
+      #
+      # @return [String] A usage string.
+      #
+      def list_string(recursive: false, search: nil, include_hidden: false,
+                      separate_sources: false, indent: nil, wrap_width: nil, styled: true)
+        # Source available in the toys-core gem
+      end
+    end
+  end
+end