toys 0.15.6 → 0.16.0

data/core-docs/toys/context.rb

@@ -1,386 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # This is the base class for tool execution. It represents `self` when your
-  # tool's methods (such as `run`) are called, and it defines the methods that
-  # can be called by your tool (such as {#logger} and {#exit}.)
-  #
-  # This class also manages the "data" available to your tool when it runs.
-  # This data is a hash of key-value pairs. It consists of values set by flags
-  # and arguments defined by the tool, plus some "well-known" values such as
-  # the logger and verbosity level.
-  #
-  # You can obtain a value from the data using the {Toys::Context#get} method.
-  # Additionally, convenience methods are provided for many of the well-known
-  # keys. For instance, you can call {Toys::Context#verbosity} to obtain the
-  # value for the key {Toys::Context::Key::VERBOSITY}. Finally, flags and
-  # positional arguments that store their data here will also typically
-  # generate convenience methods. For example, an argument with key `:abc` will
-  # add a method called `abc` that you can call to get the value.
-  #
-  # By convention, flags and arguments defined by your tool should use strings
-  # or symbols as keys. Keys that are not strings or symbols should either be
-  # well-known keys such as {Toys::Context::Key::VERBOSITY}, or should be used
-  # for internal private information needed by middleware and mixins. The
-  # module {Toys::Context::Key} defines a number of well-known keys as
-  # constants.
-  #
-  class Context
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # Well-known context keys.
-    #
-    # This module is mixed into the runtime context. This means you can
-    # reference any of these constants directly from your run method.
-    #
-    # ### Example
-    #
-    #     tool "my-name" do
-    #       def run
-    #         # TOOL_NAME is available here.
-    #         puts "My name is #{get(TOOL_NAME)}"
-    #       end
-    #     end
-    #
-    module Key
-      ##
-      # Context key for the argument list passed to the current tool. Value is
-      # an array of strings.
-      # @return [Object]
-      #
-      ARGS = ::Object.new.freeze
-
-      ##
-      # Context key for the currently running {Toys::CLI}. You can use the
-      # value to run other tools from your tool by calling {Toys::CLI#run}.
-      # @return [Object]
-      #
-      CLI = ::Object.new.freeze
-
-      ##
-      # Context key for the context directory path. The value is a string
-      # @return [Object]
-      #
-      CONTEXT_DIRECTORY = ::Object.new.freeze
-
-      ##
-      # Context key for the context from which the current call was delegated.
-      # The value is either another context object, or `nil` if the current
-      # call is not delegated.
-      # @return [Object]
-      #
-      DELEGATED_FROM = ::Object.new.freeze
-
-      ##
-      # Context key for the active `Logger` object.
-      # @return [Object]
-      #
-      LOGGER = ::Object.new.freeze
-
-      ##
-      # Context key for the {Toys::ToolDefinition} object being executed.
-      # @return [Object]
-      #
-      TOOL = ::Object.new.freeze
-
-      ##
-      # Context key for the full name of the tool being executed. Value is an
-      # array of strings.
-      # @return [Object]
-      #
-      TOOL_NAME = ::Object.new.freeze
-
-      ##
-      # Context key for the {Toys::SourceInfo} describing the source of this
-      # tool.
-      # @return [Object]
-      #
-      TOOL_SOURCE = ::Object.new.freeze
-
-      ##
-      # Context key for all unmatched args in order. The value is an array of
-      # strings.
-      # @return [Object]
-      #
-      UNMATCHED_ARGS = ::Object.new.freeze
-
-      ##
-      # Context key for unmatched flags. The value is an array of strings.
-      # @return [Object]
-      #
-      UNMATCHED_FLAGS = ::Object.new.freeze
-
-      ##
-      # Context key for unmatched positional args. The value is an array of
-      # strings.
-      # @return [Object]
-      #
-      UNMATCHED_POSITIONAL = ::Object.new.freeze
-
-      ##
-      # Context key for the list of usage errors raised. The value is an array
-      # of {Toys::ArgParser::UsageError}.
-      # @return [Object]
-      #
-      USAGE_ERRORS = ::Object.new.freeze
-
-      ##
-      # Context key for the verbosity value. The value is an integer defaulting
-      # to 0, with higher values meaning more verbose and lower meaning more
-      # quiet.
-      # @return [Object]
-      #
-      VERBOSITY = ::Object.new.freeze
-    end
-
-    ##
-    # The raw arguments passed to the tool, as an array of strings.
-    # This does not include the tool name itself.
-    #
-    # This is a convenience getter for {Toys::Context::Key::ARGS}.
-    #
-    # If the `args` method is overridden by the tool, you can still access it
-    # using the name `__args`.
-    #
-    # @return [Array<String>]
-    #
-    def args
-      # Source available in the toys-core gem
-    end
-    alias __args args
-
-    ##
-    # The currently running CLI.
-    #
-    # This is a convenience getter for {Toys::Context::Key::CLI}.
-    #
-    # If the `cli` method is overridden by the tool, you can still access it
-    # using the name `__cli`.
-    #
-    # @return [Toys::CLI]
-    #
-    def cli
-      # Source available in the toys-core gem
-    end
-    alias __cli cli
-
-    ##
-    # Return the context directory for this tool. Generally, this defaults
-    # to the directory containing the toys config directory structure being
-    # read, but it may be changed by setting a different context directory
-    # for the tool.
-    #
-    # This is a convenience getter for {Toys::Context::Key::CONTEXT_DIRECTORY}.
-    #
-    # If the `context_directory` method is overridden by the tool, you can
-    # still access it using the name `__context_directory`.
-    #
-    # @return [String] Context directory path
-    # @return [nil] if there is no context.
-    #
-    def context_directory
-      # Source available in the toys-core gem
-    end
-    alias __context_directory context_directory
-
-    ##
-    # The logger for this execution.
-    #
-    # This is a convenience getter for {Toys::Context::Key::LOGGER}.
-    #
-    # If the `logger` method is overridden by the tool, you can still access it
-    # using the name `__logger`.
-    #
-    # @return [Logger]
-    #
-    def logger
-      # Source available in the toys-core gem
-    end
-    alias __logger logger
-
-    ##
-    # The full name of the tool being executed, as an array of strings.
-    #
-    # This is a convenience getter for {Toys::Context::Key::TOOL_NAME}.
-    #
-    # If the `tool_name` method is overridden by the tool, you can still access
-    # it using the name `__tool_name`.
-    #
-    # @return [Array<String>]
-    #
-    def tool_name
-      # Source available in the toys-core gem
-    end
-    alias __tool_name tool_name
-
-    ##
-    # The source of the tool being executed.
-    #
-    # This is a convenience getter for {Toys::Context::Key::TOOL_SOURCE}.
-    #
-    # If the `tool_source` method is overridden by the tool, you can still
-    # access it using the name `__tool_source`.
-    #
-    # @return [Toys::SourceInfo]
-    #
-    def tool_source
-      # Source available in the toys-core gem
-    end
-    alias __tool_source tool_source
-
-    ##
-    # The (possibly empty) array of errors detected during argument parsing.
-    #
-    # This is a convenience getter for {Toys::Context::Key::USAGE_ERRORS}.
-    #
-    # If the `usage_errors` method is overridden by the tool, you can still
-    # access it using the name `__usage_errors`.
-    #
-    # @return [Array<Toys::ArgParser::UsageError>]
-    #
-    def usage_errors
-      # Source available in the toys-core gem
-    end
-    alias __usage_errors usage_errors
-
-    ##
-    # The current verbosity setting as an integer.
-    #
-    # This is a convenience getter for {Toys::Context::Key::VERBOSITY}.
-    #
-    # If the `verbosity` method is overridden by the tool, you can still access
-    # it using the name `__verbosity`.
-    #
-    # @return [Integer]
-    #
-    def verbosity
-      # Source available in the toys-core gem
-    end
-    alias __verbosity verbosity
-
-    ##
-    # Fetch an option or other piece of data by key.
-    #
-    # If the `get` method is overridden by the tool, you can still access it
-    # using the name `__get` or the `[]` operator.
-    #
-    # @param key [Symbol]
-    # @return [Object]
-    #
-    def [](key)
-      # Source available in the toys-core gem
-    end
-    alias get []
-    alias __get []
-
-    ##
-    # Set an option or other piece of context data by key.
-    #
-    # @param key [Symbol]
-    # @param value [Object]
-    #
-    def []=(key, value)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Set one or more options or other context data by key.
-    #
-    # If the `set` method is overridden by the tool, you can still access it
-    # using the name `__set`.
-    #
-    # @return [self]
-    #
-    # @overload set(key, value)
-    #   Set an option or other piece of context data by key.
-    #   @param key [Symbol]
-    #   @param value [Object]
-    #   @return [self]
-    #
-    # @overload set(hash)
-    #   Set multiple content data keys and values
-    #   @param hash [Hash] The keys and values to set
-    #   @return [self]
-    #
-    def set(key, value = nil)
-      # Source available in the toys-core gem
-    end
-    alias __set set
-
-    ##
-    # The subset of the context that uses string or symbol keys. By convention,
-    # this includes keys that are set by tool flags and arguments, but does not
-    # include well-known context values such as verbosity or private context
-    # values used by middleware or mixins.
-    #
-    # If the `options` method is overridden by the tool, you can still access
-    # it using the name `__options`.
-    #
-    # @return [Hash]
-    #
-    def options
-      # Source available in the toys-core gem
-    end
-    alias __options options
-
-    ##
-    # Find the given data file or directory in this tool's search path.
-    #
-    # If the `find_data` method is overridden by the tool, you can still access
-    # it using the name `__find_data`.
-    #
-    # @param path [String] The path to find
-    # @param type [nil,:file,:directory] Type of file system object to find,
-    #     or nil to return any type.
-    #
-    # @return [String] Absolute path of the result
-    # @return [nil] if the data was not found.
-    #
-    def find_data(path, type: nil)
-      # Source available in the toys-core gem
-    end
-    alias __find_data find_data
-
-    ##
-    # Exit immediately with the given status code.
-    #
-    # If the `exit` method is overridden by the tool, you can still access it
-    # using the name `__exit` or by calling {Context.exit}.
-    #
-    # @param code [Integer] The status code, which should be 0 for no error,
-    #     or nonzero for an error condition. Default is 0.
-    # @return [void]
-    #
-    def exit(code = 0)
-      # Source available in the toys-core gem
-    end
-    alias __exit exit
-
-    ##
-    # Exit immediately with the given status code. This class method can be
-    # called if the instance method is or could be replaced by the tool.
-    #
-    # @param code [Integer] The status code, which should be 0 for no error,
-    #     or nonzero for an error condition. Default is 0.
-    # @return [void]
-    #
-    def self.exit(code = 0)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Create a Context object. Applications generally will not need to create
-    # these objects directly; they are created by the tool when it is preparing
-    # for execution.
-    #
-    # @param data [Hash]
-    #
-    # @private This interface is internal and subject to change without warning.
-    #
-    def initialize(data)
-      # Source available in the toys-core gem
-    end
-  end
-end

data/core-docs/toys/core.rb

@@ -1,14 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # The core Toys classes.
-  #
-  module Core
-    ##
-    # Current version of Toys core.
-    # @return [String]
-    #
-    VERSION = "0.15.6"
-  end
-end

data/core-docs/toys/dsl/base.rb

@@ -1,56 +0,0 @@
-##
-# Create a base class for defining a tool with a given name.
-#
-# This method returns a base class for defining a tool with a given name.
-# This is useful if the naming behavior of {Toys::Tool} is not adequate for
-# your tool.
-#
-# ### Example
-#
-#     class FooBar < Toys.Tool("Foo_Bar")
-#       desc "This is a tool called Foo_Bar"
-#
-#       def run
-#         puts "Foo_Bar called"
-#       end
-#     end
-#
-# @param name [String] Name of the tool. Defaults to a name inferred from the
-#     class name. (See {Toys::Tool}.)
-# @param base [Class] Use this tool class as the base class, and inherit helper
-#     methods from it.
-# @param args [String,Class] Any string-valued positional argument is
-#     interpreted as the name. Any class-valued positional argument is
-#     interpreted as the base class.
-#
-def Toys.Tool(*args, name: nil, base: nil)
-  # Source available in the toys-core gem
-end
-
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Base class for defining tools
-  #
-  # This base class provides an alternative to the {Toys::DSL::Tool#tool}
-  # directive for defining tools in the Toys DSL. Creating a subclass of
-  # `Toys::Tool` will create a tool whose name is the "kebab-case" of the class
-  # name. Subclasses can be created only in the context of a tool configuration
-  # DSL. Furthermore, a class-defined tool can be created only at the top level
-  # of a configuration file, or within another class-defined tool. It cannot
-  # be a subtool of a tool block.
-  #
-  # ### Example
-  #
-  #     class FooBar < Toys::Tool
-  #       desc "This is a tool called foo-bar"
-  #
-  #       def run
-  #         puts "foo-bar called"
-  #       end
-  #     end
-  #
-  class Tool < Context
-  end
-end