View Source Construct behaviour (Construct v3.0.0)

Construct internally divided into three components:

construct-definition

Construct definition

defmodule StructureName do
  use Construct, struct_opts

  structure do
    include AnotherStructure
    field name, type, options
  end
end

struct_opts is options passed to make/2 and make!/2, described in Construct.Cast.make/3.

When you type use Construct — library bootstrapped few functions with Construct behaviour:

Link to this section Summary

Callbacks

Alias to make/2, used to follow Construct.Type.cast/1 callback.

Alias to make/2, but raises an Construct.MakeError exception if params have errors.

Functions

Checks if provided module is Construct module

Defines field on the structure with given name, type and options.

Includes provided structure and checks definition for validity at compile-time.

Defines a structure.

No doc at this time, should be written for 3.0.0 release

Collect types from defined Construct module to map

Link to this section Types

Link to this section Callbacks

@callback cast(params :: map(), opts :: Keyword.t()) :: {:ok, t()} | {:error, term()}

Alias to make/2, used to follow Construct.Type.cast/1 callback.

To use this structure as custom type.

@callback make(params :: map(), opts :: Keyword.t()) :: {:ok, t()} | {:error, term()}

Alias to Construct.Cast.make/3.

@callback make!(params :: map(), opts :: Keyword.t()) :: t()

Alias to make/2, but raises an Construct.MakeError exception if params have errors.

Link to this section Functions

Checks if provided module is Construct module

Link to this macro

field(name, type \\ :string, opts \\ [])

View Source (macro)
@spec field(atom(), Construct.Type.t(), Keyword.t()) :: Macro.t()

Defines field on the structure with given name, type and options.

Checks definition validity at compile time by name, type and options. For custom types checks for module existence and Construct.Type.cast/1 callback.

If field definition is invalid for some reason — it throws an Construct.DefinitionError exception with detailed reason.

options

Options

  • :default — sets default value for that field:

    • The default value is calculated at compilation time, so don't use expressions like DateTime.utc_now or Ecto.UUID.generate as they would then be the same for all structures;

    • Value from params is compared with default value before and after type cast;

    • If you pass field :a, type, default: nil and make(%{a: nil}) — type coercion will not be used, nil compares with default value and just appends that value to structure;

    • If field doesn't exist in params, it will use default value.

    By default this option is unset. Notice that you can't use functions as a default value.

Link to this macro

include(module, opts \\ [])

View Source (macro)
@spec include(
  t(),
  keyword()
) :: Macro.t()

Includes provided structure and checks definition for validity at compile-time.

options

Options

  • :only - (integer) specify fields that should be taken from included module, throws an error when field doesn't exist in provided module.

If included structure is invalid for some reason — this macro throws an Construct.DefinitionError exception with detailed reason.

Link to this macro

structure(list)

View Source (macro)

Defines a structure.

Link to this macro

structure_compile_hook(type, list)

View Source (macro)

No doc at this time, should be written for 3.0.0 release

Collect types from defined Construct module to map