@spec arity(t()) :: non_neg_integer()

Returns the number of parameters of a function.

@spec builtin(String.t(), [signature(), ...], [signature()]) :: t()

Builds a built-in function as a value, from its name and its signatures (Feel.Builtin.value/2 makes them from the function). The parameters and the result of the first signature are those that params/1 and type/1 give. variants are the signatures that the first ones were made of when they differ only in types (D-171): they are no function type of the value, and say what a call of it does (refinements/1).

iex> signature = %{parameters: [{"n", :number, false}], variadic?: false, returns: :number}
iex> function = Feel.Value.Function.builtin("abs", [signature])
iex> {function.kind, Feel.Value.Function.type(function)}
{:builtin, {:function, [:number], :number}}

@spec kind(t()) :: kind()

Returns the kind of a function.

@spec name(t()) :: String.t() | nil

Returns the name of a function, or nil when it has none.

@spec narrowings(t(), non_neg_integer()) :: [t()]

The built-in function restricted to each signature it made one of (refinements/1) that takes arity arguments, each as a function of its own (D-197): abs for a number, for a days and time duration, and for a years and months duration. One of them is what a declared function type is given when the function itself is not an instance of it (Feel.Type.Conversion).

A restricted function has the one signature it was made of, with its parameter names and the types it declares for this many arguments, and it takes only those: a call with another number of arguments, or with a value that is not of the type of its parameter, is null with an error, as it is for a function of FEEL (Feel.Runtime.Invoke). It is an instance of the function type of its signature and of no other, and has no refinement. None for a function that is not a built-in, for one that was not made of several signatures, and for a variadic signature (a refinement is none either).

iex> {:ok, abs} = Feel.Builtin.value("abs")
iex> [number | _] = Feel.Value.Function.narrowings(abs, 1)
iex> {number.name, Feel.Value.Function.params(number), Feel.Value.Function.types(number)}
{"abs", [{"n", :number}], [{:function, [:number], :number}]}
iex> Feel.Value.Function.refinements(number)
[]
iex> Feel.Value.Function.narrowings(abs, 2)
[]

@spec native(callable(), keyword()) :: t()

Builds a native function from an Elixir function.

Options

• :name - the function's name, for diagnostics.
• :params - a list of {name, boundary_type} pairs, one per parameter. Defaults to no parameters.
• :returns - the boundary type of the result. Defaults to :feel.

Raises ArgumentError for an unknown option or boundary type, or when callable does not accept as many arguments as there are parameters.

iex> function = Feel.Value.Function.native(&max/2, name: "maximum", params: [{"a", :integer}, {"b", :integer}], returns: :integer)
iex> {Feel.Value.Function.arity(function), Feel.Value.Function.type(function)}
{2, {:function, [:number, :number], :number}}

@spec params(t()) :: [param()]

Returns the parameters of a function with their FEEL types.

@spec refinements(t()) :: [Feel.Type.t()]

The function types that say what a call of a built-in function does for part of what it takes (D-171): those of the signatures that were made one for a call by name (Feel.Builtin.value/2), each as it was. abs is a function<Any> -> Any, and a call of it with a number gives a number, as function<number> -> number says; it says nothing of a call with a string. They are not function types of the value: abs instance of function<number> -> number is false, as the specification has it, and a name declared function<number> -> number is not given abs but the function of the signature for a number (narrowings/2, D-197). None for a function that was not made of several signatures, and for a function of FEEL or of the host.

iex> {:ok, abs} = Feel.Builtin.value("abs")
iex> Feel.Value.Function.refinements(abs)
[
  {:function, [:number], :number},
  {:function, [:days_and_time_duration], :days_and_time_duration},
  {:function, [:years_and_months_duration], :years_and_months_duration}
]
iex> {:ok, before} = Feel.Builtin.value("before")
iex> Feel.Value.Function.refinements(before)
[]

@spec type(t()) :: Feel.Type.t()

Returns the FEEL function type of a function.

A parameter without a declared type is :any, and so is a result without one.

@spec type([Feel.Type.t()], Feel.Type.t()) :: Feel.Type.t()

Returns the descriptor of function<T1, ..., Tn> -> R for the given parameter types and result type.

@spec types(t()) :: [Feel.Type.t()] | :open

All the function types of a function: one for a function of FEEL or of the host. For a built-in function, one for each number of arguments that its signatures take, or :open if one of them is variadic and takes any number.

iex> {:ok, length} = Feel.Builtin.value("string length")
iex> Feel.Value.Function.types(length)
[{:function, [:string], :number}]
iex> {:ok, sum} = Feel.Builtin.value("sum")
iex> Feel.Value.Function.types(sum)
:open

@spec types_at(t(), non_neg_integer()) :: [Feel.Type.t()]

The function types that a function has for a number of arguments: [type(function)] for a function with as many parameters, and none for another. A built-in function has one for each of its signatures that takes this many arguments, the parameters of an optional parameter and of a variadic one being those of the arguments.

iex> {:ok, date} = Feel.Builtin.value("date")
iex> Feel.Value.Function.types_at(date, 3)
[{:function, [:number, :number, :number], :date}]
iex> Feel.Value.Function.types_at(date, 2)
[]

@spec value?(term()) :: boolean()

Returns true for a t/0.

@spec with_origin(t(), term()) :: t()

A function of FEEL whose body reports its diagnostics with origin (D-201).

The span of a diagnostic is a range of the text of the expression that made it. A function that one expression made and another calls, as a host binds the business knowledge model that a decision calls, runs the text of the first inside the second, so the diagnostics of its body have spans in a text that is not the one being run. With an origin they say whose text it is (Feel.Diagnostic, :origin), and the host finds the span in it. The origin is whatever term the host likes.

A function that an expression writes has the origin of the run it is made in (the :origin option of Feel.run/3, nil unless the host gave one, or the origin of the function whose body writes it), so a function passed to another and called there, and one a function makes and gives back, report in their own text. This replaces that origin, for a function that was made by a run that did not know whose text it is. A diagnostic of the call itself (the conversion of an argument, the end of the call) is the caller's. A function that is not of FEEL runs no text, and is not changed.

iex> body = fn env, [_a] ->
...>   {nil, Feel.Runtime.Env.report(env, Feel.Diagnostic.new(:invalid_property, "x", span: {0, 1}))}
...> end
iex> function = Feel.Runtime.Invoke.closure([{"a", :any}], :any, body) |> Feel.Value.Function.with_origin(:member)
iex> {nil, env} = Feel.Runtime.Invoke.call(Feel.Runtime.Env.new(), function, {:positional, [1]}, {0, 4})
iex> Enum.map(Feel.Runtime.Env.diagnostics(env), & &1.origin)
[:member]