Behaviour for implementing custom Elex functions.

Functions are registered on a Elex.Context via Elex.Context.add_function/2 and invoked during evaluation by Elex.Evaluator.

units:

signature/0 may include units: :point | :additive | :none | :convert | :wrap | :unwrap. Omitted units: is :additive.

• :point — same category. The result unit is the first quantity argument (boolean/null args are skipped). Additive categories convert later quantity args into that unit. Non-additive categories require Elex.Unit.same?/2 (no silent F→C).
• :additive — reject non-additive arguments. Linear same-category args still convert into the first quantity argument's unit. This is the default, so unmarked double(1C) errors and double(1m) works.
• :none — reject all quantities (sqrt, pow, strings, pi).
• :convert — first arg a quantity, second a string target; result unit is the target (convert/2).
• :wrap — number plus a registered name or alias (add_unit/2).
• :unwrap — quantity to a number (remove_unit/1).

Implementing a function

Preserve the unit of an additive quantity (unwrap, then rewrap). See Advanced Topics for reject, :point preserve, and same-category multi-arg patterns.

defmodule MyApp.Functions.Double do
  @behaviour Elex.Function

  @impl Elex.Function
  def signature, do: %{name: :double, arity: 1}

  @impl Elex.Function
  def validate([arg_ast], context) do
    case Elex.Validator.same_numeric_type([arg_ast], context) do
      {:ok, type} -> {:ok, type}
      {:mismatch, type} -> {:error, "double expects a number, got " <> inspect(type)}
      {:error, reason} -> {:error, reason}
    end
  end

  @impl Elex.Function
  def call([%Elex.Quantity{value: value, unit: unit}]) do
    {:ok, doubled} = call([value])
    {:ok, %Elex.Quantity{value: doubled, unit: unit}}
  end

  def call([arg]) when is_struct(arg, Decimal) do
    {:ok, Decimal.mult(arg, Decimal.new(2))}
  end

  @impl Elex.Function
  def documentation do
    %{signature: "double(x)", description: "returns x multiplied by 2"}
  end
end