toys 0.12.2 → 0.13.0

data/core-docs/toys/middleware.rb

@@ -0,0 +1,295 @@
+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 using them is not required. 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
+    end
+
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A base class that provides default NOP implementations 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
+    end
+
+    ##
+    # **_Defined in the toys-core gem_**
+    #
+    # A stack of middleware specs.
+    #
+    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
+    end
+  end
+end

data/core-docs/toys/mixin.rb

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

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

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