The builtins are listed here in the order in which they appear in the ISO standard. This is preceded by a table which is in a somewhat alphabetic order.
PI is a predicate indicator, predicate indicator sequence, or predicate indicator list. Each procedure identified by PI is dynamic. The predicates abolish/1, clause/2, asserta/1, assertz/1 and retract/1 may be applied to these predicates without raising a permission_error.
PI is a predicate indicator, predicate indicator sequence, or predicate indicator list. Each procedure identified by PI may be defined by clauses that are contained in more than one Prolog text.
PI is a predicate indicator, predicate indicator sequence, or predicate indicator list. Each procedure identified by PI may be defined by clauses which are not consecutive in the Prolog text.
:- op(Priority, OpSpecifier, Operator).
The arguments Priority, OpSpecifier, and Operator are as the corresponding arguments of the builtin predicate op/3. The effect on the operator table is to be the same.
:- char_conversion(InChar,OutChar).
The arguments InChar and OutChar are as for the builtin predicate char_conversion/2, the effect on the character conversion table is the same.
A live example using this directive.
The goal Goal is to be executed immediately after the Prolog text has been prepared for execution. If there are several such directives the order in which the goals is executed is implementation defined.
The Prolog text identified by PrologText is to be textually included at this point of the current Prolog text.
The Prolog text identified by PrologText must be prepared for execution (exactly once) with the current Prolog text. This directive is idempotent.
:- set_prolog_flag(Flag, Value)
The Prolog flag Flag shall have is value set to Value.
Certain constructions, more or less difficult to achieve in pure Prolog are defined in the standard to be "control constructs".
true is true.
fail is false.
call(G) is true if and only if G represents a goal which is true.
Template call(+callable_term)
Cuts in the argument G of call are local to G.
call/1 may raise an instantiation_error, or a type_error when its argument cannot be converted to a goal.
! is true. All choice ponts between the cut and the parent goal are removed. The effect is commit to use of both the current clause and the substitutions found at the point of the cut.
Ironically, and perhaps somewhat counter intuitively cut can (in the presence of (\+)/1 increase the number of solutions. As the following example (from the book of Deransart, Ed-Dbali and Cervoni) shows:
','(First, Second) is true if and only if First is true and Second is true.
';'(Either, Or) is true iff and either Either or Or is true.
The semantics is the same as If,!, Then.
';'('->'(If, Then), Else) is true iff and only if (1) If is true and Then is true for the first solution of If or (2) If is false and Else is true.
A goal catch(Goal, Catcher, Handler) is true if
The following examples illustrate the use of catch and throw.
See also
further examples of exception handling.
Then the goal:
Succeeds twice,
The goal:
succeeds after writing helloq.
Determines the behaviour of the processor upon attempting to execute a
procedure which does not exist.
Determines the syntax of a double quoted list.
If X and Y are
Not Subject to Occurs check
then X = Y is true iff X and Y are unifiable.
Template '='(?term,?term)
unify_with_occurs_check(X,Y) is true if and only if
X and Y are unifiable.
Template unify_with_occurs_check(?term,?term)
If X and Y are
Not Subject to Occurs check
then X \= Y is true iff X and Y are not unifiable.
Template '\\='(?term,?term)
var(X) is true if and only if X is a variable.
Template var(@term)
atom(X) is true if and only if X is an atom.
Template atom(@term)
integer(X) is true if and only if X is an integer.
Template integer(@term)
float(X) is true if and only if X is a float.
Template float(@term)
atomic(X) is true if and only if X is atomic (that is
an atom, an integer or a float).
Template atomic(@term)
compound(X) is true if and only if X is a compound term,
that is neither atomic nor a variable.
Template compound(@term)
nonvar(X) is true if and only if X is not a variable.
Template nonvar(@term)
number(X) is true if and only if X is an integer or a float.
Template number(@term)
There is an ordering on Prolog terms obtained as follows:
variables term precede floats which term precede
integers which term precede atoms which term
precede compound.
Within each term the ordering is the obvious one except that
Templates
It is the second of these possibilities that explains why in the two
templates for
functor/3
functor(Term
arg(N,Term, Arg) is true if nad only if the Nth argument
of Term is Arg
Template: arg(+integer, +compound_term, ?term)
Note that arg(N, Term, Arg) throws a
domain_error if N is less than zero.
Term =.. List is true if and only if
Templates:
copy_term(X,Y) is true if and only if Y unifies with a term T which is a renamed copy of X.
Template: copy_term(?term, ?term).
'is'(Result, Expression) is true if and only if the value
of evaluating Expression as an expression is Result
Template: is(?term, @evaluable)
If Expression is a variable is/2 throws an instantiation_error
If either argument is a variable the arithmetic comparison functors
throw an instantiation_error
These predicates allow the contents of the database to be
inspected.
clause(Head, Body) is true if and only if
Template: clause(+head, ?callable_term)
Errors:
By backtracking current_predicate(X/Y) finds all the user defined
predicates in the current database.
Template: current_predicate(?predicate_indicator)
Errors: If PI is neither a variable nor a predicate
indicator throws type_error(predicate_indicator, PI).
These predicates allow the database to be altered during the course of
execution. Note however that their effect is subject to the
logical view of the database.
The database is " frozen " at the start of a query.
asserta(Clause) is true.
It has for side effect the addition of the clause H :-B to the
database before all other clauses for the predicate associated to H.
H :- B is determined as follows.
Template: asserta(@clause)
Errors:
assertz(Clause) is true.
It has for side effect the addition of the clause H :-B to the
database after all other clauses for the predicate associated to H.
H :- B is determined as follows.
Template: assertz(@clause)
Errors:
retract(Clause) is true if the database contains at least one
dynamic procedure with a clause Clause which unifies with
Head :- Body determined as follows:
Template: retract(+clause)
Errors:
abolish(Pred) is true. It has for side effect the removal of all
clauses of the predicate indicated by Pred. After abolish/1 the predicate is not found by current_predicate.
Template: abolish(@predicate_indicator)
Errors:
These predicates are convenient for collecting solutions to a given goal.
It should be noted that bagof/3 and setof/3 fail when
there are no solutions to the goal, whereas findall/3 succeeds
setting the collection to empty.
Template: findall(?term, +callable_term, ?list)
If the first argument appears in the last argument it can be instantiated
by findall.
Errors:
On backtracking bagof is resatisfiable with a different instance of W
Template: bagof(?term, +callable_term, ?list)
If the first argument appears in the last argument it can be instantiated
by bagof.
Errors
On backtracking setof is resatisfiable with a different instance of W
Template: setof(?term, +callable_term, ?list)
If the first argument appears in the last argument it can be instantiated
by setof.
Errors
A summary of the I/O predicates is given on a special
page on IO.
These predicates link an external source/sink with a Prolog stream.
Note that the standard does not prescribe the form of a Stream term.
An open stream may also be referred to by a alias
assigned when the stream is opened.
Template: current_input(?stream).
Errors.
Template: current_output(?stream).
Errors.
Template set_input(@stream_or_alias)
Errors
Template set_output(@stream_or_alias)
Errors
open/3 is like open/4 except that no open options
are supplied.
Template: open(@source_sink, @io_mode, -stream, @stream_options)
Errors
close(S_or_a) is like close/2 except that no close
options are supplied.
Template: close(@stream_or_alias, @close_options)
Errors
The predicates at_end_of_stream/0 and
at_end_of_stream/1 are defined as if as follows:
Templates:
Errors
Template:
set_stream_position(@stream_or_alias, @stream_position)
Errors
get_code/2 and get_code/1
Templates:
Errors:
peek_code/2 and peek_code/1 are defined as if
Templates:
Errors:
The predicates put_code/2, put_code/1, nl/1 and nl/0
are defined as if
Templates
Errors:
Template: get_byte(@stream_or_alias, ?in_byte)
Errors:
Template: peek_byte(@stream_or_alias, ?in_byte)
Errors:
Template: put_byte(@stream_or_alias, +byte)
Errors:
The predicates read/1, read/2 and read_term/2 are defined as if:
Template:read_term(@stream_or_alias, ?term, +read_options_list)
Errors:
The predicates write_term/2, write/1, write/2,
writeq/1, writeq/2, write_canonical/1, and write_canonical/2
are defined as if:
Template write(@stream_or_alias, @Term, @write_options_list)
Errors:
op(Priority, Op_Specifier, Operator) is true, with the side effect that
It is forbidden to alter the priority or type of ','.
It is forbidden to have an infix and a postfix operator with the same name,
or two operators with the same class and name.
The initial operator table is given by
Template:op(+integer,+operator_specifier, @atom_or_atom_list)
Errors:
Template:current_op(?integer, ?operator_specifier, ?atom)
Errors:
When the flag char_conversion has the value true, the In_char
will be replaced by Out_char when a term is read using read_term/3.
Template: char_conversion(+character, +character).
Errors:
current_char_conversion(In_char,Out_char) is true if and only if
Template: current_char_conversion(?character, ?character)
Errors:
Template:\+(@callable_term)
Errors:
Template:once(@callable_term)
Errors:
Template: repeat
Errors: None.
Template: atom_length(+atom, ?integer)
Errors:
Templates:
Errors:
Template:
sub_atom(+atom, ?integer, ?integer, ?integer, ?atom)
Errors:
Templates:
Errors:
Templates:
Errors:
Templates:
Errors:
Templates:
Errors:
Templates:
Errors:
Conforming Prolog processors are required to support flags whose value can be set or determined by the following predicates.
Template: set_prolog_flag(+flag, @nonvar)
Errors:
Template:current_prolog_flag(?flag, ?term)
Errors:
These predicates provide means for terminating a Prolog processor.
halt exits the processor and returns to the system that invoked the processor.
Templatehalt.
Errors: None.
halt(X) exits the processor and returns to the system that invoked the processor passing the value of X as a message.
Templatehalt(+int).
Errors:
Errors: It is an
evaluation_error(E) if the value of an expression E is an exceptional value -- float_overflow, int_overflow, underflow, zero_divisor, or undefined
A conforming processor must in addition support the following evaluable functors:
All of these throw
instantiation_error
when any of their arguments are variables. They throw
type_error(number, VX) ( or type_error(integer, VX)
when an argument X evaluates to an expression which is not a number (resp. an integer). In addition exp/1 can throw evaluation_error(float_overflow), or evaluation_error(underflow), and log/1 can throw
evaluation_error(undefined)
error from p.
Prolog Flags
The definition of each flag indicates whether it is changeable or not.
Default Value: Implementation defined
Changeable: No
Changeable: No
Changeable: No
Default value: implementation defined
Changeable: No
Default value: on
Changeable: Yes
Default value: off
Changeable: Yes
Changeable: No
Default value: error
Changeable: Yes
Changeable: Yes
Builtins
Templates and modes are given for each builtin.
Term Unification
Prolog Unification =/2
unify_with_occurs_check/2
(\=)/2 not Prolog Unifiable.
Type Testing
var/1
atom/1
integer/1
float/1
atomic/1
compound/1
nonvar/1
number/1
Term Comparison
'@=<'(@term,@term)
'=='(@term,@term)
'\=='(@term,@term)
'@<'(@term,@term)
'@>'(@term,@term)
'@>='(@term,@term)
Term Creation and Decomposition
functor/3
functor(Term, Name, Arity) is true if and only if:
the second parameter is atomic and not an atom.
arg/3
(=../2) -- univ
copy_term/2
Arithmetic Evaluation
Arithmetic Comparison
'=:='/2 Arithmetic Equal
'=\\='/2 Arithmetic Not equal
'<'/2 Arithmetic less than
'=<'/2 Arithmetic less than or equal to
'>'/2 Arithmetic greater than
'>='/2 Arithmetic greater than or equal to
Templates:
'=:='(@evaluable, @evaluable)
'=\\='(@evaluable, @evaluable)
'<'(@evaluable, @evaluable)
'=<'(@evaluable, @evaluable)
'>'(@evaluable, @evaluable)
'>='(@evaluable, @evaluable)
Clause Retrieval and Information
clause/2
current_predicate/1
current_predicate(PI) is true if and only if
PI is a predicate indicator for one of the user-defined
procedures in the database.
Clause Creation and Destruction
asserta/1
assertz/1
retract/1
As a side effect the clause is removed from the database.
A Predicate all of whose clauses have been removed from the database
by a sequence or retracts is still found by current_predicate
abolish/1
All Solutions
findall/3
findall(Template, Goal, Instances) is true if and only if
Instances unifies with the list of values to which a variable
X not occurring in Template or Goal
would be instantiated by successive re-executions of
call(Goal), X = Template
after systematic replacement of all variables in X by new
variables.
bagof/3
bagof(Template, Goal, Instances) is true if Instances is a
non-empty list of all terms such that each
unifies with Template for a
fixed instance W of the variables of Goal that are free
with respect to Template. The ordering of the elements of
Instances is the order in which the solutions are found.
setof/3
setof(Template, Goal, Instances) is true if Instances is a
sorted
non-empty list of all terms such that each
unifies with Template for a
fixed instance W of the variables of Goal that are free
with respect to Template.
Input and Output
Stream Selection and Control
current_input/1
current_input(Stream) is true if the stream term Stream
identifies the current input stream.
current_output/1
current_output(Stream) is true if the stream term Stream
identifies the current output stream.
set_input/1
set_input(Stream_or_Alias) is true. As a side effect
sets the current input to the Stream identified by Stream_or_Alias
set_output/1
set_output(Stream_or_Alias) is true. As a side effect
sets the current output to the Stream identified by Stream_or_Alias
Opening a Stream: open/4, open/3
open(Source_Sink, Mode, Stream, Options) is true, and has for side
effect the opening of Source/sink Source_Sink in mode Mode, the term Stream is a implementation
dependent term serving to identify the stream associated to the source/sink by the invocation of open.
Options is a list of open options
with which the stream is opened.
Closing a stream: close/1 and close/2
close(S_or_a, Options) is true, with side effect that it closes
the stream associated to S_or_a. The Options argument determines the close options for the operation.
stream_property/2, at_end_of_stream/1, at_end_of_stream/0
stream_property(stream, Property is true if and only if the stream associated with the stream-term Stream has the stream property Property. On backtracking all properties of all open streams are discovered.
stream_property(S, end_of_stream(E)),
!,
(E = at; E = past)
stream_property(S, alias(S_or_a))
;
S = S_or_a
),
stream_property(S, end_of_stream(E)),
!,
(E = at; E = past)
stream_property(?stream,?property)
at_end_of_stream
at_end_of_stream(@stream_or_alias)
set_stream_position/2
set_stream_position(S_or_a, Position) is true, with the side effect
of setting the stream_position to
Position. Normally, Position will have been obtained via the position/1 property of the stream.
Character Input Output
These predicates allow a single character or code to be input
from or output to a text stream.
get_char/2, get_char/1
get_code/2, get_code/1
get_char(S_or_a,Char) is true if and only if
Char unifies with the next character to be input from the target
stream identified by S_or_a, the character is input. get_char(Char) applies to the
current input stream.
get_char(S,Char),
(Char = end_of_file ->
Code = -1
;
char_code(Char, Code)
).
(Char = end_of_file ->
Code = -1
;
char_code(Char, Code)
).
get_char(?in_character)
get_char(@stream_or_alias, ?in_character)
get_code(?in_character_code)
get_code(@stream_or_alias, ?in_character_code)
peek_char/2, peek_char/1
peek_code/2, peek_code/1
peek_char(S_or_a,Char) is true if and only if
Char unifies with the next character that would be input from the target
stream identified by S_or_a, the character is not input. peek_char(Char) applies to the
current input stream.
peek_char(S,Char),
(Char = end_of_file ->
Code = -1
;
char_code(Char, Code)
).
(Char = end_of_file ->
Code = -1
;
char_code(Char, Code)
).
peek_char(?in_character)
peek_char(@stream_or_alias, ?in_character)
peek_code(?in_character_code)
peek_code(@stream_or_alias, ?in_character_code)
put_char/2, put_char/1, put_code/2, put_code/1, nl/0,nl/1
put_char(S_or_a, Char) is true, with the side effect that Char is output to the stream associated with S_or_a.
put_char(Char) applies to the current output stream.
char_code(Char, Code),
put_char(S, Char).
put_char(S, Char).
put_char(S, '\n').
put_char(+character)
put_char(@stream_or_alias, +character)
put_code(+character_code)
put_code(@stream_or_alias, +character_code)
nl
nl(@stream_or_alias)
Reading from Binary streams
These builtin predicates enable a single byte to be input from or output to
a binary stream.
get_byte/2, get_byte/1
get_byte(S_or_a,Byte) is true if and only if
Byte unifies with the next byte to be input from the target
stream identified by S_or_a, the byte is input. get_byte(Byte) applies to the
current input stream.
peek_byte/2, peek_byte/1
peek_byte(S_or_a,Byte) is true if and only if
Byte unifies with the next byte to be input from the target
stream identified by S_or_a, the byte is not input. peek_byte(Byte) applies to the
current input stream.
put_byte/2, put_byte/1
put_byte(S_or_a, Byte) is true, with the side effect that Byte is output to the stream associated with S_or_a.
put_byte(Byte) applies to the current output stream.
Term Input and Output
These predicates enable a Prolog term to input from or output to a
text stream. The syntax of such terms is affected by the operator table, the value of certain Prolog flags
and whether or not
character conversion is in effect.
read_term/2, read_term/3, read/1, read/2
read_term(S_or_a, Term, Options) is true if and only if Term
unifies with T where T. is a read-term which has been
constructed by inputting and parsing characters from the target stream.
The argument Options determines the
value of the read options in effect for the read.
read_term(S, Term, Options).
read_term(S, Term, []).
Writing terms
write_term/3, write_term/2, write/1, write/2,
writeq/1, writeq/2, write_canonical/1, write_canonical/2
write_term(S_or_a, Term, Options) is true, with for side effect
the output of Term to the target stream according to the operator table and the write-options.
write_term(S, Term, Options).
write_term(S, Term, [numbervars(true)]).
write_term(S, Term, [quoted(true),numbervars(true)]).
write_term(S, Term, [quoted(true),ignore_ops(true)]).
op/3 and current_op/3
These predicates allow the operator table to be altered or inspected.
Specifier Type Associativity
fx prefix no
fy prefix yes
xf postfix no
yf postfix yes
xfx infix no
yfx infix left
xfy infix right
Priority Specifier Operator(s)
1200 xfx :- -->
1200 fx :- ?-
1100 xfy ;
1050 xfy ->
1000 xfy ','
900 fy \+
700 xfx = \=
700 xfx == \== @< @=< @> @>=
700 xfx =..
700 xfx is =:= =\= < =< > >=
500 yfx + - /\ \/
400 yfx * / // rem mod << >>
200 xfx **
200 xfy ^
200 fy - \
current_op/3
current_op(Priority, Op_specifier, Operator) is true if
and only if Operator is an operator with properties given by Op_specifier and Priority
char_conversion/2 and current_char_conversion/2
char_conversion(In_char, Out_char) is true, with the side effect of adding the pair (In_char, Out_char) to the character conversion table if In_char is not equal to Out_char and removing any pair
(In_char, _) from the table if In_char is equal to
Out_char
.
Logic and Control
(\+)/1 - not provable
\+(Term) is true iff and only if call(Term) is false.
once/1
once(Term) is true. once/1 is not re-executable.
repeat/0
repeat is true. It is defined as if:
Atom Processing
These predicates allow atomic terms to be processed as a string of characters or codes.
atom_length/2
atom_length(Atom, Length) is true if and only if the integer
Length equals the number of characters in the name of the atom Atom.
atom_concat/3
atom_concat(Start, End, Whole) is true if and only if Whole
is the atom obtained by concatenating the characters of End to those of First. If Whole is instantiated then all decompositions of Whole can be obtained by back-tracking.
atom_concat(?atom, ?atom +atom)
atom-concat(+atom, +atom, -atom)
sub_atom/5
sub_atom(Atom, Before, Length, After, Sub_atom) is true
if and only if Sub_atom is the sub atomof Atom
of length Length that appears
with Before characters preceding it and After characters
following. It is re-executable.
atom_chars
atom_chars(Atom, List) succeeds if and only if List is a list whose elements are the one character atoms that in order make up Atom.
atom_chars(+atom, ?character_list)
atom_chars(-atom, +character_list)
atom_codes/2
atom_codes(Atom, List) succeeds if and only if List is a list whose elements are the character codes that in order correspond to the characters that make up Atom.
atom_codes(+atom, ?character_code_list)
atom_codes(-atom, +character_code_list)
char_code/2
char_code(Char, Code) succeeds if and only if Code is the
character code that corresponds to the character Char.
char_code(+character, ?character_code)
char_code(-character, +character_code)
number_chars/2
number_chars(Number, List) succeeds if and only if List is a list whose elements are the one character atoms that in order make up Number.
number_chars(+number, ?character_list)
number_chars(-number, +character_list)
number_codes/2
number_codes(Number, CodeList) succeeds if and only if CodeList is a list whose elements are the codes for the one character atoms that in order make up Number.
number_codes(+number, ?character_list)
number_codes(-number, +character_list)
Implementation defined hooks
set_prolog_flag/2
set_prolog_flag(Flag, Value) sets the Prolog flag Flag
to the value Value. The goal either succeeds or raises an exception.
current_prolog_flag/2
current_prolog_flag(Flag,Value) is true if and only if Flag is a supported flag and Value is its value. On backtracking the values of all supported flags can be determined.
halt/0 and halt/1
Evaluable Functors
A conforming processor is required to support the arithmetic operations specified by the following tables. They conform to the ISO/IEC 10967-1 Language Independent Arithmetic standard.
Types used for the signatures
Functor Signature Operation
(+)/2 I x I --> I Addition
(+)/2 F x F --> F Addition
(+)/2 F x I --> F Addition
(+)/2 I x F --> F Addition
(-)/2 I x I --> I Subtraction
(-)/2 F x F --> F Subtraction
(-)/2 F x I --> F Subtraction
(-)/2 I x F --> F Subtraction
(*)/2 I x I --> I Multiplication
(*)/2 F x F --> F Multiplication
(*)/2 F x I --> F Multiplication
(*)/2 I x F --> F Multiplication
(//)/2 I x I --> I Integer Division
(/)/2 I x I --> F Division
(/)/2 F x F --> F Division
(/)/2 F x I --> F Division
(/)/2 I x F --> F Division
(rem)/2 I x I --> I Remainder
(mod)/2 I x I --> I Modulus
(-)/1 I --> I Negation
(-)/1 F --> F Negation
(abs)/1 I --> I Absolute Value
(abs)/1 F --> F Absolute Value
(sign)/1 I --> I Sign
(sign)/1 F --> F SIGN
(float_integer_part)/1 F --> I integer part
(float_fractional_part)/1 F --> F
fractional part
(float)/1 I --> F float coercion.
(float)/1 F --> F float coercion.
(floor)/1 F --> I floor.
(truncate)/1 F --> I truncate.
(round)/1 F --> I round.
(ceiling)/1 F --> I ceiling.
Other arithmetic and Bitwise functors
Functor Template(s) Name
(**)/2
'**'(int-exp, int-exp) = float
'**'(float-exp, int-exp) = float
'**'(int-exp, float-exp) = float
'**'(float-exp, float-exp) = float
Power
sin/1
sin(float_exp) = float
sin(int_exp) = float
sine
cos/1
cos(float_exp) = float
cos(int_exp) = float
cosine
atan/1
atan(float_exp) = float
atan(int_exp) = float
arc tangent
exp/1
exp(float_exp) = float
exp(int_exp) = float
exponentiation
log/1
log(float_exp) = float
log(int_exp) = float
log
sqrt/1
sqrt(float_exp) = float
sqrt(int_exp) = float
square root
(>>)/2
'>>'(int_exp, int_exp) = integer
bitwise right shift
(<<)/2
'<<'(int_exp, int_exp) = integer
bitwise left shift
(/\)/2
'/\\'(int-exp, int-exp) = integer
bit-wise and
(\/)/2
'\\/'(int-exp, int-exp) = integer
bit-wise or
(\)/1
'\\'(int-exp) = integer
bitwise complement
Return to Home Page of the INRIA ISO Prolog Web
78153 Le Chesnay Cedex
France
Saint Joseph's University
Philadelphia PA 19131
USA