Module handlers
The Handlers library provides a flexible way to manage and execute a series of handlers based on patterns.
Each handler consists of a pattern function, a handle function, and a name. This library is suitable for scenarios where different actions need to be taken based on varying input criteria. Returns the handlers table.
Functions
| generateResolver (function) | Given a resolver specification, returns a resolver function. |
| receive (function) | Given a pattern, returns the next message that matches the pattern. |
| once (name, function, handle) | Given a name, a pattern, and a handle, adds a handler to the list. |
| add (name, function, handle, string) | Given a name, a pattern, and a handle, adds a handler to the list. |
| append (name, function, handle, string) | Appends a new handler to the end of the handlers list. |
| prepend (name, function, handle, string) | Prepends a new handler to the beginning of the handlers list. |
| before (handleName) | Returns an object that allows adding a new handler before a specified handler. |
| after (handleName) | Returns an object that allows adding a new handler after a specified handler. |
| remove (name) | Removes a handler from the handlers list by name. |
| evaluate (msg, env) | Evaluates each handler against a given message and environment. |
Tables
| handlers | The handlers table |
Functions
- generateResolver (function)
-
Given a resolver specification, returns a resolver function.
Parameters:
- function {table } resolveSpec The resolver specification
Returns:
-
{function}
A resolver function
- receive (function)
-
Given a pattern, returns the next message that matches the pattern.
This function uses Lua's coroutines under-the-hood to add a handler, pause,
and then resume the current coroutine. This allows us to effectively block
processing of one message until another is received that matches the pattern.
Parameters:
- function {table } pattern The pattern to check for in the message
- once (name, function, handle)
-
Given a name, a pattern, and a handle, adds a handler to the list.
If name is not provided, "_once_" prefix plus onceNonce will be used as the name.
Adds handler with maxRuns of 1 such that it will only be called once then removed from the list.
Parameters:
- add (name, function, handle, string)
-
Given a name, a pattern, and a handle, adds a handler to the list.
Parameters:
- append (name, function, handle, string)
-
Appends a new handler to the end of the handlers list.
Parameters:
- prepend (name, function, handle, string)
-
Prepends a new handler to the beginning of the handlers list.
Parameters:
- before (handleName)
-
Returns an object that allows adding a new handler before a specified handler.
Parameters:
- handleName {string} The name of the handler before which the new handler will be added
Returns:
-
{table}
An object with an `add` method to insert the new handler
- after (handleName)
-
Returns an object that allows adding a new handler after a specified handler.
Parameters:
- handleName {string} The name of the handler after which the new handler will be added
Returns:
-
{table}
An object with an `add` method to insert the new handler
- remove (name)
-
Removes a handler from the handlers list by name.
Parameters:
- name {string} The name of the handler to be removed
- evaluate (msg, env)
-
Evaluates each handler against a given message and environment. Handlers are called in the order they appear in the handlers list.
Return 0 to not call handler, -1 to break after handler is called, 1 to continue
Parameters:
- msg {table} The message to be processed by the handlers.
- env {table} The environment in which the handlers are executed.
Returns:
-
The
response from the handler(s). Returns a default message if no handler matches.
Tables
- handlers
-
The handlers table
Fields:
- _version The version number of the handlers module
- list The list of handlers
- coroutines The coroutines of the handlers
- onceNonce The nonce for the once handlers
- utils The handlers-utils module
- generateResolver The generateResolver function
- receive The receive function
- once The once function
- add The add function
- append The append function
- prepend The prepend function
- remove The remove function
- evaluate The evaluate function