@spec arrange(Feel.Builtin.Function.t(), Feel.AST.arguments()) ::
  {:ok, [argument()], [Feel.Builtin.Function.signature()]}
  | {:error, Feel.Diagnostic.t()}

Puts the arguments of a call in the order of the parameters of the function, with the signatures that the call fits. {:error, diagnostic} if it fits none.

iex> {:ok, function} = Feel.Builtin.function("time")
iex> {:ok, ast} = Feel.parse("time(minute: 2, hour: 1, second: 3)")
iex> {:call, _meta, _callee, arguments} = ast
iex> {:ok, arranged, _signatures} = Feel.Analysis.Calls.arrange(function, arguments)
iex> Enum.map(arranged, fn :missing -> :missing; {:literal, _, value} -> Decimal.to_integer(value) end)
[1, 2, 3, :missing]

@spec callee(
  Feel.AST.expression(),
  Feel.Analysis.ScopeStack.t() | nil,
  Feel.Extensions.t()
) ::
  {:builtin, Feel.Builtin.Function.t()} | {:unwritten, Feel.Name.t()} | :value

What the callee of a call is.

iex> {:ok, ast} = Feel.parse(~s|date("2020-01-01")|)
iex> {:call, _meta, callee, _arguments} = ast
iex> {:builtin, function} = Feel.Analysis.Calls.callee(callee, nil)
iex> function.name
"date"

@spec mismatch(Feel.Builtin.Function.t(), [Feel.Builtin.Function.signature()], [
  Feel.IR.t()
]) ::
  :ok | {:error, Feel.Diagnostic.t()}

Whether the arguments of a call, analyzed and in the order of the parameters, are ones that none of the signatures it fits takes (D-56): the call is then null with an :argument_out_of_domain error, which is what the function would say when it runs, but a function is given the values and not the signature that the names of a call chose, so one that reads a list for a key as keys does not (context put, TCK 1146 nested008).

Only a certain mismatch is one. An argument that may be null or may be of any type is not, and the conversions of section 10.3.2.9.4 are allowed: a list of one element is that element where a value is wanted, and a value is the list of it where a list is wanted, and a date is a date and time where one is wanted (D-56). The length of a list is the one of the node that is a list literal or a constant (D-193), and unknown for any other. A parameter that the registry types any takes every argument, as does a signature the call is not the only one for.

A signature that says some arguments have to be of one kind (same_kind, D-155) rejects arguments whose kinds have nothing in common, though each is taken by its parameter: a string and a number are two points, and before takes no pair of them. The kinds an argument may be of are those of the members of its type that have an order (a number, a string, a date, a time, a date and time, a duration of either kind); null, Any and the name of a model type may be of every kind, as they are taken by every parameter, so one of them is never in disagreement. Nor is a list that may have no element, whose elements are not compared when it has none (max([]) is null, with no error); the items of a list literal or a constant are each one that the call has, and are compared. A range is not looked at: its type holds the range with no endpoint, which can be related to a point of any kind.

iex> const = fn value -> {:const, %{span: {0, 0}, type: Feel.Type.Union.of_value(value)}, value} end
iex> {:ok, function} = Feel.Builtin.function("context put")
iex> [key_signature | _] = function.signatures
iex> arguments = [const.(%{"x" => Decimal.new(1)}), const.(["y", "a"]), const.(Decimal.new(2))]
iex> {:error, diagnostic} = Feel.Analysis.Calls.mismatch(function, [key_signature], arguments)
iex> diagnostic.message
"context put is not defined for context, list, number"
iex> arguments = [const.(%{"x" => Decimal.new(1)}), const.(["y"]), const.(Decimal.new(2))]
iex> Feel.Analysis.Calls.mismatch(function, [key_signature], arguments)
:ok
iex> {:ok, before} = Feel.Builtin.function("before")
iex> {:error, diagnostic} = Feel.Analysis.Calls.mismatch(before, before.signatures, [const.("a"), const.(Decimal.new(2))])
iex> diagnostic.message
"before is not defined for string, number"
iex> Feel.Analysis.Calls.mismatch(before, before.signatures, [const.("a"), const.("b")])
:ok

@spec quiet_places([Feel.Builtin.Function.signature()], non_neg_integer()) :: [
  non_neg_integer()
]

The places (from 0) of the arguments of a call that are read quietly (D-100): those where every signature that the call fits has a quiet parameter (Feel.Builtin.Function.parameter/3).

iex> {:ok, abs} = Feel.Builtin.function("abs")
iex> Feel.Analysis.Calls.quiet_places(abs.signatures, 1)
[]

@spec result_type(
  Feel.Builtin.Function.t(),
  [Feel.Builtin.Function.signature()],
  [Feel.IR.t()] | nil
) ::
  Feel.Type.Union.t()

The type of the result of a call: the types that the signatures give which the arguments may be for, and null too unless the function is never null.

A signature that the arguments are certainly not for (mismatch/3 says it of all of them for a call that is null with its error) is not one that the call can be answered by, so abs(duration("P1D")) is a duration, though abs has signatures for numbers and for the other kind of duration. Only a certain mismatch leaves a signature out: an argument that may be of any type is for every signature, and so is any argument of a function that does not check its arguments (Feel.Builtin.Function). A null that an argument may be is not for every signature as it is in mismatch/3, since what the call gives for a null is null, which its type has anyway, and the rest of the argument says which signature gives the other results: abs(x) of a number that may be null is a number that may be null, and not a duration. A parameter that takes null among its types takes it, and an argument that is only null is for every signature. With no argument that tells them apart, the result is that of all the signatures. Without the list of the arguments at all (nil, the default) the signatures alone are asked about: the types they declare for the result, and not those that follow the arguments (result_from), and no rule of a family (Feel.Analysis.Images) is asked. A call with no argument (now(), concatenate()) is the empty list, and a rule may answer it.

iex> {:ok, function} = Feel.Builtin.function("date")
iex> signatures = Feel.Builtin.Function.with_arity(function, 1)
iex> Feel.Analysis.Calls.result_type(function, signatures)
[:date, :null]
iex> {:ok, is} = Feel.Builtin.function("is")
iex> Feel.Analysis.Calls.result_type(is, is.signatures)
[:boolean]
iex> {:ok, abs} = Feel.Builtin.function("abs")
iex> Feel.Analysis.Calls.result_type(abs, abs.signatures)
[:number, :years_and_months_duration, :days_and_time_duration, :null]
iex> duration = {:var, %{span: {0, 0}, type: [:days_and_time_duration]}, "d"}
iex> abs |> Feel.Analysis.Calls.result_type(abs.signatures, [duration]) |> Feel.Type.Union.format()
"days and time duration in [PT0S..max]"
iex> maybe_number = {:var, %{span: {0, 0}, type: [:number, :null]}, "x"}
iex> abs |> Feel.Analysis.Calls.result_type(abs.signatures, [maybe_number]) |> Feel.Type.Union.format()
"number in [0..max] | Null"

@spec single([Feel.Builtin.Function.signature()]) ::
  Feel.Builtin.Function.signature() | nil

The one signature that a call by name has chosen, if these are its signatures: those that differ only in types are one (Feel.Builtin.Function.merge_variants/1), so abs(n: x) has the signature of n that takes the kinds of all three. nil if there are others, or none.

iex> {:ok, abs} = Feel.Builtin.function("abs")
iex> {:ok, _arranged, signatures} = Feel.Analysis.Calls.arrange(abs, {:named, [{["n"], {:literal, %{span: {0, 0}}, Decimal.new(1)}}]})
iex> length(signatures)
3
iex> Enum.map(Feel.Analysis.Calls.single(signatures).parameters, & &1.types)
[[:number, :days_and_time_duration, :years_and_months_duration]]
iex> Feel.Analysis.Calls.single([])
nil

@spec written(Feel.AST.arguments()) :: [Feel.AST.expression()]

The expressions of the arguments as they are written, for a call that has to be null with its error: they are analyzed all the same, so that their errors are reported.