Module: Toys::Middleware

Included in:
Base
Defined in:
lib/toys/middleware.rb

Overview

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: #config, and #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.

Defined Under Namespace

Classes: Base, Spec, Stack

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.spec(name, *args, **kwargs, &block) ⇒ Toys::Middleware::Spec .spec(array) ⇒ Toys::Middleware::Spec .spec(middleware_object) ⇒ Toys::Middleware::Spec

Create a middleware spec.

Overloads:

  • .spec(name, *args, **kwargs, &block) ⇒ Toys::Middleware::Spec

    Create a spec indicating a given middleware name should be instantiated with the given arguments.

    Parameters:

    • name (String, Symbol, Class) —

      The middleware name or class

    • args (Array) —

      The arguments to pass to the constructor

    • kwargs (Hash) —

      The keyword arguments to pass to the constructor

    • block (Proc, nil) —

      The block to pass to the constructor

    Returns:

  • .spec(array) ⇒ Toys::Middleware::Spec

    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

    Parameters:

    • array (Array) —

      The array input

    Returns:

  • .spec(middleware_object) ⇒ Toys::Middleware::Spec

    Create a spec wrapping an existing middleware object

    Parameters:

    Returns:



106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/toys/middleware.rb', line 106

def spec(middleware, *args, **kwargs, &block)
  case middleware
  when ::Array
    spec_from_array(middleware)
  when ::String, ::Symbol, ::Class
    Spec.new(nil, middleware, args, kwargs, block)
  when Spec
    middleware
  else
    Spec.new(middleware, nil, nil, nil, nil)
  end
end

.stack(input) ⇒ Toys::Middleware::Stack

Create a Stack from an array of middleware specs. Each element may be one of the following:

  • A Toys::Middleware object
  • A 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 spec)

Parameters:

Returns:



132
133
134
135
136
137
138
139
140
141
 
# File 'lib/toys/middleware.rb', line 132

def stack(input)
  case input
  when Stack
    input
  when ::Array
    Stack.new(default_specs: input.map { |spec| spec(spec) })
  else
    raise ::ArgumentError, "Illegal middleware stack: #{input.inspect}"
  end
end

Instance Method Details

#config(tool, loader) ⇒ void

This method returns an undefined value.

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.

Parameters:



44
45
46
 
# File 'lib/toys/middleware.rb', line 44

def config(tool, loader) # rubocop:disable Lint/UnusedMethodArgument
  yield
end

#run(context) ⇒ void

This method returns an undefined value.

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 Context#exit on the context.

This basic implementation does nothing and simply yields to the next middleware.

Parameters:



69
70
71
 
# File 'lib/toys/middleware.rb', line 69

def run(context) # rubocop:disable Lint/UnusedMethodArgument
  yield
end