toys 0.15.6 → 0.16.0

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

@@ -1,190 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A middleware that shows help text for the tool when a flag (typically
-    # `--help`) is provided. It can also be configured to show help by
-    # default if the tool is a namespace that is not runnable.
-    #
-    # If a tool is not runnable, this middleware can also add a
-    # `--[no-]recursive` flag, which, when set to `true` (the default), shows
-    # all subtools recursively rather than only immediate subtools. This
-    # middleware can also search for keywords in its subtools.
-    #
-    class ShowHelp
-      ##
-      # Default help flags
-      # @return [Array<String>]
-      #
-      DEFAULT_HELP_FLAGS = ["-?", "--help"].freeze
-
-      ##
-      # Default usage flags
-      # @return [Array<String>]
-      #
-      DEFAULT_USAGE_FLAGS = ["--usage"].freeze
-
-      ##
-      # Default list subtools flags
-      # @return [Array<String>]
-      #
-      DEFAULT_LIST_FLAGS = ["--tools"].freeze
-
-      ##
-      # Default recursive flags
-      # @return [Array<String>]
-      #
-      DEFAULT_RECURSIVE_FLAGS = ["-r", "--[no-]recursive"].freeze
-
-      ##
-      # Default search flags
-      # @return [Array<String>]
-      #
-      DEFAULT_SEARCH_FLAGS = ["-s WORD", "--search=WORD"].freeze
-
-      ##
-      # Default show-all-subtools flags
-      # @return [Array<String>]
-      #
-      DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS = ["--all"].freeze
-
-      ##
-      # Key set when the show help flag is present
-      # @return [Object]
-      #
-      SHOW_HELP_KEY = Object.new.freeze
-
-      ##
-      # Key set when the show usage flag is present
-      # @return [Object]
-      #
-      SHOW_USAGE_KEY = Object.new.freeze
-
-      ##
-      # Key set when the show subtool list flag is present
-      # @return [Object]
-      #
-      SHOW_LIST_KEY = Object.new.freeze
-
-      ##
-      # Key for the recursive setting
-      # @return [Object]
-      #
-      RECURSIVE_SUBTOOLS_KEY = Object.new.freeze
-
-      ##
-      # Key for the search string
-      # @return [Object]
-      #
-      SEARCH_STRING_KEY = Object.new.freeze
-
-      ##
-      # Key for the show-all-subtools setting
-      # @return [Object]
-      #
-      SHOW_ALL_SUBTOOLS_KEY = Object.new.freeze
-
-      ##
-      # Key for the tool name
-      # @return [Object]
-      #
-      TOOL_NAME_KEY = Object.new.freeze
-
-      ##
-      # Create a ShowHelp middleware.
-      #
-      # @param help_flags [Boolean,Array<String>,Proc] Specify flags to
-      #     display help. The value may be any of the following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_HELP_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param usage_flags [Boolean,Array<String>,Proc] Specify flags to
-      #     display usage. The value may be any of the following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_USAGE_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param list_flags [Boolean,Array<String>,Proc] Specify flags to
-      #     display subtool list. The value may be any of the following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_LIST_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param recursive_flags [Boolean,Array<String>,Proc] Specify flags
-      #     to control recursive subtool search. The value may be any of the
-      #     following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_RECURSIVE_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param search_flags [Boolean,Array<String>,Proc] Specify flags
-      #     to search subtools for a search term. The value may be any of
-      #     the following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_SEARCH_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param show_all_subtools_flags [Boolean,Array<String>,Proc] Specify
-      #     flags to show all subtools, including hidden tools and non-runnable
-      #     namespaces. The value may be any of the following:
-      #
-      #     *  An array of flags.
-      #     *  The `true` value to use {DEFAULT_SHOW_ALL_SUBTOOLS_FLAGS}.
-      #     *  The `false` value for no flags. (Default)
-      #     *  A proc that takes a tool and returns any of the above.
-      #
-      # @param default_recursive [Boolean] Whether to search recursively for
-      #     subtools by default. Default is `false`.
-      # @param default_show_all_subtools [Boolean] Whether to show all subtools
-      #     by default. Default is `false`.
-      # @param fallback_execution [Boolean] Cause the tool to display its own
-      #     help text if it is not otherwise runnable. This is mostly useful
-      #     for namespaces, which have children are not runnable. Default is
-      #     `false`.
-      # @param allow_root_args [Boolean] If the root tool includes flags for
-      #     help or usage, and doesn't otherwise use positional arguments,
-      #     then a tool name can be passed as arguments to display help for
-      #     that tool.
-      # @param show_source_path [Boolean] Show the source path section. Default
-      #     is `false`.
-      # @param separate_sources [Boolean] Split up tool list by source root.
-      #     Defaults to false.
-      # @param use_less [Boolean] If the `less` tool is available, and the
-      #     output stream is a tty, then use `less` to display help text.
-      # @param stream [IO] Output stream to write to. Default is stdout.
-      # @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(help_flags: false,
-                     usage_flags: false,
-                     list_flags: false,
-                     recursive_flags: false,
-                     search_flags: false,
-                     show_all_subtools_flags: false,
-                     default_recursive: false,
-                     default_show_all_subtools: false,
-                     fallback_execution: false,
-                     allow_root_args: false,
-                     show_source_path: false,
-                     separate_sources: false,
-                     use_less: false,
-                     stream: $stdout,
-                     styled_output: nil)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

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

@@ -1,45 +0,0 @@
-module Toys
-  module StandardMiddleware
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A middleware that displays a version string for the root tool if the
-    # `--version` flag is given.
-    #
-    class ShowRootVersion
-      ##
-      # Default version flags
-      # @return [Array<String>]
-      #
-      DEFAULT_VERSION_FLAGS = ["--version"].freeze
-
-      ##
-      # Default description for the version flags
-      # @return [String]
-      #
-      DEFAULT_VERSION_FLAG_DESC = "Display the version"
-
-      ##
-      # Key set when the version flag is present
-      # @return [Object]
-      #
-      SHOW_VERSION_KEY = Object.new.freeze
-
-      ##
-      # Create a ShowVersion middleware
-      #
-      # @param version_string [String] The string that should be displayed.
-      # @param version_flags [Array<String>] A list of flags that should
-      #     trigger displaying the version. Default is
-      #     {DEFAULT_VERSION_FLAGS}.
-      # @param stream [IO] Output stream to write to. Default is stdout.
-      #
-      def initialize(version_string: nil,
-                     version_flags: DEFAULT_VERSION_FLAGS,
-                     version_flag_desc: DEFAULT_VERSION_FLAG_DESC,
-                     stream: $stdout)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

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

@@ -1,98 +0,0 @@
-module Toys
-  module StandardMixins
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # Ensures that a bundle is installed and set up when this tool is run.
-    #
-    # This is the normal recommended way to use [bundler](https://bundler.io)
-    # with Toys. Including this mixin in a tool will cause Toys to ensure that
-    # the bundle is installed and available during tool execution. For example:
-    #
-    #     tool "run-rails" do
-    #       include :bundler
-    #       def run
-    #         # Note: no "bundle exec" required because Toys has already
-    #         # installed and loaded the bundle.
-    #         exec "rails s"
-    #       end
-    #     end
-    #
-    # ### Customization
-    #
-    # The following parameters can be passed when including this mixin:
-    #
-    #  *  `:static` (Boolean) If `true`, installs the bundle immediately, when
-    #     defining the tool. If `false` (the default), installs the bundle just
-    #     before the tool runs.
-    #
-    #  *  `:groups` (Array\<String\>) The groups to include in setup.
-    #
-    #  *  `:gemfile_path` (String) The path to the Gemfile to use. If `nil` or
-    #     not given, the `:search_dirs` will be searched for a Gemfile.
-    #
-    #  *  `:search_dirs` (String,Symbol,Array\<String,Symbol\>) Directories to
-    #     search for a Gemfile.
-    #
-    #     You can pass full directory paths, and/or any of the following:
-    #      *  `:context` - the current context directory.
-    #      *  `:current` - the current working directory.
-    #      *  `:toys` - the Toys directory containing the tool definition, and
-    #         any of its parents within the Toys directory hierarchy.
-    #
-    #     The default is to search `[:toys, :context, :current]` in that order.
-    #     See {DEFAULT_SEARCH_DIRS}.
-    #
-    #     For most directories, the bundler mixin will look for the files
-    #     ".gems.rb", "gems.rb", and "Gemfile", in that order. In `:toys`
-    #     directories, it will look only for ".gems.rb" and "Gemfile", in that
-    #     order. These can be overridden by setting the `:gemfile_names` and/or
-    #     `:toys_gemfile_names` arguments.
-    #
-    #  *  `:gemfile_names` (Array\<String\>) File names that are recognized as
-    #     Gemfiles when searching in directories other than Toys directories.
-    #     Defaults to {Toys::Utils::Gems::DEFAULT_GEMFILE_NAMES}.
-    #
-    #  *  `:toys_gemfile_names` (Array\<String\>) File names that are
-    #     recognized as Gemfiles when searching in Toys directories.
-    #     Defaults to {DEFAULT_TOYS_GEMFILE_NAMES}.
-    #
-    #  *  `:on_missing` (Symbol) What to do if a needed gem is not installed.
-    #
-    #     Supported values:
-    #      *  `:confirm` - prompt the user on whether to install (default).
-    #      *  `:error` - raise an exception.
-    #      *  `:install` - just install the gem.
-    #
-    #  *  `:on_conflict` (Symbol) What to do if bundler has already been run
-    #     with a different Gemfile.
-    #
-    #     Supported values:
-    #      *  `:error` - raise an exception (default).
-    #      *  `:ignore` - just silently proceed without bundling again.
-    #      *  `:warn` - print a warning and proceed without bundling again.
-    #
-    #  *  `:retries` (Integer) Number of times to retry bundler operations
-    #     (optional)
-    #
-    #  *  `:terminal` (Toys::Utils::Terminal) Terminal to use (optional)
-    #  *  `:input` (IO) Input IO (optional, defaults to STDIN)
-    #  *  `:output` (IO) Output IO (optional, defaults to STDOUT)
-    #
-    module Bundler
-      include Mixin
-
-      ##
-      # Default search directories for Gemfiles.
-      # @return [Array<String,Symbol>]
-      #
-      DEFAULT_SEARCH_DIRS = [:toys, :context, :current].freeze
-
-      ##
-      # The gemfile names that are searched by default in Toys directories.
-      # @return [Array<String>]
-      #
-      DEFAULT_TOYS_GEMFILE_NAMES = [".gems.rb", "Gemfile"].freeze
-    end
-  end
-end