Readmix.Generator behaviour (readmix v0.2.2)

Defines the behavior and utilities for Readmix generators.

Generators are modules that implement this behaviour and provide actions that can be invoked from documents.

To create a generator, use:

defmodule MyGenerator do
  use Readmix.Generator

  @doc "This action does something"
  action :my_action,
    as: :generate_my,
    params: [
      param1: [type: :string, doc: "Parameter documentation"]
    ]

  @moduledoc """
  My custom actions.

  #{Readmix.Docs.generate()}
  """

  defp generate_my(params, context) do
    {:ok, "Generated content"}
  end
end

This is equivalent to the following:

defmodule MyGenerator do
  @behaviour Readmix.Generator

  @actions [
    my_action: [
      as: :generate_my,
      params: [
        param1: [type: :string, doc: "Parameter documentation"]
      ],
      doc: "This action does something"
    ]
  ]

  @moduledoc """
  My custom actions.

  #{Readmix.Docs.generate(@actions)}
  """

  @impl true
  def actions, do: action

  @impl true
  def generate(:my_action, params, context) do
    generate_my(params, context)
  end

  defp generate_my(params, context) do
    {:ok, "Generated content"}
  end
end

Summary

Functions

Returns a function that reads the given key from the given context.

Types

action_name()

@type action_name() :: atom()

action_spec()

@type action_spec() :: [action_spec_opt()]

action_spec_opt()

@type action_spec_opt() ::
  {:as, function_name :: atom()}
  | {:params, NimbleOptions.schema()}
  | {:doc, String.t()}

block()

@type block() :: {:text, iodata()} | {:generated, block_spec()}

block_name()

@type block_name() :: atom()

block_spec()

@type block_spec() :: Readmix.BlockSpec.t()

context()

@type context() :: %{previous_content: [block()], readmix: Readmix.t()}

params()

@type params() :: %{optional(binary()) => integer() | float() | binary()}

Callbacks

actions()

@callback actions() :: [{action_name(), action_spec()}]

generate(block_name, params, context)

@callback generate(block_name(), params(), context()) ::
  {:ok, iodata()} | {:error, term()}

Functions

action(atom, spec)

(macro)

dispatch_actions(actions)

(macro)

get_arg(params, key, default_or_fun)

or_var(ctx, key)

Returns a function that reads the given key from the given context.

The returned function with throw {:undef_var, key} if the variable is not defined.

This is intended to be used as a default getter for get_arg, so there is an attempt to read a variable only when the argument is not defined.