use Vtc.Ecto.Postgres.Utils
defpgmodule Vtc.Ecto.Postgres.PgFramestamp do
@moduledoc """
Defines a composite type for storing rational values as a
[PgRational](`Vtc.Ecto.Postgres.PgRational`) real-world playback seconds,
[PgFramerate](`Vtc.Ecto.Postgres.PgFramerate`) pair.
These values are cast to
[Framestamp](`Vtc.Framestamp`) structs for use in application code.
The composite types is defined as follows:
```sql
CREATE TYPE framestamp AS (
__seconds_n bigint,
__seconds_d bigint,
__rate_n bigint,
__rate_d bigint,
__rate_tags framerate_tags[]
);
```
> #### `Field Access` {: .warning}
>
> framestamp's inner fields are considered semi-private to end-users. For working with
> the seconds / rate values, see
> [create_func_seconds/0](`Vtc.Ecto.Postgres.PgFramestamp.Migrations.create_func_seconds/0`),
> [create_func_rate/0](`Vtc.Ecto.Postgres.PgFramestamp.Migrations.create_func_seconds/0`),
> which create Postgres functions to act as getter functions for working with inner
> framestamp data.
```sql
SELECT (18018, 5, 24000, 1001, '{non_drop}')::framestamp
```
## Field migrations
You can create `framerate` fields during a migration like so:
```elixir
alias Vtc.Framestamp
create table("events") do
add(:in, Framestamp.type())
add(:out, Framestamp.type())
end
```
[Framestamp](`Vtc.Framestamp`) re-exports the `Ecto.Type` implementation of this module,
and can be used any place this module would be used.
## Schema fields
Then in your schema module:
```elixir
defmodule MyApp.Event do
@moduledoc false
use Ecto.Schema
alias Vtc.Framestamp
@type t() :: %__MODULE__{
in: Framestamp.t(),
out: Framestamp.t()
}
schema "events" do
field(:in, Framestamp)
field(:out, Framestamp)
end
```
## Changesets
With the above setup, changesets should just work:
```elixir
def changeset(schema, attrs) do
schema
|> Changeset.cast(attrs, [:in, :out])
|> Changeset.validate_required([:in, :out])
end
```
Framerate values can be cast from the following values in changesets:
- [Framestamp](`Vtc.Framestamp`) structs.
- Maps with the following format:
```json
{
"smpte_timecode": "01:00:00:00",
"rate": {
"playback": [24000, 1001],
"ntsc": "non_drop"
}
}
```
Where `smpte_timecode` is properly formatted SMPTE timecode string and `playback`
is a map value supported by [PgFramerate](`Vtc.Ecto.Postgres.PgFramerate`) changeset
casts.
## Fragments
Framestamp values must be explicitly cast using
[type/2](https://hexdocs.pm/ecto/Ecto.Query.html#module-interpolation-and-casting):
```elixir
framestamp = Framestamp.with_frames!("01:00:00:00", Rates.f23_98())
query = Query.from(f in fragment("SELECT ? as r", type(^framestamp, Framestamp)), select: f.r)
```
"""
use Ecto.Type
alias Ecto.Changeset
alias Vtc.Ecto.Postgres.PgFramerate
alias Vtc.Ecto.Postgres.PgFramestamp
alias Vtc.Framerate
alias Vtc.Framestamp
alias Vtc.Source.Frames.SMPTETimecodeStr
@doc section: :ecto_migrations
@doc """
The database type for [PgFramestamp](`Vtc.Ecto.Postgres.PgFramestamp`).
Can be used in migrations as the fields type.
"""
@impl Ecto.Type
@spec type() :: atom()
def type, do: :framestamp
@typedoc """
Type of the raw composite value that will be sent to / received from the database.
"""
@type db_record() :: {non_neg_integer(), pos_integer(), non_neg_integer(), pos_integer(), [String.t()]}
@doc """
The database type for [PgFramerate](`Vtc.Ecto.Postgres.PgFramerate`).
Can be used in migrations as the fields type.
"""
@impl Ecto.Type
@spec cast(Framestamp.t() | %{String.t() => any()} | %{atom() => any()}) :: {:ok, Framerate.t()} | :error
def cast(%Framestamp{} = framestamp), do: {:ok, framestamp}
def cast(json) when is_map(json) do
schema = %{
smpte_timecode: :string,
rate: Framerate
}
changeset =
{%{}, schema}
|> Changeset.cast(json, [:smpte_timecode, :rate])
|> Changeset.validate_required([:smpte_timecode, :rate])
with {:ok, %{smpte_timecode: timecode_str, rate: rate}} <- Changeset.apply_action(changeset, :loaded),
{:ok, _} = result <- Framestamp.with_frames(%SMPTETimecodeStr{in: timecode_str}, rate) do
result
else
_ -> :error
end
end
def cast(_), do: :error
# Handles converting database records into Ratio structs to be used by the
# application.
@doc false
@impl Ecto.Type
@spec load(db_record()) :: {:ok, Framestamp.t()} | :error
def load({seconds_n, seconds_d, rate_n, rate_d, rate_tags}) do
seconds = Ratio.new(seconds_n, seconds_d)
with {:ok, framerate} <- PgFramerate.load({{rate_n, rate_d}, rate_tags}),
{:ok, _} = result <- Framestamp.with_seconds(seconds, framerate, round: :off) do
result
else
_ -> :error
end
end
def load(_), do: :error
# Handles converting Ratio structs into database records.
@doc false
@impl Ecto.Type
@spec dump(Framestamp.t()) :: {:ok, db_record()} | :error
def dump(%Framestamp{} = framestamp) do
with {:ok, {{rate_n, rate_d}, rate_tags}} <- PgFramerate.dump(framestamp.rate) do
{:ok, {framestamp.seconds.numerator, framestamp.seconds.denominator, rate_n, rate_d, rate_tags}}
end
end
def dump(_), do: :error
@doc section: :changeset_validators
@doc """
Adds all constraints created by
[PgFramestamp.Migrations.create_constraints/3](`Vtc.Ecto.Postgres.PgFramestamp.Migrations.create_constraints/3`)
to changeset.
## Arguments
- `changeset`: The changeset being validated.
- `field`: The field who's constraints are being checked.
## Options
Pass the same options that were passed to
[PgFramestamp.Migrations.create_constraints/3](`Vtc.Ecto.Postgres.PgFramestamp.Migrations.create_constraints/3`)
"""
@spec validate_constraints(Changeset.t(data), atom(), [PgFramestamp.Migrations.constraint_opt()]) :: Changeset.t(data)
when data: any()
def validate_constraints(changeset, field, opts \\ []) do
"dummy_table"
|> PgFramestamp.Migrations.build_constraint_list(field, opts)
|> Enum.reduce(changeset, fn constraint, changeset ->
Changeset.check_constraint(changeset, field, name: constraint.name)
end)
end
end
