defmodule TypedStruct do
@moduledoc """
TypedStruct is a library for defining structs with a type without writing
boilerplate code.
## Rationale
To define a struct in Elixir, you probably want to define three things:
* the struct itself, with default values,
* the list of enforced keys,
* its associated type.
It ends up in something like this:
defmodule Person do
@moduledoc \"\"\"
A struct representing a person.
\"\"\"
@enforce_keys [:name]
defstruct name: nil,
age: nil,
happy?: true,
phone: nil
@typedoc "A person"
@type t() :: %__MODULE__{
name: String.t(),
age: non_neg_integer() | nil,
happy?: boolean(),
phone: String.t() | nil
}
end
In the example above you can notice several points:
* the keys are present in both the `defstruct` and type definition,
* enforced keys must also be written in `@enforce_keys`,
* if a key has no default value and is not enforced, its type should be
nullable.
If you want to add a field in the struct, you must therefore:
* add the key with its default value in the `defstruct` list,
* add the key with its type in the type definition.
If the field is not optional, you should even add it to `@enforce_keys`. This
is way too much work for lazy people like me, and moreover it can be
error-prone.
It would be way better if we could write something like this:
defmodule Person do
@moduledoc \"\"\"
A struct representing a person.
\"\"\"
use TypedStruct
typedstruct do
@typedoc "A person"
field :name, String.t(), enforce: true
field :age, non_neg_integer()
field :happy?, boolean(), default: true
field :phone, String.t()
end
end
Thanks to TypedStruct, this is now possible :)
## Usage
### Setup
To use TypedStruct in your project, add this to your Mix dependencies:
{:typed_struct, "~> #{Mix.Project.config()[:version]}"}
If you do not plan to compile modules using TypedStruct at runtime, you can
add `runtime: false` to the dependency tuple as TypedStruct is only used at
build time.
If you want to avoid `mix format` putting parentheses on field definitions,
you can add to your `.formatter.exs`:
[
...,
import_deps: [:typed_struct]
]
### General usage
To define a typed struct, use `TypedStruct`, then define your struct within a
`typedstruct` block:
defmodule MyStruct do
# Use TypedStruct to import the typedstruct macro.
use TypedStruct
# Define your struct.
typedstruct do
# Define each field with the field macro.
field :a_string, String.t()
# You can set a default value.
field :string_with_default, String.t(), default: "default"
# You can enforce a field.
field :enforced_field, integer(), enforce: true
end
end
Each field is defined through the `field/2` macro.
### Options
If you want to enforce all the keys by default, you can do:
defmodule MyStruct do
use TypedStruct
# Enforce keys by default.
typedstruct enforce: true do
# This key is enforced.
field :enforced_by_default, term()
# You can override the default behaviour.
field :not_enforced, term(), enforce: false
# A key with a default value is not enforced.
field :not_enforced_either, integer(), default: 1
end
end
You can also generate an opaque type for the struct:
defmodule MyOpaqueStruct do
use TypedStruct
# Generate an opaque type for the struct.
typedstruct opaque: true do
field :name, String.t()
end
end
If you often define submodules containing only a struct, you can avoid
boilerplate code:
defmodule MyModule do
use TypedStruct
# You now have %MyModule.Struct{}.
typedstruct module: Struct do
field :field, term()
end
end
### Documentation
To add a `@typedoc` to the struct type, just add the attribute in the
`typedstruct` block:
typedstruct do
@typedoc "A typed struct"
field :a_string, String.t()
field :an_int, integer()
end
You can also document submodules this way:
typedstruct module: MyStruct do
@moduledoc "A submodule with a typed struct."
@typedoc "A typed struct in a submodule"
field :a_string, String.t()
field :an_int, integer()
end
### Plugins
It is possible to extend the scope of TypedStruct by using its plugin
interface, as described in `TypedStruct.Plugin`. For instance, to
automatically generate lenses with the [Lens](https://github.com/obrok/lens)
library, you can use
[`TypedStructLens`](https://github.com/ejpcmac/typed_struct_lens) and do:
defmodule MyStruct do
use TypedStruct
typedstruct do
plugin TypedStructLens
field :a_field, String.t()
field :other_field, atom()
end
@spec change(t()) :: t()
def change(data) do
# a_field/0 is generated by TypedStructLens.
lens = a_field()
put_in(data, [lens], "Changed")
end
end
## What do I get?
When defining an empty `typedstruct` block:
defmodule Example do
use TypedStruct
typedstruct do
end
end
you get an empty struct with its module type `t()`:
defmodule Example do
@enforce_keys []
defstruct []
@type t() :: %__MODULE__{}
end
Each `field` call adds information to the struct, `@enforce_keys` and the type
`t()`.
A field with no options adds the name to the `defstruct` list, with `nil` as
default. The type itself is made nullable:
defmodule Example do
use TypedStruct
typedstruct do
field :name, String.t()
end
end
becomes:
defmodule Example do
@enforce_keys []
defstruct name: nil
@type t() :: %__MODULE__{
name: String.t() | nil
}
end
The `default` option adds the default value to the `defstruct`:
field :name, String.t(), default: "John Smith"
# Becomes
defstruct name: "John Smith"
When set to `true`, the `enforce` option enforces the key by adding it to the
`@enforce_keys` attribute.
field :name, String.t(), enforce: true
# Becomes
@enforce_keys [:name]
defstruct name: nil
In both cases, the type has no reason to be nullable anymore by default. In
one case the field is filled with its default value and not `nil`, and in the
other case it is enforced. Both options would generate the following type:
@type t() :: %__MODULE__{
name: String.t() # Not nullable
}
Passing `opaque: true` replaces `@type` with `@opaque` in the struct type
specification:
typedstruct opaque: true do
field :name, String.t()
end
generates the following type:
@opaque t() :: %__MODULE__{
name: String.t()
}
When passing `module: ModuleName`, the whole `typedstruct` block is wrapped in
a module definition. This way, the following definition:
defmodule MyModule do
use TypedStruct
typedstruct module: Struct do
field :field, term()
end
end
becomes:
defmodule MyModule do
defmodule Struct do
@enforce_keys []
defstruct field: nil
@type t() :: %__MODULE__{
field: term() | nil
}
end
end
"""
@doc false
defmacro __using__(_) do
quote do
import TypedStruct, only: [typedstruct: 1, typedstruct: 2]
end
end
@doc """
Defines a typed struct.
Inside a `typedstruct` block, each field is defined through the `field/2`
macro.
## Options
* `enforce` - if set to true, sets `enforce: true` to all fields by default.
This can be overridden by setting `enforce: false` or a default value on
individual fields.
* `opaque` - if set to true, creates an opaque type for the struct.
* `module` - if set, creates the struct in a submodule named `module`.
## Examples
defmodule MyStruct do
use TypedStruct
typedstruct do
field :field_one, String.t()
field :field_two, integer(), enforce: true
field :field_three, boolean(), enforce: true
field :field_four, atom(), default: :hey
end
end
The following is an equivalent using the *enforce by default* behaviour:
defmodule MyStruct do
use TypedStruct
typedstruct enforce: true do
field :field_one, String.t(), enforce: false
field :field_two, integer()
field :field_three, boolean()
field :field_four, atom(), default: :hey
end
end
You can create the struct in a submodule instead:
defmodule MyModule do
use TypedStruct
typedstruct, module: Struct do
field :field_one, String.t()
field :field_two, integer(), enforce: true
field :field_three, boolean(), enforce: true
field :field_four, atom(), default: :hey
end
end
"""
defmacro typedstruct(opts \\ [], do: block) do
if is_nil(opts[:module]) do
quote do
Module.eval_quoted(
__ENV__,
TypedStruct.__typedstruct__(
unquote(Macro.escape(block)),
unquote(opts)
)
)
end
else
quote do
defmodule unquote(opts[:module]) do
Module.eval_quoted(
__ENV__,
TypedStruct.__typedstruct__(
unquote(Macro.escape(block)),
unquote(opts)
)
)
end
end
end
end
@doc false
def __typedstruct__(block, opts) do
quote do
Module.register_attribute(__MODULE__, :ts_plugins, accumulate: true)
Module.register_attribute(__MODULE__, :ts_fields, accumulate: true)
Module.register_attribute(__MODULE__, :ts_types, accumulate: true)
Module.register_attribute(__MODULE__, :ts_enforce_keys, accumulate: true)
Module.put_attribute(__MODULE__, :ts_enforce?, unquote(!!opts[:enforce]))
# Create a scope to avoid leaks.
(fn ->
import TypedStruct
unquote(block)
end).()
@enforce_keys @ts_enforce_keys
defstruct @ts_fields
TypedStruct.__type__(@ts_types, unquote(opts))
Enum.each(@ts_plugins, fn {plugin, plugin_opts} ->
if {:after_definition, 1} in plugin.__info__(:functions) do
Module.eval_quoted(__MODULE__, plugin.after_definition(plugin_opts))
end
end)
Module.delete_attribute(__MODULE__, :ts_enforce?)
Module.delete_attribute(__MODULE__, :ts_enforce_keys)
Module.delete_attribute(__MODULE__, :ts_types)
Module.delete_attribute(__MODULE__, :ts_plugins)
end
end
@doc false
defmacro __type__(types, opts) do
if Keyword.get(opts, :opaque, false) do
quote bind_quoted: [types: types] do
@opaque t() :: %__MODULE__{unquote_splicing(types)}
end
else
quote bind_quoted: [types: types] do
@type t() :: %__MODULE__{unquote_splicing(types)}
end
end
end
@doc """
Registers a plugin for the currently defined struct.
## Example
typedstruct do
plugin MyPlugin
field :a_field, String.t()
end
For more information on how to define your own plugins, please see
`TypedStruct.Plugin`. To use a third-party plugin, please refer directly to
its documentation.
"""
defmacro plugin(plugin, opts \\ []) do
quote do
Module.put_attribute(
__MODULE__,
:ts_plugins,
{unquote(plugin), unquote(opts)}
)
require unquote(plugin)
unquote(plugin).init(unquote(opts))
end
end
@doc """
Defines a field in a typed struct.
## Example
# A field named :example of type String.t()
field :example, String.t()
## Options
* `default` - sets the default value for the field
* `enforce` - if set to true, enforces the field and makes its type
non-nullable
"""
defmacro field(name, type, opts \\ []) do
quote do
TypedStruct.__field__(
__MODULE__,
unquote(name),
unquote(Macro.escape(type)),
unquote(opts)
)
Enum.each(@ts_plugins, fn {plugin, plugin_opts} ->
if {:field, 3} in plugin.__info__(:functions) do
Module.eval_quoted(
__MODULE__,
plugin.field(
unquote(name),
unquote(Macro.escape(type)),
unquote(opts) ++ plugin_opts
)
)
end
end)
end
end
@doc false
def __field__(mod, name, type, opts) when is_atom(name) do
if mod |> Module.get_attribute(:ts_fields) |> Keyword.has_key?(name) do
raise ArgumentError, "the field #{inspect(name)} is already set"
end
has_default? = Keyword.has_key?(opts, :default)
enforce_by_default? = Module.get_attribute(mod, :ts_enforce?)
enforce? =
if is_nil(opts[:enforce]),
do: enforce_by_default? && !has_default?,
else: !!opts[:enforce]
nullable? = !has_default? && !enforce?
Module.put_attribute(mod, :ts_fields, {name, opts[:default]})
Module.put_attribute(mod, :ts_types, {name, type_for(type, nullable?)})
if enforce?, do: Module.put_attribute(mod, :ts_enforce_keys, name)
end
def __field__(_mod, name, _type, _opts) do
raise ArgumentError, "a field name must be an atom, got #{inspect(name)}"
end
# Makes the type nullable if the key is not enforced.
defp type_for(type, false), do: type
defp type_for(type, _), do: quote(do: unquote(type) | nil)
end
