View Source Q (Q v1.1.0)

Q

Documentation for Q.

Link to this section Summary

Functions

Executes the queue, running all operations in the order they were added.

Adds an operation to the queue that, when executed, prints the current state of the queue.

Creates and returns a new, empty Q struct.

Returns a list of operation names stored in the queue, in the order they were added.

Adds a value to the state so far under the given name.

Provides a DSL for creating a queue using a more declarative syntax.

Adds a function to be executed as part of the queue.

Adds a function to be executed as part of the queue. Similar to run/4, but allows to pass module name, function and arguments.

Converts the operations queue to a list, in the order they were added.

Link to this section Types

@type exec_error() :: {:error, name(), any(), list()}
@type fun_arity1() :: (state() -> {:ok | :error | :halt, any()})
@type fun_mfa() :: {module(), atom(), [any()]}
@type name() :: any()
@type state() :: map()
@type t() :: %Q{names: names(), operations: operations()}

Link to this section Functions

@spec exec(t()) :: {:ok, term()} | exec_error()

Executes the queue, running all operations in the order they were added.

Each operation is provided with the state of the queue as of the start of the operation. If an operation function returns an error, the execution of the queue is halted and an error is returned.

example

Example

iex> Q.new()
...> |> Q.run(:write, fn _ -> {:ok, "Hello world!"} end)
...> |> Q.exec()

{:ok, %{write: "Hello world!"}}
Link to this function

inspect(queue, opts \\ [])

View Source
@spec inspect(t(), Keyword.t()) :: t()

Adds an operation to the queue that, when executed, prints the current state of the queue.

The printing is performed using Elixir's IO.inspect/2, which provides a human-readable representation of the queue's state.

params

Params

  • queue: The queue to inspect.
  • opts: Options passed to IO.inspect/2. If the :only option is provided, only those keys will be printed.
@spec new() :: t()

Creates and returns a new, empty Q struct.

The resulting queue can be used as a starting point for queue operations, such as put/3 and run/4.

example

Example

iex> Q.new() |> Q.to_list()
[]
@spec operations(t()) :: list()

Returns a list of operation names stored in the queue, in the order they were added.

This function can be used to review the sequence of operations added to the queue.

example

Example

iex> Q.new()
...> |> Q.put(:init, "foo")
...> |> Q.run(:test, fn text -> {:ok, text} end, [:init])
...> |> Q.operations()

["test", "init"]
@spec put(t(), name(), any()) :: t()

Adds a value to the state so far under the given name.

This function modifies the queue by associating the given name with a value. If the operation is successful, the name will become a key in the queue's internal state map, and value will be its associated value.

params

Params

  • queue: The queue to add the value to.
  • name: The name to associate with the value. It must be unique, or an error will be raised.
  • value: The value to add to the queue.

errors

Errors

This function will raise an error if name is already present in the queue.

example

Example

iex> Q.new()
...> |> Q.put(:params, %{foo: "bar"})
...> |> Q.exec()

{:ok, %{params: %{foo: "bar"}}}

Provides a DSL for creating a queue using a more declarative syntax.

example

Example

queue do
  put(:input, "some data")
  run(:processed, &process_data/1, [:input])
  exec()      # optional, will return the result immediately
end
Link to this function

run(queue, name, fun, params \\ [])

View Source
@spec run(t(), name(), fun_arity1() | fun_mfa(), [atom()]) :: t()

Adds a function to be executed as part of the queue.

This function enables adding operations to the queue that are executed when exec/1 is called. The operations can be anonymous functions or functions in a module.

The function should return either {:ok, value} if the operation was successful or {:error, value} if the operation failed. The state of the queue is passed as arguments to the function if no params are specified.

Functions can also return {:halt, value} to halt execution at any point.

params

Params

  • queue: The queue to which the function should be added.
  • name: A unique name for this operation. It will be used as a key in the queue's internal state.
  • fun: The function to be run. It can be an anonymous function or a tuple containing a module, function, and arguments.
  • params (optional): A list of keys in the queue's internal state that should be passed to the function as arguments.
Link to this function

run(queue, name, mod, fun, args, params \\ [])

View Source
@spec run(t(), name(), module(), function :: atom(), args :: [any()], [atom()]) :: t()

Adds a function to be executed as part of the queue. Similar to run/4, but allows to pass module name, function and arguments.

The function should return either {:ok, value} if the operation was successful or {:error, value} if the operation failed. The state of the queue is passed as arguments to the function if no params are specified.

Functions can also return {:halt, value} to halt execution at any point.

params

Params

  • queue: The queue to which the function should be added.
  • name: A unique name for this operation. It will be used as a key in the queue's internal state.
  • mod: The module where the function is defined.
  • fun: The function to be executed.
  • args: Arguments that should be passed to the function.
  • params (optional): A list of keys in the queue's internal state that should be passed to the function as arguments.
@spec to_list(t()) :: [{name(), term()}]

Converts the operations queue to a list, in the order they were added.

This function is useful for inspecting the current state of the queue. Direct inspection of the queue's internal state is discouraged to maintain encapsulation.