% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(tables): XSB interface to tables}

\label{sec:tables}

This module provides an XSB compatible library to access tables as
created by tabling (see \predref{table}{1}). The aim of this library is first of
all compatibility with XSB. This library contains some old and internal
XSB predicates that are marked deprecated.\vspace{0.7cm}

\begin{description}
    \predicate{t not}{1}{:Goal}
Tabled negation.

\begin{tags}
    \tag{deprecated}
This is a synonym to \predref{tnot}{1}.
\end{tags}

    \predicate{tfindall}{3}{+Template, :Goal, -Answers}
This predicate emerged in XSB in an attempt to provide a safer
alternative to \predref{findall}{3}. This doesn't really work in XSB and the
SWI-Prolog emulation is a simple call to \predref{findall}{3}. Note that \arg{Goal}
may not be a variant of an \textit{incomplete} table.

\begin{tags}
    \tag{deprecated}
Use \predref{findall}{3}
\end{tags}

    \predicate{set_pil_on}{0}{}
\nodescription
    \predicate{set_pil_off}{0}{}
Dummy predicates for XSB compatibility.

\begin{tags}
    \tag{deprecated}
These predicates have no effect.
\end{tags}

    \predicate[semidet]{get_call}{3}{:CallTerm, -Trie, -Return}
True when \arg{Trie} is an answer trie for a variant of \arg{CallTerm}. \arg{Return}
is a term ret/N with N variables that share with variables in
\arg{CallTerm}. The \arg{Trie} contains zero or more instances of the \arg{Return}
term. See also \predref{get_calls}{3}.

    \predicate[nondet]{get_calls}{3}{:CallTerm, -Trie, -Return}
True when \arg{Trie} is an answer trie for a variant that unifies with
\arg{CallTerm} and Skeleton is the answer skeleton. See \predref{get_call}{3} for
details.

    \predicate[nondet]{get_returns}{2}{+ATrie, -Return}
True when \arg{Return} is an answer template for the AnswerTrie.

\begin{arguments}
\arg{Return} & is a term \verb$ret(...)$. See \predref{get_calls}{3}. \\
\end{arguments}

    \predicate[nondet]{get_returns}{3}{+AnswerTrie, -Return, -NodeID}
True when \arg{Return} is an answer template for the \arg{AnswerTrie} and the
answer is represented by the trie node \arg{NodeID}.

\begin{arguments}
\arg{Return} & is a term \verb$ret(...)$. See \predref{get_calls}{3}. \\
\end{arguments}

    \predicate[nondet]{get_returns_and_tvs}{3}{+AnswerTrie, -Return, -TruthValue}
Identical to \predref{get_returns}{2}, but also obtains the truth value of a
given answer, setting \arg{TruthValue} to \const{t} if the answer is
unconditional and to \const{u} if it is conditional. If a conditional
answer has multiple delay lists, this predicate will succeed only
once, so that using this predicate may be more efficient than
\predref{get_residual}{2} (although less informative)

    \predicate[nondet]{get_returns_and_dls}{3}{+AnswerTrie, -Return, :DelayLists}
True when \arg{Return} appears in \arg{AnswerTrie} with the given \arg{DelayLists}.
\arg{DelayLists} is a list of lists, where the inner lists expresses a
conjunctive condition and and outer list a disjunction.

    \predicate[nondet]{get_residual}{2}{:CallTerm, -DelayList}
True if \arg{CallTerm} appears in a table and has \arg{DelayList}. SWI-Prolog's
representation for a delay is a body term, more specifically a
disjunction of conjunctions. The XSB representation is
non-deterministic and uses a list to represent the conjunction.

The delay condition is a disjunction of conjunctions and is
represented as such in the native SWI-Prolog interface as a nested
term of ;/2 and ,/2, using \const{true} if the answer is unconditional.
This XSB predicate returns the associated conjunctions
non-deterministically as a list.

See also \predref{call_residual_program}{2} from \file{library(wfs)}.

    \predicate[nondet]{get_returns_for_call}{2}{:CallTerm, -AnswerTerm}
True if \arg{AnswerTerm} appears in the tables for the \textit{variant} \arg{CallTerm}.

    \predicate{abolish_table_pred}{1}{:CallTermOrPI}
Invalidates all tabled subgoals for the predicate denoted by the
predicate or term indicator Pred.

\begin{tags}
    \tag{To be done}
If Pred has a subgoal that contains a conditional answer, the
default behavior will be to transitively abolish any tabled
predicates with subgoals having answers that depend on any
conditional answers of S.
\end{tags}

    \predicate[det]{abolish_table_call}{1}{+Head}
\nodescription
    \predicate[det]{abolish_table_call}{2}{+Head, +Options}
Same as \predref{abolish_table_subgoals}{1}. See also \predref{abolish_table_pred}{1}.

\begin{tags}
    \tag{deprecated}
Use abolish_table_subgoals/[1,2].
\end{tags}

    \predicate{abolish_table_subgoals}{2}{:Head, +Options}
Behaves as \predref{abolish_table_subgoals}{1}, but allows the default
\verb$table_gc_action$ to be over-ridden with a flag, which can be either
\verb$abolish_tables_transitively$ or \verb$abolish_tables_singly$.

\begin{tags}
    \tag{Compatibility}
\arg{Options} is compatible with XSB, but does not follow the ISO
option handling conventions.
\end{tags}
\end{description}