Provides macros for defining schemas which is used for casting and validating params.

Due to limitations of implementation, it's impossible to document every supported macros within @doc. Because of that, I will try to best to document them within @moduledoc.

Available macros

CozyParams.Schema provides a subset of macros supported by Ecto, In addition, it makes some changes on embeds_one and embeds_many.

In a nutshell, all available macros are:

1. schema(do: block)
2. field(name, type, opts \\ [])
   • available opts:
     • :default
     • :required - default: false
     • :pre_cast - specify a unary function to process data before casting
3. embeds_one(name, opts \\ [], do: block)
   • available opts:
     • :required - default: false
4. embeds_one(name, schema, opts \\ [])
   • available opts:
     • :required - default: false
5. embeds_many(name, opts \\ [], do: block)
   • available opts:
     • :required - default: false
6. embeds_many(name, schema, opts \\ [])
   • available opts:
     • :required - default: false

type argument will be passed to Ecto.Schema, so it supports all the types supported by Ecto.Schema in theory. Read Types and casting section of Ecto.Schema to get more information.

Examples

There're 2 ways to define a schema:

1. use inline syntax
2. use extra modules

Define a schema contains embedded fields in inline syntax:

defmodule PersonParams do
  use CozyParams.Schema

  schema do
    field :name, :string, required: true
    field :age, :integer
    field :wishlist, {:array, :string}, pre_cast: &String.split(&1, ~r/,\s*/)

    embeds_one :mate, required: true do
      field :name, :string, required: true
      field :age, :integer
    end

    embeds_many :pets do
      field :name, :string, required: true
      field :breed, :string
    end
  end
end

PersonParams.from(%{
  name: "Charlie",
  mate: %{
    name: "Lucy"
  },
  wishlist: "table,chair,computer"
})

Define a schema contains embedded fields with extra modules:

defmodule PersonParams do
  use CozyParams.Schema

  defmodule Mate do
    use CozyParams.Schema

    schema do
      field :name, :string, required: true
      field :age, :integer
      field :wishlist, {:array, :string}, pre_cast: &String.split(&1, ~r/,\s*/)
    end
  end

  defmodule Pet do
    use CozyParams.Schema

    schema do
      field :name, :string, required: true
      field :breed, :string
    end
  end

  schema do
    field :name, :string, required: true
    field :age, :integer
    embeds_one :mate, Mate, required: true
    embeds_many :pets, Pet
  end
end

PersonParams.from(%{
  name: "Charlie",
  mate: %{
    name: "Lucy"
  },
  wishlist: "table,chair,computer"
})

About the generated functions

schema/1 will create 2 functions automatically:

1. changeset/2 which is overridable.
2. from/1 which will be called by high-level abstractions, such as CozyParams.

Reflection

Schemas will generate the following functions that can be used for runtime introspection of the schema:

• __cozy_params_schema__/0
• __cozy_params_schema__/1
• __cozy_params_changeset__/0
• __cozy_params_changeset__/1

All possible calls:

• __cozy_params_schema__() - an alias of __cozy_params_schema__(:metadata).
• __cozy_params_schema__(:metadata) - returns the metadata of current schema.
• __cozy_params_schema__(:original_ast) - returns the original AST passed to schema/1.
• __cozy_params_schema__(:transpiled_ast) - returns the transpiled AST used by cozy_params.
• __cozy_params_schema__(:ecto_ast) - returns the AST used by Ecto.
• __cozy_params_changeset__() - an alias of __cozy_params_changeset__(:metadata).
• __cozy_params_changeset__(:metadata) - returns the metadata used by CozyParams.Changeset.