What an expression or a program reads, calls and stores, listed for tooling.

A checker that compares every path a condition reads against a declared shape, or an editor that lists the functions a program calls, needs those facts without evaluating anything. This module answers three questions:

• references/1 - each variable read, as a path.
• calls/1 - each function call, with its name and arity.
• assignments/1 - each location a program stores to, as a path.

It is a reading surface, not a parsing one, in the Predicator.Vocabulary mould. Nothing here participates in lexing, parsing, compiling or evaluating, and no answer depends on a context: a path is read off the program text, never resolved against data.

Inputs

Each function accepts any of five forms of one program:

• a source string, read as a program the way Predicator.parse_program/2 reads it. Every expression is a program of one statement, and = is never an equality operator (== is), so a condition and a script read alike;
• an AST from Predicator.parse/2, or any single statement or block;
• a program from Predicator.parse_program/2;
• an instruction list, from Predicator.compile/1 or from storage;
• a Predicator.Compiled envelope.

The AST forms and the instruction forms give the same paths, calls and stores for the same source (the instruction form rebuilds paths by tracking what the stack holds). Positions come from the AST's own slots, or from the envelope's position table; a bare instruction list carries no positions, so every position read from one is nil.

Answers

Every answer lists every occurrence, in source order, as maps. A caller that wants a set dedupes.

• A reference is %{path: [segment], position: position}.
• A call is %{name: name, arity: arity, position: position}. A qualified name (ns.fn(x)) is reported as written, dots included; calls nested in another call's arguments are listed too, the outer call first.
• An assignment is %{path: [segment], position: position}.

A segment is a string (a variable name or a property name, or a string literal key), an integer (a literal integer index), or :dynamic (any other bracket key: a computed key, or a literal that is neither a string nor an integer). The path continues past a :dynamic segment, and a computed key's own reads are listed as references of their own.

A reference is a chain rooted at a variable. A chain rooted anywhere else (a call's result, a literal) reads no variable, so f(x).y lists x and the call, and no reference for .y. The location an assignment writes is not a read; the reads inside its bracket keys are.

A position is the node's trailing slot (Predicator.Parser.position/0). For a path - a reference or an assignment - it is the span of the whole chain when the program was parsed or compiled with spans, and otherwise the point position of the chain's root variable: either way it starts where the path starts. A call's position is the call node's own.

Examples

iex> Predicator.Analysis.references("score > limit")
{:ok, [%{path: ["score"], position: {1, 1}}, %{path: ["limit"], position: {1, 9}}]}

iex> {:ok, program} = Predicator.parse_program("total = price * 2")
iex> Predicator.Analysis.assignments(program)
{:ok, [%{path: ["total"], position: {1, 1}}]}

Errors

A source string that does not parse answers the %Predicator.Errors.ParseError{} Predicator.compile_program/1 returns for it. An instruction the analysis cannot read - an opcode outside Predicator.Instructions.opcodes/0, or an operand of the wrong shape - answers an %Predicator.Errors.EvaluationError{} with the evaluator's "unknown_instruction" reason. An instruction list that pops more values than it pushed is read as far as it goes: the missing values read nothing.

test/predicator/analysis_clause_coverage_test.exs keeps the AST clauses in step with Predicator.Parser.visitable/0 and the instruction clauses in step with Predicator.Instructions.opcodes/0, the retired opcodes included.