API reference
v0.1.4
This page lists the functions that GuardedStruct generates on your modules and the public modules of the library. It describes version 0.1.4. For the options you write in a guardedstruct block, see the DSL reference.
Functions on a guarded module
Every module that uses use GuardedStruct, and every module generated for a sub_field, has these functions.
| Function | Purpose |
|---|---|
builder(input) | Builds the struct. Returns {:ok, struct} or {:error, errors}. |
builder(input, raise?) | The same. With true, and error: true set on the section, it raises <Module>.Error instead of returning the error tuple. |
keys() | The names of the struct's keys, without virtual fields. |
keys(:all) | The keys with nested keys, as %{name: [keys]}. |
keys(name) | true when name is a key. |
enforce_keys(), enforce_keys(:all), enforce_keys(name) | The same three forms for the required keys. enforce_keys(:all) lists only the required keys, at every level. |
example() | A struct filled with defaults and placeholders. |
__information__() | A map with module, keys, path, key, options, enforce_keys, conditional_keys, dynamic_keys and virtual_keys. |
__fields__() | The metadata of every field, as a list of maps. |
__field_meta__(name) | The metadata of one field, or nil. |
__guarded_information__(), __guarded_fields__(), __guarded_field_meta__(name) | The same three, under the name the Ash extension uses. |
__guarded_has_validator__(), __guarded_has_main_validator__() | true when the module defines validator/2 or main_validator/1. |
__guarded_error_module__() | The Error module, or nil. |
__guarded_derive_extensions_opt__() | The derive_extensions: value from use GuardedStruct, or nil. |
You can define two functions yourself. validator(field, value) checks fields and main_validator(attrs) checks the whole map. See Write a field validator and a main validator.
A module whose only field is named with a regex returns a plain map from builder. Its keys() is [], its example() is %{}, and it has no struct.
Input that builder accepts
| Input | Meaning |
|---|---|
%{...} | A map with atom or string keys. |
%Struct{} | A struct, read as a map. |
{:root, attrs} or {[:root], attrs} | The same as passing attrs. |
{:root, attrs, :add} | The default. auto replaces values you sent. |
{:root, attrs, :edit} | auto fills only keys that are missing or nil. |
{key, attrs}, {key, attrs, mode} | key is an atom or a list of atoms. The struct is built from the map found at that key in attrs, and root paths read from the whole of attrs. |
| Anything else | An error with the action bad_parameters and the field :__root__. |
GuardedStruct.Validate
| Function | Purpose |
|---|---|
run(derive_string, value) | Applies a derive string to one value. Returns {:ok, value} or {:error, errors}. A string that cannot be read, or has a wrong operand, returns a bad_parameters error. |
field(module, field, value, opts \\ []) | Validates one field. Options: mode: :strict (the default) or :isolated, and context: a map that supplies the fields a rule depends on. |
partial(module, attrs) | Validates the fields present in attrs and skips the rest. |
field and partial use the module's derive_extensions, validate_derive and sanitize_derive as builder/1 does.
GuardedStruct.Info
| Function | Returns |
|---|---|
fields/1 | Field names, including virtual fields, in declaration order. A pattern-keyed module lists its patterns. |
fields_meta/1, field/2, field?/2 | All metadata, one field's metadata or nil, and true when a field exists. On a pattern-keyed module a name that a pattern matches is a field. |
enforce_keys/1 | The required keys. |
field_kind/2 | :field, :sub_field, :conditional_field, :virtual_field, :dynamic_field, :pattern_field for a name that a pattern of a pattern-keyed module matches, or nil. |
field_default/2, field_derives/2, field_validator/2, field_auto/2 | The option of one field, or nil. |
enforce?/2, virtual?/2, dynamic?/2 | A boolean for one field. |
sub_fields/1, virtual_fields/1, dynamic_fields/1, conditional_fields/1 | The names of that kind. |
conditional_keys/1 | The names of conditional fields, from __information__/0. |
pattern_keyed?/1 | true when the module is a pattern-keyed map. |
enforce?/1, opaque?/1, authorized_fields?/1, json?/1, error?/1 | The section option as a boolean. |
sub_module/2 | The module generated for a sub_field, or nil. |
conditional_children/2 | The child metadata of a conditional field, or nil. |
describe/1 | One map with module, path, key, shape, pattern_keyed?, patterns, keys, enforce_keys, conditional_keys, options and fields. |
GuardedStruct.Info also has the functions that Spark generates for the section: guardedstruct/1 returns the declared entities, and each option has accessors such as guardedstruct_json!/1.
GuardedStruct.Diff
| Function | Purpose |
|---|---|
diff(a, b) | A map of changes between two structs of one module, or two plain maps. :not_comparable for anything else. |
apply(struct, diff) | Applies a diff and returns the changed struct or map. |
equal?(a, b) | true when diff/2 finds no change. |
GuardedStruct.Errors
| Name | Purpose |
|---|---|
from_tuple/1 | Converts an error list, or an {:error, list} tuple, into a Splode error. |
GuardedStruct.Errors.Invalid | The class that holds the errors in its errors list. |
GuardedStruct.Errors.Validation | One error, with field, action, message, hint and child_errors. |
GuardedStruct.Errors.Unknown | An entry that is not a map with a field and an action. It carries the original value. |
The module also has the functions that Splode generates, such as traverse_errors/2 and to_class/1.
GuardedStruct.Derive.Extension
use GuardedStruct.Derive.Extension adds a derives block. The module it defines has __validators__/0 and __sanitizers__/0, which list the op names, __validate__/3 and __sanitize__/2, which run an op, and __derive_extension__?/0.
| Function | Purpose |
|---|---|
registered_extensions/0 | The extensions from the application config, cached. |
clear_cache/0 | Clears that cache. |
extensions_for/1 | The extensions that apply to a module. |
resolve_opt/1 | Resolves a derive_extensions: list, with :config expanded. |
validate_opt!/1 | Raises ArgumentError for a bad list. |
dispatch_validate/3,4, dispatch_sanitize/2,3 | Run an op through the extensions. They return :__not_found__ when none defines it. |
all_extension_validators/0,1, all_extension_sanitizers/0,1 | A set of the op names the extensions define. |
current_module/0 | The module a build is running for, read from the process dictionary. |
GuardedStruct.Derive.SanitizerDerive
sanitize(value, op) applies one sanitize op to a value. The value comes first, so calls pipe. See Sanitize ops.
GuardedStruct.AshResource
| Name | Purpose |
|---|---|
GuardedStruct.AshResource | The Ash extension. A resource that uses it gets __guarded_change__/1,2, __guarded_information__/0, __guarded_fields__/0, __guarded_field_meta__/1 and __guarded_field_name_set__/0. |
GuardedStruct.AshResource.Change | The change module, with change/3, atomic/3 and batch_change/3. |
GuardedStruct.AshResource.Info | fields/1, fields_meta/1, field/2, field?/2, information/1 and validate/2,3, for resources. |
Telemetry events
| Event | Measurements | Metadata |
|---|---|---|
[:guarded_struct, :builder, :start] | system_time | module |
[:guarded_struct, :builder, :stop] | duration | module, result, and error_count on an error |
[:guarded_struct, :builder, :exception] | duration | module, kind, reason, stacktrace |
Mix task
mix igniter.install guarded_struct runs mix guarded_struct.install, which needs Igniter. It adds the dependency, adds a lint alias that runs spark.formatter and format, and sets config :guarded_struct, derive_extensions: [].