pluggable v1.0.1

View Source Pluggable behaviour (pluggable v1.0.1)

The step specification.

There are two kind of steps: function steps and module steps.

Function steps

A function step is any function that receives a token and a set of options and returns a token. Its type signature must be:

(Pluggable.Token.t, Pluggable.opts) :: Pluggable.Token.t

Module steps

A module step is an extension of the function step. It is a module that must export:

  • a call/2 function with the signature defined above
  • an init/1 function which takes a set of options and initializes it.

The result returned by init/1 is passed as second argument to call/2. Note that init/1 may be called during compilation and as such it must not return pids, ports or values that are specific to the runtime.

The API expected by a module step is defined as a behaviour by the Pluggable module (this module).

examples

 Examples

Here's an example of a function step:

def json_header_step(token, _opts) do
  My.Token.put_data(token, "some_data")
end

Here's an example of a module step:

defmodule PutSomeData do
  def init(opts) do
    opts
  end

  def call(token, _opts) do
    My.Token.put_data(token, "some_data")
  end
end

the-pluggable-step-pipeline

 The Pluggable Step pipeline

The Pluggable.StepBuilder module provides conveniences for building pluggable step pipelines.

Link to this section Summary

Types

opts()

Callbacks

call(token, opts)
init(opts)

Functions

run(token, steps, opts \\ [])

Run a series of pluggable steps at runtime.

Link to this section Types

Link to this type

opts()

View Source 
@type opts() ::
  binary()
  | tuple()
  | atom()
  | integer()
  | float()
  | [opts()]
  | %{optional(opts()) => opts()}
  | MapSet.t()

Link to this section Callbacks

Link to this callback

call(token, opts)

View Source 
@callback call(token :: Pluggable.Token.t(), opts()) :: Pluggable.Token.t()
Link to this callback

init(opts)

View Source 
@callback init(opts()) :: opts()

Link to this section Functions

Link to this function

run(token, steps, opts \\ [])

View Source 
@spec run(
  Pluggable.Token.t(),
  [{module(), opts()} | (Pluggable.Token.t() -> Pluggable.Token.t())],
  Keyword.t()
) :: Pluggable.Token.t()

Run a series of pluggable steps at runtime.

The steps given here can be either a tuple, representing a module step and their options, or a simple function that receives a token and returns a token.

If any of the steps halt, the remaining steps are not invoked. If the given token was already halted, none of the steps are invoked either.

While Pluggable.StepBuilder works at compile-time, this is a straight-forward alternative that works at runtime.

examples

 Examples 

Pluggable.run(token, [{My.Step, []}, &IO.inspect/1])

options

 Options

  • :log_on_halt - a log level to be used if a pipeline halts