zf

enum.ex (6933B)

---

 defmodule Ecto.Enum do
   @moduledoc """
   A custom type that maps atoms to strings or integers.
 
   `Ecto.Enum` must be used whenever you want to keep atom values in a field.
   Since atoms cannot be persisted to the database, `Ecto.Enum` converts them
   to a string or an integer when writing to the database and converts them back
   to atoms when loading data. It can be used in your schemas as follows:
 
       # Stored as strings
       field :status, Ecto.Enum, values: [:foo, :bar, :baz]
 
   or
 
       # Stored as integers
       field :status, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
 
   Therefore, the type to be used in your migrations for enum fields depend
   on the choice above. For the cases above, one would do, respectively:
 
       add :status, :string
 
   or
 
       add :status, :integer
 
   Some databases also support enum types, which you could use in combination
   with the above.
 
   Composite types, such as `:array`, are also supported which allow selecting
   multiple values per record:
 
       field :roles, {:array, Ecto.Enum}, values: [:author, :editor, :admin]
 
   Overall, `:values` must be a list of atoms or a keyword list. Values will be
   cast to atoms safely and only if the atom exists in the list (otherwise an
   error will be raised). Attempting to load any string/integer not represented
   by an atom in the list will be invalid.
 
   The helper function `mappings/2` returns the mappings for a given schema and
   field, which can be used in places like form drop-downs. For example, given
   the following schema:
 
       defmodule EnumSchema do
         use Ecto.Schema
 
         schema "my_schema" do
           field :my_enum, Ecto.Enum, values: [:foo, :bar, :baz]
         end
       end
 
   You can call `mappings/2` like this:
 
       Ecto.Enum.mappings(EnumSchema, :my_enum)
       #=> [foo: "foo", bar: "bar", baz: "baz"]
 
   If you want the values only, you can use `Ecto.Enum.values/2`, and if you want
   the dump values only, you can use `Ecto.Enum.dump_values/2`.
 
   ## Embeds
 
   `Ecto.Enum` allows to customize how fields are dumped within embeds through the
   `:embed_as` option. Two alternatives are supported: `:values`, which will save
   the enum keys (and not their respective mapping), and `:dumped`, which will save
   the dumped value. The default is `:values`. For example, assuming the following
   schema:
 
       defmodule EnumSchema do
         use Ecto.Schema
 
         schema "my_schema" do
           embeds_one :embed, Embed do
             field :embed_as_values, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :values
             field :embed_as_dump, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :dump
           end
         end
       end
 
   The `:embed_as_values` field value will save `:foo | :bar`, while the
   `:embed_as_dump` field value will save as `1 | 2`.
   """
 
   use Ecto.ParameterizedType
 
   @impl true
   def type(params), do: params.type
 
   @impl true
   def init(opts) do
     values = opts[:values]
 
     {type, mappings} =
       cond do
         is_list(values) and Enum.all?(values, &is_atom/1) ->
           validate_unique!(values)
           {:string, Enum.map(values, fn atom -> {atom, to_string(atom)} end)}
 
         type = Keyword.keyword?(values) and infer_type(Keyword.values(values)) ->
           validate_unique!(Keyword.keys(values))
           validate_unique!(Keyword.values(values))
           {type, values}
 
         true ->
           raise ArgumentError, """
           Ecto.Enum types must have a values option specified as a list of atoms or a
           keyword list with a mapping from atoms to either integer or string values.
 
           For example:
 
               field :my_field, Ecto.Enum, values: [:foo, :bar]
 
           or
 
               field :my_field, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]
           """
       end
 
     on_load = Map.new(mappings, fn {key, val} -> {val, key} end)
     on_dump = Map.new(mappings)
     on_cast = Map.new(mappings, fn {key, _} -> {Atom.to_string(key), key} end)
 
     embed_as =
       case Keyword.get(opts, :embed_as, :values) do
         :values ->
           :self
 
         :dumped ->
           :dump
 
         other ->
           raise ArgumentError, """
           the `:embed_as` option for `Ecto.Enum` accepts either `:values` or `:dumped`,
           received: `#{inspect(other)}`
           """
       end
 
     %{
       on_load: on_load,
       on_dump: on_dump,
       on_cast: on_cast,
       mappings: mappings,
       embed_as: embed_as,
       type: type
     }
   end
 
   defp validate_unique!(values) do
     if length(Enum.uniq(values)) != length(values) do
       raise ArgumentError, """
       Ecto.Enum type values must be unique.
 
       For example:
 
           field :my_field, Ecto.Enum, values: [:foo, :bar, :foo]
 
       is invalid, while
 
           field :my_field, Ecto.Enum, values: [:foo, :bar, :baz]
 
       is valid
       """
     end
   end
 
   defp infer_type(values) do
     cond do
       Enum.all?(values, &is_integer/1) -> :integer
       Enum.all?(values, &is_binary/1) -> :string
       true -> nil
     end
   end
 
   @impl true
   def cast(nil, _params), do: {:ok, nil}
 
   def cast(data, params) do
     case params do
       %{on_load: %{^data => as_atom}} -> {:ok, as_atom}
       %{on_dump: %{^data => _}} -> {:ok, data}
       %{on_cast: %{^data => as_atom}} -> {:ok, as_atom}
       _ -> :error
     end
   end
 
   @impl true
   def load(nil, _, _), do: {:ok, nil}
 
   def load(data, _loader, %{on_load: on_load}) do
     case on_load do
       %{^data => as_atom} -> {:ok, as_atom}
       _ -> :error
     end
   end
 
   @impl true
   def dump(nil, _, _), do: {:ok, nil}
 
   def dump(data, _dumper, %{on_dump: on_dump}) do
     case on_dump do
       %{^data => as_string} -> {:ok, as_string}
       _ -> :error
     end
   end
 
   @impl true
   def equal?(a, b, _params), do: a == b
 
   @impl true
   def embed_as(_, %{embed_as: embed_as}), do: embed_as
 
   @doc "Returns the possible values for a given schema and field"
   @spec values(module, atom) :: [atom()]
   def values(schema, field) do
     schema
     |> mappings(field)
     |> Keyword.keys()
   end
 
   @doc "Returns the possible dump values for a given schema and field"
   @spec dump_values(module, atom) :: [String.t()] | [integer()]
   def dump_values(schema, field) do
     schema
     |> mappings(field)
     |> Keyword.values()
   end
 
   @doc "Returns the mappings for a given schema and field"
   @spec mappings(module, atom) :: Keyword.t()
   def mappings(schema, field) do
     try do
       schema.__changeset__()
     rescue
       _ in UndefinedFunctionError ->
         raise ArgumentError, "#{inspect(schema)} is not an Ecto schema"
     else
       %{^field => {:parameterized, Ecto.Enum, %{mappings: mappings}}} -> mappings
       %{^field => {_, {:parameterized, Ecto.Enum, %{mappings: mappings}}}} -> mappings
       %{^field => _} -> raise ArgumentError, "#{field} is not an Ecto.Enum field"
       %{} -> raise ArgumentError, "#{field} does not exist"
     end
   end
 end