Spark.Dsl.Transformer behaviour (spark v2.2.46)

View Source

A transformer manipulates and/or validates the entire DSL state of a resource.

It's transform/1 takes a map, which is just the values/configurations at each point of the DSL. Don't manipulate it directly, if possible, instead use functions like get_entities/3 and replace_entity/4 to manipulate it.

Use the after?/1 and before?/1 callbacks to ensure that your transformer runs either before or after some other transformer.

Return true in after_compile/0 to have the transformer run in an after_compile hook, but keep in mind that no modifications to the dsl structure will be retained, so there is no real point in modifying the dsl that you return.

Summary

Callbacks

after?(module)
after_compile?()
before?(module)
transform(map)

Functions

add_entity(dsl_state, path, entity, opts \\ [])
async_compile(dsl, fun)

Runs the function in an async compiler.

build_entity(extension, path, name, opts)
build_entity!(extension, path, name, opts)
eval(dsl, bindings, block)

Add a quoted expression to be evaluated in the DSL module's context.

fetch_option(dsl_state, path, option)
fetch_persisted(dsl, key)
get_entities(dsl_state, path)
get_option(dsl_state, path, option, default \\ nil)
get_persisted(dsl, key, default \\ nil)
persist(dsl, key, value)

Saves a value into the dsl config with the given key.

remove_entity(dsl_state, path, func)
replace_entity(dsl_state, path, replacement, matcher \\ nil)
set_option(dsl_state, path, option, value)
sort(transformers)

Callbacks

after?(module)

@callback after?(module()) :: boolean()

after_compile?()

@callback after_compile?() :: boolean()

before?(module)

@callback before?(module()) :: boolean()

transform(map)

@callback transform(map()) ::
  :ok
  | {:ok, map()}
  | {:error, term()}
  | {:warn, map(), String.t() | [String.t()]}
  | :halt

Functions

add_entity(dsl_state, path, entity, opts \\ [])

async_compile(dsl, fun)

Runs the function in an async compiler.

Use this for compiling new modules and having them compiled efficiently asynchronously.

build_entity(extension, path, name, opts)

build_entity!(extension, path, name, opts)

eval(dsl, bindings, block)

Add a quoted expression to be evaluated in the DSL module's context.

Use this extremely sparingly. It should almost never be necessary, unless building certain extensions that require the module in question to define a given function.

What you likely want is either one of the DSL introspection functions, like Spark.Dsl.Extension.get_entities/2 or Spark.Dsl.Extension.get_opt/5). If you simply want to store a custom value that can be retrieved easily, or cache some precomputed information onto the resource, use persist/3.

Provide the dsl state, bindings that should be unquote-able, and the quoted block to evaluate in the module. For example, if we wanted to support a resource.primary_key() function that would return the primary key (this is unnecessary, just an example), we might do this:

fields = the_primary_key_fields

dsl_state =
  Spark.Dsl.Transformer.eval(
    dsl_state,
    [fields: fields],
    quote do
      def primary_key() do
        unquote(fields)
      end
    end
  )

fetch_option(dsl_state, path, option)

fetch_persisted(dsl, key)

get_entities(dsl_state, path)

get_option(dsl_state, path, option, default \\ nil)

get_persisted(dsl, key, default \\ nil)

persist(dsl, key, value)

Saves a value into the dsl config with the given key.

This can be used to precompute some information and cache it onto the resource, or simply store a computed value. It can later be retrieved with Spark.Dsl.Extension.get_persisted/3.

remove_entity(dsl_state, path, func)

replace_entity(dsl_state, path, replacement, matcher \\ nil)

set_option(dsl_state, path, option, value)

sort(transformers)