# Rete v0.1.0 - Table of Contents

> A forward-chaining Rete rules engine for Elixir, with a pattern-matching DSL in which a rule reads as a function: its arguments are the conditions and its body is what follows.

## Pages

- Guides
  - [Rete](readme.md)
  - [Writing rules](dsl.md)

- Design
  - [The IR and the DSL front end](ir.md)
  - [The compiled network](network.md)
  - [The engine](engine.md)
  - [Observability](observability.md)

- About
  - [Changelog](changelog.md)
  - [License](license.md)

## Modules

- Public API
  - [Rete](Rete.md): Collects rule, expression and taxonomy data from ruleset modules.
  - [Rete.Inspect](Rete.Inspect.md): Asking a session why.
  - [Rete.Listener](Rete.Listener.md): Observing what a session does, through one callback.
  - [Rete.Listener.Collect](Rete.Listener.Collect.md): Records every event, newest last.
  - [Rete.Listener.Trace](Rete.Listener.Trace.md): Writes a readable line per event.
  - [Rete.Ruleset](Rete.Ruleset.md): Macros for defining rulesets in a Rete network.
  - [Rete.Session](Rete.Session.md): A session is an immutable value: every operation returns a new one.

- Internals: facts and memory
  - [Rete.Activation](Rete.Activation.md): A rule whose left hand side is satisfied, waiting to fire.
  - [Rete.Agenda](Rete.Agenda.md): The activations waiting to fire, most salient first.
  - [Rete.Element](Rete.Element.md): A fact that matched one condition, with the bindings that match produced.
  - [Rete.Memory](Rete.Memory.md): Working memory: everything a session knows, as one immutable value.
  - [Rete.Memory.Bucket](Rete.Memory.Bucket.md): One join key's worth of elements or tokens: an ordered multiset.
  - [Rete.Taxonomy](Rete.Taxonomy.md): Decides which alpha nodes a fact must be offered to.
  - [Rete.Token](Rete.Token.md): A partial match travelling down the beta network: what a rule has established so far.

- Internals: the DSL front end
  - [Rete.DSL.Bindings](Rete.DSL.Bindings.md): Binding classification and guard splitting.
  - [Rete.DSL.Codegen](Rete.DSL.Codegen.md): Expression construction and code generation: the last phase of the DSL front
end.
  - [Rete.DSL.Normalize](Rete.DSL.Normalize.md): Gate normalization: the phase between parsing and binding classification.
  - [Rete.DSL.Parser](Rete.DSL.Parser.md): Turns the quoted arguments of `Rete.Ruleset.defrule/2` and
`Rete.Ruleset.defquery/2` into `Rete.IR` structs.
  - [Rete.DSL.Vars](Rete.DSL.Vars.md): Scope aware variable analysis for DSL fragments.

- Internals: the IR
  - [Rete.IR](Rete.IR.md): The intermediate representation (IR) shared by every compile phase of `Rete`.
  - [Rete.IR.Coll](Rete.IR.Coll.md): A collection binding, e.g. `[{:order, id}]` or
`orders = [{:order, id} when amt > 0]`.
  - [Rete.IR.CompoundNegation](Rete.IR.CompoundNegation.md): The negation of a *conjunction*: "no match satisfies all of these at once".
  - [Rete.IR.Expr](Rete.IR.Expr.md): A compile-time generated named function that lives in the ruleset module.
  - [Rete.IR.Fact](Rete.IR.Fact.md): A single fact condition, e.g. `{:order, id, amt}`, `%Order{id: id}` or
`f = {:order, id} when amt > 0`.
  - [Rete.IR.Gate](Rete.IR.Gate.md): An unnormalized logical gate, `{gate, [condition, ...]}`.
  - [Rete.IR.Negation](Rete.IR.Negation.md): The negation of a single condition.
  - [Rete.IR.Production](Rete.IR.Production.md): A rule or a query.
  - [Rete.IR.Test](Rete.IR.Test.md): A guard over bindings only, with no fact input.

- Internals: the compiler
  - [Rete.Compiler](Rete.Compiler.md): Turns ruleset modules into a `Rete.Network`.
  - [Rete.Compiler.BetaGraph](Rete.Compiler.BetaGraph.md): The beta side of the network: a graph of `Rete.Network.Node` descriptions.
  - [Rete.Compiler.Negation](Rete.Compiler.Negation.md): Turns a `Rete.IR.CompoundNegation` into something a Rete network can express.
  - [Rete.Compiler.Sort](Rete.Compiler.Sort.md): Topological ordering of the left hand side of a production.
  - [Rete.Network](Rete.Network.md): A compiled rulebase: everything the engine needs, and nothing that changes.

- Internals: network nodes
  - [Rete.Network.Node](Rete.Network.Node.md): The node descriptions the engine runs.
  - [Rete.Network.Node.Accumulate](Rete.Network.Node.Accumulate.md): A collection binding: gathers every element matching the token into a list.
  - [Rete.Network.Node.AccumulateJoin](Rete.Network.Node.AccumulateJoin.md): A collection binding whose membership also depends on a cross-condition
guard, so the candidates cannot be reduced until a token is known.

  - [Rete.Network.Node.Alpha](Rete.Network.Node.Alpha.md): Matches one condition against a single fact, independently of any token.
  - [Rete.Network.Node.ExprJoin](Rete.Network.Node.ExprJoin.md): A hash join plus a filter that needs the token and the fact together.
  - [Rete.Network.Node.HashJoin](Rete.Network.Node.HashJoin.md): Joins tokens to elements on equality of `:join_bind`. The common case: no
guard reaches across conditions, so the join is a hash lookup.

  - [Rete.Network.Node.Negation](Rete.Network.Node.Negation.md): Propagates a token only while **no** element matches it on `:join_bind`.

  - [Rete.Network.Node.NegationJoin](Rete.Network.Node.NegationJoin.md): A negation whose match also depends on a cross-condition guard.

  - [Rete.Network.Node.Production](Rete.Network.Node.Production.md): A terminal node for a rule. Firing it calls `:rhs` with the token's bindings
and logically inserts whatever comes back.
  - [Rete.Network.Node.Query](Rete.Network.Node.Query.md): A terminal node for a query. Holds the tokens that reached it, to be read back by
name.
  - [Rete.Network.Node.RootJoin](Rete.Network.Node.RootJoin.md): The first condition of a rule. Has no token to join against, so it turns
each matching element straight into a token.

  - [Rete.Network.Node.Test](Rete.Network.Node.Test.md): A predicate over the token's bindings, with no fact input. Produced by a
rule level `when` guard.

- Internals: the engine
  - [Rete.Engine](Rete.Engine.md): The propagation loop and the fire cycle.
  - [Rete.Engine.Nodes](Rete.Engine.Nodes.md): What each node kind does when tokens or elements arrive.
  - [Rete.Engine.State](Rete.Engine.State.md): Everything that changes while rules fire, as one value threaded through the loop.

