@spec base_scope(t()) :: Feel.Scope.t()

The scope that has the types of the definitions and no variable: what scope/3 adds the variables of an expression to.

@spec constraints(t()) :: %{optional(String.t()) => [constraint()]}

What a value of each item definition that has any has to satisfy, as the source text of unary tests: its own, those of the definition it refers to, and those of its components, by the member they are for.

iex> definitions = Feel.ItemDefinitions.new([
...>   %{name: "tPerson", components: [%{name: "age", type_ref: "number", allowed_values: "[0..150]"}]},
...>   %{name: "tPeople", type_ref: "tPerson", collection?: true, type_constraint: "count(?) > 0"}
...> ])
iex> Feel.ItemDefinitions.constraints(definitions)["tPeople"]
[
  %{steps: [:each, "age"], kind: :allowed_values, source: "[0..150]"},
  %{steps: [], kind: :type_constraint, source: "count(?) > 0"}
]

@spec new([definition()], [{:recursive, :error | :any | :guarded}]) :: t()

Reads the item definitions of a model. Raises ArgumentError for two with one name.

The option :recursive is :error by default, and a definition that refers to itself has no type (problems/1). With :any it has the type that the loop is cut at, the reference that closes it being Any (D-189): the definitions are read in the order of their names, so that what the cut is does not depend on the order the model gave them in.

iex> definitions = Feel.ItemDefinitions.new([
...>   %{name: "tNames", type_ref: "string", collection?: true},
...>   %{name: "tPerson", components: [%{name: "name", type_ref: "string"}, %{name: "friends", type_ref: "tNames"}]}
...> ])
iex> Feel.ItemDefinitions.types(definitions)
%{"tNames" => {:list, :string}, "tPerson" => {:context, %{"name" => :string, "friends" => {:list, :string}}}}

The option :guarded retains guarded data recursion as a finite graph, checks full finite values and recursive component constraints, and rejects unguarded or function-type cycles. Type relations remain conservative.

iex> definitions = Feel.ItemDefinitions.new([
...>   %{name: "Node", components: [%{name: "next", type_ref: "Node"}]}
...> ], recursive: :guarded)
iex> type = Feel.ItemDefinitions.types(definitions)["Node"]
iex> {Feel.Type.value_conforms?(%{"next" => %{"next" => nil}}, type),
...>  Feel.Type.value_conforms?(%{"next" => %{}}, type)}
{true, false}

@spec problems(t()) :: %{optional(String.t()) => [problem()]}

Why the item definitions that have no type have none, by name. They are not in types/1.

@spec scope(t(), %{optional(String.t()) => String.t() | nil}, Feel.Scope.t() | nil) ::
  {Feel.Scope.t(), %{optional(String.t()) => [problem()]}}

A scope of the variables of a model, given as name => typeRef, and the ones that could not be given a type, with why.

The types of the scope are all the item definitions that could be read, so that their names mean something in an expression; the names are the variables, each of its declared type, and their constraints are those of the definition it is declared with, for the variable and for its members.

Making the types of a scope costs what the definitions are (every name is canonicalized), so a caller that makes a scope for each of many expressions over one set of definitions makes base_scope/1 once and gives it as the third argument: the scope is the same, and the types are not made again.

iex> definitions = Feel.ItemDefinitions.new([%{name: "tAge", type_ref: "number", allowed_values: "[0..150]"}])
iex> variables = %{"age" => "tAge", "nobody" => "tNowhere"}
iex> {scope, unread} = Feel.ItemDefinitions.scope(definitions, variables)
iex> {Feel.Scope.fetch_name(scope, "age"), Feel.Scope.allowed_values(scope), Map.keys(unread)}
{{:ok, :number}, %{"age" => "[0..150]"}, ["nobody"]}
iex> base = Feel.ItemDefinitions.base_scope(definitions)
iex> {^scope, ^unread} = Feel.ItemDefinitions.scope(definitions, variables, base)

Use scope/3 to carry guarded recursive constraints into an expression. Passing only the type returned by types/1 checks structure, but does not attach the declaration's allowed values or type constraints. Under the default declarations: :enforce, an invalid descendant makes the bound value null; its diagnostic identifies the concrete path. Other declaration stances retain their ordinary meaning (Feel.Scope).

iex> definitions = Feel.ItemDefinitions.new([
...>   %{name: "Node", components: [
...>     %{name: "value", type_ref: "number", allowed_values: "[0..9]"},
...>     %{name: "next", type_ref: "Node"}
...>   ]}
...> ], recursive: :guarded)
iex> {scope, unread} = Feel.ItemDefinitions.scope(definitions, %{"node" => "Node"})
iex> unread
%{}
iex> {:ok, expression} = Feel.prepare("node", scope: scope)
iex> bad = %{"value" => Decimal.new(1), "next" => %{"value" => Decimal.new(20), "next" => nil}}
iex> {:ok, nil, [diagnostic]} = Feel.run(expression, %{"node" => bad})
iex> {diagnostic.code, diagnostic.details.path}
{:value_not_allowed, ["next", "value"]}

For an expression's result boundary, use variable/2 to obtain both the type and its constraints, and pass them as :result_type and :result_allowed_values to Feel.prepare/2.

@spec types(t()) :: %{optional(String.t()) => Feel.Type.t()}

The type of each item definition that could be read, by its name.

@spec variable(t(), String.t() | nil) ::
  {:ok, Feel.Type.t(), [constraint()]} | {:error, [problem()]}

The type and the constraints of a variable that is declared with this typeRef, or why it cannot be had.

nil is no declaration, which is the type Any. A built-in type has no constraints.

iex> definitions = Feel.ItemDefinitions.new([%{name: "tFooBar", type_ref: "string", allowed_values: ~s("FOO", "BAR")}])
iex> Feel.ItemDefinitions.variable(definitions, "tFooBar")
{:ok, :string, [%{steps: [], kind: :allowed_values, source: ~s("FOO", "BAR")}]}
iex> Feel.ItemDefinitions.variable(definitions, "number")
{:ok, :number, []}
iex> Feel.ItemDefinitions.variable(definitions, "tNowhere")
{:error, [{:undefined_type, "tNowhere"}]}
iex> Feel.ItemDefinitions.variable(definitions, "list<number!>")
{:ok, {:list, {:non_null, :number}}, []}
iex> Feel.ItemDefinitions.variable(definitions, "tFooBar!")
{:ok, {:non_null, :string}, [%{steps: [], kind: :allowed_values, source: ~s("FOO", "BAR")}]}
iex> Feel.ItemDefinitions.variable(definitions, "list<tFooBar>")
{:error, [{:undefined_type, "list<tFooBar>"}]}