Mine v0.3.1 Mine View Source
Link to this section Summary
Functions
When to_view
is invoked, an extra field with the key key
will be added
to the resulting map with the value value
.
Changes the name of the default view to name
.
Used to specify the requirements for generating to_view
and from_view
functions
on a module.
Changes the name use to identify a field in an external view.
Declares that the given key will not be considered when mapping a struct in
either to_view
or from_view
.
Link to this section Types
Link to this section Functions
When to_view
is invoked, an extra field with the key key
will be added
to the resulting map with the value value
.
Useful when an external API is not hygienic and requires constant metadata for an entity to be properly parsed.
For example:
defmodule MyModule do
use Mine
struct [:field]
defview do
append "@class", "Some.Java.Class"
end
end
MyModule.to_view(%MyModule{field: "example"})
# %{"field" => "example", "@class" => "Some.Java.Class"}
Changes the name of the default view to name
.
The default view name will be the fallback parameter for any calls to
to_view/1
and from_view/1
.
Normally, these functions will be generated with signatures similar to the following:
def to_view(struct = %MyModule{}, view \\ :default)
def from_view(map, view \\ :default)
But declaring default_view :other
in your module...
defmodule MyModule do
use Mine
# create struct
default_view :other
defview :other do
# ...
end
end
...yields signatures like these:
def to_view(struct = %MyModule{}, view \\ :other)
def from_view(map, view \\ :other)
Used to specify the requirements for generating to_view
and from_view
functions
on a module.
Within the scope of this macro, Mine.field/2
, Mine.append/2
, and
Mine.ignore/1
will be in scope.
The name
argument is a value used to identify this view when invoking the
generated to_view
and from_view
functions. This defaults to, well, :default
.
If there are multiple views declared in a module and you wish to change the
default behavior of the single arity to_view
and from_view
functions,
use Mine.default_view/1
.
Note that any fields that exist in the modules struct and are not explicitly
ignored with a call to Mine.ignore/1
will not be ignored. This behavior
may be configurable in the future.
Annotations can be placed before defview
to augment the view.
@default_view
: if passedtrue
, indicates that the following view should be the default. It can also be passed the name of a view, similar toMine.default_view/1
.@exclude_if
: should be passed a function with arity 1 that returnstrue
orfalse
. Used to filter values maps resulting from a call toto_view
. This is useful for when empty fields should not be included in the final data representation. Two helper functions can be referenced using atoms::is_nil
(entries whose values are nil will be filtered out), and:is_blank
(entries whose values are nil or an empty string are removed).
Changes the name use to identify a field in an external view.
There are many cases where the name you use for a field within your Elixir application is not the name used outside of your application. This is especially apparent when interfacing with an API that defines variables in camel case. Since we conventionally represent atoms (and therefore the keys of structs) in snake case, this can lead to code mapping field names to and from the external naming convention.
field/2
is a simpler way to represent this relationship.
Options:
- as: Name to use when mapping to/from an external view
- default: Value to be used when struct does not contain an entry for the given key
- map_to: Function with arity 1 that will be invoked on the existing value
in the struct when using
to_view
- map_from: Function with arity 1 that will be invoked on the value found in
the external view when using
from_view
Example:
defmodule MyModule do
use Mine
struct [:my_field, :foo, :to_upper]
defview do
field :my_field, as: "myField"
field :foo, default: "bar"
field :to_upper, map_to: &String.upcase/1
end
end
MyModule.to_view(%MyModule{my_field: 1, to_upper: "upper!"})
# %{"myField" => 1, "foo" => "bar", "to_upper" => "UPPER!"}
Declares that the given key will not be considered when mapping a struct in
either to_view
or from_view
.
For example:
defmodule MyModule do
use Mine
struct [:public, :private]
defview do
ignore :private
end
end
MyModule.to_view(%MyModule{public: "hello", private: "world"})
# %{"public" => "hello"}
MyModule.from_view(%{"public" => "hello", "private" => "world"})
# %MyModule{public: "hello"}
A field that has been declared as ignored cannot be used in Mine.field/2
and
vice versa. Doing so will raise an error.