Module: Toys::Middleware
- Included in:
- Base
- Defined in:
- core-docs/toys/middleware.rb
Overview
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: #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
Class Method Summary collapse
-
.spec(middleware, *args, **kwargs, &block) ⇒ Object
Create a middleware spec.
-
.stack(input) ⇒ Toys::Middleware::Stack
Create a Stack from an array of middleware specs.
Instance Method Summary collapse
-
#config(tool, loader) ⇒ void
This method is called after a tool has been defined, and gives this middleware the opportunity to modify the tool definition.
-
#run(context) ⇒ void
This method is called when the tool is run.
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.
106 107 108 |
# File 'core-docs/toys/middleware.rb', line 106 def spec(middleware, *args, **kwargs, &block) # Source available in the toys-core gem 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)
123 124 125 |
# File 'core-docs/toys/middleware.rb', line 123 def stack(input) # Source available in the toys-core gem 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.
44 45 46 |
# File 'core-docs/toys/middleware.rb', line 44 def config(tool, loader) # Source available in the toys-core gem 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.
69 70 71 |
# File 'core-docs/toys/middleware.rb', line 69 def run(context) # Source available in the toys-core gem end |