defprotocol Describe do
@doc "Returns a short human description."
def describe(value)
end
Elixir has two ways to let one piece of code work with many kinds of things:
Protocols are how to_string/1, inspect/1 and
Enum work on so many types.
defprotocol Describe do
@doc "Returns a short human description."
def describe(value)
end
Implementations live with defimpl, for built-in
types or your own structs, and can sit in a
different module or library from the protocol.
Strings are binaries, and protocols call that type
BitString.
defimpl Describe, for: Integer do
def describe(n) when n < 0, do: "a negative integer"
def describe(_n), do: "an integer"
end
defimpl Describe, for: BitString do
def describe(s), do: "a string of #{String.length(s)} characters"
end
defimpl Describe, for: List do
def describe(list), do: "a list of #{length(list)} items"
end
IO.puts(Describe.describe(42))
IO.puts(Describe.describe(-1))
IO.puts(Describe.describe("héllo"))
IO.puts(Describe.describe([1, 2, 3]))
an integer
a negative integer
a string of 5 characters
a list of 3 items
Structs get their own implementation, separate from
plain maps. (struct/2 is struct!/2 without the
checks: it ignores unknown keys.)
defmodule Temp do
defstruct [:celsius]
end
defimpl Describe, for: Temp do
def describe(%{celsius: c}), do: "a temperature of #{c}°C"
end
IO.puts(Describe.describe(struct(Temp, celsius: 21)))
a temperature of 21°C
Calling a protocol for a type with no
implementation raises Protocol.UndefinedError.
try do
Describe.describe(:an_atom)
rescue
e in Protocol.UndefinedError ->
IO.puts(e |> Exception.message() |> String.split("\n") |> hd())
end
protocol Describe not implemented for Atom
Built-in protocols plug your types into the
language. Implementing String.Chars makes
to_string/1 and interpolation work; @derive
picks a ready-made implementation. This one hides a
field from inspect.
defmodule Account do
@derive {Inspect, except: [:password]}
defstruct [:login, :password]
end
defimpl String.Chars, for: Account do
def to_string(%{login: login}), do: "account #{login}"
end
account = struct(Account, login: "ada", password: "hunter2")
IO.puts("Logged in as #{account}")
IO.inspect(account)
Logged in as account ada
#Account<login: "ada", ...>
A behaviour lists callbacks with @callback, each
with a typespec (see
Typespecs and Types). Here: any
module that can deliver a notification.
defmodule Notifier do
@callback deliver(to :: String.t(), message :: String.t()) :: :ok | {:error, term()}
@callback channel() :: String.t()
end
A module adopts it with @behaviour. @impl true
marks each function that implements a callback, so
the compiler can check names and arities.
defmodule Sms do
@behaviour Notifier
@impl true
def deliver(to, message), do: IO.puts("SMS to #{to}: #{message}")
@impl true
def channel, do: "sms"
end
defmodule Email do
@behaviour Notifier
@impl true
def deliver(to, message), do: IO.puts("email to #{to}: #{message}")
@impl true
def channel, do: "email"
end
A module name is just an atom, so it can live in a
variable (or in config), and module.function(...)
calls into whichever module is there. The code that
sends doesn't know or care which one it got.
for notifier <- [Sms, Email] do
notifier.deliver("ada", "your order shipped via #{notifier.channel()}")
end
SMS to ada: your order shipped via sms
email to ada: your order shipped via email
The checks are compile-time warnings. To show them
without failing this page, compile a broken module
from a string and collect the warnings as data:
it misspells deliver/2 and forgets @impl on
channel/0.
broken = """
defmodule Pigeon do
@behaviour Notifier
def channel, do: "pigeon"
@impl true
def delivr(_to, _message), do: :ok
end
"""
{_, warnings} = Code.with_diagnostics(fn -> Code.compile_string(broken) end)
for w <- warnings, do: IO.puts(w.message |> String.split(". ") |> hd())
got "@impl true" for function delivr/2 but no behaviour specifies such callback
module attribute @impl was not set for function channel/0 callback (specified in Notifier)
function deliver/2 required by behaviour Notifier is not implemented (in module Pigeon)
use Mod runs the macro Mod.__using__/1, which
injects code into your module: usually
@behaviour Mod plus default implementations you
may override. quote returns code instead of
running it (From Source to BEAM
goes deeper). This is what use GenServer does in
the Processes and OTP track.
defmodule Notifier.Base do
defmacro __using__(_opts) do
quote do
@behaviour Notifier
@impl true
def channel, do: __MODULE__ |> Module.split() |> List.last() |> String.downcase()
defoverridable channel: 0
end
end
end
defmodule Slack do
use Notifier.Base
@impl true
def deliver(to, message), do: IO.puts("Slack DM to #{to}: #{message}")
end
Slack.deliver("ada", "deploy finished")
IO.inspect(Slack.channel(), label: "default channel")
Slack DM to ada: deploy finished
default channel: "slack"
When to use which:
Pitfall: prefer a protocol over a big
case/condon types when other people need to add types later. If every type is yours and known up front, plain pattern matching in function heads is simpler.
Pitfall: a behaviour is only checked with warnings. A module that misses a callback still compiles, and calling the missing function raises
UndefinedFunctionErrorat runtime. Make your build treat warnings as errors (Mix Projects shows how).
Pitfall:
@derive {Inspect, except: [...]}only hides values frominspect, such as logs and crash reports. The data is still in the struct and still serialized by JSON encoders unless you exclude it there too.