toys 0.15.6 → 0.16.0

data/core-docs/toys/middleware.rb

@@ -1,336 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # A middleware is an object that has the opportunity to alter the
-  # configuration and runtime behavior of each tool in a Toys CLI. A CLI
-  # contains an ordered list of middleware, known as the *middleware stack*,
-  # that together define the CLI's default behavior.
-  #
-  # Specifically, a middleware can perform two functions.
-  #
-  # First, it can modify the configuration of a tool. After tools are defined
-  # from configuration, the middleware stack can make modifications to each
-  # tool. A middleware can add flags and arguments to the tool, modify the
-  # description, or make any other changes to how the tool is set up.
-  #
-  # Second, a middleware can intercept and change tool execution. Like a Rack
-  # middleware, a Toys middleware can wrap execution with its own code,
-  # replace it outright, or leave it unmodified.
-  #
-  # Generally, a middleware is a class that implements one or more of the
-  # methods defined in this module: {Toys::Middleware#config}, and
-  # {Toys::Middleware#run}. This module provides default implementations that
-  # do nothing, but it is not required to include this module, or even to
-  # define both methods. Middleware objects need respond only to methods they
-  # care about.
-  #
-  module Middleware
-    ##
-    # This method is called *after* a tool has been defined, and gives this
-    # middleware the opportunity to modify the tool definition. It is passed
-    # the tool definition object and the loader, and can make any changes to
-    # the tool definition. In most cases, this method should also call
-    # `yield`, which passes control to the next middleware in the stack. A
-    # middleware can disable modifications done by subsequent middleware by
-    # omitting the `yield` call, but this is uncommon.
-    #
-    # This basic implementation does nothing and simply yields to the next
-    # middleware.
-    #
-    # @param tool [Toys::ToolDefinition] The tool definition to modify.
-    # @param loader [Toys::Loader] The loader that loaded this tool.
-    # @return [void]
-    #
-    def config(tool, loader)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # This method is called when the tool is run. It gives the middleware an
-    # opportunity to modify the runtime behavior of the tool. It is passed
-    # the tool instance (i.e. the object that hosts a tool's `run` method),
-    # and you can use this object to access the tool's options and other
-    # context data. In most cases, this method should also call `yield`,
-    # which passes control to the next middleware in the stack. A middleware
-    # can "wrap" normal execution by calling `yield` somewhere in its
-    # implementation of this method, or it can completely replace the
-    # execution behavior by not calling `yield` at all.
-    #
-    # Like a tool's `run` method, this method's return value is unused. If
-    # you want to output from a tool, write to stdout or stderr. If you want
-    # to set the exit status code, call {Toys::Context#exit} on the context.
-    #
-    # This basic implementation does nothing and simply yields to the next
-    # middleware.
-    #
-    # @param context [Toys::Context] The tool execution context.
-    # @return [void]
-    #
-    def run(context)
-      # Source available in the toys-core gem
-    end
-
-    class << self
-      ##
-      # Create a middleware spec.
-      #
-      # @overload spec(name, *args, **kwargs, &block)
-      #   Create a spec indicating a given middleware name should be
-      #   instantiated with the given arguments.
-      #
-      #   @param name [String,Symbol,Class] The middleware name or class
-      #   @param args [Array] The arguments to pass to the constructor
-      #   @param kwargs [Hash] The keyword arguments to pass to the constructor
-      #   @param block [Proc,nil] The block to pass to the constructor
-      #   @return [Toys::Middleware::Spec] A spec
-      #
-      # @overload spec(array)
-      #   Create a middleware spec from an array specification.
-      #
-      #   The array must be 1-4 elements long. The first element must be the
-      #   middleware name or class. The other three arguments may include any
-      #   or all of the following optional elements, in any order:
-      #    *  An array for the positional arguments to pass to the constructor
-      #    *  A hash for the keyword arguments to pass to the constructor
-      #    *  A proc for the block to pass to the constructor
-      #
-      #   @param array [Array] The array input
-      #   @return [Toys::Middleware::Spec] A spec
-      #
-      # @overload spec(middleware_object)
-      #   Create a spec wrapping an existing middleware object
-      #
-      #   @param middleware_object [Toys::Middleware] The middleware object
-      #   @return [Toys::Middleware::Spec] A spec
-      #
-      def spec(middleware, *args, **kwargs, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Create a {Toys::Middleware::Stack} from an array of middleware specs.
-      # Each element may be one of the following:
-      #
-      #  *  A {Toys::Middleware} object
-      #  *  A {Toys::Middleware::Spec}
-      #  *  An array whose first element is a middleware name or class, and the
-      #     subsequent elements are params that define what to pass to the class
-      #     constructor (see {Toys::Middleware.spec})
-      #
-      # @param input [Array<Toys::Middleware,Toys::Middleware::Spec,Array>]
-      # @return [Toys::Middleware::Stack]
-      #
-      def stack(input)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Create a spec from an array specification.
-      #
-      # @private This interface is internal and subject to change without warning.
-      #
-      def spec_from_array(array)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A base class that provides default no-op implementation of the middleware
-    # interface. This base class may optionally be subclassed by a middleware
-    # implementation.
-    #
-    class Base
-      include Middleware
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A middleware specification, including the middleware class and the
-    # arguments to pass to the constructor.
-    #
-    # Use {Toys::Middleware.spec} to create a middleware spec.
-    #
-    class Spec
-      ##
-      # Builds a middleware for this spec, given a ModuleLookup for middleware.
-      #
-      # If this spec wraps an existing middleware object, returns that object.
-      # Otherwise, constructs a middleware object from the spec.
-      #
-      # @param lookup [Toys::ModuleLookup] A module lookup to resolve
-      #     middleware names
-      # @return [Toys::Middleware] The middleware
-      #
-      def build(lookup)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # @return [Toys::Middleware] if this spec wraps a middleware object
-      # @return [nil] if this spec represents a class to instantiate
-      #
-      attr_reader :object
-
-      ##
-      # @return [String,Symbol] if this spec represents a middleware name
-      # @return [Class] if this spec represents a middleware class
-      # @return [nil] if this spec wraps a middleware object
-      #
-      attr_reader :name
-
-      ##
-      # @return [Array] the positional arguments to be passed to a middleware
-      #     class constructor, or the empty array if there are no positional
-      #     arguments
-      # @return [nil] if this spec wraps a middleware object
-      #
-      attr_reader :args
-
-      ##
-      # @return [Hash] the keyword arguments to be passed to a middleware class
-      #     constructor, or the empty hash if there are no keyword arguments
-      # @return [nil] if this spec wraps a middleware object
-      #
-      attr_reader :kwargs
-
-      ##
-      # @return [Proc] if there is a block argument to be passed to a
-      #     middleware class constructor
-      # @return [nil] if there is no block argument, or this spec wraps a
-      #     middleware object
-      #
-      attr_reader :block
-
-      ##
-      # Equality check
-      #
-      # @param other [Object]
-      # @return [Boolean]
-      #
-      def ==(other)
-        # Source available in the toys-core gem
-      end
-      alias eql? ==
-
-      ##
-      # Return the hash code
-      #
-      # @return [Integer]
-      #
-      def hash
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Internal constructor. Use {Toys::Middleware.spec} instead.
-      #
-      # @private This interface is internal and subject to change without warning.
-      #
-      def initialize(object, name, args, kwargs, block)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # A stack of middleware specs, which can be applied in order to a tool.
-    #
-    # A middleware stack is separated into three groups:
-    #
-    #  *  {#pre_specs}, which are applied first.
-    #  *  {#default_specs}, which are applied next. The default specs are set
-    #     when the stack is created and are generally not modified.
-    #  *  {#post_specs}, which are applied third.
-    #
-    # When adding middleware to a stack, you should normally add them to the
-    # pre or post specs. By default, {Stack#add} appends to the pre specs,
-    # inserting new middleware just before the defaults.
-    #
-    # Use {Toys::Middleware.stack} to create a middleware stack.
-    #
-    class Stack
-      ##
-      # The middleware specs that precede the default set.
-      # @return [Array<Toys::Middleware:Spec>]
-      #
-      attr_reader :pre_specs
-
-      ##
-      # The default set of middleware specs.
-      # @return [Array<Toys::Middleware:Spec>]
-      #
-      attr_reader :default_specs
-
-      ##
-      # The middleware specs that follow the default set.
-      # @return [Array<Toys::Middleware:Spec>]
-      #
-      attr_reader :post_specs
-
-      ##
-      # Add a middleware spec to the stack, in the default location, which is
-      # at the end of pre_specs). See {Toys::Middleware.spec} for a description
-      # of the arguments you can pass.
-      #
-      # @overload add(name, *args, **kwargs, &block)
-      # @overload add(array)
-      # @overload add(middleware_object)
-      #
-      def add(middleware, *args, **kwargs, &block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Duplicate this stack.
-      #
-      # @return [Toys::Middleware::Stack]
-      #
-      def dup
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Build the middleware in this stack.
-      #
-      # @return [Array<Toys::Middleware>]
-      #
-      def build(middleware_lookup)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Equality check
-      #
-      # @param other [Object]
-      # @return [Boolean]
-      #
-      def ==(other)
-        # Source available in the toys-core gem
-      end
-      alias eql? ==
-
-      ##
-      # Return the hash code
-      #
-      # @return [Integer]
-      #
-      def hash
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Internal constructor. Use {Toys::Middleware.stack} instead.
-      #
-      # @private This interface is internal and subject to change without warning.
-      #
-      def initialize(default_specs: nil, pre_specs: nil, post_specs: nil)
-        # Source available in the toys-core gem
-      end
-    end
-  end
-end

data/core-docs/toys/mixin.rb

@@ -1,142 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # A mixin definition. Mixin modules should include this module.
-  #
-  # A mixin is a collection of methods that are available to be called from a
-  # tool implementation (i.e. its run method). The mixin is added to the tool
-  # class, so it has access to the same methods that can be called by the tool,
-  # such as {Toys::Context#get}.
-  #
-  # ### Usage
-  #
-  # To create a mixin, define a module, and include this module. Then define
-  # the methods you want to be available.
-  #
-  # If you want to perform some initialization specific to the mixin, you can
-  # provide an *initializer* block and/or an *inclusion* block. These can be
-  # specified by calling the module methods defined in
-  # {Toys::Mixin::ModuleMethods}.
-  #
-  # The initializer block is called when the tool context is instantiated
-  # in preparation for execution. It has access to context methods such as
-  # {Toys::Context#get}, and can perform setup for the tool execution itself,
-  # such as initializing some persistent state and storing it in the tool using
-  # {Toys::Context#set}. The initializer block is passed any extra arguments
-  # that were provided to the `include` directive. Define the initializer by
-  # calling {Toys::Mixin::ModuleMethods#on_initialize}.
-  #
-  # The inclusion block is called in the context of your tool class when your
-  # mixin is included. It is also passed any extra arguments that were provided
-  # to the `include` directive. It can be used to issue directives to define
-  # tools or other objects in the DSL, or even enhance the DSL by defining DSL
-  # methods specific to the mixin. Define the inclusion block by calling
-  # {Toys::Mixin::ModuleMethods#on_include}.
-  #
-  # ### Example
-  #
-  # This is an example that implements a simple counter. Whenever the counter
-  # is incremented, a log message is emitted. The tool can also retrieve the
-  # final counter value.
-  #
-  #     # Define a mixin by creating a module that includes Toys::Mixin
-  #     module MyCounterMixin
-  #       include Toys::Mixin
-  #
-  #       # Initialize the counter. Notice that the initializer is evaluated
-  #       # in the context of the runtime context, so has access to the runtime
-  #       # context state.
-  #       on_initialize do |start = 0|
-  #         set(:counter_value, start)
-  #       end
-  #
-  #       # Mixin methods are evaluated in the runtime context and so have
-  #       # access to the runtime context state, just as if you had defined
-  #       # them in your tool.
-  #       def counter_value
-  #         get(:counter_value)
-  #       end
-  #
-  #       def increment
-  #         set(:counter_value, counter_value + 1)
-  #         logger.info("Incremented counter")
-  #       end
-  #     end
-  #
-  # Now we can use it from a tool:
-  #
-  #     tool "count-up" do
-  #       # Pass 1 as an extra argument to the mixin initializer
-  #       include MyCounterMixin, 1
-  #
-  #       def run
-  #         # Mixin methods can be called.
-  #         5.times { increment }
-  #         puts "Final value is #{counter_value}"
-  #       end
-  #     end
-  #
-  module Mixin
-    ##
-    # Create a mixin module with the given block.
-    #
-    # @param block [Proc] Defines the mixin module.
-    # @return [Class]
-    #
-    def self.create(&block)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # **_Defined in the toys-core gem_**
-    #
-    # Methods that will be added to a mixin module object.
-    #
-    module ModuleMethods
-      ##
-      # Set the initializer for this mixin. This block is evaluated in the
-      # runtime context before execution, and is passed any arguments provided
-      # to the `include` directive. It can perform any runtime initialization
-      # needed by the mixin.
-      #
-      # @param block [Proc] Sets the initializer proc.
-      # @return [self]
-      #
-      def on_initialize(&block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The initializer proc for this mixin. This proc is evaluated in the
-      # runtime context before execution, and is passed any arguments provided
-      # to the `include` directive. It can perform any runtime initialization
-      # needed by the mixin.
-      #
-      # @return [Proc] The iniitiliazer for this mixin.
-      #
-      attr_accessor :initializer
-
-      ##
-      # Set an inclusion proc for this mixin. This block is evaluated in the
-      # tool class immediately after the mixin is included, and is passed any
-      # arguments provided to the `include` directive.
-      #
-      # @param block [Proc] Sets the inclusion proc.
-      # @return [self]
-      #
-      def on_include(&block)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # The inclusion proc for this mixin. This block is evaluated in the tool
-      # class immediately after the mixin is included, and is passed any
-      # arguments provided to the `include` directive.
-      #
-      # @return [Proc] The inclusion procedure for this mixin.
-      #
-      attr_accessor :inclusion
-    end
-  end
-end

data/core-docs/toys/module_lookup.rb

@@ -1,75 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # A helper module that provides methods to do module lookups. This is
-  # used to obtain named helpers, middleware, and templates from the
-  # respective modules.
-  #
-  class ModuleLookup
-    class << self
-      ##
-      # Convert the given string to a path element. Specifically, converts
-      # to `lower_snake_case`.
-      #
-      # @param str [String,Symbol] String to convert.
-      # @return [String] Converted string
-      #
-      def to_path_name(str)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Convert the given string to a module name. Specifically, converts
-      # to `UpperCamelCase`, and then to a symbol.
-      #
-      # @param str [String,Symbol] String to convert.
-      # @return [Symbol] Converted name
-      #
-      def to_module_name(str)
-        # Source available in the toys-core gem
-      end
-
-      ##
-      # Given a require path, return the module expected to be defined.
-      #
-      # @param path [String] File path, delimited by forward slash
-      # @return [Module] The module loaded from that path
-      #
-      def path_to_module(path)
-        # Source available in the toys-core gem
-      end
-    end
-
-    ##
-    # Create an empty ModuleLookup
-    #
-    def initialize
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Add a lookup path for modules.
-    #
-    # @param path_base [String] The base require path
-    # @param module_base [Module] The base module, or `nil` (the default) to
-    #     infer a default from the path base.
-    # @param high_priority [Boolean] If true, add to the head of the lookup
-    #     path, otherwise add to the end.
-    # @return [self]
-    #
-    def add_path(path_base, module_base: nil, high_priority: false)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Obtain a named module. Returns `nil` if the name is not present.
-    #
-    # @param name [String,Symbol] The name of the module to return.
-    # @return [Module] The specified module
-    #
-    def lookup(name)
-      # Source available in the toys-core gem
-    end
-  end
-end

data/core-docs/toys/positional_arg.rb

@@ -1,145 +0,0 @@
-module Toys
-  ##
-  # **_Defined in the toys-core gem_**
-  #
-  # Representation of a formal positional argument
-  #
-  class PositionalArg
-    ##
-    # Create a PositionalArg definition.
-    #
-    # @param key [String,Symbol] The key to use to retrieve the value from
-    #     the execution context.
-    # @param type [Symbol] The type of arg. Valid values are `:required`,
-    #     `:optional`, and `:remaining`.
-    # @param accept [Object] An acceptor that validates and/or converts the
-    #     value. See {Toys::Acceptor.create} for recognized formats. Optional.
-    #     If not specified, defaults to {Toys::Acceptor::DEFAULT}.
-    # @param complete [Object] A specifier for shell tab completion. See
-    #     {Toys::Completion.create} for recognized formats.
-    # @param display_name [String] A name to use for display (in help text and
-    #     error reports). Defaults to the key in upper case.
-    # @param desc [String,Array<String>,Toys::WrappableString] Short
-    #     description for the flag. See {Toys::ToolDefintion#desc} for a
-    #     description of the allowed formats. Defaults to the empty string.
-    # @param long_desc [Array<String,Array<String>,Toys::WrappableString>]
-    #     Long description for the flag. See {Toys::ToolDefintion#long_desc}
-    #     for a description of the allowed formats. (But note that this param
-    #     takes an Array of description lines, rather than a series of
-    #     arguments.) Defaults to the empty array.
-    # @return [Toys::PositionalArg]
-    #
-    def self.create(key, type,
-                    accept: nil, default: nil, complete: nil, desc: nil,
-                    long_desc: nil, display_name: nil)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # The key for this arg.
-    # @return [Symbol]
-    #
-    attr_reader :key
-
-    ##
-    # Type of this argument.
-    # @return [:required,:optional,:remaining]
-    #
-    attr_reader :type
-
-    ##
-    # The effective acceptor.
-    # @return [Toys::Acceptor::Base]
-    #
-    attr_accessor :acceptor
-
-    ##
-    # The default value, which may be `nil`.
-    # @return [Object]
-    #
-    attr_reader :default
-
-    ##
-    # The proc that determines shell completions for the value.
-    # @return [Proc,Toys::Completion::Base]
-    #
-    attr_reader :completion
-
-    ##
-    # The short description string.
-    #
-    # When reading, this is always returned as a {Toys::WrappableString}.
-    #
-    # When setting, the description may be provided as any of the following:
-    #  *  A {Toys::WrappableString}.
-    #  *  A normal String, which will be transformed into a
-    #     {Toys::WrappableString} using spaces as word delimiters.
-    #  *  An Array of String, which will be transformed into a
-    #     {Toys::WrappableString} where each array element represents an
-    #     individual word for wrapping.
-    #
-    # @return [Toys::WrappableString]
-    #
-    attr_reader :desc
-
-    ##
-    # The long description strings.
-    #
-    # When reading, this is returned as an Array of {Toys::WrappableString}
-    # representing the lines in the description.
-    #
-    # When setting, the description must be provided as an Array where *each
-    # element* may be any of the following:
-    #  *  A {Toys::WrappableString} representing one line.
-    #  *  A normal String representing a line. This will be transformed into a
-    #     {Toys::WrappableString} using spaces as word delimiters.
-    #  *  An Array of String representing a line. This will be transformed into
-    #     a {Toys::WrappableString} where each array element represents an
-    #     individual word for wrapping.
-    #
-    # @return [Array<Toys::WrappableString>]
-    #
-    attr_reader :long_desc
-
-    ##
-    # The displayable name.
-    # @return [String]
-    #
-    attr_accessor :display_name
-
-    ##
-    # Set the short description string.
-    #
-    # See {#desc} for details.
-    #
-    # @param desc [Toys::WrappableString,String,Array<String>]
-    #
-    def desc=(desc)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Set the long description strings.
-    #
-    # See {#long_desc} for details.
-    #
-    # @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
-    #
-    def long_desc=(long_desc)
-      # Source available in the toys-core gem
-    end
-
-    ##
-    # Append long description strings.
-    #
-    # You must pass an array of lines in the long description. See {#long_desc}
-    # for details on how each line may be represented.
-    #
-    # @param long_desc [Array<Toys::WrappableString,String,Array<String>>]
-    # @return [self]
-    #
-    def append_long_desc(long_desc)
-      # Source available in the toys-core gem
-    end
-  end
-end