yap-6.3/docs/builtins.tex

@c -*- mode: texinfo; coding: utf-8; -*

@node Built-ins, Library, Modules, Top

@chapter Built-In Predicates

@menu

Built-ins, Debugging, Syntax, Top
* Control:: Controlling the Execution of Prolog Programs
* Undefined Procedures:: Handling calls to Undefined Procedures
* Messages:: Message Handling in YAP
* Testing Terms:: Predicates on Terms
* Predicates on Atoms:: Manipulating Atoms
* Predicates on Characters:: Manipulating Characters
* Comparing Terms:: Comparison of Terms
* Arithmetic:: Arithmetic in YAP
* I/O:: Input/Output with YAP
* Database:: Modifying Prolog's Database
* Sets:: Finding All Possible Solutions
* Grammars:: Grammar Rules
* Preds:: Predicate Information
* OS:: Access to Operating System Functionality
* Term Modification:: Updating Prolog Terms
* Global Variables:: Manipulating Global Variables
* Profiling:: Profiling Prolog Execution
* Call Counting:: Limiting the Maximum Number of Reductions
* Arrays:: Supporting Global and Local Arrays
* Preds:: Information on Predicates
* Misc:: Miscellaneous Predicates

@end menu

@node Control, Undefined Procedures, , Top
@chapter Control Predicates


This chapter describes the predicates for controlling the execution of
Prolog programs.

In the description of the arguments of functors the following notation
will be used:

@itemize @bullet
@item
a preceding plus sign will denote an argument as an "input argument" -
it cannot be a free variable at the time of the call; 
@item
 a preceding minus sign will denote an "output argument";
@item
an argument with no preceding symbol can be used in both ways.
@end itemize


@table @code

@item +@var{P}, +@var{Q} [ISO]
@findex ,/2
@syindex ,/2
@cyindex ,/2
Conjunction of goals (and).

@noindent
Example:
@example
 p(X) :- q(X), r(X).
@end example

@noindent
should be read as "p(@var{X}) if q(@var{X}) and r(@var{X})".

@item +@var{P} ; +@var{Q} [ISO]
@findex ;/2 
@syindex ;/2 
@cyindex ;/2 
Disjunction of goals (or).

@noindent
Example:
@example
 p(X) :- q(X); r(X).
@end example
@noindent
should be read as "p(@var{X}) if q(@var{X}) or r(@var{X})".

@item true [ISO]
@findex true/0
@syindex true/0
@cyindex true/0
Succeeds once.

@item fail [ISO]
@findex fail/0
@syindex fail/0
@cyindex fail/0
Always fails.

@item false [ISO]
@findex false/0
@syindex false/0
@cnindex false/0
The same as fail.

@item ! [ISO]
@findex !/0
@syindex !/0
@cyindex !/0
  Read as "cut". Cuts any choices taken in the current procedure.
When first found "cut" succeeds as a goal, but if backtracking should
later return to it, the parent goal (the one which matches the head of
the clause containing the "cut", causing the clause activation) will
fail. This is an extra-logical predicate and cannot be explained in
terms of the declarative semantics of Prolog.

example:

@example
 member(X,[X|_]).
 member(X,[_|L]) :- member(X,L).
@end example

@noindent
With the above definition

@example
 ?- member(X,[1,2,3]).
@end example

@noindent
will return each element of the list by backtracking. With the following
definition:

@example
 member(X,[X|_]) :- !.
 member(X,[_|L]) :- member(X,L).
@end example

@noindent
the same query would return only the first element of the 
list, since backtracking could not "pass through" the cut.

@item \+ +@var{P} [ISO]
@findex \+/1
@syindex \+/1
@cyindex \+/1
Goal @var{P} is not provable. The execution of this predicate fails if
and only if the goal @var{P} finitely succeeds. It is not a true logical
negation, which is impossible in standard Prolog, but
"negation-by-failure".

@noindent
This predicate might be defined as:
@example
 \+(P) :- P, !, fail.
 \+(_).
@end example
@noindent
if @var{P} did not include "cuts".

@item not +@var{P}
@findex not/1
@snindex not/1
@cyindex not/1
Goal @var{P} is not provable. The same as @code{'\+ @var{P}'}.

This predicate is kept for compatibility with C-Prolog and previous
versions of YAP. Uses of @code{not/1} should be replace by
@code{(\+)/1}, as YAP does not implement true negation.

@item  +@var{P} -> +@var{Q} [ISO]
@findex ->/2
@syindex ->/2
@cnindex ->/2
Read as "if-then-else" or "commit". This operator is similar to the
conditional operator of imperative languages and can be used alone or
with an else part as follows:

@table @code
@item +P -> +Q
"if P then Q".
@item +P -> +Q; +R
"if P then Q else R".
@end table

@noindent
These two predicates could be defined respectively in Prolog as:
@example
 (P -> Q) :- P, !, Q.
@end example
@noindent
and
@example
 (P -> Q; R) :- P, !, Q.
 (P -> Q; R) :- R.
@end example
@noindent
if there were no "cuts" in @var{P}, @var{Q} and @var{R}.

Note that the commit operator works by "cutting" any alternative
solutions of @var{P}.

Note also that you can use chains of commit operators like:
@example
    P -> Q ; R -> S ; T.
@end example
@noindent
Note that @code{(->)/2} does not affect the scope of cuts in its
arguments.

@item  +@var{Condition} *-> +@var{Action} ; +@var{Else}
@findex ->*/2
@snindex ->*/2
@cnindex ->*/2
This construct implements the so-called @emph{soft-cut}. The control is
    defined as follows: If @var{Condition} succeeds at least once, the
    semantics is the same as (@var{Condition}, @var{Action}). If
    @var{Condition} does not succeed, the semantics is that of (\+
    @var{Condition}, @var{Else}). In other words, If @var{Condition}
    succeeds at least once, simply behave as the conjunction of
    @var{Condition} and @var{Action}, otherwise execute @var{Else}.

    The construct @var{A *-> B}, i.e. without an @var{Else} branch, is
translated as the normal conjunction @var{A}, @var{B}.

@item repeat [ISO]
@findex repeat/0
@syindex repeat/0
@cyindex repeat/0
Succeeds repeatedly.
 
In the next example, @code{repeat} is used as an efficient way to implement
a loop. The next example reads all terms in a file:

@example
 a :- repeat, read(X), write(X), nl, X=end_of_file, !.
@end example
@noindent
the loop is effectively terminated by the cut-goal, when the test-goal
@code{X=end} succeeds. While the test fails, the goals @code{read(X)},
@code{write(X)}, and @code{nl} are executed repeatedly, because
backtracking is caught by the @code{repeat} goal.

The built-in @code{repeat/1} could be defined in Prolog by:
@example
 repeat.
 repeat :- repeat.
@end example

@item call(+@var{P}) [ISO]
@findex call/1
@syindex call/1
@cyindex call/1
 If @var{P} is instantiated to an atom or a compound term, the goal
@code{call(@var{P})} is executed as if the value of @code{P} was found
instead of the call to @code{call/1}, except that any "cut" occurring in
@var{P} only cuts alternatives in the execution of @var{P}.

@item incore(+@var{P})
@findex incore/1
@syindex incore/1
@cnindex incore/1
The same as @code{call/1}.

@item call(+@var{Closure},...,?@var{Ai},...) [ISO]
@findex call/n
@snindex call/n
@cnindex call/n
Meta-call where @var{Closure} is a closure that is converted into a goal by 
appending the @var{Ai} additional arguments. The number of arguments varies 
between 0 and 10.

@item call_with_args(+@var{Name},...,?@var{Ai},...)
@findex call_with_args/n
@snindex call_with_args/n
@cnindex call_with_args/n
Meta-call where @var{Name} is the name of the procedure to be called and
the @var{Ai} are the arguments. The number of arguments varies between 0
and 10. New code should use @code{call/N} for better portability.

If @var{Name} is a complex term, then @code{call_with_args/n} behaves as
@code{call/n}:

@example
call(p(X1,...,Xm), Y1,...,Yn) :- p(X1,...,Xm,Y1,...,Yn).
@end example


@item +@var{P}
@findex var_call/1
 The same as @code{call(@var{P})}. This feature has been kept to provide
compatibility with C-Prolog. When compiling a goal, YAP
generates a @code{call(@var{X})} whenever a variable @var{X} is found as
a goal.

@example
 a(X) :- X.
@end example
@noindent
is converted to:
@example
 a(X) :- call(X).
@end example

@item if(?@var{G},?@var{H},?@var{I})
@findex if/3
@syindex if/3
@cnindex if/3
Call goal @var{H} once per each solution of goal @var{H}. If goal
@var{H} has no solutions, call goal @var{I}.

The built-in @code{if/3} is similar to @code{->/3}, with the difference
that it will backtrack over the test goal. Consider the following
small data-base:

@example
a(1).        b(a).          c(x).
a(2).        b(b).          c(y).
@end example

Execution of an @code{if/3} query will proceed as follows:

@example
   ?- if(a(X),b(Y),c(Z)).

X = 1,
Y = a ? ;

X = 1,
Y = b ? ;

X = 2,
Y = a ? ;

X = 2,
Y = b ? ;

no
@end example


@noindent
The system will backtrack over the two solutions for @code{a/1} and the
two solutions for @code{b/1}, generating four solutions.

Cuts are allowed inside the first goal @var{G}, but they will only prune
over @var{G}.

If you want @var{G} to be deterministic you should use if-then-else, as
it is both more efficient and more portable.

@item once(:@var{G}) [ISO]
@findex once/1
@snindex once/1
@cnindex once/1
Execute the goal @var{G} only once. The predicate is defined by:

@example
 once(G) :- call(G), !.
@end example

@noindent
Note that cuts inside @code{once/1} can only cut the other goals inside
@code{once/1}.

@item forall(:@var{Cond},:@var{Action})
@findex forall/2
@snindex forall/2
@cnindex forall/2
For all alternative bindings of @var{Cond} @var{Action} can be
proven. The example verifies that all arithmetic statements in the list
@var{L} are correct. It does not say which is wrong if one proves wrong.

@example
?- forall(member(Result = Formula, [2 = 1 + 1, 4 = 2 * 2]),
                 Result =:= Formula).
@end example

@item ignore(:@var{Goal})
@findex ignore/1
@snindex ignore/1
@cnindex ignore/1
Calls @var{Goal} as @code{once/1}, but succeeds, regardless of whether
@code{Goal} succeeded or not. Defined as:

@example
ignore(Goal) :-
        Goal, !.
ignore(_).
@end example

@item abort
@findex abort/0
@syindex abort/0
@cyindex abort/0
Abandons the execution of the current goal and returns to top level. All
break levels (see @code{break/0} below) are terminated. It is mainly
used during debugging or after a serious execution error, to return to
the top-level.


@item break
@findex break/0
@syindex break/0
@cyindex break/0
Suspends the execution of the current goal and creates a new execution
level similar to the top level, displaying the following message:

@example
 [ Break (level <number>) ]
@end example
@noindent
telling the depth of the break level just entered. To return to the
previous level just type the end-of-file character or call the
end_of_file predicate.  This predicate is especially useful during
debugging.

@item halt [ISO]
@findex halt/0
@syindex halt/0
@cyindex halt/0
Halts Prolog, and exits to the calling application. In YAP,
@code{halt/0} returns the exit code @code{0}.

@item halt(+ @var{I}) [ISO]
@findex halt/1
@syindex halt/1
@cnindex halt/1
Halts Prolog, and exits to the calling application returning the code
given by the integer @var{I}.

@item catch(+@var{Goal},+@var{Exception},+@var{Action}) [ISO]
@findex catch/3
@snindex catch/3
@cnindex catch/3
The goal @code{catch(@var{Goal},@var{Exception},@var{Action})} tries to
execute goal @var{Goal}. If during its execution, @var{Goal} throws an
exception @var{E'} and this exception unifies with @var{Exception}, the
exception is considered to be caught and @var{Action} is executed. If
the exception @var{E'} does not unify with @var{Exception}, control
again throws the exception.

The top-level of YAP maintains a default exception handler that
is responsible to capture uncaught exceptions.

@item throw(+@var{Ball}) [ISO]
@findex throw/1
@snindex throw/1
@cnindex throw/1
The goal @code{throw(@var{Ball})} throws an exception. Execution is
stopped, and the exception is sent to the ancestor goals until reaching
a matching @code{catch/3}, or until reaching top-level.

@item garbage_collect
@findex garbage_collect/0
@syindex garbage_collect/0
@cnindex garbage_collect/0
The goal @code{garbage_collect} forces a garbage collection.

@item garbage_collect_atoms
@findex garbage_collect_atoms/0
@syindex garbage_collect_atoms/0
@cnindex garbage_collect_atoms/0
The goal @code{garbage_collect} forces a garbage collection of the atoms
in the data-base. Currently, only atoms are recovered.

@item gc
@findex gc/0
@syindex gc/0
@cnindex gc/0
The goal @code{gc} enables garbage collection. The same as
@code{yap_flag(gc,on)}.

@item nogc
@findex nogc/0 
@syindex nogc/0
@cnindex nogc/0
The goal @code{nogc} disables garbage collection. The same as
@code{yap_flag(gc,off)}.

@item grow_heap(+@var{Size})
@findex grow_heap/1
@snindex grow_heap/1
@cnindex grow_heap/1
Increase heap size @var{Size} kilobytes.

@item grow_stack(+@var{Size})
@findex grow_stack/1
@snindex grow_stack/1
@cnindex grow_stack/1
Increase stack size @var{Size} kilobytes.

@end table

@node Undefined Procedures, Messages, Control, Top
@section Handling Undefined Procedures

A predicate in a module is said to be undefined if there are no clauses
defining the predicate, and if the predicate has not been declared to be
dynamic. What YAP does when trying to execute undefined predicates can
be specified in three different ways:
@itemize @bullet
@item By setting an YAP flag, through the @code{yap_flag/2} or
@code{set_prolog_flag/2} built-ins. This solution generalizes the
ISO standard.
@item By using the @code{unknown/2} built-in (this solution is
compatible with previous releases of YAP).
@item By defining clauses for the hook predicate
@code{user:unknown_predicate_handler/3}. This solution is compatible
with SICStus Prolog.
@end itemize

In more detail:
@table @code
@item unknown(-@var{O},+@var{N})
@findex unknown/2
@saindex unknown/2
@cnindex unknown/2
Specifies an handler to be called is a program tries to call an
undefined static procedure @var{P}.

The arity of @var{N} may be zero or one. If the arity is @code{0}, the
new action must be one of @code{fail}, @code{warning}, or
@code{error}. If the arity is @code{1}, @var{P} is an user-defined
handler and at run-time, the argument to the handler @var{P} will be
unified with the undefined goal. Note that @var{N} must be defined prior
to calling @code{unknown/2}, and that the single argument to @var{N} must
be unbound.

In YAP, the default action is to @code{fail} (note that in the ISO
Prolog standard the default action is @code{error}).

After defining @code{undefined/1} by:
@example
undefined(A) :- format('Undefined predicate: ~w~n',[A]), fail.
@end example
@noindent
and executing the goal:
@example
unknown(U,undefined(X)).
@end example
@noindent
a call to a predicate for which no clauses were defined will result in
the output of a message of the form:
@example
Undefined predicate: user:xyz(A1,A2)
@end example
@noindent
followed by the failure of that call.

@item yap_flag(unknown,+@var{SPEC})
@findex yap_flag_unknown/1
Alternatively, one can use @code{yap_flag/2},
@code{current_prolog_flag/2}, or @code{set_prolog_flag/2}, to set this
functionality. In this case, the first argument for the built-ins should
be @code{unknown}, and the second argument should be either
@code{error}, @code{warning}, @code{fail}, or a goal.

@item user:unknown_predicate_handler(+G,+M,?NG)
@findex unknown_predicate_handler/3
@syindex unknown_predicate_handler/3
@cnindex unknown_predicate_handler/3
The user may also define clauses for
@code{user:unknown_predicate_handler/3} hook predicate. This
user-defined procedure is called before any system processing for the
undefined procedure, with the first argument @var{G} set to the current
goal, and the second @var{M} set to the current module. The predicate
@var{G} will be called from within the user module.

If @code{user:unknown_predicate_handler/3} succeeds, the system will
execute @var{NG}. If  @code{user:unknown_predicate_handler/3} fails, the
system will execute default action as specified by @code{unknown/2}.

@item exception(+@var{Exception}, +@var{Context}, -@var{Action})
@findex exception/3
@syindex exception/3
@cnindex exception/3
 Dynamic predicate, normally not defined. Called by the Prolog system on run-time exceptions that can be repaired `just-in-time'. The values for @var{Exception} are described below. See also @code{catch/3} and @code{throw/1}.
If this hook predicate succeeds it must instantiate the @var{Action} argument to the atom @code{fail} to make the operation fail silently, @code{retry} to tell Prolog to retry the operation or @code{error} to make the system generate an exception. The action @code{retry} only makes sense if this hook modified the environment such that the operation can now succeed without error.

@table @code
@item undefined_predicate
@var{Context} is instantiated to a predicate-indicator (@var{Module:Name/Arity}). If the predicate fails Prolog will generate an existence_error exception. The hook is intended to implement alternatives to the SWI built-in autoloader, such as autoloading code from a database. Do not use this hook to suppress existence errors on predicates. See also @code{unknown}.
@item undefined_global_variable
@var{Context} is instantiated to the name of the missing global variable. The hook must call @code{nb_setval/2} or @code{b_setval/2} before returning with the action retry.
@end table

@end table

@node Messages, Testing Terms, Undefined Procedures, Top
@section Message Handling

The interaction between YAP and the user relies on YAP's ability to
portray messages. These messages range from prompts to error
information. All message processing is performed through the builtin
@code{print_message/2}, in two steps:

@itemize @bullet
@item The message is processed into a list of commands 
@item The commands in the list are sent to the @code{format/3} builtin
in sequence.
@end itemize 

The first argument to @code{print_message/2} specifies the importance of
the message. The options are:

@table @code
@item error
error handling
@item warning
compilation and run-time warnings,
@item informational
generic informational messages
@item help 
help messages (not currently implemented in YAP)
@item query
query 	used in query processing (not currently implemented in YAP)
@item  silent
messages that do not produce output but that can be intercepted by hooks.
@end table

The next table shows the main predicates and hooks associated to message
handling in YAP:
@table @code
@item print_message(+@var{Kind}, @var{Term})
@findex print_message/2
@syindex print_message/2
@cnindex print_message/2
The predicate print_message/2 is used to print messages, notably from
exceptions in a human-readable format. @var{Kind} is one of
@code{informational}, @code{banner}, @code{warning}, @code{error},
@code{help} or @code{silent}. A human-readable message is printed to
the stream @code{user_error}.

@c \index{silent}\index{quiet}%
If the Prolog flag @code{verbose} is @code{silent}, messages with
@var{Kind} @code{informational}, or @code{banner} are treated as
silent.@c  See \cmdlineoption{-q}.

This predicate first translates the @var{Term} into a list of `message
lines' (see @code{print_message_lines/3} for details).  Next it will
call the hook @code{message_hook/3} to allow the user intercepting the
message.  If @code{message_hook/3} fails it will print the message unless
@var{Kind} is silent.

@c The print_message/2 predicate and its rules are in the file
@c \file{<plhome>/boot/messages.pl}, which may be inspected for more
@c information on the error messages and related error terms. 
If you need to report errors from your own predicates, we advise you to
stick to the existing error terms if you can; but should you need to
invent new ones, you can define corresponding error messages by
asserting clauses for @code{prolog:message/2}. You will need to declare
the predicate as multifile.

@c See also message_to_string/2.

@item print_message_lines(+@var{Stream}, +@var{Prefix}, +@var{Lines})
@findex print_message_lines/3
@syindex print_message_lines/3
@cnindex print_message_lines/3
Print a message (see @code{print_message/2}) that has been translated to
a list of message elements.  The elements of this list are:

@table @code
    @item @code{<Format>}-@code{<Args>}
        Where @var{Format} is an atom and @var{Args} is a list
	of format argument.  Handed to @code{format/3}.
    @item @code{flush}
	If this appears as the last element, @var{Stream} is flushed
	(see @code{flush_output/1}) and no final newline is generated.
    @item @code{at_same_line}
        If this appears as first element, no prefix is printed for
	the first line and the line-position is not forced to 0
	(see @code{format/1}, @code{~N}).
    @item @code{<Format>}
        Handed to @code{format/3} as @code{format(Stream, Format, [])}.
    @item nl
        A new line is started and if the message is not complete
	the @var{Prefix} is printed too.
@end table

@item user:message_hook(+@var{Term}, +@var{Kind}, +@var{Lines})
@findex message_hook/3
@syindex message_hook/3
@cnindex message_hook/3
Hook predicate that may be define in the module @code{user} to intercept
messages from @code{print_message/2}. @var{Term} and @var{Kind} are the
same as passed to @code{print_message/2}. @var{Lines} is a list of
format statements as described with @code{print_message_lines/3}.

This predicate should be defined dynamic and multifile to allow other
modules defining clauses for it too.

@item message_to_string(+@var{Term}, -@var{String})
@findex message_to_string/2
@snindex message_to_string/2
@cnindex message_to_string/2 
Translates a message-term into a string object. Primarily intended for SWI-Prolog emulation.
@end table

@node Testing Terms, Predicates on Atoms, Messages, Top
@chapter Predicates on terms

@table @code

@item var(@var{T}) [ISO]
@findex var/1
@syindex var/1
@cyindex var/1
Succeeds if @var{T} is currently a free variable, otherwise fails. 

@item atom(@var{T}) [ISO]
@findex atom/1
@syindex atom/1
@cyindex atom/1
Succeeds if and only if @var{T} is currently instantiated to an  atom.

@item atomic(T) [ISO]
@findex atomic/1
@syindex atomic/1
@cyindex atomic/1
Checks whether @var{T} is an atomic symbol (atom or number).

@item compound(@var{T}) [ISO]
@findex compound/1
@syindex compound/1
@cnindex compound/1
Checks whether @var{T} is a compound term.

@item db_reference(@var{T})
@findex db_reference/1C
@syindex db_reference/1
@cyindex db_reference/1
Checks whether @var{T} is a database reference.

@item float(@var{T}) [ISO]
@findex float/1
@syindex float/1
@cnindex float/1
Checks whether @var{T} is a floating point number.

@item rational(@var{T})
@findex rational/1
@syindex rational/1
@cyindex rational/1
Checks whether @code{T} is a rational number.

@item integer(@var{T}) [ISO]
@findex integer/1
@syindex integer/1
@cyindex integer/1
Succeeds if and only if @var{T} is currently instantiated to an  integer.

@item nonvar(@var{T}) [ISO]
@findex nonvar/1
@syindex nonvar/1
@cyindex nonvar/1
The opposite of @code{var(@var{T})}.

@item number(@var{T}) [ISO]
@findex number/1
@syindex number/1
@cyindex number/1
Checks whether @code{T} is an integer, rational or a float.

@item primitive(@var{T})
@findex primitive/1
@syindex primitive/1
@cyindex primitive/1
Checks whether @var{T} is an atomic term or a database reference.

@item simple(@var{T})
@findex simple/1
@syindex simple/1
@cnindex simple/1
Checks whether @var{T} is unbound, an atom, or a number.

@item callable(@var{T}) [ISO]
@findex callable/1
@syindex callable/1
@cnindex callable/1
Checks whether @var{T} is a callable term, that is, an atom or a
compound term.

@item numbervars(@var{T},+@var{N1},-@var{Nn})
@findex numbervars/3
@syindex numbervars/3
@cnindex numbervars/3
Instantiates each variable in term @var{T} to a term of the form:
@code{'$VAR'(@var{I})}, with @var{I} increasing from @var{N1} to @var{Nn}.

@item unnumbervars(@var{T},+@var{NT})
@findex unnumbervars/2
@syindex unnumbervars/2
@cnindex unnumbervars/2
Replace every @code{'$VAR'(@var{I})} by a free variable.

@item ground(@var{T}) [ISO]
@findex ground/1
@syindex ground/1
@cnindex ground/1
Succeeds if there are no free variables in the term @var{T}.

@item acyclic_term(@var{T}) [ISO]
@findex acyclic_term/1
@snindex acyclic_term/1
@cnindex acyclic_term/1
Succeeds if there are loops in the term @var{T}, that is, it is an infinite term.

@item arg(+@var{N},+@var{T},@var{A}) [ISO]
@findex arg/3
@syindex arg/3
@cnindex arg/3
Succeeds if the argument @var{N} of the term @var{T} unifies with
@var{A}. The arguments are numbered from 1 to the arity of the term.

The current version will generate an error if @var{T} or @var{N} are
unbound, if @var{T} is not a compound term, of if @var{N} is not a positive
integer. Note that previous versions of YAP would fail silently
under these errors.

@item functor(@var{T},@var{F},@var{N}) [ISO]
@findex functor/3
@syindex functor/3
@cyindex functor/3
The top functor of term @var{T} is named @var{F} and has  arity @var{N}.

When @var{T} is not instantiated, @var{F} and @var{N} must be. If
@var{N} is 0, @var{F} must be an atomic symbol, which will be unified
with @var{T}. If @var{N} is not 0, then @var{F} must be an atom and
@var{T} becomes instantiated to the most general term having functor
@var{F} and arity @var{N}. If @var{T} is instantiated to a term then
@var{F} and @var{N} are respectively unified with its top functor name
and arity.

In the current version of YAP the arity @var{N} must be an
integer. Previous versions allowed evaluable expressions, as long as the
expression would evaluate to an integer. This feature is not available
in the ISO Prolog standard.

@item @var{T} =.. @var{L} [ISO]
@findex =../2
@syindex =../2
@cyindex =../2
The list @var{L} is built with the functor and arguments of the term
@var{T}. If @var{T} is instantiated to a variable, then @var{L} must be
instantiated either to a list whose head is an atom, or to a list
consisting of just a number.

@item @var{X} = @var{Y} [ISO]
@findex =/2
@syindex =/2
@cnindex =/2
Tries to unify terms @var{X} and @var{Y}.

@item @var{X} \= @var{Y} [ISO]
@findex \=/2
@snindex \=/2
@cnindex \=/2
Succeeds if terms @var{X} and @var{Y} are not unifiable.

@item unify_with_occurs_check(?T1,?T2) [ISO]
@findex unify_with_occurs_check/2
@syindex unify_with_occurs_check/2
@cnindex unify_with_occurs_check/2
Obtain the most general unifier of terms @var{T1} and @var{T2}, if there
is one.

This predicate implements the full unification algorithm. An example:n
@example
unify_with_occurs_check(a(X,b,Z),a(X,A,f(B)).
@end example
@noindent
will succeed with the bindings @code{A = b} and @code{Z = f(B)}. On the
other hand:
@example
unify_with_occurs_check(a(X,b,Z),a(X,A,f(Z)).
@end example
@noindent
would fail, because @code{Z} is not unifiable with @code{f(Z)}. Note that
@code{(=)/2} would succeed for the previous examples, giving the following
bindings @code{A = b} and @code{Z = f(Z)}.


@item copy_term(?@var{TI},-@var{TF}) [ISO]
@findex copy_term/2
@syindex copy_term/2
@cnindex copy_term/2
Term @var{TF} is a variant of the original term @var{TI}, such that for
each variable @var{V} in the term @var{TI} there is a new variable @var{V'}
in term @var{TF}. Notice that:

@itemize @bullet
@item suspended goals and attributes for attributed variables in
  @var{TI} are also duplicated;
@item ground terms are shared between the new and the old term.
@end itemize

If you do not want any sharing to occur please use
@code{duplicate_term/2}.

@item duplicate_term(?@var{TI},-@var{TF})
@findex duplicate_term/2
@syindex duplicate_term/2
@cnindex duplicate_term/2
Term @var{TF} is a variant of the original term @var{TI}, such that
for each variable @var{V} in the term @var{TI} there is a new variable
@var{V'} in term @var{TF}, and the two terms do not share any
structure. All suspended goals and attributes for attributed variables
in @var{TI} are also duplicated.

Also refer to @code{copy_term/2}.

@item is_list(+@var{List})
@findex is_list/1
@syindex is_list/1
@cnindex is_list/1
True when @var{List} is a proper list. That is, @var{List}
is bound to the empty list (nil) or a term with functor '.' and arity 2.

@item ?@var{Term1} =@@= ?@var{Term2}
@findex  =@=/2
@syindex =@=/2
@cnindex =@=/2

Same as @code{variant/2}, succeeds if @var{Term1} and @var{Term2} are variant terms.


@item subsumes_term(?@var{Subsumer}, ?@var{Subsumed})
@findex  subsumes_term/2
@syindex subsumes_term/2
@cnindex subsumes_term/2

Succeed if @var{Submuser} subsumes @var{Subsuned} but does not bind any
variable in @var{Subsumer}.

@item term_subsumer(?@var{T1}, ?@var{T2}, ?@var{Subsumer})
@findex  term_subsumer/2
@syindex term_subsumer/2
@cnindex term_subsumer/2

Succeed if @var{Subsumer} unifies with the least general
generalization over @var{T1} and
@var{T2}.

@item term_variables(?@var{Term}, -@var{Variables}) [ISO]
@findex  term_variables/2
@syindex term_variables/2
@cnindex term_variables/2

Unify @var{Variables} with the list of all variables of term
@var{Term}.  The variables occur in the order of their first
appearance when traversing the term depth-first, left-to-right.

@item rational_term_to_tree(?@var{TI},-@var{TF})
@findex rational_term_to_tree/2
@syindex rational_term_to_term/2
@cnindex rational_term_to_tree/2
The term @var{TF} is a tree representation (without cycles) for the
 Prolog term @var{TI}. Loops are replaced by terms of the form
 @code{_LOOP_(@var{LevelsAbove})} where @var{LevelsAbove} is the size of
 the loop.

@item tree_to_rational_term(?@var{TI},-@var{TF})
@findex tree_to_rational_term/2
@syindex tree_to_rational_term/2
@cnindex tree_to_rational_term/2
Inverse of above. The term @var{TI} is a tree representation (without
 cycles) for the Prolog term @var{TF}. Loops replace terms of the form
 @code{_LOOP_(@var{LevelsAbove})} where @var{LevelsAbove} is the size of
 the loop.


@end table

@node Predicates on Atoms, Predicates on Characters, Testing Terms, Top
@section Predicates on Atoms

The following predicates are used to manipulate atoms:

@table @code
@item name(@var{A},@var{L})
@findex name/2
@syindex name/2
@cyindex name/2
The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{A} will
be unified with an atomic symbol and @var{L} with the list of the ASCII
codes for the characters of the external representation of @var{A}.

@example
 name(yap,L).
@end example
@noindent
will return:
@example
 L = [121,97,112].
@end example
@noindent
and
@example
 name(3,L).
@end example
@noindent
will return:
@example
 L = [51].
@end example

@item atom_chars(?@var{A},?@var{L}) [ISO]
@findex atom_chars/2
@saindex atom_chars/2
@cnindex atom_chars/2
The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{A} must
be unifiable with an atom, and the argument @var{L} with the list of the
characters of @var{A}.

@item atom_codes(?@var{A},?@var{L}) [ISO]
@findex atom_codes/2
@syindex atom_codes/2
@cnindex atom_codes/2
The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{A} will
be unified with an atom and @var{L} with the list of the ASCII
codes for the characters of the external representation of @var{A}.

@item atom_concat(+@var{As},?@var{A})
@findex atom_concat/2
@syindex atom_concat/2
@cnindex atom_concat/2
The predicate holds when the first argument is a list of atoms, and the
second unifies with the atom obtained by concatenating all the atoms in
the first list.

@item atomic_concat(+@var{As},?@var{A})
@findex atomic_concat/2
@snindex atomic_concat/2
@cnindex atomic_concat/2
The predicate holds when the first argument is a list of atomic terms, and
the second unifies with the atom obtained by concatenating all the
atomic terms in the first list. The first argument thus may contain
atoms or numbers.

@item atomic_list_concat(+@var{As},?@var{A})
@findex atomic_list_concat/2
@snindex atomic_list_concat/2
@cnindex atomic_list_concat/2
The predicate holds when the first argument is a list of atomic terms, and
the second unifies with the atom obtained by concatenating all the
atomic terms in the first list. The first argument thus may contain
atoms or numbers.

@item atomic_list_concat(?@var{As},+@var{Separator},?@var{A})
@findex atomic_list_concat/3
@snindex atomic_list_concat/3
@cnindex atomic_list_concat/3
Creates an atom just like @code{atomic_list_concat/2}, but inserts
@var{Separator} between each pair of atoms. For example:

@example
?- atomic_list_concat([gnu, gnat], ', ', A).

A = 'gnu, gnat'
@end example

YAP emulates the SWI-Prolog version of this predicate that can also be
used to split atoms by instantiating @var{Separator} and @var{Atom} as
shown below.

@example
?- atomic_list_concat(L, -, 'gnu-gnat').

L = [gnu, gnat]
@end example

@item atom_length(+@var{A},?@var{I}) [ISO]
@findex atom_length/2
@snindex atom_length/2
@cnindex atom_length/2
The predicate holds when the first argument is an atom, and the second
unifies with the number of characters forming that atom.

@item atom_concat(?@var{A1},?@var{A2},?@var{A12}) [ISO]
@findex atom_concat/3
@snindex atom_concat/3
@cnindex atom_concat/3
The predicate holds when the third argument unifies with an atom, and
the first and second unify with atoms such that their representations
concatenated are the representation for @var{A12}.

If @var{A1} and @var{A2} are unbound, the built-in will find all the atoms
that concatenated give @var{A12}.

@item number_chars(?@var{I},?@var{L}) [ISO]
@findex number_chars/2
@saindex number_chars/2
@cnindex number_chars/2

The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{I} must
be unifiable with a number, and the argument @var{L} with the list of the
characters of the external representation of @var{I}.

@item number_codes(?@var{A},?@var{L}) [ISO]
@findex number_codes/2
@syindex number_codes/2
@cnindex number_codes/2
The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{A}
will be unified with a number and @var{L} with the list of the ASCII
codes for the characters of the external representation of @var{A}.

@item atom_number(?@var{Atom},?@var{Number})
@findex atom_number/2
@syindex atom_number/2
@cnindex atom_number/2
The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). If the argument
@var{Atom} is an atom, @var{Number} must be the number corresponding
to the characters in @var{Atom}, otherwise the characters in
@var{Atom} must encode a number @var{Number}.

@item number_atom(?@var{I},?@var{L})
@findex number_atom/2
@snindex number_atom/2
@cnindex number_atom/2

The predicate holds when at least one of the arguments is ground
(otherwise, an error message will be displayed). The argument @var{I} must
be unifiable with a number, and the argument @var{L} must be unifiable
with an atom representing the number.

@item sub_atom(+@var{A},?@var{Bef}, ?@var{Size}, ?@var{After}, ?@var{At_out}) [ISO]
@findex sub_atom/5
@snindex sub_atom/5
@cnindex sub_atom/5
True when @var{A} and @var{At_out} are atoms such that the name of
@var{At_out} has size @var{Size} and is a sub-string of the name of
@var{A}, such that @var{Bef} is the number of characters before and
@var{After} the number of characters afterwards.

Note that @var{A} must always be known, but @var{At_out} can be unbound when
calling this built-in. If all the arguments for @code{sub_atom/5} but @var{A}
are unbound, the built-in will backtrack through all possible
sub-strings of @var{A}.

@end table

@node Predicates on Characters, Comparing Terms, Predicates on Atoms, Top
@section Predicates on Characters

The following predicates are used to manipulate characters:

@table @code
@item char_code(?@var{A},?@var{I}) [ISO]
@findex char_code/2
@syindex char_code/2
@cnindex char_code/2
The built-in succeeds with @var{A} bound to character represented as an
atom, and @var{I} bound to the character code represented as an
integer. At least, one of either @var{A} or @var{I} must be bound before
the call.

@item char_type(?@var{Char}, ?@var{Type})
@findex char_type/2
@snindex char_type/2
@cnindex char_type/2
    Tests or generates alternative @var{Types} or @var{Chars}. The
    character-types are inspired by the standard @code{C}
    @code{<ctype.h>} primitives.

@table @code
@item    alnum
        @var{Char} is a letter (upper- or lowercase) or digit.

@item    alpha
        @var{Char} is a letter (upper- or lowercase).

@item    csym
        @var{Char} is a letter (upper- or lowercase), digit or the underscore (_). These are valid C- and Prolog symbol characters.

@item    csymf
        @var{Char} is a letter (upper- or lowercase) or the underscore (_). These are valid first characters for C- and Prolog symbols

@item    ascii
        @var{Char} is a 7-bits ASCII character (0..127).

@item    white
        @var{Char} is a space or tab. E.i. white space inside a line.

@item    cntrl
        @var{Char} is an ASCII control-character (0..31).

@item    digit
        @var{Char} is a digit.

@item    digit(@var{Weight})
        @var{Char} is a digit with value
        @var{Weight}. I.e. @code{char_type(X, digit(6))} yields @code{X =
        '6'}. Useful for parsing numbers.

@item    xdigit(@var{Weight})
        @var{Char} is a hexa-decimal digit with value @var{Weight}. I.e. char_type(a, xdigit(X) yields X = '10'. Useful for parsing numbers.

@item    graph
        @var{Char} produces a visible mark on a page when printed. Note that the space is not included!

@item    lower
        @var{Char} is a lower-case letter.

@item    lower(Upper)
        @var{Char} is a lower-case version of @var{Upper}. Only true if
        @var{Char} is lowercase and @var{Upper} uppercase.

@item    to_lower(Upper)
        @var{Char} is a lower-case version of Upper. For non-letters, or letter without case, @var{Char} and Lower are the same. See also upcase_atom/2 and downcase_atom/2.

@item    upper
        @var{Char} is an upper-case letter.

@item    upper(Lower)
        @var{Char} is an upper-case version of Lower. Only true if @var{Char} is uppercase and Lower lowercase.

@item    to_upper(Lower)
        @var{Char} is an upper-case version of Lower. For non-letters, or letter without case, @var{Char} and Lower are the same. See also upcase_atom/2 and downcase_atom/2.

@item    punct
        @var{Char} is a punctuation character. This is a graph character that is not a letter or digit.

@item    space
        @var{Char} is some form of layout character (tab, vertical-tab, newline, etc.).

@item    end_of_file
        @var{Char} is -1.

@item    end_of_line
        @var{Char} ends a line (ASCII: 10..13).

@item    newline
        @var{Char} is a the newline character (10).

@item    period
        @var{Char} counts as the end of a sentence (.,!,?).

@item    quote
        @var{Char} is a quote-character (", ', `).

@item    paren(Close)
        @var{Char} is an open-parenthesis and Close is the corresponding close-parenthesis. 
@end table

@item code_type(?@var{Code}, ?@var{Type})
@findex code_type/2
@snindex code_type/2
@cnindex code_type/2
    As @code{char_type/2}, but uses character-codes rather than
    one-character atoms. Please note that both predicates are as
    flexible as possible. They handle either representation if the
    argument is instantiated and only will instantiate with an integer
    code or one-character atom depending of the version used. See also
    the prolog-flag @code{double_quotes} and the built-in predicates 
    @code{atom_chars/2} and @code{atom_codes/2}.

@end table

@node Comparing Terms, Arithmetic, Predicates on Characters, Top
@section Comparing Terms

The following predicates are used to compare and order terms, using the
standard ordering:

@itemize @bullet
@item
variables come before numbers, numbers come before atoms which in turn
come before compound terms, i.e.: variables @@< numbers @@< atoms @@<
compound terms.
@item
Variables are roughly ordered by "age" (the "oldest" variable is put
first);
@item
Floating point numbers are sorted in increasing order;
@item
Rational numbers are sorted in increasing order;
@item
Integers are sorted in increasing order;
@item
Atoms are sorted in lexicographic order;
@item
Compound terms are ordered first by arity of the main functor, then by
the name of the main functor, and finally by their arguments in
left-to-right order.
@end itemize

@table @code

@item compare(@var{C},@var{X},@var{Y}) [ISO]
@findex compare/3
@syindex compare/3
@cyindex compare/3
As a result of comparing @var{X} and @var{Y}, @var{C} may take one of
the following values:

@itemize @bullet
@item
@code{=} if @var{X} and @var{Y} are identical;
@item
@code{<} if @var{X} precedes @var{Y} in the defined order;
@item
@code{>} if @var{Y} precedes @var{X} in the defined order;
@end itemize

@item @var{X} == @var{Y} [ISO]
@findex ==/2
@syindex ==/2
@cyindex ==/2
Succeeds if terms @var{X} and @var{Y} are strictly identical. The
difference between this predicate and @code{=/2} is that, if one of the
arguments is a free variable, it only succeeds when they have already
been unified.

@example
?- X == Y.
@end example
@noindent
fails, but,
@example
?- X = Y, X == Y.
@end example
@noindent
succeeds.
@example
?- X == 2.
@end example
@noindent
fails, but,
@example
?- X = 2, X == 2.
@end example
@noindent
succeeds.


@item @var{X} \== @var{Y} [ISO]
@findex \==/2
@syindex \==/2
@cyindex \==/2
Terms @var{X} and @var{Y} are not strictly identical.

@item @var{X} @@< @var{Y} [ISO]
@findex @@</2
@syindex @@</2
@cyindex @@</2
Term @var{X} precedes term @var{Y} in the standard order.

@item @var{X} @@=< @var{Y} [ISO]
@findex @@=</2
@syindex @@</2
@cyindex @@</2
Term @var{X} does not follow term @var{Y} in the standard order.

@item @var{X} @@> @var{Y} [ISO]
@findex @@>/2
@syindex @@>/2
@cyindex @@>/2
Term @var{X} follows term @var{Y} in the standard order.

@item @var{X} @@>= @var{Y} [ISO]
@findex @@>=/2
@syindex @@>=/2
@cyindex @@>=/2
Term @var{X} does not precede term @var{Y} in the standard order.

@item sort(+@var{L},-@var{S}) [ISO]
@findex sort/2
@syindex sort/2
@cyindex sort/2
Unifies @var{S} with the list obtained by sorting @var{L} and  merging
identical (in the sense of @code{==}) elements.

@item keysort(+@var{L},@var{S}) [ISO]
@findex keysort/2
@syindex keysort/2
@cyindex keysort/2
Assuming L is a list of the form @code{@var{Key}-@var{Value}},
@code{keysort(+@var{L},@var{S})} unifies @var{S} with the list obtained
from @var{L}, by sorting its elements according to the value of
@var{Key}.
@example
?- keysort([3-a,1-b,2-c,1-a,1-b],S).
@end example
@noindent
would return:
@example
S = [1-b,1-a,1-b,2-c,3-a]
@end example

@item predsort(+@var{Pred}, +@var{List}, -@var{Sorted})
@findex predsort/3
@snindex predsort/3
@cnindex predsort/3
Sorts similar to sort/2, but determines the order of two terms by
calling @var{Pred}(-@var{Delta}, +@var{E1}, +@var{E2}) . This call must
unify @var{Delta} with one of @code{<}, @code{>} or @code{=}. If
built-in predicate compare/3 is used, the result is the same as
sort/2.

@item length(?@var{L},?@var{S})
@findex length/2
@syindex length/2
@cyindex length/2
Unify the well-defined list @var{L} with its length. The procedure can
be used to find the length of a pre-defined list, or to build a list
of length @var{S}.

@end table

@node Arithmetic, I/O, Comparing Terms, Top
@section Arithmetic

YAP now supports several different numeric types:

@table @code
@item integers
      When YAP is built using the GNU multiple precision arithmetic
      library (GMP), integer arithmetic is unbounded, which means that
      the size of integers is limited by available memory only. Without
      GMP, SWI-Prolog integers have the same size as an address. The
      type of integer support can be detected using the Prolog flags
      bounded, min_integer and max_integer. As the use of GMP is
      default, most of the following descriptions assume unbounded
      integer arithmetic.

      Internally, SWI-Prolog has three integer representations. Small
      integers (defined by the Prolog flag max_tagged_integer) are
      encoded directly. Larger integers are represented as cell values
      on the global stack. Integers that do not fit in 64-bit are
      represented as serialised GNU MPZ structures on the global stack.

@item number
      Rational numbers (Q) are quotients of two integers. Rational
      arithmetic is only provided if GMP is used (see above). Rational
      numbers that are returned from is/2 are canonical, which means M
      is positive and N and M have no common divisors. Rational numbers
      are introduced in the computation using the rational/1,
      rationalize/1 or the rdiv/2 (rational division) function. 

@item float
      Floating point numbers are represented using the C-type double. On most today platforms these are 64-bit IEEE floating point numbers.

@end table

Arithmetic functions that require integer arguments accept, in addition
to integers, rational numbers with denominator `1' and floating point
numbers that can be accurately converted to integers. If the required
argument is a float the argument is converted to float. Note that
conversion of integers to floating point numbers may raise an overflow
exception. In all other cases, arguments are converted to the same type
using the order integer to rational number to floating point number.

@subsection Arithmetic Expressions

Arithmetic expressions in YAP may use the following operators or
@i{evaluable predicates}:

@table @code

@item +@var{X} [ISO]
The value of @var{X} itself.

@item -@var{X} [ISO]
Symmetric value.

@item @var{X}+@var{Y} [ISO]
Sum.

@item @var{X}-@var{Y} [ISO]
Difference.

@item @var{X}*@var{Y} [ISO]
Product.

@item @var{X}/@var{Y} [ISO]
Quotient.

@item @var{X}//@var{Y} [ISO]
Integer quotient.

@item @var{X} mod @var{Y} [ISO]
Integer module operator, always positive.

@item @var{X} rem @var{Y} [ISO]
Integer remainder, similar to @code{mod} but always has the same sign
@code{X}.

@item @var{X} div @var{Y} [ISO]
Integer division, as if defined by @code{(@var{X} - @var{X} mod @var{Y})
// @var{Y}}.

@item exp(@var{X}) [ISO]
Natural exponential.

@item log(@var{X}) [ISO]
Natural logarithm.

@item log10(@var{X})
Decimal logarithm.

@item sqrt(@var{X}) [ISO]
Square root.

@item sin(@var{X}) [ISO]
Sine.

@item cos(@var{X}) [ISO]
Cosine.

@item tan(@var{X}) [ISO]
Tangent.

@item asin(@var{X}) [ISO]
Arc sine.

@item acos(@var{X}) [ISO]
Arc cosine.

@item atan(@var{X}) [ISO]
Arc tangent.

@item atan(@var{X},@var{Y})
Four-quadrant arc tangent. Also available as @code{atan2/2}.

@item atan2(@var{X},@var{Y}) [ISO]
Four-quadrant arc tangent.

@item sinh(@var{X})
Hyperbolic sine.

@item cosh(@var{X})
Hyperbolic cosine.

@item tanh(@var{X})
Hyperbolic tangent.

@item asinh(@var{X})
Hyperbolic arc sine.

@item acosh(@var{X})
Hyperbolic arc cosine.

@item atanh(@var{X})
Hyperbolic arc tangent.

@item lgamma(@var{X})
Logarithm of gamma function.

@item erf(@var{X})
Gaussian error function.

@item erfc(@var{X})
Complementary gaussian error function.

@item random(@var{X}) [ISO]
An integer random number between 0 and @var{X}.

In @code{iso} language mode the argument must be a floating
point-number, the result is an integer and it the float is equidistant
it is rounded up, that is, to the least integer greater than @var{X}.

@item integer(@var{X})
If @var{X} evaluates to a float, the integer between the value of @var{X}
and 0 closest to the value of @var{X}, else if @var{X} evaluates to an
integer, the value of @var{X}.

@item float(@var{X}) [ISO]
If @var{X} evaluates to an integer, the corresponding float, else the float
itself.

@item float_fractional_part(@var{X}) [ISO]
The fractional part of the floating point number @var{X}, or @code{0.0}
if @var{X} is an integer. In the @code{iso} language mode,
@var{X} must be an integer.

@item float_integer_part(@var{X}) [ISO]
The float giving the integer part of the floating point number @var{X},
or @var{X} if @var{X} is an integer. In the @code{iso} language mode,
@var{X} must be an integer.

@item abs(@var{X}) [ISO]
The absolute value of @var{X}.

@item ceiling(@var{X}) [ISO]
The integer that is the smallest integral value not smaller than @var{X}.

In @code{iso} language mode the argument must be a floating
point-number and the result is an integer.

@item floor(@var{X}) [ISO]
The integer that is the greatest integral value not greater than @var{X}.

In @code{iso} language mode the argument must be a floating
point-number and the result is an integer.

@item round(@var{X}) [ISO]
The nearest integral value to @var{X}. If @var{X} is
equidistant to two integers, it will be rounded to the closest even
integral value.

In @code{iso} language mode the argument must be a floating
point-number, the result is an integer and it the float is equidistant
it is rounded up, that is, to the least integer greater than @var{X}.

@item sign(@var{X}) [ISO]
Return 1 if the @var{X} evaluates to a positive integer, 0 it if
evaluates to 0, and -1 if it evaluates to a negative integer. If @var{X}
evaluates to a floating-point number return 1.0 for a positive @var{X},
0.0 for 0.0, and -1.0 otherwise.

@item truncate(@var{X}) [ISO]
The integral value between @var{X} and 0 closest to
@var{X}.

@item rational(@var{X})
Convert the expression @var{X} to a rational number or integer. The
function returns the input on integers and rational numbers. For
floating point numbers, the returned rational number exactly represents
the float. As floats cannot exactly represent all decimal numbers the
results may be surprising. In the examples below, doubles can represent
@code{0.25} and the result is as expected, in contrast to the result of
@code{rational(0.1)}. The function @code{rationalize/1} gives a more
intuitive result.

@example
?- A is rational(0.25).

A is 1 rdiv 4
?- A is rational(0.1).
A = 3602879701896397 rdiv 36028797018963968
@end example

@item rationalize(@var{X})
Convert the Expr to a rational number or integer. The function is
similar to @code{rational/1}, but the result is only accurate within the
rounding error of floating point numbers, generally producing a much
smaller denominator. 

@example
?- A is rationalize(0.25).

A = 1 rdiv 4
?- A is rationalize(0.1).

A = 1 rdiv 10
@end example


@item max(@var{X},@var{Y}) [ISO]
The greater value of @var{X} and @var{Y}.

@item min(@var{X},@var{Y}) [ISO]
The lesser value of @var{X} and @var{Y}.

@item @var{X} ^ @var{Y} [ISO]
@var{X} raised to the power of @var{Y}, (from the C-Prolog syntax).

@item exp(@var{X},@var{Y})
@var{X} raised to the power of @var{Y}, (from the Quintus Prolog syntax).

@item @var{X} ** @var{Y} [ISO]
@var{X} raised to the power of @var{Y}  (from ISO).

@item @var{X} /\ @var{Y} [ISO]
Integer bitwise conjunction.

@item @var{X} \/ @var{Y} [ISO]
Integer bitwise disjunction.

@item @var{X} # @var{Y}
@item @var{X} >< @var{Y}
@item xor(@var{X} , @var{Y}) [ISO]
Integer bitwise exclusive disjunction.

@item @var{X} << @var{Y}
Integer bitwise left logical shift of @var{X} by @var{Y} places.

@item @var{X} >> @var{Y} [ISO]
Integer bitwise right logical shift of @var{X} by @var{Y} places.

@item \ @var{X} [ISO]
Integer bitwise negation.

@item gcd(@var{X},@var{Y})
The greatest common divisor of the two integers @var{X} and @var{Y}.

@item msb(@var{X})
The most significant bit of the non-negative integer @var{X}.

@item lsb(@var{X})
The least significant bit of the non-negative integer @var{X}.

@item popcount(@var{X})
The number of bits set to @code{1} in the binary representation of the
non-negative integer @var{X}.

@item [@var{X}]
Evaluates to @var{X} for expression @var{X}. Useful because character
strings in Prolog are lists of character codes.

@example
X is Y*10+C-"0"
@end example
@noindent
is the same as
@example
X is Y*10+C-[48].
@end example
@noindent
which would be evaluated as:
@example
X is Y*10+C-48.
@end example

@end table

Besides numbers and the arithmetic operators described above, certain
atoms have a special meaning when present in arithmetic expressions:

@table @code
@item pi [ISO]
The value of @emph{pi}, the ratio of a circle's circumference to its
diameter.

@item e
The base of the natural logarithms.

@item epsilon
The difference between the float @code{1.0} and the first larger floating point
number.

@item inf
Infinity according to the IEEE Floating-Point standard. Note that
evaluating this term will generate a domain error in the @code{iso}
language mode.

@item nan
Not-a-number according to the IEEE Floating-Point standard. Note that
evaluating this term will generate a domain error in the @code{iso}
language mode.

@item cputime
CPU time in seconds, since YAP was invoked.

@item heapused
Heap space used, in bytes.

@item local
Local stack in use, in bytes.

@item global
Global stack in use, in bytes.

@item random
A "random" floating point number between 0 and 1.

@end table

@subsection Arithmetic Primitives

The primitive YAP predicates involving arithmetic expressions are:

@table @code

@item @var{X} is +@var{Y} [2]
@findex is/2
@syindex is/2
@caindex is/2
This predicate succeeds iff the result of evaluating the expression
@var{Y} unifies with @var{X}. This is the predicate normally used to
perform evaluation of arithmetic expressions:

@example
X is 2+3*4
@end example
@noindent
succeeds with @code{X = 14}.

@item +@var{X} < +@var{Y} [ISO]
@findex </2
@syindex </2
@cyindex </2
The value of the expression @var{X} is less than the value of expression
@var{Y}.

@item +@var{X} =< +@var{Y} [ISO]
@findex =</2
@syindex =</2
@cyindex =</2
The value of the expression @var{X} is less than or equal to the value
of expression @var{Y}.


@item +@var{X} > +@var{Y} [ISO]
@findex >/2
@syindex >/2
@cyindex >/2
The value of the expression @var{X} is greater than the value of
expression @var{Y}.

@item +@var{X} >= +@var{Y} [ISO]
@findex >=/2
@syindex >=/2
@cyindex >=/2
The value of the expression @var{X} is greater than or equal to the
value of expression @var{Y}.

@item +@var{X} =:= +@var{Y} [ISO]
@findex =:=/2
@syindex =:=/2
@cyindex =:=/2
The value of the expression @var{X} is equal to the value of expression
@var{Y}.

@item +@var{X} =\= +@var{Y} [ISO]
@findex =\=/2
@syindex =\=/2
@cyindex =\=/2
The value of the expression @var{X} is different from the value of
expression @var{Y}.

@item srandom(+@var{X})
@findex srandom/1
@snindex srandom/1
@cnindex srandom/1
Use the argument @var{X} as a new seed for YAP's random number
generator. The argument should be an integer, but floats are acceptable.
@end table

@noindent
@strong{Notes:}

@itemize @bullet
@item 
Since YAP4, YAP @emph{does not} convert automatically between integers
and floats.
@item
arguments to trigonometric functions are expressed in radians.
@item
if a (non-instantiated) variable occurs in an arithmetic expression YAP
will generate an exception. If no error handler is available, execution
will be thrown back to the top-level.
@end itemize

@subsection Counting

The following predicates provide counting:

@table @code

@item between(+@var{Low}, +@var{High}, ?@var{Value})
@findex between/3
@syindex between/3
@cnindex between/3

    @var{Low} and @var{High} are integers, @var{High} >=@var{Low}. If
    @var{Value} is an integer, @var{Low} =<@var{Value}
    =<@var{High}. When @var{Value} is a variable it is successively
    bound to all integers between @var{Low} and @var{High}. If
    @var{High} is inf or infinite @code{between/3} is true iff
    @var{Value} >= @var{Low}, a feature that is particularly interesting
    for generating integers from a certain value.

@item succ(?@var{Int1}, ?@var{Int2})
@findex succ/3
@syindex succ/3
@cnindex succ/3

    True if @var{Int2} = @var{Int1} + 1 and @var{Int1} >= 0. At least
    one of the arguments must be instantiated to a natural number. This
    predicate raises the domain-error not_less_than_zero if called with
    a negative integer. E.g. @code{succ(X, 0)} fails silently and succ(X, -1)
    raises a domain-error. The behaviour to deal with natural numbers
    only was defined by Richard O'Keefe to support the common
    count-down-to-zero in a natural way. 

@item plus(?@var{Int1}, ?@var{Int2}, ?@var{Int3})
@findex plus/3
@syindex plus/3
@cnindex plus/3
    True if @var{Int3} = @var{Int1} + @var{Int2}. At least two of the
    three arguments must be instantiated to integers.

@item logsum(+@var{Log1}, +@var{Log2}, -@var{Out} )
@findex logsum/3
@snindex logsum/3
@cnindex logsum/3
 True if @var{Log1} is the logarithm of the positive number @var{A1},
 @var{Log2} is the logarithm of the positive number @var{A2}, and
 @var{Out} is the logarithm of the sum of the numbers @var{A1} and
 @var{A2}. Useful in probability computation.

@item isnan(+@var{Float})
@findex isnan/1
@snindex isnan/1
@cnindex isnan/1
 True if @var{Float} is not a number.

@item isinf(+@var{Float})
@findex isinf/1
@snindex isinf/1
@cnindex isinf/1
 True if floating point expression @var{Float} evaluates to infinity.


@end table

@node I/O, Database, Arithmetic, Top
@chapter I/O Predicates

Some of the I/O predicates described below will in certain conditions
provide error messages and abort only if the file_errors flag is set.
If this flag is cleared the same predicates will just fail. Details on
setting and clearing this flag are given under 7.7.

@menu

Subnodes of Input/Output
* Streams and Files:: Handling Streams and Files
* C-Prolog File Handling:: C-Prolog Compatible File Handling
* I/O of Terms:: Input/Output of terms
* I/O of Characters:: Input/Output of Characters
* I/O for Streams:: Input/Output using Streams
* C-Prolog to Terminal:: C-Prolog compatible Character I/O to terminal
* I/O Control:: Controlling your Input/Output
* Sockets:: Using Sockets from YAP

@end menu

@node Streams and Files, C-Prolog File Handling, , I/O
@section Handling Streams and Files

@table @code

@item open(+@var{F},+@var{M},-@var{S}) [ISO]
@findex open/3
@syindex open/3
@cnindex open/3
Opens the file with name @var{F} in mode @var{M} ('read', 'write' or
'append'), returning @var{S} unified with the stream name.

At most, there are 17 streams  opened at the same time. Each stream is
either an input or an output stream but not both. There are always 3
open streams:  @code{user_input} for reading, @code{user_output} for writing
and @code{user_error} for writing. If there is no  ambiguity, the atoms
@code{user_input} and @code{user_output} may be referred to as  @code{user}.

The @code{file_errors} flag controls whether errors are reported when in
mode 'read' or 'append' the file @var{F} does not exist or is not
readable, and whether in mode 'write' or 'append' the file is not
writable.

@item open(+@var{F},+@var{M},-@var{S},+@var{Opts}) [ISO]
@findex open/4
@saindex open/4
@cnindex open/4
Opens the file with name @var{F} in mode @var{M} ('read',  'write' or
'append'), returning @var{S} unified with the stream name, and following
these options:

@table @code

@item type(+@var{T}) [ISO]
Specify whether the stream is a @code{text} stream (default), or a
@code{binary} stream.

@item reposition(+@var{Bool}) [ISO]
Specify whether it is possible to reposition the stream (@code{true}), or
not (@code{false}). By default, YAP enables repositioning for all
files, except terminal files and sockets.

@item eof_action(+@var{Action}) [ISO]
Specify the action to take if attempting to input characters from a
stream where we have previously found an @code{end_of_file}. The possible
actions are @code{error}, that raises an error, @code{reset}, that tries to
reset the stream and is used for @code{tty} type files, and @code{eof_code},
which generates a new @code{end_of_file} (default for non-tty files).

@item alias(+@var{Name}) [ISO]
Specify an alias to the stream. The alias @t{Name} must be an atom. The
alias can be used instead of the stream descriptor for every operation
concerning the stream.

The operation will fail and give an error if the alias name is already
in use. YAP allows several aliases for the same file, but only
one is returned by @code{stream_property/2}

@item bom(+@var{Bool})
If present and @code{true}, a BOM (@emph{Byte Order Mark}) was
detected while opening the file for reading or a BOM was written while
opening the stream. See @ref{BOM} for details.

@item encoding(+@var{Encoding})
Set the encoding used for text.  See @ref{Encoding} for an overview of
wide character and encoding issues.

@item representation_errors(+@var{Mode})
Change the behaviour when writing characters to the stream that cannot
be represented by the encoding.  The behaviour is one of @code{error}
(throw and I/O error exception), @code{prolog} (write @code{\u...\}
escape code or @code{xml} (write @code{&#...;} XML character entity).
The initial mode is @code{prolog} for the user streams and
@code{error} for all other streams. See also @ref{Encoding}.

@item expand_filename(+@var{Mode})
If @var{Mode} is @code{true} then do filename expansion, then ask Prolog
to do file name expansion before actually trying to opening the file:
this includes processing @code{~} characters and processing @code{$}
environment variables at the beginning of the file. Otherwise, just try
to open the file using the given name.

The default behavior is given by the Prolog flag
@code{open_expands_filename}.

@end table

@item close(+@var{S}) [ISO]
@findex close/1
@syindex close/1
@cyindex close/1
Closes the stream @var{S}. If @var{S} does not stand for a stream
currently opened an error is reported. The streams @code{user_input},
@code{user_output}, and @code{user_error} can never be closed.

@c By default, give a file name, @code{close/1} will also try to close a
@c corresponding open stream. This feature is not available in ISO or
@c SICStus languages mode and is deprecated.

@item close(+@var{S},+@var{O}) [ISO]
@findex close/2
@saindex close/2
@cnindex close/2
Closes the stream @var{S}, following options @var{O}. 

The only valid options are @code{force(true)} and @code{force(false)}.
YAP currently ignores these options.

@item time_file(+@var{File},-@var{Time})
@findex time_file/2
@snindex time_file/2
@cnindex time_file/2
Unify the last modification time of @var{File} with
@var{Time}. @var{Time} is a floating point number expressing the seconds
elapsed since Jan 1, 1970.

@item absolute_file_name(+@var{Name},+@var{Options}, -@var{FullPath}) absolute_file_name(+@var{Name}, -@var{FullPath},+@var{Options})
@findex absolute_file_name/3
@syindex absolute_file_name/3
@cnindex absolute_file_name/3

Converts the given file specification into an absolute path.
@var{Option} is a list of options to guide the conversion:

@table @code
    @item extensions(+@var{ListOfExtensions})
List of file-extensions to try.  Default is @samp{''}.  For each
extension, @code{absolute_file_name/3} will first add the extension and then
verify the conditions imposed by the other options.  If the condition
fails, the next extension of the list is tried.  Extensions may be
specified both as @code{.ext} or plain @code{ext}.

    @item relative_to(+@var{FileOrDir})
Resolve the path relative to the given directory or directory the
holding the given file.  Without this option, paths are resolved
relative to the working directory (see @code{working_directory/2}) or,
if @var{Spec} is atomic and @code{absolute_file_name/[2,3]} is executed
in a directive, it uses the current source-file as reference.

    @item access(+@var{Mode})
Imposes the condition access_file(@var{File}, @var{Mode}).  @var{Mode}
is on of @code{read}, @code{write}, @code{append}, @code{exist} or
@code{none} (default). 
See also @code{access_file/2}.

    @item file_type(+@var{Type})
Defines extensions. Current mapping: @code{txt} implies @code{['']},
@code{prolog} implies @code{['.yap', '.pl', '.prolog', '']}, @code{executable} 
implies @code{['.so', '']}, @code{qlf} implies @code{['.qlf', '']} and
@code{directory} implies @code{['']}.  The file-type @code{source}
is an alias for @code{prolog} for compatibility to SICStus Prolog.
See also @code{prolog_file_type/2}. Notice also that this predicate only
returns non-directories, unless the option @code{file_type(directory)} is
specified, or unless @code{access(none)}.

    @item file_errors(@code{fail}/@code{error})
If @code{error} (default), throw and @code{existence_error} exception
if the file cannot be found.  If @code{fail}, stay silent.

    @item solutions(@code{first}/@code{all})
If @code{first} (default), the predicates leaves no choice-point.
Otherwise a choice-point will be left and backtracking may yield
more solutions.

 @item expand(@code{true}/@code{false})
 If @code{true} (default is @code{false}) and @var{Spec} is atomic,
 call @code{expand_file_name/2} followed by @code{member/2} on @var{Spec} before
 proceeding.  This is originally a SWI-Prolog extension.
@end table

@c The Prolog flag @code{verbose_file_search} can be set to @code{true}
@c to help debugging Prolog's search for files.

Compatibility considerations to common argument-order in ISO as well
as SICStus @code{absolute_file_name/3} forced us to be flexible here.
If the last argument is a list and the 2nd not, the arguments are
swapped, making the call @code{absolute_file_name}(+@var{Spec}, -@var{Path},
+@var{Options}) valid as well.

@item absolute_file_name(+@var{Name},-@var{FullPath})
@findex absolute_file_name/2
@syindex absolute_file_name/2
@cnindex absolute_file_name/2
Give the path a full path @var{FullPath} YAP would use to consult a file
named @var{Name}.  Unify @var{FullPath} with @code{user} if the file
name is @code{user}.

@item file_base_name(+@var{Name},-@var{FileName})
@findex file_base_name/2
@snindex file_base_name/2
@cnindex file_base_name/2
Give the path a full path @var{FullPath} extract the @var{FileName}.

@item file_name_extension(?@var{Base},?@var{Extension}, ?@var{Name})
@findex file_name_extension/3
@snindex file_name_extension/3
@cnindex file_name_extension/3

This predicate is used to add, remove or test filename extensions. The
main reason for its introduction is to deal with different filename
properties in a portable manner. If the file system is
case-insensitive, testing for an extension will be done
case-insensitive too. @var{Extension} may be specified with or
without a leading dot (.). If an @var{Extension} is generated, it
will not have a leading dot.

@item current_stream(@var{F},@var{M},@var{S})
@findex current_stream/3
@syindex current_stream/3
@cnindex current_stream/3
Defines the relation: The stream @var{S} is opened on the file @var{F}
in mode @var{M}. It might be used to obtain all open streams (by
backtracking) or to access the stream for a file @var{F} in mode
@var{M}, or to find properties for a stream @var{S}. Notice that some
streams might not be associated to a file: in this case YAP tries to
return the file number. If that is not available, YAP unifies @var{F}
with @var{S}.

@item is_stream(@var{S})
@findex is_stream/1
@snindex is_stream/1
@cnindex is_stream/1
Succeeds if @var{S} is a currently open stream.

@item flush_output [ISO]
@findex flush_output/0
@syindex flush_output/0
@cnindex flush_output/0
Send out all data in the output buffer of the current output stream.

@item flush_output(+@var{S}) [ISO]
@findex flush_output/1
@syindex flush_output/1
@cnindex flush_output/1
Send all data in the output buffer for stream @var{S}.

@item set_input(+@var{S}) [ISO]
@findex set_input/1
@syindex set_input/1
@cnindex set_input/1
Set stream @var{S} as the current input stream. Predicates like @code{read/1}
and @code{get/1} will start using stream @var{S}.

@item set_output(+@var{S}) [ISO]
@findex set_output/1
@syindex set_output/1
@cnindex set_output/1
Set stream @var{S} as the current output stream. Predicates like
@code{write/1} and @code{put/1} will start using stream @var{S}.

@item stream_select(+@var{STREAMS},+@var{TIMEOUT},-@var{READSTREAMS})
@findex stream_select/3
@syindex stream_select/3
@cnindex stream_select/3
Given a list of open @var{STREAMS} opened in read mode and a @var{TIMEOUT}
return a list of streams who are now available for reading. 

If the @var{TIMEOUT} is instantiated to @code{off},
@code{stream_select/3} will wait indefinitely for a stream to become
open. Otherwise the timeout must be of the form @code{SECS:USECS} where
@code{SECS} is an integer gives the number of seconds to wait for a timeout
and @code{USECS} adds the number of micro-seconds.

This built-in is only defined if the system call @code{select} is
available in the system.

@item current_input(-@var{S}) [ISO]
@findex current_input/1
@syindex current_input/1
@cnindex current_input/1
Unify @var{S} with the current input stream.

@item current_output(-@var{S}) [ISO]
@findex current_output/1
@syindex current_output/1
@cnindex current_output/1
Unify @var{S} with the current output stream.

@item at_end_of_stream [ISO]
@findex at_end_of_stream/0
@syindex at_end_of_stream/0
@cnindex at_end_of_stream/0
Succeed if the current stream has stream position end-of-stream or
past-end-of-stream.

@item at_end_of_stream(+@var{S}) [ISO]
@findex at_end_of_stream/1
@syindex at_end_of_stream/1
@cnindex at_end_of_stream/1
Succeed if the stream @var{S} has stream position end-of-stream or
past-end-of-stream. Note that @var{S} must be a readable stream.

@item set_stream_position(+@var{S}, +@var{POS}) [ISO]
@findex set_stream_position/2
@syindex set_stream_position/2
@cnindex set_stream_position/2
Given a stream position @var{POS} for a stream @var{S}, set the current
stream position for @var{S} to be @var{POS}.

@item stream_property(?@var{Stream},?@var{Prop}) [ISO]
@findex stream_property/2
@snindex stream_property/2
@cnindex stream_property/2

Obtain the properties for the open streams. If the first argument is
unbound, the procedure will backtrack through all open
streams. Otherwise, the first argument must be a stream term (you may
use @code{current_stream} to obtain a current stream given a file name).

The following properties are recognized:

@table @code

@item file_name(@var{P})
An atom giving the file name for the current stream. The file names are
@code{user_input}, @code{user_output}, and @code{user_error} for the
standard streams.

@item mode(@var{P})
The mode used to open the file. It may be one of @code{append},
@code{read}, or @code{write}.

@item input
The stream is readable.

@item output
The stream is writable.

@item alias(@var{A})
ISO-Prolog primitive for stream aliases. @t{YAP} returns one of the
existing aliases for the stream.

@item position(@var{P})
A term describing the position in the stream.

@item end_of_stream(@var{E})
Whether the stream is @code{at} the end of stream, or it has found the
end of stream and is @code{past}, or whether it has @code{not} yet
reached the end of stream.

@item eof_action(@var{A})
The action to take when trying to read after reaching the end of
stream. The action may be one of @code{error}, generate an error,
@code{eof_code}, return character code @code{-1}, or @code{reset} the
stream.

@item reposition(@var{B})
Whether the stream can be repositioned or not, that is, whether it is
seekable.

@item type(@var{T})
Whether the stream is a @code{text} stream or a @code{binary} stream.

@item bom(+@var{Bool})
If present and @code{true}, a BOM (@emph{Byte Order Mark}) was
detected while opening the file for reading or a BOM was written while
opening the stream. See @ref{BOM} for details.

@item encoding(+@var{Encoding})
Query the encoding used for text.  See @ref{Encoding} for an
overview of wide character and encoding issues in YAP.

@item representation_errors(+@var{Mode})
Behaviour when writing characters to the stream that cannot be
represented by the encoding.  The behaviour is one of @code{error}
(throw and I/O error exception), @code{prolog} (write @code{\u...\}
escape code or @code{xml} (write @code{&#...;} XML character entity).
The initial mode is @code{prolog} for the user streams and
@code{error} for all other streams. See also @ref{Encoding} and
@code{open/4}.

@end table

@item current_line_number(-@var{LineNumber})
@findex current_line_number/1
@saindex current_line_number/1
@cnindex current_line_number/1
Unify @var{LineNumber} with the line number for the current stream.

@item current_line_number(+@var{Stream},-@var{LineNumber})
@findex current_line_number/2
@saindex current_line_number/2
@cnindex current_line_number/2
Unify @var{LineNumber} with the line number for the @var{Stream}. 

@item line_count(+@var{Stream},-@var{LineNumber})
@findex line_count/2
@syindex line_count/2
@cnindex line_count/2
Unify @var{LineNumber} with the line number for the @var{Stream}.

@item character_count(+@var{Stream},-@var{CharacterCount})
@findex character_count/2
@syindex character_count/2
@cnindex character_count/2
Unify @var{CharacterCount} with the number of characters written to or
read to @var{Stream}.

@item line_position(+@var{Stream},-@var{LinePosition})
@findex line_position/2
@syindex line_position/2
@cnindex line_position/2
Unify @var{LinePosition} with the position on current text stream
@var{Stream}.

@item stream_position(+@var{Stream},-@var{StreamPosition})
@findex stream_position/2
@syindex stream_position/2
@cnindex stream_position/2
Unify @var{StreamPosition} with the packaged information of position on
current stream @var{Stream}. Use @code{stream_position_data/3} to
retrieve information on character or line count.

@item stream_position_data(+@var{Field},+@var{StreamPosition},-@var{Info})
@findex stream_position_data/3
@syindex stream_position_data/3
@cnindex stream_position_data/3
Given the packaged stream position term @var{StreamPosition}, unify
@var{Info} with @var{Field} @code{line_count}, @code{byte_count}, or
@code{char_count}.

@end table

@node C-Prolog File Handling, I/O of Terms, Streams and Files, I/O
@section C-Prolog File Handling
         
@table @code

@item tell(+@var{S})
@findex tell/1
@syindex tell/1
@cyindex tell/1
If @var{S} is a currently opened stream for output, it becomes the
current output stream. If @var{S} is an atom it is taken to be a
filename.  If there is no output stream currently associated with it,
then it is opened for output, and the new output stream created becomes
the current output stream. If it is not possible to open the file, an
error occurs.  If there is a single opened output stream currently
associated with the file, then it becomes the current output stream; if
there are more than one in that condition, one of them is chosen.

Whenever @var{S} is a stream not currently opened for output, an error
may be reported, depending on the state of the file_errors flag. The
predicate just fails, if @var{S} is neither a stream nor an atom.

@item telling(-@var{S})
@findex telling/1
@syindex telling/1
@cyindex telling/1
The current output stream is unified with @var{S}.

@item told
@findex told/0
@syindex told/0
@cyindex told/0
Closes the current output stream, and the user's terminal becomes again
the current output stream. It is important to remember to close streams
after having finished using them, as the maximum number of
simultaneously opened streams is 17.

@item see(+@var{S})
@findex see/1
@syindex see/1
@cyindex see/1
If @var{S} is a currently opened input stream then it is assumed to be
the current input stream. If @var{S} is an atom it is taken as a
filename. If there is no input stream currently associated with it, then
it is opened for input, and the new input stream thus created becomes
the current input stream. If it is not possible to open the file, an
error occurs.  If there is a single opened input stream currently
associated with the file, it becomes the current input stream; if there
are more than one in that condition, then one of them is chosen.

When @var{S} is a stream not currently opened for input, an error may be
reported, depending on the state of the @code{file_errors} flag. If
@var{S} is neither a stream nor an atom the predicates just fails.

@item seeing(-@var{S})
@findex seeing/1
@syindex seeing/1
@cyindex seeing/1
The current input stream is unified with @var{S}.

@item seen
@findex seen/0
@syindex seen/0
@cyindex seen/0
Closes the current input stream (see 6.7.).

@end table

@node I/O of Terms, I/O of Characters, C-Prolog File Handling, I/O
@section Handling Input/Output of Terms

@table @code

@item read(-@var{T}) [ISO]
@findex read/1
@syindex read/1
@cyindex read/1
Reads the next term from the current input stream, and unifies it with
@var{T}. The term must be followed by a dot ('.') and any blank-character
as previously defined. The syntax of the term must match the current
declarations for operators (see op). If the end-of-stream is reached, 
@var{T} is unified with the atom @code{end_of_file}. Further reads from of 
the same stream may cause an error failure (see @code{open/3}).

@item read_term(-@var{T},+@var{Options}) [ISO]
@findex read_term/2
@saindex read_term/2
@cnindex read_term/2
Reads term @var{T} from the current input stream with execution
controlled by the following options:

@table @code

@item  term_position(-@var{Position})
@findex term_position/1 (read_term/2 option)
Unify @var{Position} with a term describing the position of the stream
at the start of parse. Use @code{stream_position_data/3} to obtain extra
information.

@item  singletons(-@var{Names})
@findex singletons/1 (read_term/2 option)
Unify @var{Names} with a list of the form @var{Name=Var}, where
@var{Name} is the name of a non-anonymous singleton variable in the
original term, and @code{Var} is the variable's representation in
YAP.
The variables occur in left-to-right traversal order.

@item  syntax_errors(+@var{Val})
@findex syntax_errors/1 (read_term/2 option)
Control action to be taken after syntax errors. See @code{yap_flag/2}
for detailed information.

@item  variable_names(-@var{Names})
@findex variable_names/1 (read_term/2 option)
Unify @var{Names} with a list of the form @var{Name=Var}, where @var{Name} is
the name of a non-anonymous variable in the original term, and @var{Var}
is the variable's representation in YAP.
The variables occur in left-to-right traversal order.

@item  variables(-@var{Names})
@findex variables/1 (read_term/2 option)
Unify @var{Names} with a list of the variables in term @var{T}.
The variables occur in left-to-right traversal order.

@end table

@item char_conversion(+@var{IN},+@var{OUT}) [ISO]
@findex char_conversion/2
@syindex char_conversion/2
@cnindex char_conversion/2
While reading terms convert unquoted occurrences of the character
@var{IN} to the character @var{OUT}. Both @var{IN} and @var{OUT} must be
bound to single characters atoms.

Character conversion only works if the flag @code{char_conversion} is
on. This is default in the @code{iso} and @code{sicstus} language
modes. As an example, character conversion can be used for instance to
convert characters from the ISO-LATIN-1 character set to ASCII.

If @var{IN} is the same character as @var{OUT}, @code{char_conversion/2}
will remove this conversion from the table.

@item current_char_conversion(?@var{IN},?@var{OUT}) [ISO]
@findex current_char_conversion/2
@syindex current_char_conversion/2
@cnindex current_char_conversion/2
If @var{IN} is unbound give all current character
translations. Otherwise, give the translation for @var{IN}, if one
exists.

@item write(@var{T}) [ISO]
@findex write/1
@syindex write/1
@cyindex write/1
The term @var{T} is written to the current output stream according to
the operator declarations in force.

@item writeln(@var{T}) [ISO]
@findex writeln/1
@snindex writeln/1
@cnindex writeln/1
Same as @code{write/1} followed by @code{nl/0}.

@item display(+@var{T})
@findex display/1
@syindex display/1
@cyindex display/1
Displays term @var{T} on the current output stream. All Prolog terms are
written in standard parenthesized prefix notation.

@item write_canonical(+@var{T}) [ISO]
@findex display/1
@syindex display/1
@cnindex display/1
Displays term @var{T} on the current output stream. Atoms are quoted
when necessary, and operators are ignored, that is, the term is written
in standard parenthesized prefix notation.

@item write_term(+@var{T}, +@var{Opts}) [ISO]
@findex write_term/2
@syindex write_term/2
@cnindex write_term/2
Displays term @var{T} on the current output stream, according to the
following options:

@table @code
@item quoted(+@var{Bool}) [ISO]
If @code{true}, quote atoms if this would be necessary for the atom to
be recognized as an atom by YAP's parser. The default value is
@code{false}.

@item ignore_ops(+@var{Bool}) [ISO]
If @code{true}, ignore operator declarations when writing the term. The
default value is @code{false}.

@item numbervars(+@var{Bool}) [ISO]
If @code{true}, output terms of the form
@code{'$VAR'(N)}, where @var{N} is an integer, as a sequence of capital
letters. The default value is @code{false}.

@item portrayed(+@var{Bool})
If @code{true}, use @t{portray/1} to portray bound terms. The default
value is @code{false}.

@item portray(+@var{Bool})
If @code{true}, use @t{portray/1} to portray bound terms. The default
value is @code{false}.

@item max_depth(+@var{Depth})
If @code{Depth} is a positive integer, use @t{Depth} as
the maximum depth to portray a term. The default is @code{0}, that is,
unlimited depth.

@item priority(+@var{Piority})
If @code{Priority} is a positive integer smaller than @code{1200}, 
give the context priority. The default is @code{1200}.

@item cycles(+@var{Bool})
Do not loop in rational trees (default).
@end table

@item writeq(@var{T}) [ISO]
@findex writeq/1
@syindex writeq/1
@cyindex writeq/1
 Writes the term @var{T}, quoting names to make the result acceptable to
the predicate 'read' whenever necessary.

@item print(@var{T})
@findex print/1
@syindex print/1
@cyindex print/1
Prints the term @var{T} to the current output stream using @code{write/1}
unless T is bound and a call to the user-defined  predicate
@code{portray/1} succeeds. To do pretty  printing of terms the user should
define suitable clauses for @code{portray/1} and use @code{print/1}.

@item format(+@var{T},+@var{L})
@findex format/2
@saindex format/2
@cnindex format/2
Print formatted output to the current output stream. The arguments in
list @var{L} are output according to the string or atom @var{T}.

A control sequence is introduced by a @code{w}. The following control
sequences are available in YAP:

@table @code

@item '~~'
Print a single tilde.

@item '~a'
The next argument must be an atom, that will be printed as if by @code{write}.

@item '~Nc'
The next argument must be an integer, that will be printed as a
character code. The number @var{N} is the number of times to print the
character (default 1).

@item '~Ne'
@itemx '~NE'
@itemx '~Nf'
@itemx '~Ng'
@itemx '~NG'
The next argument must be a floating point number. The float @var{F}, the number
@var{N} and the control code @code{c} will be passed to @code{printf} as:

@example
    printf("%s.Nc", F)
    @end example

As an example:

@example
?- format("~8e, ~8E, ~8f, ~8g, ~8G~w",
          [3.14,3.14,3.14,3.14,3.14,3.14]).
3.140000e+00, 3.140000E+00, 3.140000, 3.14, 3.143.14
@end example

@item '~Nd'
The next argument must be an integer, and @var{N} is the number of digits
after the decimal point. If @var{N} is @code{0} no decimal points will be
printed. The default is @var{N = 0}.

@example
?- format("~2d, ~d",[15000, 15000]).
150.00, 15000
@end example

@item '~ND'
Identical to @code{'~Nd'}, except that commas are used to separate groups
of three digits.

@example
?- format("~2D, ~D",[150000, 150000]).
1,500.00, 150,000
@end example

@item '~i'
Ignore the next argument in the list of arguments:

@example
?- format('The ~i met the boregrove',[mimsy]).
The  met the boregrove
@end example

@item '~k'
Print the next argument with @code{write_canonical}:

@example
?- format("Good night ~k",a+[1,2]).
Good night +(a,[1,2])
@end example

@item '~Nn'
Print @var{N} newlines (where @var{N} defaults to 1).

@item '~NN'
Print @var{N} newlines if at the beginning of the line (where @var{N}
defaults to 1).

@item '~Nr'
The next argument must be an integer, and @var{N} is interpreted as a
radix, such that @code{2 <= N <= 36} (the default is 8).

@example
?- format("~2r, 0x~16r, ~r",
          [150000, 150000, 150000]).
100100100111110000, 0x249f0, 444760
@end example

@noindent
Note that the letters @code{a-z} denote digits larger than 9.

@item '~NR'
Similar to '~NR'. The next argument must be an integer, and @var{N} is
interpreted as a radix, such that @code{2 <= N <= 36} (the default is 8).

@example
?- format("~2r, 0x~16r, ~r",
          [150000, 150000, 150000]).
100100100111110000, 0x249F0, 444760
@end example

@noindent
The only difference is that letters @code{A-Z} denote digits larger than 9.

@item '~p'
Print the next argument with @code{print/1}:

@example
?- format("Good night ~p",a+[1,2]).
Good night a+[1,2]
@end example

@item '~q'
Print the next argument with @code{writeq/1}:

@example
?- format("Good night ~q",'Hello'+[1,2]).
Good night 'Hello'+[1,2]
@end example

@item '~Ns'
The next argument must be a list of character codes. The system then
outputs their representation as a string, where @var{N} is the maximum
number of characters for the string (@var{N} defaults to the length of the
string).

@example
?- format("The ~s are ~4s",["woods","lovely"]).
The woods are love
@end example

@item '~w'
Print the next argument with @code{write/1}:

@example
?- format("Good night ~w",'Hello'+[1,2]).
Good night Hello+[1,2]
@end example

@end table
The number of arguments, @code{N}, may be given as an integer, or it
may be given as an extra argument. The next example shows a small
procedure to write a variable number of @code{a} characters:

@example
write_many_as(N) :-
        format("~*c",[N,0'a]).
@end example

The @code{format/2} built-in also allows for formatted output.  One can
specify column boundaries and fill the intermediate space by a padding
character: 

@table @code
@item '~N|'
Set a column boundary at position @var{N}, where @var{N} defaults to the
current position.

@item '~N+'
Set a column boundary at @var{N} characters past the current position, where
@var{N} defaults to @code{8}.


@item '~Nt'
Set padding for a column, where @var{N} is the fill code (default is
@key{SPC}).

@end table

The next example shows how to align columns and padding. We first show
left-alignment:

@example
   ?- format("~n*Hello~16+*~n",[]).
*Hello          *
@end example

Note that we reserve 16 characters for the column.

The following example shows how to do right-alignment:


@example
   ?- format("*~tHello~16+*~n",[]).
*          Hello*

@end example


The @code{~t} escape sequence forces filling before @code{Hello}. 

We next show how to do centering:

@example
   ?- format("*~tHello~t~16+*~n",[]).
*     Hello     *
@end example


The two @code{~t} escape sequence force filling both before and after
@code{Hello}. Space is then evenly divided between the right and the
left sides.


@item format(+@var{T})
@findex format/1
@saindex format/1
@cnindex format/1
Print formatted output to the current output stream.


@item format(+@var{S},+@var{T},+@var{L})
@findex format/3
@saindex format/3
@cnindex format/3
Print formatted output to stream @var{S}.

@item with_output_to(+@var{Ouput},:@var{Goal})
@findex with_output_to/2
@saindex with_output_to/2
@cnindex with_output_to/2
Run @var{Goal} as @code{once/1}, while characters written to the current
output are sent to @var{Output}. The predicate is SWI-Prolog
specific.

Applications should generally avoid creating atoms by breaking and
concatenating other atoms as the creation of large numbers of
intermediate atoms generally leads to poor performance, even more so in
multi-threaded applications. This predicate supports creating
difference-lists from character data efficiently. The example below
defines the DCG rule @code{term/3} to insert a term in the output:

@example
 term(Term, In, Tail) :-
        with_output_to(codes(In, Tail), write(Term)).

?- phrase(term(hello), X).

X = [104, 101, 108, 108, 111]
@end example

@table @code
@item A Stream handle or alias
    Temporary switch current output to the given stream. Redirection using with_output_to/2 guarantees the original output is restored, also if Goal fails or raises an exception. See also call_cleanup/2. 
@item atom(-@var{Atom})
    Create an atom from the emitted characters. Please note the remark above. 
@item string(-@var{String})
    Create a string-object (not supported in YAP). 
@item codes(-@var{Codes})
    Create a list of character codes from the emitted characters, similar to atom_codes/2. 
@item codes(-@var{Codes}, -@var{Tail})
    Create a list of character codes as a difference-list. 
@item chars(-@var{Chars})
    Create a list of one-character-atoms codes from the emitted characters, similar to atom_chars/2. 
@item chars(-@var{Chars}, -@var{Tail})
    Create a list of one-character-atoms as a difference-list. 
@end table

@end table

@node I/O of Characters, I/O for Streams, I/O of Terms, I/O
@section Handling Input/Output of Characters

@table @code

@item put(+@var{N})
@findex put/1
@syindex put/1
@cyindex put/1
Outputs to the current output stream the character whose ASCII code is
@var{N}. The character @var{N} must be a legal ASCII character code, an
expression yielding such a code, or a list in which case only the first
element is used.

@item put_byte(+@var{N}) [ISO]
@findex put_byte/1
@snindex put_byte/1
@cnindex put_byte/1
Outputs to the current output stream the character whose code is
@var{N}. The current output stream must be a binary stream.

@item put_char(+@var{N}) [ISO]
@findex put_char/1
@snindex put_char/1
@cnindex put_char/1
Outputs to the current output stream the character who is used to build
the representation of atom @code{A}. The current output stream must be a
text stream.

@item put_code(+@var{N}) [ISO]
@findex put_code/1
@snindex put_code/1
@cnindex put_code/1
Outputs to the current output stream the character whose ASCII code is
@var{N}. The current output stream must be a text stream. The character
@var{N} must be a legal ASCII character code, an expression yielding such
a code, or a list in which case only the first element is used.

@item get(-@var{C})
@findex get/1
@syindex get/1
@cyindex get/1
The next non-blank character from the current input stream is unified
with @var{C}. Blank characters are the ones whose ASCII codes are not
greater than 32. If there are no more non-blank characters in the
stream, @var{C} is unified with -1. If @code{end_of_stream} has already
been reached in the previous reading, this call will give an error message.

@item get0(-@var{C})
@findex get0/1
@syindex get0/1
@cyindex get0/1
The next character from the current input stream is consumed, and then
unified with @var{C}. There are no restrictions on the possible
values of the ASCII code for the character, but the character will be
internally converted by YAP.

@item get_byte(-@var{C}) [ISO]
@findex get_byte/1
@snindex get_byte/1
@cnindex get_byte/1
If @var{C} is unbound, or is a character code, and the current stream is a
binary stream, read the next byte from the current stream and unify its
code with @var{C}.

@item get_char(-@var{C}) [ISO]
@findex get_char/1
@snindex get_char/1
@cnindex get_char/1
If @var{C} is unbound, or is an atom representation of a character, and
the current stream is a text stream, read the next character from the
current stream and unify its atom representation with @var{C}.

@item get_code(-@var{C}) [ISO]
@findex get_code/1
@snindex get_code/1
@cnindex get_code/1
If @var{C} is unbound, or is the code for a character, and
the current stream is a text stream, read the next character from the
current stream and unify its code with @var{C}.

@item peek_byte(-@var{C}) [ISO]
@findex peek_byte/1
@snindex peek_byte/1
@cnindex peek_byte/1
If @var{C} is unbound, or is a character code, and the current stream is a
binary stream, read the next byte from the current stream and unify its
code with @var{C}, while leaving the current stream position unaltered.

@item peek_char(-@var{C}) [ISO]
@findex peek_char/1
@syindex peek_char/1
@cnindex peek_char/1
If @var{C} is unbound, or is an atom representation of a character, and
the current stream is a text stream, read the next character from the
current stream and unify its atom representation with @var{C}, while
leaving the current stream position unaltered.

@item peek_code(-@var{C}) [ISO]
@findex peek_code/1
@snindex peek_code/1
@cnindex peek_code/1
If @var{C} is unbound, or is the code for a character, and
the current stream is a text stream, read the next character from the
current stream and unify its code with @var{C}, while
leaving the current stream position unaltered.

@item skip(+@var{N})
@findex skip/1
@syindex skip/1
@cyindex skip/1
Skips input characters until the next occurrence of the character with
ASCII code @var{N}. The argument to this predicate can take the same forms
as those for @code{put} (see 6.11).

@item tab(+@var{N})
@findex tab/1
@syindex tab/1
@cyindex tab/1
Outputs @var{N} spaces to the current output stream.

@item nl [ISO]
@findex nl/0
@syindex nl/0
@cyindex nl/0
Outputs a new line to the current output stream.

@end table

@node I/O for Streams, C-Prolog to Terminal, I/O of Characters, I/O
@section Input/Output Predicates applied to Streams

@table @code

@item read(+@var{S},-@var{T}) [ISO]
@findex read/2
@syindex read/2
@cnindex read/2
Reads term @var{T} from the stream @var{S} instead of from the current input
stream.

@item read_term(+@var{S},-@var{T},+@var{Options}) [ISO]
@findex read_term/3
@saindex read_term/3
@cnindex read_term/3
Reads term @var{T} from stream @var{S} with execution controlled by the
same options as @code{read_term/2}.

@item write(+@var{S},@var{T}) [ISO]
@findex write/2
@syindex write/2
@cnindex write/2
Writes term @var{T} to stream @var{S} instead of to the current output
stream.

@item write_canonical(+@var{S},+@var{T}) [ISO]
@findex write_canonical/2
@syindex write_canonical/2
@cnindex write_canonical/2
Displays term @var{T} on the stream @var{S}. Atoms are quoted when
necessary, and operators are ignored.

@item write_term(+@var{S}, +@var{T}, +@var{Opts}) [ISO]
@findex write_term/3
@syindex write_term/3
@cnindex write_term/3
Displays term @var{T} on the current output stream, according to the same
options used by @code{write_term/3}.

@item writeq(+@var{S},@var{T}) [ISO]
@findex writeq/2
@syindex writeq/2
@cnindex writeq/2
As @code{writeq/1}, but the output is sent to the stream @var{S}.

@item display(+@var{S},@var{T})
@findex display/2
@syindex display/2
@cnindex display/2
Like @code{display/1}, but using stream @var{S} to display the term.

@item print(+@var{S},@var{T})
@findex print/2
@syindex print/2
@cnindex print/2
Prints term @var{T} to the stream @var{S} instead of to the current output
stream.

@item put(+@var{S},+@var{N})
@findex put/2
@syindex put/2
@cnindex put/2
As @code{put(N)}, but to stream @var{S}.

@item put_byte(+@var{S},+@var{N}) [ISO]
@findex put_byte/2
@snindex put_byte/2
@cnindex put_byte/2
As @code{put_byte(N)}, but to binary stream @var{S}.

@item put_char(+@var{S},+@var{A}) [ISO]
@findex put_char/2
@snindex put_char/2
@cnindex put_char/2
As @code{put_char(A)}, but to text stream @var{S}.

@item put_code(+@var{S},+@var{N}) [ISO]
@findex put_code/2
@snindex put_code/2
@cnindex put_code/2
As @code{put_code(N)}, but to text stream @var{S}.

@item get(+@var{S},-@var{C})
@findex get/2
@syindex get/2
@cnindex get/2
The same as @code{get(C)}, but from stream @var{S}.

@item get0(+@var{S},-@var{C})
@findex get0/2
@syindex get0/2
@cnindex get0/2
The same as @code{get0(C)}, but from stream @var{S}.

@item get_byte(+@var{S},-@var{C}) [ISO]
@findex get_byte/2
@snindex get_byte/2
@cnindex get_byte/2
If @var{C} is unbound, or is a character code, and the stream @var{S} is a
binary stream, read the next byte from that stream and unify its
code with @var{C}.

@item get_char(+@var{S},-@var{C}) [ISO]
@findex get_char/2
@snindex get_char/2
@cnindex get_char/2
If @var{C} is unbound, or is an atom representation of a character, and
the stream @var{S} is a text stream, read the next character from that
stream and unify its representation as an atom with @var{C}.

@item get_code(+@var{S},-@var{C}) [ISO]
@findex get_code/2
@snindex get_code/2
@cnindex get_code/2
If @var{C} is unbound, or is a character code, and the stream @var{S} is a
text stream, read the next character from that stream and unify its
code with @var{C}.

@item peek_byte(+@var{S},-@var{C}) [ISO]
@findex peek_byte/2
@snindex peek_byte/2
@cnindex peek_byte/2
If @var{C} is unbound, or is a character code, and @var{S} is a binary
stream, read the next byte from the current stream and unify its code
with @var{C}, while leaving the current stream position unaltered.

@item peek_char(+@var{S},-@var{C}) [ISO]
@findex peek_char/2
@snindex peek_char/2
@cnindex peek_char/2
If @var{C} is unbound, or is an atom representation of a character, and
the stream @var{S} is a text stream, read the next character from that
stream and unify its representation as an atom with @var{C}, while leaving
the current stream position unaltered.

@item peek_code(+@var{S},-@var{C}) [ISO]
@findex peek_code/2
@snindex peek_code/2
@cnindex peek_code/2
If @var{C} is unbound, or is an atom representation of a character, and
the stream @var{S} is a text stream, read the next character from that
stream and unify its representation as an atom with @var{C}, while leaving
the current stream position unaltered.

@item skip(+@var{S},-@var{C})
@findex skip/2
@syindex skip/2
@cnindex skip/2
Like @code{skip/1}, but using stream @var{S} instead of the current
input stream.

@item tab(+@var{S},+@var{N})
@findex tab/2
@syindex tab/2
@cnindex tab/2
The same as @code{tab/1}, but using stream @var{S}.

@item nl(+@var{S}) [ISO]
@findex nl/1
@syindex nl/1
@cnindex nl/1
Outputs a new line to stream @var{S}.

@end table

@node C-Prolog to Terminal, I/O Control, I/O for Streams, I/O
@section Compatible C-Prolog predicates for Terminal I/O

@table @code

@item ttyput(+@var{N})
@findex ttyput/1
@syindex ttyput/1
@cnindex ttyput/1
As @code{put(N)} but always to @code{user_output}.

@item ttyget(-@var{C})
@findex ttyget/1
@syindex ttyget/1
@cnindex ttyget/1
The same as @code{get(C)}, but from stream @code{user_input}.

@item ttyget0(-@var{C})
@findex ttyget0/1
@syindex ttyget0/1
@cnindex ttyget0/1
The same as @code{get0(C)}, but from stream @code{user_input}.

@item ttyskip(-@var{C})
@findex ttyskip/1
@syindex ttyskip/1
@cnindex ttyskip/1
Like @code{skip/1}, but always using stream @code{user_input}.
stream.

@item ttytab(+@var{N})
@findex ttytab/1
@syindex ttytab/1
@cnindex ttytab/1
The same as @code{tab/1}, but using stream @code{user_output}.

@item ttynl
@findex ttynl/0
@syindex ttynl/0
@cnindex ttynl/0
Outputs a new line to stream @code{user_output}.

@end table

@node I/O Control, Sockets, C-Prolog to Terminal, I/O
@section Controlling Input/Output

@table @code

@item exists(+@var{F})
@findex exists/1
@snindex exists/1
@cyindex exists/1
Checks if file @var{F} exists in the current directory.

@item nofileerrors
@findex nofileerrors/0
@syindex nofileerrors/0
@cyindex nofileerrors/0
Switches off the file_errors flag, so that the predicates @code{see/1},
@code{tell/1}, @code{open/3} and @code{close/1} just fail, instead of producing
an error message and aborting whenever the specified file cannot be
opened or closed.

@item fileerrors
@findex fileerrors/0
@syindex fileerrors/0
@cyindex fileerrors/0
Switches on the file_errors flag so that in certain error conditions
I/O predicates will produce an appropriated message and abort.

@item always_prompt_user
@findex always_prompt_user/0
@snindex always_prompt_user/0
@cnindex always_prompt_user/0
Force the system to prompt the user even if the @code{user_input} stream
is not a terminal. This command is useful if you want to obtain
interactive control from a pipe or a socket.

@end table

@node Sockets, , I/O Control, I/O
@section Using Sockets From YAP

YAP includes a SICStus Prolog compatible socket interface. In YAP-6.3
this uses the @c{clib} package to emulate the old low level interface that
provides direct access to the major socket system calls. These calls
can be used both to open a new connection in the network or connect to
a networked server. Socket connections are described as read/write
streams, and standard I/O built-ins can be used to write on or read
from sockets. The following calls are available:

@table @code

@item socket(+@var{DOMAIN},+@var{TYPE},+@var{PROTOCOL},-@var{SOCKET})
@findex socket/4
@syindex socket/4
@cnindex socket/4
Corresponds to the BSD system call @code{socket}. Create a socket for
domain @var{DOMAIN} of type @var{TYPE} and protocol
@var{PROTOCOL}. Both @var{DOMAIN} and @var{TYPE} should be atoms,
whereas @var{PROTOCOL} must be an integer.
The new socket object is
accessible through a descriptor bound to the variable @var{SOCKET}.

The current implementation of YAP only accepts one socket
domain: @code{'AF_INET'}. @c and @code{'AF_UNIX'}. 
Socket types depend on the
underlying operating system, but at least the following types are
supported: @code{'SOCK_STREAM'} and @code{'SOCK_DGRAM'} (untested in 6.3).

@item socket(+@var{DOMAIN},-@var{SOCKET})
@findex socket/2
@syindex socket/2
@cnindex socket/2

Call @code{socket/4} with @var{TYPE} bound to @code{'SOCK_STREAM'} and
@var{PROTOCOL} bound to @code{0}.

@item socket_close(+@var{SOCKET})
@findex socket_close/1
@syindex socket_close/1
@cnindex socket_close/1

Close socket @var{SOCKET}. Note that sockets used in
@code{socket_connect} (that is, client sockets) should not be closed with
@code{socket_close}, as they will be automatically closed when the
corresponding stream is closed with @code{close/1} or @code{close/2}.

@item socket_bind(+@var{SOCKET}, ?@var{PORT})
@findex socket_bind/2
@syindex socket_bind/2
@cnindex socket_bind/2

Interface to system call @code{bind}, as used for servers: bind socket
to a port. Port information depends on the domain:
@table @code
@item 'AF_UNIX'(+@var{FILENAME}) (unsupported)
@item 'AF_FILE'(+@var{FILENAME})
use file name @var{FILENAME} for UNIX or local sockets.

@item 'AF_INET'(?@var{HOST},?PORT)
If @var{HOST} is bound to an atom, bind to host @var{HOST}, otherwise
if unbound bind to local host (@var{HOST} remains unbound). If port
@var{PORT} is bound to an integer, try to bind to the corresponding
port. If variable @var{PORT} is unbound allow operating systems to
choose a port number, which is unified with @var{PORT}.

@end table

@item socket_connect(+@var{SOCKET}, +@var{PORT}, -@var{STREAM})
@findex socket_connect/3
@syindex socket_connect/3
@cnindex socket_connect/3

Interface to system call @code{connect}, used for clients: connect
socket @var{SOCKET} to @var{PORT}. The connection results in the
read/write stream @var{STREAM}.

Port information depends on the domain:
@table @code
@item 'AF_UNIX'(+@var{FILENAME})
@item 'AF_FILE'(+@var{FILENAME})
connect to socket at file @var{FILENAME}.

@item 'AF_INET'(+@var{HOST},+@var{PORT})
Connect to socket at host @var{HOST} and port @var{PORT}.
@end table

@item socket_listen(+@var{SOCKET}, +@var{LENGTH})
@findex socket_listen/2
@syindex socket_listen/2
@cnindex socket_listen/2
Interface to system call @code{listen}, used for servers to indicate
willingness to wait for connections at socket @var{SOCKET}. The
integer @var{LENGTH} gives the queue limit for incoming connections,
and should be limited to @code{5} for portable applications. The socket
must be of type @code{SOCK_STREAM} or @code{SOCK_SEQPACKET}.

@item socket_accept(+@var{SOCKET}, -@var{CLIENT}, -@var{STREAM})
@findex socket_accept/3
@syindex socket_accept/3
@cnindex socket_accept/3
Interface to system call @code{accept}, used for servers to wait for
connections at socket @var{SOCKET}. The stream descriptor @var{STREAM}
represents the resulting connection.  If the socket belongs to the
domain @code{'AF_INET'}, @var{CLIENT} unifies with an atom containing
the IP address for the client in numbers and dots notation.

@item socket_accept(+@var{SOCKET}, -@var{STREAM})
@findex socket_accept/2
@syindex socket_accept/2
@cnindex socket_accept/2
Accept a connection but do not return client information.

@item socket_buffering(+@var{SOCKET}, -@var{MODE}, -@var{OLD}, +@var{NEW})
@findex socket_buffering/4
@syindex socket_buffering/4
@cnindex socket_buffering/4
Set buffering for @var{SOCKET} in @code{read} or @code{write}
@var{MODE}. @var{OLD} is unified with the previous status, and @var{NEW}
receives the new status which may be one of @code{unbuf} or
@code{fullbuf}.

@item socket_select(+@var{SOCKETS}, -@var{NEWSTREAMS}, +@var{TIMEOUT},
+@var{STREAMS}, -@var{READSTREAMS}) [unsupported in YAP-6.3]
@findex socket_select/5 
@syindex socket_select/5
@cnindex socket_select/5
Interface to system call @code{select}, used for servers to wait for
connection requests or for data at sockets. The variable
@var{SOCKETS} is a list of form @var{KEY-SOCKET}, where @var{KEY} is
an user-defined identifier and @var{SOCKET} is a socket descriptor. The
variable @var{TIMEOUT} is either @code{off}, indicating execution will
wait until something is available, or of the form @var{SEC-USEC}, where
@var{SEC} and @var{USEC} give the seconds and microseconds before
@code{socket_select/5} returns. The variable @var{SOCKETS} is a list of
form @var{KEY-STREAM}, where @var{KEY} is an user-defined identifier
and @var{STREAM} is a stream descriptor

Execution of @code{socket_select/5} unifies @var{READSTREAMS} from
@var{STREAMS} with readable data, and @var{NEWSTREAMS} with a list of
the form @var{KEY-STREAM}, where @var{KEY} was the key for a socket
with pending data, and @var{STREAM} the stream descriptor resulting
from accepting the connection.  

@item current_host(?@var{HOSTNAME})
@findex current_host/1
 Unify @var{HOSTNAME} with an atom representing the fully qualified
hostname for the current host. Also succeeds if @var{HOSTNAME} is bound
to the unqualified hostname.

@item hostname_address(?@var{HOSTNAME},?@var{IP_ADDRESS})
@findex hostname_address/2
@var{HOSTNAME} is an host name and @var{IP_ADDRESS} its IP
address in number and dots notation.


@end table

@node Database, Sets, I/O, Top
@chapter Using the Clausal Data Base

Predicates in YAP may be dynamic or static. By default, when
consulting or reconsulting, predicates are assumed to be static:
execution is faster and the code will probably use less space.
Static predicates impose some restrictions: in general there can be no 
addition or removal of  clauses for a procedure if it is being used in the
current execution.

Dynamic predicates allow programmers to change the Clausal Data Base with
the same flexibility as in C-Prolog. With dynamic predicates it is
always possible to add or remove clauses during execution and the
semantics will be the same as for C-Prolog. But the programmer should be
aware of the fact that asserting or retracting are still expensive operations, 
and therefore he should try to avoid them whenever possible.

@table @code

@item dynamic +@var{P}
@findex dynamic/1
@saindex dynamic/1
@cnindex dynamic/1
Declares predicate @var{P} or list of predicates [@var{P1},...,@var{Pn}]
as a dynamic predicate. @var{P} must be written in form:
@var{name/arity}.

@example
:- dynamic god/1.
@end example

@noindent 
a more convenient form can be used:

@example
:- dynamic son/3, father/2, mother/2.
@end example

or, equivalently,

@example
:- dynamic [son/3, father/2, mother/2].
@end example

@noindent
Note:

a predicate is assumed to be dynamic when 
asserted before being defined.

@item dynamic_predicate(+@var{P},+@var{Semantics})
@findex dynamic_predicate/2
@snindex dynamic_predicate/2
@cnindex dynamic_predicate/2
Declares predicate @var{P} or list of predicates [@var{P1},...,@var{Pn}]
as a dynamic predicate following either @code{logical} or
@code{immediate} semantics.
               
@item compile_predicates(:@var{ListOfNameArity})
@findex compile_predicates/1
@snindex compile_predicates/1
@cnindex compile_predicates/1

Compile a list of specified dynamic predicates (see @code{dynamic/1} and
@code{assert/1} into normal static predicates. This call tells the
Prolog environment the definition will not change anymore and further
calls to @code{assert/1} or @code{retract/1} on the named predicates
raise a permission error. This predicate is designed to deal with parts
of the program that is generated at runtime but does not change during
the remainder of the program execution.

@menu

Subnodes of Database
* Modifying the Database:: Asserting and Retracting
* Looking at the Database:: Finding out what is in the Data Base
* Database References:: Using Data Base References
* Internal Database:: YAP's Internal Database
* BlackBoard:: Storing and Fetching Terms in the BlackBoard

@end menu

@end table

@node Modifying the Database, Looking at the Database, , Database
@section Modification of the Data Base

These predicates can be used either for static or for dynamic
predicates:

@table @code

@item assert(+@var{C})
@findex assert/1
@saindex assert/1
@caindex assert/1
 Same as @code{assertz/1}. Adds clause @var{C} to the program. If the predicate is undefined,
declare it as dynamic. New code should use @code{assertz/1} for better portability.

 Most Prolog systems only allow asserting clauses for dynamic
predicates. This is also as specified in the ISO standard. YAP allows
asserting clauses for static predicates, as long as the predicate is not
in use and the language flag is @t{cprolog}. Note that this feature is
deprecated, if you want to assert clauses for static procedures you
should use @code{assert_static/1}.

@item asserta(+@var{C}) [ISO]
@findex asserta/1
@saindex asserta/1
@caindex asserta/1
 Adds clause @var{C} to the beginning of the program. If the predicate is
undefined, declare it as dynamic.

@item assertz(+@var{C}) [ISO]
@findex assertz/1
@saindex assertz/1
@caindex assertz/1
 Adds clause @var{C} to the end of the program. If the predicate is
undefined, declare it as dynamic.

 Most Prolog systems only allow asserting clauses for dynamic
predicates. This is also as specified in the ISO standard. YAP allows
asserting clauses for static predicates. The current version of YAP
supports this feature, but this feature is deprecated and support may go
away in future versions.

@item abolish(+@var{PredSpec}) [ISO]
@findex abolish/1
@saindex abolish/1
@caindex abolish/1
   Deletes the predicate given by @var{PredSpec} from the database. If
@var{PredSpec} is an unbound variable, delete all predicates for the
current module. The
specification must include the name and arity, and it may include module
information. Under @t{iso} language mode this built-in will only abolish
dynamic procedures. Under other modes it will abolish any procedures. 

@item abolish(+@var{P},+@var{N})
@findex abolish/2
@saindex abolish/2
@caindex abolish/2
 Deletes the predicate with name @var{P} and arity @var{N}. It will remove
both static and dynamic predicates.

@item assert_static(:@var{C})
@findex assert_static/1
@snindex assert_static/1
@cnindex assert_static/1
Adds clause @var{C} to a static procedure. Asserting a static clause
for a predicate while choice-points for the predicate are available has
undefined results.

@item asserta_static(:@var{C})
@findex asserta_static/1
@snindex asserta_static/1
@cnindex asserta_static/1
 Adds clause @var{C} to the beginning of a static procedure. 

@item assertz_static(:@var{C})
@findex assertz_static/1
@snindex assertz_static/1
@cnindex assertz_static/1
 Adds clause @var{C} to the end of a static procedure.  Asserting a
static clause for a predicate while choice-points for the predicate are
available has undefined results.

@end table

The following predicates can be used for dynamic predicates and for
static predicates, if source mode was on when they were compiled:

@table @code

@item clause(+@var{H},@var{B}) [ISO]
@findex clause/2
@saindex clause/2
@caindex clause/2
  A clause whose head matches @var{H} is searched for in the
program. Its head and body are respectively unified with @var{H} and
@var{B}. If the clause is a unit clause, @var{B} is unified with
@var{true}.

This predicate is applicable to static procedures compiled with
@code{source} active, and to all dynamic procedures.

@item clause(+@var{H},@var{B},-@var{R})
@findex clause/3
@saindex clause/3
@caindex clause/3
The same as @code{clause/2}, plus @var{R} is unified with the
reference to the clause in the database. You can use @code{instance/2}
to access the reference's value. Note that you may not use
@code{erase/1} on the reference on static procedures.

@item nth_clause(+@var{H},@var{I},-@var{R})
@findex nth_clause/3
@saindex nth_clause/3
@caindex nth_clause/3
Find the @var{I}th clause in the predicate defining @var{H}, and give
a reference to the clause. Alternatively, if the reference @var{R} is
given the head @var{H} is unified with a description of the predicate
and @var{I} is bound to its position.

@end table

The following predicates can only be used for dynamic predicates:

@table @code

@item retract(+@var{C}) [ISO]
@findex retract/1
@saindex retract/1
@cnindex retract/1
Erases the first clause in the program that matches @var{C}. This
predicate may also be used for the static predicates that have been
compiled when the source mode was @code{on}. For more information on
@code{source/0} (@pxref{Setting the Compiler}).

@item retractall(+@var{G}) [ISO]
@findex retractall/1
@saindex retractall/1
@cnindex retractall/1
Retract all the clauses whose head matches the goal @var{G}. Goal
@var{G} must be a call to a dynamic predicate.

@end table

@node Looking at the Database, Database References, Modifying the Database, Database
@section Looking at the Data Base

@table @code

@item listing
@findex listing/0
@saindex listing/0
@caindex listing/0
Lists in the current output stream all the clauses for which source code
is available (these include all clauses for dynamic predicates and
clauses for static predicates compiled when source mode was @code{on}).

@item listing(+@var{P})
@findex listing/1
@syindex listing/1
@caindex listing/1
Lists predicate @var{P} if its source code is available.

@item portray_clause(+@var{C})
@findex portray_clause/1
@syindex portray_clause/1
@cnindex portray_clause/1
Write clause @var{C} as if written by @code{listing/0}.

@item portray_clause(+@var{S},+@var{C})
@findex portray_clause/2
@syindex portray_clause/2
@cnindex portray_clause/2
Write clause @var{C} on stream @var{S} as if written by @code{listing/0}.

@item current_atom(@var{A})
@findex current_atom/1
@syindex current_atom/1
@cyindex current_atom/1
Checks whether @var{A} is a currently defined atom. It is used to find all
currently defined atoms by backtracking.

@item current_predicate(@var{F}) [ISO]
@findex current_predicate/1
@syindex current_predicate/1
@cyindex current_predicate/1
@var{F} is the predicate indicator for a currently defined user or
library predicate. @var{F} is of the form @var{Na/Ar}, where the atom
@var{Na} is the name of the predicate, and @var{Ar} its arity.

@item current_predicate(@var{A},@var{P})
@findex current_predicate/2
@syindex current_predicate/2
@cnindex current_predicate/2
Defines the relation: @var{P} is a currently defined predicate whose
name is the atom @var{A}.

@item system_predicate(@var{A},@var{P})
@findex system_predicate/2
@syindex system_predicate/2
@cnindex system_predicate/2
Defines the relation:  @var{P} is a built-in predicate whose name
is the atom @var{A}.

@item predicate_property(@var{P},@var{Prop}) [ISO]
@findex predicate_property/2
@saindex predicate_property/2
@cnindex predicate_property/2
For the predicates obeying the specification @var{P} unify @var{Prop}
with a property of @var{P}. These properties may be:
@table @code
@item built_in
@findex built_in/0 (predicate_property flag)
true for built-in predicates,
@item dynamic
@findex dynamic/0 (predicate_property flag)
true if the predicate is dynamic
@item static
@findex static/0 (predicate_property flag)
true if the predicate is static
@item meta_predicate(@var{M})
@findex meta_predicate/1 (predicate_property flag)
true if the predicate has a meta_predicate declaration @var{M}.
@item multifile
@findex multifile/1 (predicate_property flag)
true if the predicate was declared to be multifile
@item imported_from(@var{Mod})
@findex imported_from/1 (predicate_property flag)
true if the predicate was imported from module @var{Mod}.
@item exported
@findex exported/0 (predicate_property flag)
true if the predicate is exported in the current module.
@item public
@findex public/0 (predicate_property flag)
true if the predicate is public; note that all dynamic predicates are
public.
@item tabled
@findex tabled/0 (predicate_property flag)
true if the predicate is tabled; note that only static predicates can
be tabled in YAP.
@item source (predicate_property flag)
@findex source/0 (predicate_property flag)
true if source for the predicate is available.
@item number_of_clauses(@var{ClauseCount})
@findex number_of_clauses/1 (predicate_property flag)
Number of clauses in the predicate definition. Always one if external
or built-in.
@end table

@item predicate_statistics(@var{P},@var{NCls},@var{Sz},@var{IndexSz}) 
@findex predicate_statistics/4

Given predicate @var{P}, @var{NCls} is the number of clauses for
@var{P}, @var{Sz} is the amount of space taken to store those clauses
(in bytes), and @var{IndexSz} is the amount of space required to store
indices to those clauses (in bytes).

@item predicate_erased_statistics(@var{P},@var{NCls},@var{Sz},@var{IndexSz}) 
@findex predicate_statistics/4

Given predicate @var{P}, @var{NCls} is the number of erased clauses for
@var{P} that could not be discarded yet, @var{Sz} is the amount of space
taken to store those clauses (in bytes), and @var{IndexSz} is the amount
of space required to store indices to those clauses (in bytes).

@end table

@node Database References, Internal Database, Looking at the Database, Database
@section Using Data Base References

Data Base references are a fast way of accessing terms. The predicates
@code{erase/1} and @code{instance/1} also apply to these references and may
sometimes be used instead of @code{retract/1} and @code{clause/2}.

@table @code

@item assert(+@var{C},-@var{R})
@findex assert/2
@saindex assert/2
@caindex assert/2
 The same as @code{assert(C)} (@pxref{Modifying the Database}) but
unifies @var{R} with the  database reference that identifies the new
clause, in a one-to-one way. Note that @code{asserta/2} only works for dynamic
predicates. If the predicate is undefined, it will automatically be
declared dynamic.

@item asserta(+@var{C},-@var{R})
@findex asserta/2
@saindex asserta/2
@caindex asserta/2
 The same as @code{asserta(C)} but unifying @var{R} with
the  database reference that identifies the new clause, in a 
one-to-one way. Note that @code{asserta/2} only works for dynamic
predicates. If the predicate is undefined, it will automatically be
declared dynamic.

@item assertz(+@var{C},-@var{R})
@findex assertz/2
@saindex assertz/2
@caindex assertz/2
 The same as @code{assertz(C)} but unifying @var{R} with
the  database reference that identifies the new clause, in a 
one-to-one way. Note that @code{asserta/2} only works for dynamic
predicates. If the predicate is undefined, it will automatically be
declared dynamic.

@item retract(+@var{C},-@var{R})
@findex retract/2
@saindex retract/2
@caindex retract/2
 Erases from the program the clause @var{C} whose 
database reference is @var{R}. The predicate must be dynamic.


@end table

@node Internal Database, BlackBoard, Database References, Database
@section Internal Data Base

Some programs need global information for, e.g. counting or collecting 
data obtained by backtracking. As a rule, to keep this information, the
internal data base should be used instead of asserting and retracting
clauses (as most novice programmers  do), .
In YAP (as in some other Prolog systems) the internal data base (i.d.b. 
for short) is faster, needs less space and provides a better insulation of 
program and data than using asserted/retracted clauses.
The i.d.b. is implemented as a set of terms, accessed by keys that 
unlikely what happens in (non-Prolog) data bases are not part of the 
term. Under each key a list of terms is kept. References are provided so that 
terms can be identified: each term in the i.d.b. has a unique reference 
(references are also available for clauses of dynamic predicates).

@table @code

@item recorda(+@var{K},@var{T},-@var{R})
@findex recorda/3
@saindex recorda/3
@cyindex recorda/3
Makes term @var{T} the first record under key @var{K} and  unifies @var{R}
with its reference.

@item recordz(+@var{K},@var{T},-@var{R})
@findex recordz/3
@saindex recordz/3
@cyindex recordz/3
Makes term @var{T} the last record under key @var{K} and unifies @var{R}
with its reference.

@item recorda_at(+@var{R0},@var{T},-@var{R})
@findex recorda_at/3
@snindex recorda_at/3
@cnindex recorda_at/3
Makes term @var{T} the record preceding record with reference
@var{R0}, and unifies @var{R} with its reference.

@item recordz_at(+@var{R0},@var{T},-@var{R})
@findex recordz_at/3
@snindex recordz_at/3
@cnindex recordz_at/3
Makes term @var{T} the record following record with reference
@var{R0}, and unifies @var{R} with its reference.

@item recordaifnot(+@var{K},@var{T},-@var{R})
@findex recordaifnot/3
@saindex recordaifnot/3
@cnindex recordaifnot/3
If a term equal to @var{T} up to variable renaming is stored under key
@var{K} fail. Otherwise, make term @var{T} the first record under key
@var{K} and unify @var{R} with its reference.

@item recordzifnot(+@var{K},@var{T},-@var{R})
@findex recorda/3
@snindex recorda/3
@cnindex recorda/3
If a term equal to @var{T} up to variable renaming is stored under key
@var{K} fail. Otherwise, make term @var{T} the first record under key
@var{K} and unify @var{R} with its reference.

This predicate is YAP specific.


@item recorded(+@var{K},@var{T},@var{R})
@findex recorded/3
@saindex recorded/3
@cyindex recorded/3
Searches in the internal database under the key @var{K}, a term that
unifies with @var{T} and whose reference matches @var{R}. This
built-in may be used in one of two ways:
@itemize @bullet
@item @var{K} may be given, in this case the built-in will return all
elements of the internal data-base that match the key.
@item @var{R} may be given, if so returning the key and element that
match the reference.
@end itemize

@item erase(+@var{R})
@findex erase/1
@saindex erase/1
@cyindex erase/1
The term referred to by @var{R} is erased from the internal database. If
reference @var{R} does not exist in the database, @code{erase} just fails.

@item erased(+@var{R})
@findex erased/1
@saindex erased/1
@cyindex erased/1
Succeeds if the object whose database reference is @var{R} has been
erased.

@item instance(+@var{R},-@var{T})
@findex instance/2
@saindex instance/2
@cyindex instance/2
If @var{R} refers to a clause or a recorded term, @var{T} is unified
with its most general instance. If @var{R} refers to an unit clause
@var{C}, then @var{T} is unified with @code{@var{C} :- true}. When
@var{R} is not a reference to an existing clause or to a recorded term,
this goal fails.

@item eraseall(+@var{K})
@findex eraseall/1
@snindex eraseall/1
@cnindex eraseall/1
All terms belonging to the key @code{K} are erased from the internal
database. The predicate always succeeds.

@item current_key(?@var{A},?@var{K})
@findex current_key/2
@syindex current_key/2
@cnindex current_key/2
Defines the relation: @var{K} is a currently defined database key whose
name is the atom @var{A}. It can be used to generate all the keys for
the internal data-base.

@item nth_instance(?@var{Key},?@var{Index},?@var{R})
@findex nth_instance/3
@saindex nth_instance/3
@cnindex nth_instance/3
Fetches the @var{Index}nth entry in the internal database under the key
@var{Key}. Entries are numbered from one. If the key @var{Key} or the
@var{Index} are bound, a reference is unified with @var{R}. Otherwise,
the reference @var{R} must be given, and YAP will find
the matching key and index.


@item nth_instance(?@var{Key},?@var{Index},@var{T},?@var{R})
@findex nth_instance/4
@saindex nth_instance/4
@cnindex nth_instance/4
Fetches the @var{Index}nth entry in the internal database under the key
@var{Key}. Entries are numbered from one. If the key @var{Key} or the
@var{Index} are bound, a reference is unified with @var{R}. Otherwise,
the reference @var{R} must be given, and YAP will find
the matching key and index.

@item key_statistics(+@var{K},-@var{Entries},-@var{Size},-@var{IndexSize})
@findex key_statistics/4
@snindex key_statistics/4
@cnindex key_statistics/4
Returns several statistics for a key @var{K}. Currently, it says how
many entries we have for that key, @var{Entries}, what is the
total size spent on entries, @var{Size}, and what is the amount of
space spent in indices.

@item key_statistics(+@var{K},-@var{Entries},-@var{TotalSize})
@findex key_statistics/3
@snindex key_statistics/3
@cnindex key_statistics/3
Returns several statistics for a key @var{K}. Currently, it says how
many entries we have for that key, @var{Entries}, what is the
total size spent on this key.

@item get_value(+@var{A},-@var{V})
@findex get_value/2
@snindex get_value/2
@cnindex get_value/2
In YAP, atoms can be associated with constants. If one such
association exists for atom @var{A}, unify the second argument with the
constant. Otherwise, unify @var{V} with @code{[]}.

This predicate is YAP specific.

@item set_value(+@var{A},+@var{C})
@findex set_value/2 
@snindex set_value/2 
@cnindex set_value/2 
Associate atom @var{A} with constant @var{C}.

The @code{set_value} and @code{get_value} built-ins give a fast alternative to
the internal data-base. This is a simple form of implementing a global
counter.
@example
       read_and_increment_counter(Value) :-
                get_value(counter, Value),
                Value1 is Value+1,
                set_value(counter, Value1).
@end example
@noindent
This predicate is YAP specific.

@end table

There is a strong analogy between the i.d.b. and the way dynamic 
predicates are stored. In fact, the main i.d.b. predicates might be 
implemented using dynamic predicates:

@example
recorda(X,T,R) :- asserta(idb(X,T),R).
recordz(X,T,R) :- assertz(idb(X,T),R).
recorded(X,T,R) :- clause(idb(X,T),R).
@end example
@noindent
 We can take advantage of this, the other way around, as it is quite 
easy to write a simple Prolog interpreter, using the i.d.b.:

@example
asserta(G) :- recorda(interpreter,G,_).
assertz(G) :- recordz(interpreter,G,_).
retract(G) :- recorded(interpreter,G,R), !, erase(R).
call(V) :- var(V), !, fail.
call((H :- B)) :- !, recorded(interpreter,(H :- B),_), call(B).
call(G) :- recorded(interpreter,G,_).
@end example
@noindent
In YAP, much attention has been given to the implementation of the 
i.d.b., especially to the problem of accelerating the access to terms kept in 
a large list under the same key. Besides using the key, YAP uses an internal 
lookup function, transparent to the user, to find only the terms that might 
unify. For instance, in a data base containing the terms

@example
b
b(a)
c(d)
e(g)
b(X)
e(h)
@end example

@noindent
stored under the key k/1, when executing the query 

@example
:- recorded(k(_),c(_),R).
@end example

@noindent
@code{recorded} would proceed directly to the third term, spending almost the 
time as if @code{a(X)} or @code{b(X)} was being searched.
 The lookup function uses the functor of the term, and its first three
arguments (when they exist). So, @code{recorded(k(_),e(h),_)} would go
directly to the last term, while @code{recorded(k(_),e(_),_)} would find
first the fourth term, and then, after backtracking, the last one.

 This mechanism may be useful to implement a sort of hierarchy, where 
the functors of the terms (and eventually the first arguments) work as 
secondary keys.

 In the YAP's i.d.b. an optimized representation is used for 
terms without free variables. This results in a faster retrieval of terms 
and better space usage. Whenever possible, avoid variables in terms in terms stored in the  i.d.b.


@node BlackBoard, , Internal Database, Database
@section The Blackboard

YAP implements a blackboard in the style of the SICStus Prolog
blackboard. The blackboard uses the same underlying mechanism as the
internal data-base but has several important differences:
@itemize @bullet
@item It is module aware, in contrast to the internal data-base.
@item Keys can only be atoms or integers, and not compound terms.
@item A single term can be stored per key.
@item An atomic update operation is provided; this is useful for
parallelism.
@end itemize


@table @code
@item bb_put(+@var{Key},?@var{Term})
@findex bb_put/2
@syindex bb_put/2
@cnindex bb_put/2
Store term table @var{Term} in the blackboard under key @var{Key}. If a
previous term was stored under key @var{Key} it is simply forgotten.

@item bb_get(+@var{Key},?@var{Term})
@findex bb_get/2
@syindex bb_get/2
@cnindex bb_get/2
Unify @var{Term} with a term stored in the blackboard under key
@var{Key}, or fail silently if no such term exists.

@item bb_delete(+@var{Key},?@var{Term})
@findex bb_delete/2
@syindex bb_delete/2
@cnindex bb_delete/2
Delete any term stored in the blackboard under key @var{Key} and unify
it with @var{Term}. Fail silently if no such term exists.

@item bb_update(+@var{Key},?@var{Term},?@var{New})
@findex bb_update/3
@syindex bb_update/3
@cnindex bb_update/3
Atomically  unify a term stored in the blackboard under key @var{Key}
with @var{Term}, and if the unification succeeds replace it by
@var{New}. Fail silently if no such term exists or if unification fails.

@end table

@node Sets, Grammars, Database, Top
@section Collecting Solutions to a Goal

When there are several solutions to a goal, if the user wants to collect all
the solutions he may be led to use the data base, because backtracking will
forget previous solutions.

YAP allows the programmer to choose from several system
predicates instead of writing his own routines.  @code{findall/3} gives you
the fastest, but crudest solution. The other built-in predicates
post-process the result of the query in several different ways:

@table @code

@item findall(@var{T},+@var{G},-@var{L}) [ISO]
@findex findall/3
@syindex findall/3
@cyindex findall/3
Unifies @var{L} with a list that contains all the instantiations of the
term @var{T} satisfying the goal @var{G}.

With the following program:
@example
a(2,1).
a(1,1).
a(2,2).
@end example
@noindent
the answer to the query
@example
findall(X,a(X,Y),L).
@end example
@noindent
would be:
@example
X = _32
Y = _33
L = [2,1,2];
no
@end example

@item findall(@var{T},+@var{G},+@var{L},-@var{L0})
@findex findall/4
@syindex findall/4
@cnindex findall/4
Similar to @code{findall/3}, but appends all answers to list @var{L0}.

@item all(@var{T},+@var{G},-@var{L})
@findex all/3
@snindex all/3
@cnindex all/3
Similar to @code{findall(@var{T},@var{G},@var{L})} but eliminate
repeated elements. Thus, assuming the same clauses as in the above
example, the reply to the query

@example
all(X,a(X,Y),L).
@end example
@noindent
would be:

@example
X = _32
Y = _33
L = [2,1];
no
@end example

Note that @code{all/3} will fail if no answers are found.

@item bagof(@var{T},+@var{G},-@var{L}) [ISO]
@findex bagof/3
@saindex bagof/3
@cyindex bagof/3
For each set of possible instances of the free variables occurring in
@var{G} but not in @var{T}, generates the list @var{L} of the instances of
@var{T} satisfying @var{G}. Again, assuming the same clauses as in the
examples above, the reply to the query

@example
bagof(X,a(X,Y),L).

would be:
X = _32
Y = 1
L = [2,1];
X = _32
Y = 2
L = [2];
no
@end example

@item setof(@var{X},+@var{P},-@var{B}) [ISO]
@findex setof/3
@saindex setof/3
@cyindex setof/3
Similar to @code{bagof(@var{T},@var{G},@var{L})} but sorts list
@var{L} and keeping only one copy of each element.  Again, assuming the
same clauses as in the examples above, the reply to the query
@example
setof(X,a(X,Y),L).
@end example
@noindent
would be:
@example
X = _32
Y = 1
L = [1,2];
X = _32
Y = 2
L = [2];
no
@end example

@end table

@node Grammars, OS, Sets, Top
@chapter Grammar Rules

Grammar rules in Prolog are both a convenient way to express definite
clause grammars and  an extension of the well known context-free grammars.

A grammar rule is of the form:

@example
@i{ head --> body }
@end example
@noindent
where both @i{head} and @i{body} are sequences of one or more items
linked by the standard conjunction operator ','.

@emph{Items can be:}

@itemize @bullet
@item
a @emph{non-terminal} symbol may be either a complex term or an atom.
@item
a @emph{terminal} symbol may be any Prolog symbol. Terminals are
written as Prolog lists.
@item
an @emph{empty body} is written as the empty list '[ ]'.
@item
@emph{extra conditions} may be inserted as Prolog procedure calls, by being
written inside curly brackets '@{' and '@}'.
@item
the left side of a rule consists of a nonterminal and an optional list
of terminals.
@item
alternatives may be stated in the right-hand side of the rule by using
the disjunction operator ';'.
@item
the @emph{cut} and @emph{conditional} symbol ('->') may be inserted in the 
right hand side of a grammar rule
@end itemize

Grammar related built-in predicates:

@table @code

@item expand_term(@var{T},-@var{X})
@findex expand_term/2
@syindex expand_term/2
@cyindex expand_term/2

This predicate is used by YAP for preprocessing each top level
term read when consulting a file and before asserting or executing it.
It rewrites a term @var{T} to a term @var{X} according to the following
rules: first try @code{term_expansion/2}  in the current module, and then try to use the user defined predicate
@code{user:term_expansion/2}. If this call fails then the translating process
for DCG rules is applied, together with the arithmetic optimizer
whenever the compilation of arithmetic expressions is in progress.

@item @var{CurrentModule}:term_expansion(@var{T},-@var{X}),  user:term_expansion(@var{T},-@var{X})
@findex term_expansion/2
@syindex term_expansion/2
@cyindex term_expansion/2
This user-defined predicate is called by @code{expand_term/3} to
preprocess all terms read when consulting a file. If it succeeds:

@itemize
@item
If @var{X} is of the form @code{:- G} or @code{?- G}, it is processed as
a directive.
@item
If @var{X} is of the form @code{'$source_location'(<File>,
<Line>):<Clause>} it is processed as if from @code{File} and line @code{Line}.

@item
If @var{X} is a list, all terms of the list are asserted or processed
as directives.
@item The term @var{X} is asserted instead of @var{T}.
@end itemize

@item @var{CurrentModule}:goal_expansion(+@var{G},+@var{M},-@var{NG}), user:goal_expansion(+@var{G},+@var{M},-@var{NG})
@findex goal_expansion/3
@snindex goal_expansion/3
@cnindex goal_expansion/3
YAP now supports @code{goal_expansion/3}. This is an user-defined
procedure that is called after term expansion when compiling or
asserting goals for each sub-goal in a clause. The first argument is
bound to the goal and the second to the module under which the goal
@var{G} will execute. If @code{goal_expansion/3} succeeds the new
sub-goal @var{NG} will replace @var{G} and will be processed in the same
way. If @code{goal_expansion/3} fails the system will use the default
rules.

@item phrase(+@var{P},@var{L},@var{R})
@findex phrase/3
@syindex phrase/3
@cnindex phrase/3
This predicate succeeds when the difference list @code{@var{L}-@var{R}}
is a phrase of type @var{P}.

@item phrase(+@var{P},@var{L})
@findex phrase/2
@syindex phrase/2
@cnindex phrase/2
This predicate succeeds when @var{L} is a phrase of type @var{P}. The
same as @code{phrase(P,L,[])}.

Both this predicate and the previous are used as a convenient way to
start execution of grammar rules.

@item 'C'(@var{S1},@var{T},@var{S2})
@findex C/3
@syindex C/3
@cnindex C/3
This predicate is used by the grammar rules compiler and is defined as
@code{'C'([H|T],H,T)}.

@end table

@node OS, Term Modification, Grammars, Top
@chapter Access to Operating System Functionality

The following built-in predicates allow access to underlying
Operating System functionality: 

@table @code

@item cd(+@var{D})
@findex cd/1
@snindex cd/1
@cnindex cd/1
Changes the current directory (on UNIX environments).

@item cd
@findex cd/0
@snindex cd/0
@cnindex cd/0
Changes the current directory (on UNIX environments) to the user's home directory.

@item environ(+@var{E},-@var{S})
@findex environ/2
@syindex environ/2
@cnindex environ/2
@comment This backtrackable predicate unifies the first argument with an
@comment environment variable @var{E}, and the second with its value @var{S}. It
@comment can used to detect all environment variables.
    Given an environment variable @var{E} this predicate unifies the second argument @var{S} with its value.

@item getcwd(-@var{D})
@findex getcwd/1
@snindex getcwd/1
@cnindex getcwd/1
Unify the current directory, represented as an atom, with the argument
@var{D}.

@item pwd
@findex pwd/0
@snindex pwd/0
@cnindex pwd/0
Prints the current directory.

@item ls
@findex ls/0
@snindex ls/0
@cnindex ls/0
Prints a list of all files in the current directory.

@item putenv(+@var{E},+@var{S})
@findex putenv/2
@snindex putenv/2
@cnindex putenv/2
Set environment variable @var{E} to the value @var{S}. If the
environment variable @var{E} does not exist, create a new one. Both the
environment variable and the value must be atoms.

@item rename(+@var{F},+@var{G})
@findex rename/2
@snindex rename/2
@cyindex rename/2
Renames file @var{F} to @var{G}.

@item sh
@findex sh/0
@snindex sh/0
@cyindex sh/0
Creates a new shell interaction.

@item system(+@var{S})
@findex system/1
@snindex system/1
@cyindex system/1
Passes command @var{S} to the Bourne shell (on UNIX environments) or the
current command interpreter in WIN32 environments.

@item unix(+@var{S})
@findex unix/1
@snindex unix/1
@cnindex unix/1
Access to Unix-like functionality:
@table @code
@item argv/1
Return a list of arguments to the program. These are the arguments that
follow a @code{--}, as in the usual Unix convention.
@item cd/0
Change to home directory.
@item cd/1
Change to given directory. Acceptable directory names are strings or
atoms.
@item environ/2
If the first argument is an atom, unify the second argument with the
value of the corresponding environment variable.
@item getcwd/1
Unify the first argument with an atom representing the current directory.
@item putenv/2
Set environment variable @var{E} to the value @var{S}. If the
environment variable @var{E} does not exist, create a new one. Both the
environment variable and the value must be atoms.
@item shell/1
Execute command under current shell. Acceptable commands are strings or
atoms.
@item system/1
Execute command with @code{/bin/sh}. Acceptable commands are strings or
atoms.
@item shell/0
Execute a new shell.
@end table

@item working_directory(-@var{CurDir},?@var{NextDir})
@findex  working_directory/2
@syindex working_directory/2
@cnindex working_directory/2    @c 
Fetch the current directory at @var{CurDir}. If @var{NextDir} is bound
to an atom, make its value the current working directory.

@item alarm(+@var{Seconds},+@var{Callable},+@var{OldAlarm})
@findex alarm/3
@snindex alarm/3
@cnindex alarm/3
Arranges for YAP to be interrupted in @var{Seconds} seconds, or in
[@var{Seconds}|@var{MicroSeconds}]. When interrupted, YAP will execute
@var{Callable} and then return to the previous execution. If
@var{Seconds} is @code{0}, no new alarm is scheduled. In any event,
any previously set alarm is canceled.

The variable @var{OldAlarm} unifies with the number of seconds remaining
until any previously scheduled alarm was due to be delivered, or with
@code{0} if there was no previously scheduled alarm.

Note that execution of @var{Callable} will wait if YAP is
executing built-in predicates, such as Input/Output operations.

The next example shows how @var{alarm/3} can be used to implement a
simple clock:

@example
loop :- loop.

ticker :- write('.'), flush_output,
          get_value(tick, yes),
          alarm(1,ticker,_).

:- set_value(tick, yes), alarm(1,ticker,_), loop.
@end example

The clock, @code{ticker}, writes a dot and then checks the flag
@code{tick} to see whether it can continue ticking. If so, it calls
itself again. Note that there is no guarantee that the each dot
corresponds a second: for instance, if the YAP is waiting for
user input, @code{ticker} will wait until the user types the entry in.

The next example shows how @code{alarm/3} can be used to guarantee that
a certain procedure does not take longer than a certain amount of time:

@example
loop :- loop.

:-   catch((alarm(10, throw(ball), _),loop),
        ball,
        format('Quota exhausted.~n',[])).
@end example
In this case after @code{10} seconds our @code{loop} is interrupted,
@code{ball} is thrown,  and the handler writes @code{Quota exhausted}.
Execution then continues from the handler.

Note that in this case @code{loop/0} always executes until the alarm is
sent. Often, the code you are executing succeeds or fails before the
alarm is actually delivered. In this case, you probably want to disable
the alarm when you leave the procedure. The next procedure does exactly so:
@example
once_with_alarm(Time,Goal,DoOnAlarm) :-
   catch(execute_once_with_alarm(Time, Goal), alarm, DoOnAlarm).

execute_once_with_alarm(Time, Goal) :-
        alarm(Time, alarm, _),
        ( call(Goal) -> alarm(0, alarm, _) ; alarm(0, alarm, _), fail).
@end example

The procedure @code{once_with_alarm/3} has three arguments:
the @var{Time} to wait before the alarm is
sent; the @var{Goal} to execute; and the goal @var{DoOnAlarm} to execute
if the alarm is sent. It uses @code{catch/3} to handle the case the
@code{alarm} is sent. Then it starts the alarm, calls the goal
@var{Goal}, and disables the alarm on success or failure.

@item on_signal(+@var{Signal},?@var{OldAction},+@var{Callable})
@findex on_signal/3
@snindex on_signal/3
@cnindex on_signal/3
Set the interrupt handler for soft interrupt @var{Signal} to be
@var{Callable}. @var{OldAction} is unified with the previous handler.

Only a subset of the software interrupts (signals) can have their
handlers manipulated through @code{on_signal/3}.
Their POSIX names, YAP names and default behavior is given below.
The "YAP name" of the signal is the atom that is associated with
each signal, and should be used as the first argument to
@code{on_signal/3}. It is chosen so that it matches the signal's POSIX
name.

@code{on_signal/3} succeeds, unless when called with an invalid
signal name or one that is not supported on this platform. No checks
are made on the handler provided by the user.

@table @code
@item sig_up (Hangup)
  SIGHUP in Unix/Linux; Reconsult the initialization files
  ~/.yaprc, ~/.prologrc and ~/prolog.ini.
@item sig_usr1 and sig_usr2 (User signals)
  SIGUSR1 and SIGUSR2 in Unix/Linux; Print a message and halt.
@end table

A special case is made, where if @var{Callable} is bound to
@code{default}, then the default handler is restored for that signal.

A call in the form @code{on_signal(@var{S},@var{H},@var{H})} can be used
to retrieve a signal's current handler without changing it.

It must be noted that although a signal can be received at all times,
the handler is not executed while YAP is waiting for a query at the
prompt. The signal will be, however, registered and dealt with as soon
as the user makes a query.

Please also note, that neither POSIX Operating Systems nor YAP guarantee
that the order of delivery and handling is going to correspond with the
order of dispatch.

@end table

@node Term Modification, Global Variables, OS, Top
@chapter Term Modification

@cindex updating terms
It is sometimes useful to change the value of instantiated
variables. Although, this is against the spirit of logic programming, it
is sometimes useful. As in other Prolog systems, YAP has
several primitives that allow updating Prolog terms. Note that these
primitives are also backtrackable.

The @code{setarg/3} primitive allows updating any argument of a Prolog
compound terms. The @code{mutable} family of predicates provides
@emph{mutable variables}. They should be used instead of @code{setarg/3},
as they allow the encapsulation of accesses to updatable
variables. Their implementation can also be more efficient for long
deterministic computations.

@table @code
@item setarg(+@var{I},+@var{S},?@var{T})
@findex setarg/3n
@snindex setarg/3n
@cnindex setarg/3n
Set the value of the @var{I}th argument of term @var{S} to term @var{T}. 

@cindex mutable variables
@item create_mutable(+@var{D},-@var{M})
@findex create_mutable/2
@syindex create_mutable/2
@cnindex create_mutable/2
Create new mutable variable @var{M} with initial value @var{D}.

@item is_mutable(?@var{D})
@findex is_mutable/1
@syindex is_mutable/1
@cnindex is_mutable/1
Holds if @var{D} is a mutable term.

@item get_mutable(?@var{D},+@var{M})
@findex get_mutable/2
@syindex get_mutable/2
@cnindex get_mutable/2
Unify the current value of mutable term @var{M} with term @var{D}.

@item update_mutable(+@var{D},+@var{M})
@findex update_mutable/2
@syindex update_mutable/2
@cnindex update_mutable/2
Set the current value of mutable term @var{M} to term @var{D}.
@end table

@node Global Variables, Profiling, Term Modification, Top
@chapter Global Variables

@cindex global variables

Global variables are associations between names (atoms) and
terms. They differ in various ways from storing information using
@code{assert/1} or @code{recorda/3}.

@itemize @bullet
@item The value lives on the Prolog (global) stack. This implies that
lookup time is independent from the size of the term. This is
particularly interesting for large data structures such as parsed XML
documents or the CHR global constraint store. 

@item They support both global assignment using @code{nb_setval/2} and
backtrackable assignment using @code{b_setval/2}.

@item Only one value (which can be an arbitrary complex Prolog term)
can be associated to a variable at a time. 

@item Their value cannot be shared among threads. Each thread has its own
namespace and values for global variables.
@end itemize

Currently global variables are scoped globally. We may consider module
scoping in future versions.   Both @code{b_setval/2} and
@code{nb_setval/2} implicitly create a variable if the referenced name
does not already refer to a variable.

Global variables may be initialised from directives to make them
available during the program lifetime, but some considerations are
necessary for saved-states and threads. Saved-states to not store
global variables, which implies they have to be declared with
@code{initialization/1} to recreate them after loading the saved
state. Each thread has its own set of global variables, starting with
an empty set. Using @code{thread_initialization/1} to define a global
variable it will be defined, restored after reloading a saved state
and created in all threads that are created after the
registration. Finally, global variables can be initialised using the
exception hook called @code{exception/3}. The latter technique is used
by CHR.

@table @code
@item b_setval(+@var{Name}, +@var{Value}) 
@findex b_setval/2
@snindex b_setval/2
@cnindex b_setval/2
Associate the term @var{Value} with the atom @var{Name} or replaces
the currently associated value with @var{Value}. If @var{Name} does
not refer to an existing global variable a variable with initial value
[] is created (the empty list). On backtracking the assignment is
reversed. 

@item b_getval(+@var{Name}, -@var{Value}) 
@findex b_getval/2
@snindex b_getval/2
@cnindex b_getval/2
Get the value associated with the global variable @var{Name} and unify
it with @var{Value}. Note that this unification may further
instantiate the value of the global variable. If this is undesirable
the normal precautions (double negation or @code{copy_term/2}) must be
taken. The @code{b_getval/2} predicate generates errors if @var{Name} is not
an atom or the requested variable does not exist. 

Notice that for compatibility with other systems @var{Name} @emph{must} be already associated with a term: otherwise the system will generate an error.

@item nb_setval(+@var{Name}, +@var{Value}) 
@findex nb_setval/2
@snindex nb_setval/2
@cnindex nb_setval/2
Associates a copy of @var{Value} created with @code{duplicate_term/2} with
the atom @var{Name}. Note that this can be used to set an initial
value other than @code{[]} prior to backtrackable assignment.

@item nb_getval(+@var{Name}, -@var{Value}) 
@findex nb_getval/2
@snindex nb_getval/2
@cnindex nb_getval/2
The @code{nb_getval/2} predicate is a synonym for @code{b_getval/2},
introduced for compatibility and symmetry. As most scenarios will use
a particular global variable either using non-backtrackable or
backtrackable assignment, using @code{nb_getval/2} can be used to
document that the variable is used non-backtrackable.

@item nb_linkval(+@var{Name}, +@var{Value}) 
@findex nb_linkval/2
@snindex nb_linkval/2
@cnindex nb_linkval/2
Associates the term @var{Value} with the atom @var{Name} without
copying it. This is a fast special-purpose variation of @code{nb_setval/2}
intended for expert users only because the semantics on backtracking
to a point before creating the link are poorly defined for compound
terms. The principal term is always left untouched, but backtracking
behaviour on arguments is undone if the original assignment was
trailed and left alone otherwise, which implies that the history that
created the term affects the behaviour on backtracking. Please
consider the following example:

@example
demo_nb_linkval :-
        T = nice(N),
        (   N = world,
            nb_linkval(myvar, T),
            fail
        ;   nb_getval(myvar, V),
            writeln(V)
        ).
@end example

@item nb_set_shared_val(+@var{Name}, +@var{Value}) 
@findex nb_set_shared_val/2
@snindex nb_set_shared_val/2
@cnindex nb_set_shared_val/2
Associates the term @var{Value} with the atom @var{Name}, but sharing
non-backtrackable terms. This may be useful if you want to rewrite a
global variable so that the new copy will survive backtracking, but
you want to share structure with the previous term.

The next example shows the differences between the three built-ins:
@example
?- nb_setval(a,a(_)),nb_getval(a,A),nb_setval(b,t(C,A)),nb_getval(b,B).
A = a(_A),
B = t(_B,a(_C)) ? 

?- nb_setval(a,a(_)),nb_getval(a,A),nb_set_shared_val(b,t(C,A)),nb_getval(b,B).

?- nb_setval(a,a(_)),nb_getval(a,A),nb_linkval(b,t(C,A)),nb_getval(b,B).
A = a(_A),
B = t(C,a(_A)) ?
@end example

@item nb_setarg(+@{Arg], +@var{Term}, +@var{Value})
@findex nb_setarg/3
@snindex nb_setarg/3
@cnindex nb_setarg/3

Assigns the @var{Arg}-th argument of the compound term @var{Term} with
the given @var{Value} as setarg/3, but on backtracking the assignment
is not reversed. If @var{Term} is not atomic, it is duplicated using
duplicate_term/2. This predicate uses the same technique as
@code{nb_setval/2}. We therefore refer to the description of
@code{nb_setval/2} for details on non-backtrackable assignment of
terms. This predicate is compatible to GNU-Prolog
@code{setarg(A,T,V,false)}, removing the type-restriction on
@var{Value}. See also @code{nb_linkarg/3}. Below is an example for
counting the number of solutions of a goal. Note that this
implementation is thread-safe, reentrant and capable of handling
exceptions. Realising these features with a traditional implementation
based on assert/retract or flag/3 is much more complicated.

@example
    succeeds_n_times(Goal, Times) :-
            Counter = counter(0),
            (   Goal,
                arg(1, Counter, N0),
                N is N0 + 1,
                nb_setarg(1, Counter, N),
                fail
            ;   arg(1, Counter, Times)
            ).
@end example

@item nb_set_shared_arg(+@var{Arg}, +@var{Term}, +@var{Value}) 
@findex nb_set_shared_arg/3
@snindex nb_set_shared_arg/3
@cnindex nb_set_shared_arg/3

As @code{nb_setarg/3}, but like @code{nb_linkval/2} it does not
duplicate the global sub-terms in @var{Value}. Use with extreme care
and consult the documentation of @code{nb_linkval/2} before use.

@item nb_linkarg(+@var{Arg}, +@var{Term}, +@var{Value}) 
@findex nb_linkarg/3
@snindex nb_lnkarg/3
@cnindex nb_linkarg/3

As @code{nb_setarg/3}, but like @code{nb_linkval/2} it does not
duplicate @var{Value}. Use with extreme care and consult the
documentation of @code{nb_linkval/2} before use.


@item nb_current(?@var{Name}, ?@var{Value}) 
@findex nb_current/2
@snindex nb_current/2
@cnindex nb_current/2
Enumerate all defined variables with their value. The order of
enumeration is undefined. 

@item nb_delete(+@var{Name}) 
@findex nb_delete/2
@snindex nb_delete/2
@cnindex nb_delete/2
Delete the named global variable. 
@end table

Global variables have been introduced by various Prolog
implementations recently. We follow the implementation of them in
SWI-Prolog, itself based on hProlog by Bart Demoen.

GNU-Prolog provides a rich set of global variables, including
arrays. Arrays can be implemented easily in YAP and SWI-Prolog using
@code{functor/3} and @code{setarg/3} due to the unrestricted arity of
compound terms.


@node Profiling, Call Counting, Global Variables, Top
@chapter Profiling Prolog Programs

@cindex profiling

YAP includes two profilers. The count profiler keeps information on the
number of times a predicate was called. This information can be used to
detect what are the most commonly called predicates in the program.  The
count profiler can be compiled by setting YAP's flag @code{profiling}
to @code{on}. The time-profiler is a @code{gprof} profiler, and counts
how many ticks are being spent on specific predicates, or on other
system functions such as internal data-base accesses or garbage collects.

The YAP profiling sub-system is currently under
development. Functionality for this sub-system will increase with newer
implementation.

@section The Count Profiler

@strong{Notes:}

The count profiler works by incrementing counters at procedure entry or
backtracking. It provides exact information:

@itemize @bullet
@item Profiling works for both static and dynamic predicates.
@item Currently only information on entries and retries to a predicate
are maintained. This may change in the future.
@item As an example, the following user-level program gives a list of
the most often called procedures in a program. The procedure
@code{list_profile} shows all procedures, irrespective of module, and
the procedure @code{list_profile/1} shows the procedures being used in
a specific module.
@example
list_profile :-
        % get number of calls for each profiled procedure
        setof(D-[M:P|D1],(current_module(M),profile_data(M:P,calls,D),profile_data(M:P,retries,D1)),LP),
        % output so that the most often called
        % predicates will come last:
        write_profile_data(LP).

list_profile(Module) :-
        % get number of calls for each profiled procedure
        setof(D-[Module:P|D1],(profile_data(Module:P,calls,D),profile_data(Module:P,retries,D1)),LP),
        % output so that the most often called
        % predicates will come last:
        write_profile_data(LP).

write_profile_data([]).
write_profile_data([D-[M:P|R]|SLP]) :-
        % swap the two calls if you want the most often
        %  called predicates first.
        format('~a:~w: ~32+~t~d~12+~t~d~12+~n', [M,P,D,R]),
        write_profile_data(SLP).
@end example
@end itemize

These are  the current predicates to access and clear profiling data:

@table @code
@item profile_data(?@var{Na/Ar}, ?@var{Parameter}, -@var{Data})
@findex profile_data/3
@snindex profile_data/3
@cnindex profile_data/3
Give current profile data on @var{Parameter} for a predicate described
by the predicate indicator @var{Na/Ar}. If any of @var{Na/Ar} or
@var{Parameter} are unbound, backtrack through all profiled predicates
or stored parameters. Current parameters are:

@table @code
@item calls
Number of times a procedure was called.

@item retries
 Number of times a call to the procedure was backtracked to and retried.
@end table

@item profile_reset
@findex profiled_reset/0
@snindex profiled_reset/0
@cnindex profiled_reset/0
Reset all profiling information.

@end table

@section Tick Profiler

The tick profiler works by interrupting the Prolog code every so often
and checking at each point the code was. The profiler must be able to
retrace the state of the abstract machine at every moment. The major
advantage of this approach is that it gives the actual amount of time
being spent per procedure, or whether garbage collection dominates
execution time. The major drawback is that tracking down the state of
the abstract machine may take significant time, and in the worst case
may slow down the whole execution.

The following procedures are available:

@table @code
@item profinit
@findex profinit/0
@snindex profinit/0
@cnindex profinit/0
Initialise the data-structures for the profiler. Unnecessary for
dynamic profiler.

@item profon
@findex profon/0
@snindex profon/0
@cnindex profon/0
Start profiling.

@item profoff
@findex profoff/0
@snindex profoff/0
@cnindex profoff/0
Stop profiling.

@item showprofres
@findex showprofres/0
@snindex showprofres/0
@cnindex showprofres/0
Show profiling info.

@item showprofres(@var{N})
@findex showprofres/1
@snindex showprofres/1
@cnindex showprofres/1
Show profiling info for the top-most @var{N} predicates.

@end table

The @code{showprofres/0} and @code{showprofres/1} predicates call a user-defined multifile hook predicate, @code{user:prolog_predicate_name/2}, that can be used for converting a possibly explicitly-qualified callable term into an atom that will used when printing the profiling information.

@node Call Counting, Arrays, Profiling, Top
@chapter Counting Calls

@cindex Counting Calls
Predicates compiled with YAP's flag @code{call_counting} set to
@code{on} update counters on the numbers of calls and of
retries. Counters are actually decreasing counters, so that they can be
used as timers.  Three counters are available:
@itemize @bullet
@item @code{calls}: number of predicate calls since execution started or since
system was reset; 
@item @code{retries}: number of retries for predicates called since
execution started or since counters were reset;
@item @code{calls_and_retries}: count both on predicate calls and
retries.
@end itemize
These counters can be used to find out how many calls a certain
goal takes to execute. They can also be used as timers.

The code for the call counters piggybacks on the profiling
code. Therefore, activating the call counters also activates the profiling
counters.

These are  the predicates that access and manipulate the call counters:

@table @code
@item call_count_data(-@var{Calls}, -@var{Retries}, -@var{CallsAndRetries})
@findex call_count_data/3
@snindex call_count_data/3
@cnindex call_count_data/3
Give current call count data. The first argument gives the current value
for the @var{Calls} counter, next the @var{Retries} counter, and last
the @var{CallsAndRetries} counter.

@item call_count_reset
@findex call_count_data/0
@snindex call_count_data/0
@cnindex call_count_data/0
Reset call count counters. All timers are also reset.

@item call_count(?@var{CallsMax}, ?@var{RetriesMax}, ?@var{CallsAndRetriesMax})
@findex call_count_data/3
@snindex call_count_data/3
@cnindex call_count_data/3
Set call count counter as timers. YAP will generate an exception
if one of the instantiated call counters decreases to 0. YAP will ignore
unbound arguments:
@itemize @bullet
@item @var{CallsMax}: throw the exception @code{call_counter} when the
counter @code{calls} reaches 0;
@item @var{RetriesMax}: throw the exception @code{retry_counter} when the
counter @code{retries} reaches 0;
@item @var{CallsAndRetriesMax}: throw the exception
@code{call_and_retry_counter} when the counter @code{calls_and_retries}
reaches 0.
@end itemize
@end table

Next, we show a simple example of how to use call counters:
@example
   ?- yap_flag(call_counting,on), [-user]. l :- l. end_of_file. yap_flag(call_counting,off).

yes

yes
   ?- catch((call_count(10000,_,_),l),call_counter,format("limit_exceeded.~n",[])).

limit_exceeded.

yes
@end example
Notice that we first compile the looping predicate @code{l/0} with
@code{call_counting} @code{on}. Next, we @code{catch/3} to handle an
exception when @code{l/0} performs more than 10000 reductions.


@node Arrays, Preds, Call Counting , Top
@chapter Arrays

The YAP system includes experimental support for arrays. The
support is enabled with the option @code{YAP_ARRAYS}.

There are two very distinct forms of arrays in YAP. The
@emph{dynamic arrays} are a different way to access compound terms
created during the execution. Like any other terms, any bindings to
these terms and eventually the terms themselves will be destroyed during
backtracking. Our goal in supporting dynamic arrays is twofold. First,
they provide an alternative to the standard @code{arg/3}
built-in. Second, because dynamic arrays may have name that are globally
visible, a dynamic array can be visible from any point in the
program. In more detail, the clause
@example
g(X) :- array_element(a,2,X).
@end example
will succeed as long as the programmer has used the built-in @t{array/2}
to create an array term with at least 3 elements in the current
environment, and the array was associated with the name @code{a}.  The
element @code{X} is a Prolog term, so one can bind it and any such
bindings will be undone when backtracking. Note that dynamic arrays do
not have a type: each element may be any Prolog term.

The @emph{static arrays} are an extension of the database. They provide
a compact way for manipulating data-structures formed by characters,
integers, or floats imperatively. They can also be used to provide
two-way communication between YAP and external programs through
shared memory.

In order to efficiently manage space elements in a static array must
have a type. Currently, elements of static arrays in YAP should
have one of the following predefined types:

@itemize @bullet
@item  @code{byte}: an 8-bit signed character.
@item  @code{unsigned_byte}: an 8-bit unsigned character.
@item  @code{int}: Prolog integers. Size would be the natural size for
the machine's architecture.
@item  @code{float}: Prolog floating point number. Size would be equivalent
to a double in @code{C}.
@item  @code{atom}: a Prolog atom.
@item  @code{dbref}: an internal database reference.
@item  @code{term}: a generic Prolog term. Note that this will term will
not be stored in the array itself, but instead will be stored in the
Prolog internal database.
@end itemize

Arrays may be @emph{named} or @emph{anonymous}. Most arrays will be
@emph{named}, that is associated with an atom that will be used to find
the array. Anonymous arrays do not have a name, and they are only of
interest if the @code{TERM_EXTENSIONS} compilation flag is enabled. In
this case, the unification and parser are extended to replace
occurrences of Prolog terms of the form @code{X[I]} by run-time calls to
@code{array_element/3}, so that one can use array references instead of
extra calls to @code{arg/3}. As an example:
@example
g(X,Y,Z,I,J) :- X[I] is Y[J]+Z[I].
@end example
should give the same results as:
@example
G(X,Y,Z,I,J) :-
        array_element(X,I,E1),
        array_element(Y,J,E2),  
        array_element(Z,I,E3),  
        E1 is E2+E3.
@end example

Note that the only limitation on array size are the stack size for
dynamic arrays; and, the heap size for static (not memory mapped)
arrays. Memory mapped arrays are limited by available space in the file
system and in the virtual memory space.

The following predicates manipulate arrays:

@table @code

@item array(+@var{Name}, +@var{Size})
@findex array/2
@snindex array/2
@cnindex array/2
Creates a new dynamic array. The @var{Size} must evaluate to an
integer. The @var{Name} may be either an atom (named array) or an
unbound variable (anonymous array).

Dynamic arrays work as standard compound terms, hence space for the
array is recovered automatically on backtracking.

@item static_array(+@var{Name}, +@var{Size}, +@var{Type})
@findex static_array/3
@snindex static_array/3
@cnindex static_array/3
Create a new static array with name @var{Name}. Note that the @var{Name}
must be an atom (named array). The @var{Size} must evaluate to an
integer.  The @var{Type} must be bound to one of types mentioned
previously.

@item reset_static_array(+@var{Name})
@findex reset_static_array/1
@snindex reset_static_array/1
@cnindex reset_static_array/1
Reset static array with name @var{Name} to its initial value.

@item static_array_location(+@var{Name}, -@var{Ptr})
@findex static_array_location/4
@snindex static_array_location/4
@cnindex static_array_location/4
Give the location for  a static array with name
@var{Name}.

@item static_array_properties(?@var{Name}, ?@var{Size}, ?@var{Type})
@findex static_array_properties/3
@snindex static_array_properties/3
@cnindex static_array_properties/3
Show the properties size and type of a static array with name
@var{Name}. Can also be used to enumerate all current
static arrays. 

This built-in will silently fail if the there is no static array with
that name.

@item static_array_to_term(?@var{Name}, ?@var{Term})
@findex static_array_to_term/3
@snindex static_array_to_term/3
@cnindex static_array_to_term/3
Convert a static array with name
@var{Name} to a compound term of name @var{Name}.

This built-in will silently fail if the there is no static array with
that name.

@item mmapped_array(+@var{Name}, +@var{Size}, +@var{Type}, +@var{File})
@findex static_array/3
@snindex static_array/3
@cnindex static_array/3
Similar to @code{static_array/3}, but the array is memory mapped to file
@var{File}. This means that the array is initialized from the file, and
that any changes to the array will also be stored in the file. 

This built-in is only available in operating systems that support the
system call @code{mmap}. Moreover, mmapped arrays do not store generic
terms (type @code{term}).

@item close_static_array(+@var{Name})
@findex close_static_array/1
@snindex close_static_array/1
@cnindex close_static_array/1
Close an existing static array of name @var{Name}. The @var{Name} must
be an atom (named array). Space for the array will be recovered and
further accesses to the array will return an error. 

@item resize_static_array(+@var{Name}, -@var{OldSize}, +@var{NewSize})
@findex resize_static_array/3
@snindex resize_static_array/3
@cnindex resize_static_array/3
Expand or reduce a static array, The @var{Size} must evaluate to an
integer. The @var{Name} must be an atom (named array). The @var{Type}
must be bound to one of @code{int}, @code{dbref}, @code{float} or
@code{atom}.

Note that if the array is a mmapped array the size of the mmapped file
will be actually adjusted to correspond to the size of the array.

@item array_element(+@var{Name}, +@var{Index}, ?@var{Element})
@findex array_element/3
@snindex array_element/3
@cnindex array_element/3
Unify @var{Element} with @var{Name}[@var{Index}]. It works for both
static and dynamic arrays, but it is read-only for static arrays, while
it can be used to unify with an element of a dynamic array.

@item update_array(+@var{Name}, +@var{Index}, ?@var{Value}) 
@findex update_array/3
@snindex update_array/3
@cnindex update_array/3
Attribute value @var{Value} to @var{Name}[@var{Index}]. Type
restrictions must be respected for static arrays. This operation is
available for dynamic arrays if @code{MULTI_ASSIGNMENT_VARIABLES} is
enabled (true by default). Backtracking undoes @var{update_array/3} for
dynamic arrays, but not for static arrays.

Note that @code{update_array/3} actually uses @code{setarg/3} to update
elements of dynamic arrays, and @code{setarg/3} spends an extra cell for
every update. For intensive operations we suggest it may be less
expensive to unify each element of the array with a mutable terms and
to use the operations on mutable terms.

@item add_to_array_element(+@var{Name}, +@var{Index}, , +@var{Number}, ?@var{NewValue}) 
@findex add_to_array_element/4
@snindex add_to_array_element/4
@cnindex add_to_array_element/4
Add @var{Number} @var{Name}[@var{Index}] and unify @var{NewValue} with
the incremented value. Observe that @var{Name}[@var{Index}] must be an
number. If @var{Name} is a static array the type of the array must be
@code{int} or @code{float}. If the type of the array is @code{int} you
only may add integers, if it is @code{float} you may add integers or
floats. If @var{Name} corresponds to a dynamic array the array element
must have been previously bound to a number and @code{Number} can be
any kind of number.

The @code{add_to_array_element/3} built-in actually uses
@code{setarg/3} to update elements of dynamic arrays. For intensive
operations we suggest it may be less expensive to unify each element
of the array with a mutable terms and to use the operations on mutable
terms.

@end table

@node Preds, Misc, Arrays, Top
@chapter Predicate Information

Built-ins that return information on the current predicates and modules:

@table @code
@c ......... begin of 'module' documentation .........
@item current_module(@var{M})
@findex current_module/1
@syindex current_module/1
@cnindex current_module/1
Succeeds if @var{M} are defined modules. A module is defined as soon as some
predicate defined in the module is loaded, as soon as a goal in the
module is called, or as soon as it becomes the current type-in module.

@item current_module(@var{M},@var{F})
@findex current_module/2
@syindex current_module/2
@cnindex current_module/2
Succeeds if @var{M} are current modules associated to the file @var{F}.

@c .......... end of 'module' documentation ..........
@end table

@node Misc, , Preds, Top
@chapter Miscellaneous

@table @code

@item statistics/0
@findex statistics/0
@saindex statistics/0
@cyindex statistics/0
Send to the current user error stream general information on space used and time
spent by the system.
@example
?- statistics.
memory (total)        4784124 bytes
   program space      3055616 bytes:    1392224 in use,      1663392 free
                                                             2228132  max
   stack space        1531904 bytes:        464 in use,      1531440 free
     global stack:                           96 in use,       616684  max
      local stack:                          368 in use,       546208  max
   trail stack         196604 bytes:          8 in use,       196596 free

       0.010 sec. for 5 code, 2 stack, and 1 trail space overflows
       0.130 sec. for 3 garbage collections which collected 421000 bytes
       0.000 sec. for 0 atom garbage collections which collected 0 bytes
       0.880 sec. runtime
       1.020 sec. cputime
      25.055 sec. elapsed time

@end example
The example shows how much memory the system spends. Memory is divided
into Program Space, Stack Space and Trail. In the example we have 3MB
allocated for program spaces, with less than half being actually
used. YAP also shows the maximum amount of heap space having been used
which was over 2MB.

The stack space is divided into two stacks which grow against each
other. We are in the top level so very little stack is being used. On
the other hand, the system did use a lot of global and local stack
during the previous execution (we refer the reader to a WAM tutorial in
order to understand what are the global and local stacks).

YAP also shows information on how many memory overflows and garbage
collections the system executed, and statistics on total execution
time. Cputime includes all running time, runtime excludes garbage
collection and stack overflow time.

@item statistics(?@var{Param},-@var{Info})
@findex statistics/2
@saindex statistics/2
@cnindex statistics/2
Gives statistical information on the system parameter given by first
argument:

@table @code

@item atoms
@findex atoms (statistics/2 option)
@code{[@var{NumberOfAtoms},@var{SpaceUsedBy Atoms}]}
@* 
This gives the total number of atoms @code{NumberOfAtoms} and how much
space they require in bytes, @var{SpaceUsedBy Atoms}.

@item cputime
@findex cputime (statistics/2 option)
@code{[@var{Time since Boot},@var{Time From Last Call to Cputime}]}
@* 
This gives the total cputime in milliseconds spent executing Prolog code,
garbage collection and stack shifts time included.

@item dynamic_code
@findex dynamic_code (statistics/2 option)
@code{[@var{Clause Size},@var{Index Size},@var{Tree Index
Size},@var{Choice Point Instructions
Size},@var{Expansion Nodes Size},@var{Index Switch Size}]}
@*
Size of static code in YAP in bytes: @var{Clause Size}, the number of
bytes allocated for clauses, plus
@var{Index Size}, the number of bytes spent in the indexing code. The
indexing code is divided into main tree, @var{Tree Index
Size}, tables that implement choice-point manipulation, @var{Choice Point Instructions
Size}, tables that cache clauses for future expansion of the index
tree, @var{Expansion Nodes Size}, and 
tables such as hash tables that select according to value,  @var{Index Switch Size}.

@item garbage_collection
@findex garbage_collection (statistics/2 option)
@code{[@var{Number of GCs},@var{Total Global Recovered},@var{Total Time
Spent}]}
@*
Number of garbage collections, amount of space recovered in kbytes, and
total time spent doing garbage collection in milliseconds. More detailed
information is available using @code{yap_flag(gc_trace,verbose)}.

@item global_stack
@findex global_stack (statistics/2 option)
@code{[@var{Global Stack Used},@var{Execution Stack Free}]}
@*
Space in kbytes currently used in the global stack, and space available for
expansion by the local and global stacks.

@item local_stack
@findex local_stack (statistics/2 option)
@code{[@var{Local Stack Used},@var{Execution Stack Free}]}
@*
Space in kbytes currently used in the local stack, and space available for
expansion by the local and global stacks.

@item heap
@findex heap (statistics/2 option)
@code{[@var{Heap Used},@var{Heap Free}]}
@*
Total space in kbytes not recoverable
in backtracking. It includes the program code, internal data base, and,
atom symbol table.

@item program
@findex program (statistics/2 option)
@code{[@var{Program Space Used},@var{Program Space Free}]}
@*
Equivalent to @code{heap}.

@item runtime
@findex runtime (statistics/2 option)
@code{[@var{Time since Boot},@var{Time From Last Call to Runtime}]}
@* 
This gives the total cputime in milliseconds spent executing Prolog
code, not including garbage collections and stack shifts. Note that
until YAP4.1.2 the @code{runtime} statistics would return time spent on
garbage collection and stack shifting.

@item stack_shifts
@findex stack_shifts (statistics/2 option)
@code{[@var{Number of Heap Shifts},@var{Number of Stack
Shifts},@var{Number of Trail Shifts}]}
@*
Number of times YAP had to
expand the heap, the stacks, or the trail. More detailed information is
available using @code{yap_flag(gc_trace,verbose)}.

@item static_code
@findex static_code (statistics/2 option)
@code{[@var{Clause Size},@var{Index Size},@var{Tree Index
Size},@var{Expansion Nodes Size},@var{Index Switch Size}]}
@*
Size of static code in YAP in bytes: @var{Clause Size}, the number of
bytes allocated for clauses, plus
@var{Index Size}, the number of bytes spent in the indexing code. The
indexing code is divided into a main tree, @var{Tree Index
Size}, table that cache clauses for future expansion of the index
tree, @var{Expansion Nodes Size}, and and 
tables such as hash tables that select according to value,  @var{Index Switch Size}.

@item trail
@findex trail (statistics/2 option)
@code{[@var{Trail Used},@var{Trail Free}]}
@*
Space in kbytes currently being used and still available for the trail.

@item walltime
@findex walltime (statistics/2 option)
@code{[@var{Time since Boot},@var{Time From Last Call to Walltime}]}
@* 
This gives the clock time in milliseconds since starting Prolog.

@end table

@item time(:@var{Goal})
@findex time/1
@snindex time/1
@cnindex time/1
Prints the CPU time and the wall time for the execution of @var{Goal}.
Possible choice-points of @var{Goal} are removed. Based on the SWI-Prolog 
definition (minus reporting the number of inferences, which YAP currently
does not support).

@item yap_flag(?@var{Param},?@var{Value})
@findex yap_flag/2
@snindex yap_flag/2
@cnindex yap_flag/2
Set or read system properties for @var{Param}:

@table @code

@item argv
@findex argv (yap_flag/2 option)
@* Read-only flag. It unifies with a list of atoms that gives the
arguments to YAP after @code{--}.

@item agc_margin
@findex agc_margin (yap_flag/2 option)
An integer: if this amount of atoms has been created since the last
atom-garbage collection, perform atom garbage collection at the first
opportunity. Initial value is 10,000. May be changed. A value of 0
(zero) disables atom garbage collection.

@item associate
@findex associate (yap_flag/2 option)
@*
Read-write flag telling a suffix for files associated to Prolog
sources. It is @code{yap} by default.

@item bounded [ISO]
@findex bounded (yap_flag/2 option)
@*
Read-only flag telling whether integers are bounded. The value depends
on whether YAP uses the GMP library or not.

@item  profiling
@findex call_counting (yap_flag/2 option)
@*
If @code{off} (default) do not compile call counting information for
procedures. If @code{on} compile predicates so that they calls and
retries to the predicate may be counted. Profiling data can be read through the
@code{call_count_data/3} built-in.

@item char_conversion [ISO]
@findex  char_conversion (yap_flag/2 option)
@*
Writable flag telling whether a character conversion table is used when
reading terms. The default value for this flag is @code{off} except in
@code{sicstus} and @code{iso} language modes, where it is @code{on}.

@item character_escapes [ISO]
@findex  character_escapes (yap_flag/2 option)
@* Writable flag telling whether a character escapes are enables,
@code{true}, or disabled, @code{false}. The default value for this flag is
@code{on}.

@c You can also use @code{cprolog} mode, which corresponds to @code{off},
@c @code{iso} mode, which corresponds to @code{on}, and @code{sicstus}
@c mode, which corresponds to the mode traditionally used in SICStus
@c Prolog. In this mode back-quoted escape sequences should not close with
@c a backquote and unrecognized escape codes do not result in error.

@item debug [ISO]
@findex debug (yap_flag/2 option)
@*
If @var{Value} is unbound, tell whether debugging is @code{true} or
@code{false}. If @var{Value} is bound to @code{true} enable debugging, and if
it is bound to @code{false} disable debugging.

@item debugger_print_options
@findex debugger_print_options (yap_flag/2 option)
@* 
If bound, set the argument to the @code{write_term/3} options the
debugger uses to write terms. If unbound, show the current options.

@item dialect
@findex dialect (yap_flag/2 option)
@*
Read-only flag that always returns @code{yap}.

@item discontiguous_warnings
@findex discontiguous_warnings (yap_flag/2 option)
@*
If @var{Value} is unbound, tell whether warnings for discontiguous
predicates are @code{on} or
@code{off}. If @var{Value} is bound to @code{on} enable these warnings,
and if it is bound to @code{off} disable them. The default for YAP is
@code{off}, unless we are in @code{sicstus} or @code{iso} mode.

@item  dollar_as_lower_case
@findex dollar_as_lower_case (yap_flag/2 option)
@*
If @code{off} (default)  consider the character '$' a control character, if
@code{on} consider '$' a lower case character.

@item double_quotes [ISO]
@findex double_quotes (yap_flag/2 option)
@*
If @var{Value} is unbound, tell whether a double quoted list of characters
token is converted to a list of atoms, @code{chars}, to a list of integers,
@code{codes}, or to a single atom, @code{atom}. If @var{Value} is bound, set to
the corresponding behavior. The default value is @code{codes}.

@item executable
@findex executable (yap_flag/2 option)
@* Read-only flag. It unifies with an atom that gives the
original program path.

@item  fast
@findex fast (yap_flag/2 option)
@*
If @code{on} allow fast machine code, if @code{off} (default) disable it. Only
available in experimental implementations.

@item  fileerrors
@findex fileerrors (yap_flag/2 option)
@*
If @code{on} @code{fileerrors} is @code{on}, if @code{off} (default)
@code{fileerrors} is disabled.

@item float_format
@findex float_format (yap_flag/2 option)
@* C-library @code{printf()} format specification used by @code{write/1} and
friends to determine how floating point numbers are printed. The
default is @code{%.15g}. The specified value is passed to @code{printf()}
without further checking. For example, if you want less digits
printed, @code{%g} will print all floats using 6 digits instead of the
default 15.

@item  gc
@findex gc (yap_flag/2 option)
@*
If @code{on} allow garbage collection (default), if @code{off} disable it.

@item  gc_margin
@findex gc_margin (yap_flag/2 option)
@*
Set or show the minimum free stack before starting garbage
collection. The default depends on total stack size. 

@item  gc_trace
@findex gc_trace (yap_flag/2 option)
@* If @code{off} (default) do not show information on garbage collection
and stack shifts, if @code{on} inform when a garbage collection or stack
shift happened, if @code{verbose} give detailed information on garbage
collection and stack shifts. Last, if @code{very_verbose} give detailed
information on data-structures found during the garbage collection
process, namely, on choice-points.

@item  generate_debugging_info
@findex generate_debugging_info (yap_flag/2 option)
@* If @code{true} (default) generate debugging information for
procedures, including source mode. If @code{false} predicates no
information is generated, although debugging is still possible, and
source mode is disabled.

@item  host_type
@findex host_type (yap_flag/2 option)
@* Return @code{configure} system information, including the machine-id
for which YAP was compiled and Operating System information. 

@item  index
@findex index (yap_flag/2 option)
@* If @code{on} allow indexing (default), if @code{off} disable it, if
@code{single} allow on first argument only.

@item  index_sub_term_search_depth
@findex index (yap_flag/2 option)
@*
Maximum bound on searching sub-terms for indexing, if @code{0} (default) no bound.

@item  informational_messages
@findex informational_messages (yap_flag/2 option)
@*
If @code{on} allow printing of informational messages, such as the ones
that are printed when consulting. If @code{off} disable printing
these messages. It is @code{on} by default except if YAP is booted with
the @code{-L} flag.

@item integer_rounding_function [ISO]
@findex integer_rounding_function (yap_flag/2 option)
@*
Read-only flag telling the rounding function used for integers. Takes the value
@code{toward_zero} for the current version of YAP.

@item language
@findex language (yap_flag/2 option)
@* 
Choose whether YAP is closer to C-Prolog, @code{cprolog}, iso-prolog,
@code{iso} or SICStus Prolog, @code{sicstus}. The current default is
@code{cprolog}. This flag affects update semantics, leashing mode,
style checking, handling calls to undefined procedures, how directives
are interpreted, when to use dynamic, character escapes, and how files
are consulted.

@item max_arity [ISO]
@findex max_arity (yap_flag/2 option)
@*
Read-only flag telling the maximum arity of a functor. Takes the value
@code{unbounded} for the current version of YAP.

@item max_integer [ISO]
@findex max_integer (yap_flag/2 option)
@*
Read-only flag telling the maximum integer in the
implementation. Depends on machine and Operating System
architecture, and on whether YAP uses the @code{GMP} multi-precision
library. If @code{bounded} is false, requests for @code{max_integer}
will fail.

@item max_tagged_integer 
@findex max_tagged_integer (yap_flag/2 option)
@*
Read-only flag telling the maximum integer we can store as a single
word. Depends on machine and Operating System
architecture. It can be used to find the word size of the current machine.

@item min_integer [ISO]
@findex min_integer (yap_flag/2 option)
@* Read-only flag telling the minimum integer in the
implementation. Depends on machine and Operating System architecture,
and on whether YAP uses the @code{GMP} multi-precision library. If
@code{bounded} is false, requests for @code{min_integer} will fail.

@item min_tagged_integer 
@findex max_tagged_integer (yap_flag/2 option)
@*
Read-only flag telling the minimum integer we can store as a single
word. Depends on machine and Operating System
architecture.

@item n_of_integer_keys_in_bb
@findex n_of_integer_keys_in_bb (yap_flag/2 option)
@*
Read or set the size of the hash table that is used for looking up the
blackboard when the key is an integer.

@item occurs_check
@findex occurs_check (yap_flag/2 option)
@*
Current read-only and set to @code{false}.

@item n_of_integer_keys_in_db
@findex n_of_integer_keys_in_db (yap_flag/2 option)
@*
Read or set the size of the hash table that is used for looking up the
internal data-base when the key is an integer.

@item open_expands_filename
@findex open_expands_filename (yap_flag/2 option)
@*
If @code{true} the @code{open/3} builtin performs filename-expansion
before opening a file (SICStus Prolog like). If @code{false} it does not
(SWI-Prolog like).

@item open_shared_object
@findex open_shared_object (yap_flag/2 option)
@*
If true, @code{open_shared_object/2} and friends are implemented,
providing access to shared libraries (@code{.so} files) or to dynamic link
libraries (@code{.DLL} files).

@item  profiling
@findex profiling (yap_flag/2 option)
@*
If @code{off} (default) do not compile profiling information for
procedures. If @code{on} compile predicates so that they will output
profiling information. Profiling data can be read through the
@code{profile_data/3} built-in.

@item  prompt_alternatives_on(atom, changeable)
@findex  prompt_alternatives_on  (yap_flag/2 option)
SWI-Compatible option, determines prompting for alternatives in the Prolog toplevel. Default is @t{groundness}, YAP prompts for alternatives if and only if the query contains variables. The alternative, default in SWI-Prolog is @t{determinism} which implies the system prompts for alternatives if the goal succeeded while leaving choicepoints.


@item redefine_warnings
@findex discontiguous_warnings (yap_flag/2 option)
@*
If @var{Value} is unbound, tell whether warnings for procedures defined
in several different files are @code{on} or
@code{off}. If @var{Value} is bound to @code{on} enable these warnings,
and if it is bound to @code{off} disable them. The default for YAP is
@code{off}, unless we are in @code{sicstus} or @code{iso} mode.

@item shared_object_search_path
@findex shared_object_search_path (yap_flag/2 option)
Name of the environment variable used by the system to search for shared
objects.

@item shared_object_extension
@findex shared_object_extension (yap_flag/2 option)
Suffix associated with loadable code.

@item single_var_warnings
@findex single_var_warnings (yap_flag/2 option)
@*
If @var{Value} is unbound, tell whether warnings for singleton variables
are @code{on} or @code{off}. If @var{Value} is bound to @code{on} enable
these warnings, and if it is bound to @code{off} disable them. The
default for YAP is @code{off}, unless we are in @code{sicstus} or
@code{iso} mode.

@item strict_iso
@findex strict_iso (yap_flag/2 option)
@*
 If @var{Value} is unbound, tell whether strict ISO compatibility mode
is @code{on} or @code{off}. If @var{Value} is bound to @code{on} set
language mode to @code{iso} and enable strict mode. If @var{Value} is
bound to @code{off} disable strict mode, and keep the current language
mode. The default for YAP is @code{off}.

Under strict ISO Prolog mode all calls to non-ISO built-ins generate an
error. Compilation of clauses that would call non-ISO built-ins will
also generate errors. Pre-processing for grammar rules is also
disabled. Module expansion is still performed.

Arguably, ISO Prolog does not provide all the functionality required
from a modern Prolog system. Moreover, because most Prolog
implementations do not fully implement the standard and because the
standard itself gives the implementor latitude in a few important
questions, such as the unification algorithm and maximum size for
numbers there is no guarantee that programs compliant with this mode
will work the same way in every Prolog and in every platform. We thus
believe this mode is mostly useful when investigating how a program
depends on a Prolog's platform specific features.

@item  stack_dump_on_error
@findex stack_dump_on_error (yap_flag/2 option)
@*
If @code{on} show a stack dump when YAP finds an error. The default is
@code{off}.

@item  syntax_errors
@findex syntax_errors (yap_flag/2 option)
@*
Control action to be taken after syntax errors while executing @code{read/1},
@code{read/2}, or @code{read_term/3}:
@table @code

@item dec10
@*
Report the syntax error and retry reading the term.
 
@item fail
@*
Report the syntax error and fail (default).

@item error
@*
Report the syntax error and generate an error.

@item quiet
@*
Just fail
@end table

@item system_options
@findex system_options (yap_flag/2 option)
@* This read only flag tells which options were used to compile
YAP. Currently it informs whether the system supports @code{big_numbers},
@code{coroutining}, @code{depth_limit}, @code{low_level_tracer},
@code{or-parallelism}, @code{rational_trees}, @code{readline}, @code{tabling},
@code{threads}, or the @code{wam_profiler}.

@item tabling_mode
@* Sets or reads the tabling mode for all tabled predicates. Please
@pxref{Tabling} for the list of options.

@item to_chars_mode
@findex to_chars_modes (yap_flag/2 option)
@* Define whether YAP should follow @code{quintus}-like
semantics for the @code{atom_chars/1} or @code{number_chars/1} built-in,
or whether it should follow the ISO standard (@code{iso} option).

@item toplevel_hook
@findex toplevel_hook (yap_flag/2 option)
@*
+If bound, set the argument to a goal to be executed before entering the
top-level. If unbound show the current goal or @code{true} if none is
presented. Only the first solution is considered and the goal is not
backtracked into.

@item toplevel_print_options
@findex toplevel_print_options (yap_flag/2 option)
@*
+If bound, set the argument to the @code{write_term/3} options used to write
terms from the top-level. If unbound, show the current options.

@item typein_module
@findex typein_module (yap_flag/2 option)
@*
If bound, set the current working or type-in module to the argument,
which must be an atom. If unbound, unify the argument with the current
working module.

@item  unix
@findex unix (yap_flag/2 option)
@* Read-only Boolean flag that unifies with @code{true} if YAP is
running on an Unix system.  Defined if the C-compiler used to compile
this version of YAP either defines @code{__unix__} or @code{unix}.

@item unknown [ISO]
@findex unknown (yap_flag/2 option)
@*
Corresponds to calling the @code{unknown/2} built-in. Possible values 
are @code{error}, @code{fail}, and @code{warning}.

@item update_semantics
@findex update_semantics (yap_flag/2 option)
@*
Define whether YAP should follow @code{immediate} update
semantics, as in C-Prolog (default), @code{logical} update semantics,
as in Quintus Prolog, SICStus Prolog, or in the ISO standard. There is
also an intermediate mode, @code{logical_assert}, where dynamic
procedures follow logical semantics but the internal data base still
follows immediate semantics.

@item user_error
@findex user_error (yap_flag/2 option)
@*
If the second argument is bound to a stream, set @code{user_error} to
this stream. If the second argument is unbound, unify the argument with
the current @code{user_error} stream.

By default, the @code{user_error} stream is set to a stream
corresponding to the Unix @code{stderr} stream.

The next example shows how to use this flag:
@example
   ?- open( '/dev/null', append, Error,
           [alias(mauri_tripa)] ).

Error = '$stream'(3) ? ;

no
   ?- set_prolog_flag(user_error, mauri_tripa).

close(mauri_tripa).

yes
   ?- 
@end example
We execute three commands. First, we open a stream in write mode and
give it an alias, in this case @code{mauri_tripa}. Next, we set
@code{user_error} to the stream via the alias. Note that after we did so
prompts from the system were redirected to the stream
@code{mauri_tripa}. Last, we close the stream. At this point, YAP
automatically redirects the @code{user_error} alias to the original
@code{stderr}.

@item user_flags
@findex user_flags  (yap_flag/2 option)
@*
Define the behaviour of @code{set_prolog_flag/2} if the flag is not known. Values are @code{silent}, @code{warning} and @code{error}. The first two create the flag on-the-fly, with @code{warning} printing a message. The value @code{error} is consistent with ISO: it raises an existence error and does not create the flag. See also @code{create_prolog_flag/3}. The default is@code{error}, and developers are encouraged to use @code{create_prolog_flag/3} to create flags for their library.

@item user_input
@findex user_input (yap_flag/2 option)
@*
If the second argument is bound to a stream, set @code{user_input} to
this stream. If the second argument is unbound, unify the argument with
the current @code{user_input} stream.

By default, the @code{user_input} stream is set to a stream
corresponding to the Unix @code{stdin} stream.

@item user_output
@findex user_output (yap_flag/2 option)
@*
If the second argument is bound to a stream, set @code{user_output} to
this stream. If the second argument is unbound, unify the argument with
the current @code{user_output} stream.

By default, the @code{user_output} stream is set to a stream
corresponding to the Unix @code{stdout} stream.

@item  verbose
@findex verbose (yap_flag/2 option)
@*
If @code{normal} allow printing of informational and banner messages,
such as the ones that are printed when consulting. If @code{silent}
disable printing these messages. It is @code{normal} by default except if
YAP is booted with the @code{-q} or @code{-L} flag.

@item  verbose_load
@findex verbose_load (yap_flag/2 option)
@* If @code{true} allow printing of informational messages when
consulting files. If @code{false} disable printing these messages. It
is @code{normal} by default except if YAP is booted with the @code{-L}
flag.

@item  verbose_load
@findex verbose_load (yap_flag/2 option)
@* If @code{true} allow printing of informational messages when
consulting files. If @code{false} disable printing these messages. It
is @code{normal} by default except if YAP is booted with the @code{-L}
flag.

@item version
@findex version (yap_flag/2 option)
@* Read-only flag that returns an atom with the current version of
YAP.

@item version_data
@findex version_data (yap_flag/2 option)
@* Read-only flag that reads a term of the form
@code{yap}(@var{Major},@var{Minor},@var{Patch},@var{Undefined}), where
@var{Major} is the major version, @var{Minor} is the minor version,
and @var{Patch} is the patch number.

@item  windows
@findex windoes (yap_flag/2 option)
@* 
Read-only boolean flag that unifies with tr @code{true} if YAP is
running on an Windows machine.

@item write_strings
@findex  write_strings (yap_flag/2 option)
@* Writable flag telling whether the system should write lists of
integers that are writable character codes using the list notation. It
is @code{on} if enables or @code{off} if disabled. The default value for
this flag is @code{off}.

@item max_workers
@findex  max_workers (yap_flag/2 option)
@* Read-only flag telling the maximum number of parallel processes.

@item max_threads
@findex  max_threads (yap_flag/2 option)
@* Read-only flag telling the maximum number of Prolog threads that can 
be created.

@end table

@item current_prolog_flag(?@var{Flag},-@var{Value}) [ISO]
@findex current_prolog_flag/2
@snindex current_prolog_flag/2
@cnindex current_prolog_flag/2

Obtain the value for a YAP Prolog flag. Equivalent to calling
@code{yap_flag/2} with the second argument unbound, and unifying the
returned second argument with @var{Value}.

@item prolog_flag(?@var{Flag},-@var{OldValue},+@var{NewValue})
@findex prolog_flag/3
@syindex prolog_flag/3
@cnindex prolog_flag/3

Obtain the value for a YAP Prolog flag and then set it to a new
value. Equivalent to first calling @code{current_prolog_flag/2} with the
second argument @var{OldValue} unbound and then calling
@code{set_prolog_flag/2} with the third argument @var{NewValue}.

@item set_prolog_flag(+@var{Flag},+@var{Value}) [ISO]
@findex set_prolog_flag/2
@snindex set_prolog_flag/2
@cnindex set_prolog_flag/2

Set the value for YAP Prolog flag @code{Flag}. Equivalent to
calling @code{yap_flag/2} with both arguments bound.


@item create_prolog_flag(+@var{Flag},+@var{Value},+@var{Options})
@findex create_prolog_flag/2
@snindex create_prolog_flag/2
@cnindex create_prolog_flag/2

Create a new YAP Prolog flag. @var{Options} include @code{type(+Type)} and @code{access(+Access)} with @var{Access}
one of @code{read_only} or @code{read_write} and @var{Type} one of @code{boolean}, @code{integer}, @code{float}, @code{atom}
and @code{term} (that is, no type).

@item op(+@var{P},+@var{T},+@var{A}) [ISO]
@findex op/3
@syindex op/3
@cyindex op/3
Defines the operator @var{A} or the list of operators @var{A} with type
@var{T} (which must be one of @code{xfx}, @code{xfy},@code{yfx},
@code{xf}, @code{yf}, @code{fx} or @code{fy}) and precedence @var{P}
(see appendix iv for a list of predefined operators).

Note that if there is a preexisting operator with the same name and
type, this operator will be discarded. Also, @code{','} may not be defined
as an operator, and it is not allowed to have the same for an infix and
a postfix operator.

@item current_op(@var{P},@var{T},@var{F}) [ISO]
@findex current_op/3
@syindex current_op/3
@cnindex current_op/3
Defines the relation: @var{P} is a currently defined  operator of type
@var{T} and precedence @var{P}.

@item prompt(-@var{A},+@var{B})
@findex prompt/2
@syindex prompt/2
@cyindex prompt/2
Changes YAP input prompt from @var{A} to @var{B}.

@item initialization
@findex initialization/0
@syindex initialization/0
@cnindex initialization/0
Execute the goals defined by initialization/1. Only the first answer is
considered.

@item prolog_initialization(@var{G})
@findex prolog_initialization/1
@saindex prolog_initialization/1
@cnindex prolog_initialization/1
Add a goal to be executed on system initialization. This is compatible
with SICStus Prolog's @code{initialization/1}.

@item version
@findex version/0
@saindex version/0
@cnindex version/0
Write YAP's boot message. 

@item version(-@var{Message})
@findex version/1
@syindex version/1
@cnindex version/1
Add a message to be written when yap boots or after aborting. It is not
possible to remove messages.

@item prolog_load_context(?@var{Key}, ?@var{Value})
@findex prolog_load_context/2
@syindex prolog_load_context/2
@cnindex prolog_load_context/2
Obtain information on what is going on in the compilation process. The
following keys are available:

@table @code

@item directory
@findex directory (prolog_load_context/2 option)
@* 
Full name for the directory where YAP is currently consulting the
file.

@item file
@findex file (prolog_load_context/2 option)
@*
Full name for the file currently being consulted. Notice that included
filed are ignored.

@item module
@findex module (prolog_load_context/2 option)
@*
Current source module.

@item source (prolog_load_context/2 option)
@findex file (prolog_load_context/2 option)
@*
Full name for the file currently being read in, which may be consulted,
reconsulted, or included.

@item stream
@findex file (prolog_load_context/2 option)
@*
Stream currently being read in.

@item term_position
@findex file (prolog_load_context/2 option)
@*
Stream position at the stream currently being read in. For SWI
compatibility, it is a term of the form
@code{'$stream_position'(0,Line,0,0,0)}.
@end table

@item source_location(?@var{FileName}, ?@var{Line})
@findex source_location/2
@syindex source_location/2
@cnindex source_location/2
SWI-compatible predicate. If the last term has been read from a physical file (i.e., not from the file user or a string), unify File with an absolute path to the file and Line with the line-number in the file. Please use @code{prolog_load_context/2}.

@item source_file(?@var{File})
@findex source_file/1
@syindex source_file/1
@cnindex source_file/1
SWI-compatible predicate. True if @var{File} is a loaded Prolog source file.

@item source_file(?@var{ModuleAndPred},?@var{File})
@findex source_file/2
@syindex source_file/2
@cnindex source_file/2
SWI-compatible predicate. True if the predicate specified by @var{ModuleAndPred} was loaded from file @var{File}, where @var{File} is an absolute path name (see @code{absolute_file_name/2}).



@end table