Reference: the Aletheia language

A systematic, lookup-style reference for the Aletheia language itself — the Prolog dialect, independent of how it's embedded in a host application. If you want to learn it step by step instead, see the language tutorial; for using Aletheia as a library from Elixir (creating databases, querying them, the REPL), see the library tutorial instead.

Every predicate implemented and reachable from .alp source today, with its signature, semantics, and enough of an example to use it correctly. This covers the entire v0.1-v0.5 roadmap — the whole numbered milestone list is done. Two genuine, deliberate gaps remain, both called out where relevant below: =../2 (univ/2 works, but the ISO punctuation form can't be tokenized by this reader's own simplified lexer — see Term inspection), and format/2's column/radix directives (~t, ~|, ~Nr, numeric-prefixed ~Nd — see I/O). Past v0.5, only the roadmap's explicitly unscheduled, need-driven later bucket (module system, tabling, CLP(FD)) remains, and isn't started.

Syntax

Classic Prolog surface syntax, read by Aletheia.Reader:

• Atoms: lowercase-start identifiers (foo, parent42) or single-quoted for anything else ('John Doe', ';').
• Variables: uppercase- or _-start identifiers (X, _Acc). A bare _ is anonymous — every occurrence is a distinct fresh variable, even within the same clause.
• Numbers: integers (42) and floats (3.14) — an integer never unifies or compares equal (==/2) with a float holding the same value, matching ISO.
• Strings: double-quoted ("hello") — a real, native Elixir binary under the hood, a genuinely distinct term class from atoms, never a code list. No escape processing (a literal " can't appear inside one at all), same simplification quoted atoms already have.
• Lists: [] (empty), [1, 2, 3] (proper), [H|T] (cons, T can be a variable or another list) — backed by native Elixir lists, decomposing as ISO's own ./2 cons functor so unification recurses into them correctly.
• Compounds: functor(Arg1, Arg2, ...), plus operator syntax as sugar for the same thing — 1 + 2 is +(1, 2).
• {Goal}: ISO's own {}/1 term shape, valid anywhere a term is — ordinary syntax, not DCG-specific, though a DCG body is where it takes on special meaning (an embedded plain goal, no difference-list threading). Requires non-empty content; the bare atom {} isn't supported.
• Comments: % to end of line, /* ... */ block comments.
• Clauses: Head. (a fact), Head :- Body. (a rule), Head --> Body. (a DCG rule), :- Goal. (a directive — currently only op/3 has any effect as one). Every clause ends with a bare ..

Comma is a real operator here (xfy, ISO priority 1000) — unlike a few textbook-simplified Prolog-in-X implementations that treat it as pure grammar structure, p :- a, (b ; c). composes exactly like real Prolog. The trade-off: inside a compound's arguments or a list's elements, only operators of priority ≤ 999 are accepted (ISO's own rule) — so a bare ,/;/-> there needs parentheses, exactly as in any other conforming Prolog.

Default operator table (ISO priorities; bigger number binds looser):

Head --> Body. (DCG rules, see DCG) is handled as its own dedicated clause form, not through this operator table — --> never needs an op/3 entry to work at the top level of a clause.

Extend the table itself at read time with op/3 (see Operators below).

Two documented simplifications: no genuine xfx (non-associative) vs. yfx (left-associative) distinction yet, inherited from the underlying parsing substrate (Ichor) — an a is b is c-style chain parses left-associatively instead of being rejected the way ISO would reject it outright; and an operator symbol can't yet be used as an explicit compound functor the way ISO allows (=(X, Y) as another way to write X = Y) — a compound's functor position only accepts a plain or quoted atom today, not a bare operator token. A third, narrower one: =../2 (univ)'s own ISO punctuation can't be tokenized by this reader's simplified lexer (a lone . inside a longer operator token is indistinguishable from end-of-clause) — use univ/2 directly (see Term inspection).

Control

% if-then-else
sign(X, R) :- (X > 0 -> R = pos ; X < 0 -> R = neg ; R = zero).

% call/N: call(Goal, Extra1, ..., ExtraN) appends Extra1..ExtraN to Goal's own args
add(X, Y, Z) :- Z is X + Y.
add_five(Y, Z) :- call(add(5), Y, Z).   % call(add(5), Y, Z) runs add(5, Y, Z)

Cut

! commits to every choice made since entering the current clause — pruning both (a) any remaining alternatives for goals earlier in the same clause body, and (b) any remaining sibling clauses of the same predicate call. This is a real, clause-scoped commitment, genuinely different from "stop after the first solution of whatever goal contains it" (that's once/1) — the difference is observable the moment a cut is followed by something that fails:

p(1) :- !, fail.
p(2).

Aletheia.query("p(X)", db)
#=> {:ok, []}

p(X) fails outright — cut commits to clause 1 before fail runs, so clause 2 is never tried. Swap ! for a hypothetical "run once" and p(2) would still fire; real cut never lets that happen.

Cut is transparent within the clause it appears in — including inside a disjunction:

r(X) :- (X = 1, ! ; X = 2).
r(3).

Aletheia.query("r(X)", db)
#=> {:ok, [%{"X" => 1}]}

— but goals after the cut in the same clause still backtrack among themselves normally:

p(X) :- !, member(X, [1, 2, 3]).
p(_) :- true.

Aletheia.query("p(X)", db)
#=> {:ok, [%{"X" => 1}, %{"X" => 2}, %{"X" => 3}]}

— all three solutions of member/2 come through (cut doesn't limit that), but once they're exhausted, the second clause p(_) :- true. is never tried (cut already committed to the first).

Cut is opaque inside call/1..N, once/1, and \+/1 (per ISO): a ! inside any of those only commits within that sub-call, never escaping to prune the caller's own choice points.

Unification & comparison

Aletheia.query("X = foo(1, 2)", db)
#=> {:ok, [%{"X" => %Episteme.Term.Compound{name: :foo, args: [1, 2]}}]}

Aletheia.query("1 == 1.0", db)   #=> {:ok, []}          -- different types
Aletheia.query("X = 2, X \\= 1", db)  #=> {:ok, [%{"X" => 2}]}

Aletheia.query("unify_with_occurs_check(X, f(X))", db)  #=> {:ok, []}
Aletheia.query("zzz @< aaa", db)                        #=> {:ok, []}
Aletheia.query("aaa @< zzz", db)                        #=> {:ok, [%{}]}

Type checking

Each of these inspects its (fully-resolved) argument's shape and succeeds or fails accordingly — none of them bind anything.

Term inspection

Aletheia.query("copy_term(f(X, X), Y)", db)
#=> {:ok, [%{"Y" => %Episteme.Term.Compound{name: :f, args: [freshA, freshA]}}]}

Aletheia.query("functor(foo(a, b), Name, Arity)", db)
#=> {:ok, [%{"Name" => :foo, "Arity" => 2}]}

Aletheia.query("univ(foo(1, 2), L)", db)
#=> {:ok, [%{"L" => [:foo, 1, 2]}]}

Arithmetic

is/2 evaluates its right-hand side as an arithmetic expression and unifies the result with its left-hand side:

Division/mod/rem/integer-division by zero raise a domain_error; a non-numeric, non-variable, non-evaluable expression raises a type_error(evaluable, _) (see Exceptions).

Arithmetic comparisons evaluate both sides the same way is/2 does: =:=/2, =\=/2, </2, >/2, =</2, >=/2.

Aletheia.query("X is 2 + 3 * 4", db)  #=> {:ok, [%{"X" => 14}]}
Aletheia.query("X is 7 // 2", db)     #=> {:ok, [%{"X" => 3}]}
Aletheia.query("3 =:= 3.0", db)       #=> {:ok, [%{}]}

between/3 is a goal, not an expression functor (not ISO, but a de facto standard across most Prolog implementations): between(Low, High, X) enumerates every integer in [Low, High] on backtracking when X is unbound, or just checks membership when it's bound. Low/ High are evaluated as arithmetic expressions, same as is/2's right-hand side.

Aletheia.query("between(1, 5, X)", db)
#=> {:ok, [%{"X" => 1}, %{"X" => 2}, %{"X" => 3}, %{"X" => 4}, %{"X" => 5}]}

Exceptions

An exception nothing in your program catches surfaces at the top level as {:error, term} from Aletheia.query/2/query_once/2 (and as :none-adjacent text in the REPL), rather than crashing the calling Elixir process. Calling an undefined predicate raises a standard existence_error(procedure, Name/Arity) the same way.

{:ok, db} = Aletheia.consult_string(
  "safe_div(X, Y, R) :- catch(R is X / Y, error(_, _), R = undefined)."
)
Aletheia.query("safe_div(10, 0, R)", db)  #=> {:ok, [%{"R" => :undefined}]}

Operators

:- op(700, xfx, likes).
example(X) :- X = (tom likes wine).

Aletheia.query("example(X)", db)
#=> {:ok, [%{"X" => %Episteme.Term.Compound{name: :likes, args: [:tom, :wine]}}]}

op/3 takes effect at read time — it's a directive processed while consulting a source (extending how later clauses in that same source get parsed), not a callable goal at query time, and not something the arithmetic evaluator picks up automatically: registering a new operator only changes what parses, not what is/2 knows how to compute — X is 1 likes 2 would still raise a type_error(evaluable, _) unless likes also happened to be one of the functors Arithmetic already recognizes.

Database

Mutating the clause database at query time — effects persist across separate Aletheia.query/2 calls against the same database, not just within one. No dynamic/1 declaration is required first: asserting a brand-new predicate works immediately, unlike strict ISO Prolog.

{:ok, db} = Aletheia.consult_string("p(a). p(b).")
Aletheia.query("assertz(p(c)), findall(X, p(X), L)", db)
#=> {:ok, [%{"L" => [:a, :b, :c]}]}

Aletheia.query_once("assert(q(1)), retract(q(1)), \\+ q(1)", db)
#=> {:ok, %{}}

Aggregation

{:ok, db} = Aletheia.consult_string("parent(tom, bob). parent(tom, liz).")
Aletheia.query("findall(X, parent(tom, X), L)", db)
#=> {:ok, [%{"L" => [:bob, :liz], "X" => %Episteme.Term.Var{...}}]}
#   (X, used only inside findall/3's own template/goal, comes back too, still unbound --
#   every named query variable does, whether or not it ends up bound; use an
#   anonymous _ instead if you don't want it in the result map)

{:ok, db2} =
  Aletheia.consult_string(
    "likes(mary, apples). likes(mary, pears). likes(john, apples)."
  )

Aletheia.query("bagof(X, likes(mary, X), L)", db2)
#=> {:ok, [%{"L" => [:apples, :pears], "X" => %Episteme.Term.Var{...}}]}

Aletheia.query("bagof(X, likes(nobody, X), L)", db2)  #=> {:ok, []}    -- fails, not L = []

Lists

Over native [H|T] lists:

Aletheia.query("append([1, 2], [3, 4], X)", db)
#=> {:ok, [%{"X" => [1, 2, 3, 4]}]}

Aletheia.query("append(X, Y, [1, 2, 3])", db)
#=> {:ok, [%{"X" => [], "Y" => [1, 2, 3]}, %{"X" => [1], "Y" => [2, 3]},
#          %{"X" => [1, 2], "Y" => [3]}, %{"X" => [1, 2, 3], "Y" => []}]}

Aletheia.query("sort([3, 1, 2, 1], L)", db)
#=> {:ok, [%{"L" => [1, 2, 3]}]}

Atom, number, and string conversions

Two families: atom_*/number_* (classic ISO/de-facto, working with atoms — atom_chars/2's own chars are single-character atoms) and string_*/split_string (SWI-style, working with real strings — string_chars/2's chars are single-character strings). Not interchangeable.

Aletheia.query("atom_concat(foo, bar, X)", db)
#=> {:ok, [%{"X" => :foobar}]}

Aletheia.query("sub_atom(abc, 1, 2, After, Sub)", db)
#=> {:ok, [%{"After" => 0, "Sub" => :bc}]}

Aletheia.query("atom_string(hello, S)", db)
#=> {:ok, [%{"S" => "hello"}]}

I/O

Aletheia.query("format(\"~w and ~d~n\", [hello, 42])", db)
#=> prints "hello and 42\n", then {:ok, [%{}]}

DCG

A DCG rule (Head --> Body) threads an incoming/outgoing difference-list pair through every nonterminal call, so a grammar reads like a sequence of things matched rather than explicit list splitting. A practical subset of real DCG translation: terminals ([t1, ..., tn]), {Goal} (embedded plain goal, no list threading — see Syntax), !, ,/;/->, \+, a bare nonterminal (atom or compound), and a variable body. No call//N pushback (parameterized higher-order nonterminals).

greeting --> [hello], [world].
digit(D) --> [D], { integer(D) }.

Aletheia.query("phrase(greeting, [hello, world])", db)
#=> {:ok, [%{}]}

Aletheia.query("phrase(greeting, [hello, world, extra], Rest)", db)
#=> {:ok, [%{"Rest" => [:extra]}]}

Aletheia.query("phrase(digit(X), [5])", db)
#=> {:ok, [%{"X" => 5}]}

A -->/2-shaped clause term passed to assert/1 translates and stores the same way, dynamically.

See also

• ../TUTORIAL.md — using Aletheia as a library from Elixir: consult/1/consult_string/2, query/2 and friends, the REPL.
• ../CHEATSHEET.md — quick reference for that same embedding API.