@spec build(Macro.Env.t(), Macro.t(), Macro.t(), :rule | :query) ::
  Rete.IR.Production.t()

Runs the front end pipeline over a quoted production declaration.

Returns the fully classified Rete.IR.Production, ready for Rete.DSL.Codegen.compile/1. This is exposed so a test can inspect the IR of a declaration, without compiling a module for it.

The last step recomputes :bind from the classified LHS. So :bind is exactly the set of variables a token reaching the right hand side can carry.

@spec check_name!(module(), atom(), :rule | :query, String.t(), pos_integer()) :: :ok

Rejects a production name the module has already used, and records it.

The compiler calls this from the module body, not at macro expansion. A module body is expanded in full before any of it is evaluated. So at expansion time, the attribute that records earlier declarations is still empty, and every declaration would look like the first.

Rules and queries share one namespace.

Defines a query.

A query has the same left hand side as a rule, but it never fires. It holds the matches that reached it. Its body is what the caller gets, one result per match.

The query is a function. defquery find_user(...) also defines find_user/1,2 in the same module, so you run it by calling it. That is what makes a query addressable, and why two rulesets may each define one of the same name. Use Rete.Session.query/3, with {MyRuleset, :find_user}, when the query is decided at runtime.

A head before the conditions declares the parameters of the query. The engine keys the matches of the query on those parameters, and they are the only way to read it.

defquery find_user(id)({:user, id, name}) do
  {id, name}
end
#=> MyRuleset.find_user(session, id: 1)  [{1, "Ada"}]

A call must name every parameter, and no other name. A read is thus one map lookup, and not a scan. A partial key, an extra key or an unknown key raises an error. It does not answer [].

A query without a head takes no parameters. It answers with every match that it holds, in arrival order. This is the default, and it costs nothing more.

defquery all_users({:user, id, name}) do
  {id, name}
end
#=> MyRuleset.all_users(session)  [{1, "Ada"}, {2, "Grace"}]

A parameter must be a variable that the left hand side binds. Every match must also carry that variable. Thus you cannot use a variable that only some branches of a disjunction bind. A rule cannot take parameters, because you never read a rule. See docs/dsl.md.

Defines a rule.

The declaration is the left hand side, and the body is the right hand side. The engine logically inserts and truth-maintains what the body returns. nil or [] inserts nothing.

{:user, id}                      fact pattern, any arity, including {:tick}
%User{id: id}                    struct fact pattern, the type is the module
%{__type__: :user, id: id}       tagged map fact pattern
%User{__type__: :vip, id: id}    a declared type overrides the module
user = {:user, id}               bind the whole fact
{:order, total} when total > 10  per condition guard
orders = [{:order, id}]          collect all matching facts, bound or anonymous
{:not, [{:order, id}]}           gate: :and :or :not :nand :nor :xor :xnor

A %{...} literal in first position is the rule's options, not a condition. A when after the argument list is a guard over all bindings. See docs/dsl.md.

defrule high_value(%{salience: 100}, {:user, id}, {:order, id, t} when t > 1000) do
  {:high_value, id, t}
end

Declares that child is a kind of parent.

A child fact then reaches every condition written against parent. The reverse does not hold. Derivation is transitive.

derive(:dog, :mammal)
derive(:mammal, :animal)

# a {:dog, "Rex"} fact now matches this rule
defrule process_animal({:animal, name}), do: {:seen, name}

Removes a derivation declared earlier.

Declarations are folded in module order, so a module can only undo what a module before it declared.

derive(:cat, :mammal)
underive(:cat, :mammal)