Mine v0.3.3 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

Link to this macro

append(key, value)

View Source (macro)

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"}
Link to this macro

default_view(name)

View Source (macro)

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)
Link to this macro

defview(name, list)

View Source (macro)

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 passed true, indicates that the following view should be the default. It can also be passed the name of a view, similar to Mine.default_view/1.
  • @exclude_if: should be passed a function with arity 1 that returns true or false. Used to filter values maps resulting from a call to to_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).
Link to this macro

field(key, opts)

View Source (macro)

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!"}
Link to this function

handle_attributes!(mod, view_name)

View Source

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.

Link to this function

valid_key?(val)

View Source
valid_key?(any()) :: boolean()