ex_structable v0.4.0 ExStructable.Hooks behaviour View Source

Behaviour for default hook implementations.

Implement methods below in the module with use ExStructable to override behaviour (default implementations are provided in ExStructable).

Be sure to use @impl true above the hook implementation to add compile-time warnings about incorrect hook definitions.

Link to this section Summary

Callbacks

after_new(validation_result, options)

Called when a struct has passed validation after a call to YourModule.new/2. Does not get called if validate_struct throws an exception

after_put(validation_result, options)

Called when a struct has passed validation after a call to YourModule.put/3. Does not get called if validate_struct throws an exception

create_struct(args, options)

Override to create your struct in a custom way. This function ignores validity

put_into_struct(args, struct, options)

Override to put args into struct in a custom way, and return new struct. This function ignores validity

validate_struct(struct, options)

Override to check that the created struct has valid values

Link to this section Types

ignored_return_type()

ignored_return_type() :: any()

Link to this section Callbacks

after_new(validation_result, options)

after_new(
  validation_result :: ExStructable.validation_result(),
  options :: ExStructable.options()
) :: ignored_return_type()

Called when a struct has passed validation after a call to YourModule.new/2. Does not get called if validate_struct throws an exception.

Override to add custom functionality.

after_put(validation_result, options)

after_put(
  validation_result :: ExStructable.validation_result(),
  options :: ExStructable.options()
) :: ignored_return_type()

Called when a struct has passed validation after a call to YourModule.put/3. Does not get called if validate_struct throws an exception.

Override to add custom functionality.

create_struct(args, options)

create_struct(args :: ExStructable.args(), options :: ExStructable.options()) ::
  struct()

Override to create your struct in a custom way. This function ignores validity.

By default creates the struct with the given key/value args. This is used in YourModule.new/2.

put_into_struct(args, struct, options)

put_into_struct(
  args :: ExStructable.args(),
  struct(),
  options :: ExStructable.options()
) :: struct()

Override to put args into struct in a custom way, and return new struct. This function ignores validity.

By default puts the given key/value args into the given struct. This is used in YourModule.put/3.

validate_struct(struct, options)

validate_struct(struct(), options :: ExStructable.options()) ::
  ExStructable.validation_result()

Override to check that the created struct has valid values.

The return value is the return value of YourModule.new/2/YourModule.put/3, so usually returns a struct when validation passes. (You could return something else if you want to.)

When validation fails you should raise, or return a custom error value such as {:error, struct, reason}. If validation fails, one option would be to alter the struct so that it is valid. The choice of implementation is up to you.

By default returns the given struct without any checking.

You can even define a hook using guards such as:

@impl true
def validate_struct(struct = %Line{length: length}) when length > 0 do
  struct
end

because it raises a FunctionClauseError when the guard isn’t matched.