Package-level declarations

Base type for constant, alphanumeric Terms, a.k.a. strings. An Atom is at the same time a String-valued Constant and a 0-argument Struct, whose functor is equal to value. Modelling it as both, rather than picking a single parent, is what lets generic code written against Struct (functor/arity/argument-based) keep working on atoms without special-casing, while code that only cares about "a ground value" can use Constant instead.

A Recursive structure with functor {}, representing Prolog's curly-braced term ({Goal}), most commonly seen in the body of DCG (Definite Clause Grammar) rules. A Block wrapping zero terms is an EmptyBlock (the atom {}); one wrapping a single term stores it directly; two or more are folded, right to left, using Tuple as the inner structure — the same folding convention used by List and Tuple themselves, so Recursive operations like unfold/toList work identically across all three.

An Iterator walking the goals wrapped by a Block, unfolding the Tuple its arguments are folded into (if any), left to right.

A logic clause, i.e. a Struct with functor :-, representing either a Rule (head :- body, head non-null) or a Directive (:- body, head null). A theory (see :theory) is, at its core, a sequence of Clauses.

A non-empty logic LogicList, i.e. a Struct with functor . and arity 2, conventionally read as "head followed by tail". A well-formed Cons chain ends in EmptyList; when tail is anything else (another Var, or a non-list term), the list is a partial (a.k.a. improper) list — see List.isWellFormed.

Base type for Terms that carry a single, immutable, ground value and no sub-terms: Atoms (a String value) and Numerics (an Integer/Real value). Constants are always ground, since they contain no Variables.

A Clause with no head, i.e. :- body, such as :- initialization(main).. Directives typically carry instructions executed by the Prolog engine at load time, rather than facts/rules meant to be queried.

Base type for the two "empty" singleton atoms of the term hierarchy: EmptyList ([]) and EmptyBlock ({}). Both are 0-arity Atoms that also happen to be recognized as (degenerate) Recursive structures with zero elements.

The empty logic block, i.e. the atom {}. It is a singleton: EmptyBlock.instance (equivalently, EmptyBlock()) always returns the same instance, and Atom.of and Block.empty both return it whenever asked to build the {} atom.

The empty logic list, i.e. the atom []. It is a singleton: EmptyList.instance (equivalently, EmptyList()) always returns the same instance, and Atom.of and List.empty both return it whenever asked to build the [] atom.

A Rule whose body is (equivalent to) the true atom, e.g. parent(tom, bob).. Rule.of and Clause.of already return a Fact automatically whenever the body they are given reduces to true; Fact.of is a shortcut for when the absence of a body is known upfront.

A type for objects encapsulating some logic to convert any object of type T into a String

A predicate indicator is used to denote predicates or functors.

A Numeric whose value is an arbitrary-precision integer, e.g. 1, -42, or a value far outside the range of a Long. Being arbitrary-precision (backed by BigInteger) means arithmetic on Integers never silently overflows, matching how ISO Prolog integers are meant to behave.

A logic list, i.e. either an EmptyList (the atom []) or a Cons cell. Logic lists are, in Prolog syntax, [a, b, c], which desugars to .(a, .(b, .(c, []))) — a chain of Cons cells terminated by EmptyList. When the final tail is something other than EmptyList (a variable, or another term), the chain is a partial list, and isWellFormed is false.

An Iterator walking the elements of a List, from Cons.head to Cons.head, following Cons.tail chains. Iterating a partial (ill-formed) list simply stops when a non-Cons, non-EmptyList tail is reached, without throwing. The Substituting variants additionally apply a Substitution.Unifier to each element (and to the tail being followed) as they go, and the SkippingLast variants stop before yielding the final EmptyList marker (useful when only the "real" elements are wanted).

Base type for numeric Constants, i.e. Prolog numbers.

A Numeric whose value is an arbitrary-precision decimal number, e.g. 1.0, -3.14. Being backed by BigDecimal rather than a Double avoids the rounding surprises of binary floating point, at the cost of requiring explicit conversion when interoperating with APIs that expect a native floating-point type.

Base type for Structs that conventionally represent a (possibly improper) sequence of Terms folded into nested binary structures: List (functor .), Tuple (functor , ), and Block (functor {}). Recursive exposes that sequence uniformly, regardless of which folding convention the concrete sub-type uses, via unfold/unfoldedSequence/toList/toArray.

A Clause with a non-null head, i.e. head :- body. Fact is the special case where body is (equivalent to) the true atom; Rule.of automatically returns a Fact whenever body reduces to true, so most code building rules can just call Rule.of uniformly and let it decide.

A small, stateful factory of Terms that remembers the Variables it has already created, by Var.name.

Base type for compound Terms, a.k.a. structures. A Struct is characterised by a functor and a given (non-negative) amount of args, namely arity. Each argument can be a Term of any sort.

General type for logic substitutions (i.e. variables assignments). There are two sorts of substitutions:

Base type for all logic terms: Variables, Constants (Atoms and Numerics), and Structures (including Clauses, Lists, Tuples, and Blocks, which are all just structures with a conventional functor). Every piece of data 2P-Kt's logic engine manipulates is, ultimately, a Term.

A Comparator for a specific sort of Term, following the standard logic-term total order: variables order before numbers, which order before atoms, which order before structures (compared first by arity, then functor, then arguments left-to-right). DefaultComparator implements the full order across any two Terms and backs Term.compareTo; the other nested objects handle one specific sub-type each, and are mostly useful when only same-sort terms are ever compared (e.g. sorting a list of Atoms).

An interface to be implemented by types convertible to Prolog Terms

A Formatter specialized in rendering Terms as Strings, implemented as a TermVisitor (each visitX method renders the corresponding sub-type). The companion offers ready-made formatters covering the usual combinations of options (canonical, default, readable, prettyVariables, prettyExpressions); of is the general entry point when a custom combination of VarFormat/OpFormat/FuncFormat is needed.

Internal-use constants and patterns (well-formedness patterns, canonical/reserved functors) shared across the Term hierarchy's interfaces and companions. Most of these are re-exposed as named constants on the relevant type (e.g. Var.NAME_PATTERN, Struct.WELL_FORMED_FUNCTOR_PATTERN, Cons.FUNCTOR); prefer those over referencing Terms directly, which exists mainly to avoid duplicating these values across types.

The Visitor-pattern counterpart of the Term hierarchy (see Term.accept). Each visitX method has a default implementation delegating to the visitY method of its immediate supertype Y in the hierarchy (e.g. visitAtom delegates to visitStruct, which delegates to visitTerm, which delegates to defaultValue), so implementers only need to override the methods for the specific sub-types they care about, letting everything else fall back sensibly. defaultValue is the only method that must be implemented.

An Atom representing one of Prolog's canonical boolean values: true, fail, or false.

A Recursive structure with functor , and arity 2, i.e. the classic Prolog conjunction (A, B). Tuples of more than two terms are represented by right-nesting: (A, B, C) is [left]=A, [right]=(B, C). This is the same functor Prolog uses for clause bodies with multiple goals — that is why Clause.body and Rule.of fold multi-goal bodies into a Tuple under the hood.

An Iterator walking the elements of a Tuple, from Tuple.left to Tuple.left, following Tuple.right chains.

A logic variable, i.e. a placeholder for a Term that is yet to be determined.

A Scope extended with 26 pre-declared Var properties, one per uppercase Latin letter (A to Z), for quickly sketching terms in Kotlin code without spelling out varOf("X") for every commonly-named variable. Being also a Kotlin property delegate provider (via getValue), a VariablesProvider lets a Kotlin val declaration mint (or fetch) a same-named Scope variable directly:

Conversion from a raw Map<Var, Term> to the Substitution.Unifier type

Infix-style shorthand for formatter.format(this), e.g. myTerm.format(TermFormatter.default()).

Prepares the receiver Clause for execution, using the provided visitor

Prepares the receiver Clause for execution like prepareForExecution, additionally applying unifier to each variable encountered along the way.

Converts this String into an Atom with it as Atom.value. Shorthand for Atom.of.

Converts this Array of Terms into a logic List. Shorthand for List.of.

Converts this Byte into an Integer. Shorthand for Numeric.of.

Converts this Double into a Real. Shorthand for Numeric.of.

Converts this Float into a Real. Shorthand for Numeric.of.

Converts this Int into an Integer. Shorthand for Numeric.of.

Converts this Long into an Integer. Shorthand for Numeric.of.

Converts this Number into a Numeric. Shorthand for Numeric.of.

Converts this Short into an Integer. Shorthand for Numeric.of.

Converts this String into a Term: a Var if it matches Terms.VAR_NAME_PATTERN (i.e. it looks like a legal variable name), or an Atom otherwise.

Converts this Iterable of Terms into a logic List. Shorthand for List.of.

Converts this Kotlin kotlin.collections.List of Terms into a logic List. Shorthand for List.of.

Converts this Sequence of Terms into a logic List. Shorthand for List.of.

Converts this BigDecimal into a Real. Shorthand for Numeric.of.

Converts this BigInteger into an Integer. Shorthand for Numeric.of.

Converts this String into a Var named after it. Shorthand for Var.of.