toys 0.12.2 → 0.13.0

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

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

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

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

@@ -0,0 +1,83 @@
+module Toys
+  module StandardMixins
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # Ensures that a bundle is installed and set up when this tool is run.
+    #
+    # 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 wearching 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