ISO Builtin Predicate Set

In the examples below, assume the database contains 

?- dynamic(test/1).
?- public(test/2).

test(1).
test(1).	% Note that this is asserted twice
test(2) :- atom(a).
test(3).

test(a, b).
test(a, c).

Also, assume that the standard input stream will yield the following when read (where <space> stands for a single space). 

<space>a(b, C).
/* This is a comment */ abc.

Also, assume that there exists a text input stream with alias textin, a text output stream with alias textout, a binary input stream with alias binaryin, a binary output stream with alias binaryout, and a repositionable binary stream with alias repositionable_binary. Assume that the the first line of textin contains 

<space>x(y, Z).

and that the first byte in binaryin is 42.
 

at_end_of_stream / 0
Prototype: at_end_of_stream
Succeeds if the current input stream is at or past the end of input.
Example: at_end_of_stream - fails.
 
 at_end_of_stream / 1
Prototype: at_end_of_stream(StreamOrAlias)
Succeeds if the stream / stream having alias StreamOrAlias is at or past end of stream.
Example: at_end_of_stream(textin) - fails.
 
 atom_chars / 2
Prototype: atom_chars(Atom, List)
Unifies List with a list of characters corresponding to the name of Atom. One (but not both) of the arguments may be uninstantiated - can either convert an atom to a list of characters or a list of characters to an atom.
Example: atom_chars(abc, L) - instantiates L to [ a, b, c ].
Example: atom_chars(A, [c, b, a]) - instantiates A to cba.
 
 atom_codes / 2
Prototype: atom_codes(Atom, List)
Unifies List with a list of character codes corresponding to the name of Atom. One (but not both) of the arguments may be uninstantiated - can either convert an atom to a list of character codes or a list of character codes to an atom.
Example: atom_codes(abc, L) - instantiates L to [ 97, 98, 99 ]).
Example: atom_codes(A, [99, 98, 97]) - instantiates A to cba.
 
 atom_concat / 3
Prototype: atom_concat(Atom1, Atom2, Atom3)
Unifies the name of Atom3 with the concatenation of the names of Atom1 and Atom2. If Atom1 and Atom2 are instantiated, Atom3 may be uninstantiated. If Atom3 is instantiated, one or both of Atom1 and Atom2 may be uninstantiated.
Example: atom_concat(abc, def, A) - instantiates A to abcdef.
Example: atom_concat(abc, A, abcdef) - instantiated A to def.
Example: atom_concat(A1, A2, abc) - instantiates A1 to '' and A2 to abc. On backtracking, instantiates A1 and A2 to a and bc respectively, then ab and c, then abc and ''.
 
 atom_length / 2
Prototype: atom_length(Atom, Length)
Unifies Length with the number of characters in the name of Atom.
Example: atom_length(abc, N) - instantiates N to 3.
 
 bagof / 3
Prototype: bagof(Template, BagofGoal, List)
Create a bag of occurrences of Template for each way of satisfying the goal contained in BagofGoal then unify the resulting bag with List. BagofGoal may contain variables that are not to be considered when forming the bag. Because List is a bag, the same element may occur more than once. Opaque to cuts in the subgoal.
Example: bagof(X, test(X, Y), L) - instantiates L to [ a, a, ].
Example: bagof(X, Y^test(X, Y), L) - instantiates L to [ a ]. (The specification of Y as a bound variable causes distinct values to be ignored in forming the bag).
 
 catch / 3
Prototype: catch(Goal, Ball, RecoverGoal)
Call Goal and succeed if Goal succeeds. If Goal throws a ball that unifies with Ball, call RecoverGoal instead. If Goal throws a ball that does not unify with Ball, or if RecoverGoal throws a ball, it is propagated instead. Either Goal or RecoverGoal (as appropriate) can be redone. Opaque to cuts occurring in either subgoal.
Example: catch(test(X), error(E, _), write(E)) - instantiates X to 1 initially, and to 1, 2, 3 if redone.
Example: catch(nonexistent, error(E, _), write(E)) - writes error(existence, procedure, nonexistent/0).
 
 char_code / 2
Prototype: char_code(Character, Code)
Unifies Code with the numeric code for Character. One or the other argument (but not both) may be uninstantiated.
Example: char_code(a, C) - instantiates C to 97.
Example: char_code(A, 99) - instantiated A to c.
 
 char_conversion / 2
Prototype: char_conversion(InChar, OutChar)
Causes every occurrence of InChar in unquoted text read subsequently to be replaced by OutChar. Specifying the same character for InChar and OutChar turns off conversion for that character in subsequent reads.
Example: char_conversion(a, b) - causes every occurrence of a in unquoted input to be replaced by b.
 
 close / 1
Prototype: close(StreamOrAlias)
Terminates access to the stream / stream having alias StreamOrAlias.
Example: close(textin) - terminates access to textin.
 
 close / 2
Prototype: close(StreamOrAlias, OptionList)
Terminates access to the stream / stream having alias StreamOrAlias, with the operation being modified by options specified in OptionList. See below.
Example: close(textin, [force(true)]) - terminates access to textin, ignoring any system error that may occur.
 
Possible options: compound / 1
Prototype: compound(Term)
Succeeds if Term is compound.
Example: compound(a(b)) - succeeds.
Example: compound([a, b]) - succeeds.
Example: compound(1) - fails.
Example: compound(A) - fails.
 
 copy_term / 2
Prototype: copy_term(Term, Copy)
Unifies Copy with a copy of Term in which uninstantiated variables are replaced with fresh variables.
Example: copy_term(a(B, C), T) - instantiates T to a fresh copy of a(B, C) - with fresh variables in place of B and C.
 
 current_char_conversion / 2
Prototype: current_char_conversion(InChar, OutChar)
Unifies OutChar with the current conversion for InChar - or fail if no conversion for it is currently in force.
Example: current_char_conversion(a, C) - instantiates C to the current conversion for a, or fails if there is no conversion in force.
 
 current_input / 1
Prototype: current_input(Stream)
Unifies Stream with the current input stream.
Example: current_input(S) - instantiates S to the current input stream - e.g. standard input or the stream most recently set by set_input/1 or see/1.
 
 current_op / 3
Prototype: current_op(P, A, S)
Unifies P with the priority, A the associativity, and S the symbol of a currently defined operator.
Example: current_op(P, A, +) - instantiates P to 500 and A to yfx (assuming standard operator declarations are in force).
Example: current_op(1200, A, S) - instantiates A to xfx and S to :-. On backtracking, instantiates A to fx and S to :-, then A to fx and S to ?-.
 
 current_output / 1
Prototype: current_output(Stream)
Unifies Stream with the current output stream.
Example: current_output(S) - instantiates S to the current output stream - e.g. standard output or the stream most recently set by set_output/1 or tell/1.
 
 current_predicate / 1
Prototype: current_predicate(PredicateIndicatorPattern)
Unifies PredicateIndicatorPattern with the predicate indicator for a user predicate. On backtracking, unifies it with an other pattern. (Builtin predicates are not seen.)
Example: current_predicate(test/A) - instantiates A to 1. On backtracking, instantiates it to 2.
 
 current_prolog_flag / 2
Prototype: current_prolog_flag(Flag, Value)
Unifies Flag and Value with a current flag value. Can be redone on backtracking if Flag is a variable.
Example: current_prolog_flag(debug, V) - unifies V with on or off as the case may be.
Example: current_prolog_flag(F, on) - unifies F, in turn, with the name of each flag whose current setting is on.
Example: current_prolog_flag(F, V) - unifies F and V, in turn, with the name and value of each of the flags supported by the system.
 
 findall / 3
Prototype: findall(Template, Goal, List)
Create a bag of values of Template for each way of satisfying Goal then unify the resulting bag with List. Opaque to cuts in the subgoal.
Example: findall(X, test(X), L) - instantiates L to [ 1, 1, 2, 3 ].
 
 float / 1
Prototype: float(Term)
Succeeds if Term is a real number.
Example: float(1.0) - succeeds.
Example: float(1) - fails.
Example: float(a(b)) - fails.
Example: float(A) - fails.
 
 flush_output / 0
Prototype: flush_output
Forces any pending output to the current output stream.
Example: flush_output - flushes pending output on the current output stream.
 
 flush_output / 1
Prototype: flush_output(StreamOrAlias)
Forces any pending output to the stream / stream having alias StreamOrAlias.
Example: flush_output(textout) - flushes pending output to textout.
 
 get_byte / 1
Prototype: get_byte(Byte)
Reads a byte from the current input stream (which must be a binary stream), and unifies Byte with it. End of file is represented by a value of -1.
Example: get_byte(B) - (Assume that binaryin is the current input stream.) instantiates B to 42.
 
 get_byte / 2
Prototype: get_byte(StreamOrAlias, Byte)
Reads a byte from the binary stream / stream having alias StreamOrAlias, and unifies Byte with it. End of file is represented by a value of -1.
Example: get_byte(binaryin, B) - instantiates B to 42.
 
 get_char / 1
Prototype: get_char(Char)
Reads the first character - including whitespace - from the current input stream and unifies it with Char. End of file is represented by the atom end_of_file.
Example: get_char(C) - instantiates C to ' '.
 
 get_char / 2
Prototype: get_char(StreamOrAlias, Char)
Reads the first character - including whitespace - from the stream / stream having alias StreamOrAlias and unifies it with Char. End of file is represented by by the atom end_of_file.
Example: get_char(textin, C) - instantiates C to ' '.
 
 get_code / 1
Prototype: get_code(Code)
Reads the first character - including whitespace - from the current input stream and unifies its code with Code. End of file is represented by a code of -1.
Example: get_code(C) - instantiates C to 32 (the code for space).
 
 get_code / 2
Prototype: get_code(StreamOrAlias, Code)
Reads the first character - including whitespace - from the stream / stream having alias StreamOrAlias and unifies its code with Code. End of file is represented by a code of -1.
Example: get_code(textin, C) - instantiates C to 32 (the code for space).
 
 -> / 2
Prototype: Condition -> Then
Calls Condition as if by once/1 and, if it succeeds, calls Then; otherwise fails. Then is redoable, but Condition is not. Opaque to cuts ocurring in Condition, but transparent to cuts occurring in Then.
Example: atom(a) -> test(X) - instantiates X to 1, and if redone to 1 again, then 2, then 3.
Example: atom(1) -> test(X) - fails.
 
 -> ; / 3
Prototype: Condition -> Then ; Else
Calls Condition as if by once/1 and, if it succeeds, calls Then; otherwise calls Else. Only one of Then or Else is called, and which ever one is called is is redoable, but Condition is not. Opaque to cuts ocurring in Condition, but transparent to cuts occurring in Then or Else.
Example: atom(a) -> test(X);write(hello). - instantiates X to 1, and if redone to 1 again, then 2, then 3.
Example: atom(1) -> test(X);write(hello). - writes hello.
 
 nl / 1
Prototype: nl(StreamOrAlias)
Writes a newline to the text output stream / stream having alias StreamOrAlias.
Example: nl(textout) - writes a newline to textout.
 
 \+ / 1
Prototype: \+ Goal
Calls Goal as if by once/1. If Goal succeeds, this predicate fails; if Goal fails, this predicate succeeds. Not redoable Opaque to cuts occurring in Goal.
Example: \+ atom(a) - fails.
Example: \+ atom(1) - succeeds.
 
 number / 1
Prototype: number(Term)
Succeeds if Term is a number.
Example: number(1) - succeeds.
Example: number(1.0) - succeeds.
Example: number(a(b)) - fails.
Example: number(A) - fails.
 
 number_chars / 2
Prototype: number_chars(Number, List)
Unifies List with a list of characters corresponding to the printed form of Number. One (but not both) of the arguments may be uninstantiated - can either convert a number to a list of characters or a list of characters to a number.
Example: number_chars(3.14, L) - instantiates L to [ '3', '.', '1', '4' ].
Example: number_chars(N, ['3', '.', '1', '4']) - instantiates N to 3.14.
 
 number_codes / 2
Prototype: number_codes(Number, List)
Unifies List with a list of character codes corresponding to the printed form of Number. One (but not both) of the arguments may be uninstantiated - can either convert a number to a list of character codes or a list of character codes to a number.
Example: number_codes(3.14, L) - instantiates L to [ 51, 46, 49, 52 ].
Example: number_codes(N, [51, 46, 49, 52 ]) - instantiates N to 3.14.
 
 once / 1
Prototype: once(Goal)
Calls Goal, and succeeds if Goal succeeds. During backtracking, Goal cannot be redone. Opaque to cuts in Goal.
Example: once(test(X)) - instantiates X to 1, and cannot be redone.
 
 open / 3
Prototype: open(Path, Mode, Stream)
Unifies Stream (which must initially be a variable) with a newly-created stream connected to a file specified by Path, having mode as specified by Mode. Mode can be read (input), write (output - a new file is always created, replacing any file of the same name, append (append to an existing file if possible).
Example: open('foo/bar', read, S) - instantiates S to a newly opened text input file connected to a file named bar in subdirectory foo of the user's current default directory.
 
 open / 4
Prototype: open(Path, Mode, Stream, OptionList)
Unifies Stream (which must initially be a variable) with a newly-created stream connected to a file specified by Path, having mode as specified by Mode, with the options specified in OptionList. Mode can be any of the values specified for open/3, or read_write or read_append to create an input-output stream (which must be of type(binary)). See below.
Example: open('foo/bar', read, S, [alias(foo)]) - instantiates S to a newly opened text input file connected to a file named bar in subdirectory foo of the user's current default directory. The new stream will have alias foo.
 
Possible options: peek_byte / 1
Prototype: peek_byte(Byte)
Unify Byte with the byte that would be accessed by get_byte/1, without actually extracting the byte from the input stream.
Example: peek_byte(B) - instantiates B to 42.
 
 peek_byte / 2
Prototype: peek_byte(StreamOrAlias, Byte)
Unify Byte with the byte that would be accessed by get_byte/2 on the same stream, without actually extracting the byte from the input stream.
Example: peek_byte(binaryin, B) - instantiates B to 42.
 
 peek_char / 1
Prototype: peek_char(Char)
Unify Char with the character that would be accessed by get_char/1 on the same stream, without actually extracting the character from the input stream.
Example: peek_char(C) - instantiates C to ' '.
 
 peek_char / 2
Prototype: peek_char(StreamOrAlias, Char)
Unify Char with the character that would be accessed by get_char/2 on the same stream, without actually extracting the character from the input stream.
Example: peek_char(textin, C) - instantiates C to ' '.
 
 peek_code / 1
Prototype: peek_code(StreamOrAlias, Code)
Unify Code with the code for the character that would be accessed by get_code/2 on the same stream, without actually extracting the character from the input stream.
Example: peek_code(C) - instantiates C to 32 (the code for space).
 
 peek_code / 2
Prototype: peek_code(StreamOrAlias, Code)
Unify Code with the code for the character that would be accessed by get_code/2 on the same stream, without actually extracting the character from the input stream.
Example: peek_code(textin, C) - instantiates C to 32 (the code for space).
 
 put_byte / 1
Prototype: put_byte(Byte)
Writes Byte to the current output stream (which must be a binary stream).
Example: put_byte(42) - writes A to the current output stream.
 
 put_byte / 2
Prototype: put_byte(StreamOrAlias, Byte)
Writes Byte to the binary stream / stream having alias StreamOrAlias.
Example: put_byte(textout, 42) - writes 42 to textout.
 
 put_char / 1
Prototype: put_char(Char)
Writes Char to the current output stream.
Example: put_char('A') - writes A to the current output stream.
 
 put_char / 2
Prototype: put_char(StreamOrAlias, Char)
Writes Char to the stream / stream having alias StreamOrAlias.
Example: put_char(textout, 'A') - writes A to textout.
 
 put_code / 1
Prototype: put_code(Code)
Writes the character whose ASCII code is Code to the current output stream.
Example: put_code(65) - writes A to the current output stream.
 
 put_code / 2
Prototype: put_code(StreamOrAlias, Code)
Writes the character whose ASCII code is Code to the stream / stream having alias StreamOrAlias.
Example: put_code(textout, 65) - writes A to textout.
 
 read / 2
Prototype: read(StreamOrAlias, Term)
Reads a term (terminated by a period) from the stream / stream having alias StreamOrAlias and unifies it with Term.
Example: read(T) - instantiates T to x(y, _0).
 
 read_term / 2
Prototype: read_term(Term, Options)
Reads a term (terminated by a period) from the current input stream, and then unifies it with Term. Unifies variables specified by Options with the names of variables read. See below.
Example: read_term(T, variables_names(V)) - instantiates T to a(b, _0), and V to [ C = _0 ].
 
Possible options: read_term / 3
Prototype: read_term(StreamOrAlias, Term, Options)
Reads a term (terminated by a period) from the stream / stream having the alias StreamOrAlias, and then unifies it with Term. Unifies variables specified by Options with the names of variables read. See below.
Example: read_term(textin, T, variables_names(V)) - instantiates T to x(y, _0), and V to [ Z = _0 ].
 
Possible options: set_input / 1
Prototype: set_input(StreamOrAlias)
Make the stream / stream having alias StreamOrAlias be the current input stream.
Example: set_input(textin) - makes textin the current input stream.
 
 set_output / 1
Prototype: set_output(StreamOrAlias)
Make the stream / stream having alias StreamOrAlias be the current output stream.
Example: set_output(textout) - makes textin the current output stream.
 
 set_prolog_flag / 2
Prototype: set_prolog_flag(Name, Value)
Set the flag whose name is Name to Value.
Example: set_prolog_flag(debug, on) - set the debug flag to on.
 
 set_stream_position / 2
Prototype: set_stream_position(StreamOrAlias, Position)
Set the current position of the stream / stream having alias StreamOrAlias to be Position, where Position is typically a previous value of the stream's position property.
Example: set_stream_position(repositionable_binary, X) - set the position or repositionable_binary to the value of the (previously instantiated) variable X.
 
 setof / 3
Prototype: setof(Template, BagofGoal, List)
Create a set of occurrences of Template for each way of satisfying the goal contained in BagofGoal then unify the resulting set with List. BagofGoal may contain variables that are not considered when forming the set. Because List is a set, the same element will not occur more than once. Opaque to cuts in thesubgoal.
Example: setof(X, test(X, Y), L) - instantiates L to [ a ].
 
 stream_property / 2
Prototype: stream_property(Stream, Property)
Unifies Stream and Property with a stream / stream property pair. Either or both parameters may be uninstantiated.
Example: stream_property(S, alias(textin)) - instantiates S to the stream whose alias is textin.
 
 sub_atom / 5
Prototype: sub_atom(Atom, Before, Actual, After, SubAtom)
Unifies SubAtom with a substring constructed from the name of Atom, beginning at position Before, Actual characters long and with After characters following it. Any or all of the arguments (except Atom) may be uninstantiated, in which case the predicate may succeed multiple times.
Example: sub_atom(ab, B, Act, Aft, S) - instantiates B to 0, Act to 0, Aft to 2, and S to ''. On backtracking, instantiates these, in turn, to 0, 1, 1, a; 0, 2, 0, ab; 1, 0, 1, ''; 1, 1, 0, b; 2, 0, 0, ''.
 
 @> / 2
Prototype: Term1 @> Term2
Succeeds if Term1 comes after Term2 in term_precedes order.
Example: a(b, c) @>a(b, c) - fails.
Example: a(b, X) @>a(b, c) - fails.
Example: a(b, c) @>a(b, X) - succeeds.
 
 @>= / 2
Prototype: Term1 @>= Term2
Succeeds if Term1 comes after Term2 in term_precedes order, or they are identical.
Example: a(b, c) @>=a(b, c) - succeeds.
Example: a(b, X) @>=a(b, c) - fails.
Example: a(b, c) @>=a(b, X) - succeeds.
 
 @< / 2
Prototype: Term1 @< Term2
Succeeds if Term1 comes before Term2 in term_precedes order.
Example: a(b, c) @ - fails.
Example: a(b, X) @ - succeeds.
Example: a(b, c) @ - fails.
 
 @=< / 2
Prototype: Term1 @=< Term2
Succeeds if Term1 comes before Term2 in term_precedes order, or they are identical.
Example: a(b, c) @= - succeeds.
Example: a(b, X) @= - succeeds.
Example: a(b, c) @= - fails.
 
 throw / 1
Prototype: throw(Ball)
Throw a ball that might be caught by catch/3.
Example: throw(foo) - throws the ball foo.
 
 unify_with_occurs_check / 2
Prototype: unify_with_occurs_check(Term1, Term2)
Unifies Term1 with Term2, unless doing so would result in instantiating a variable to a term which contains it (the occurs check).
Example: unify_with_occurs_check(a(X, c), a(b, Y)) - instantiates X to b and Y to c.
Example: unify_with_occurs_check(a, 1) - fails.
Example: unify_with_occurs_check(X, a(X)) - fails, because X occurs in a(X).
 
 write / 2
Prototype: write(StreamOrAlias, Term)
Writes a printed representation of Term to the stream / stream having alias StreamOrAlias, using operator and list notation as appropriate, but not quotes.
Example: write(textout, 1) - writes 1 to textout.
Example: write(textout, [ 2 + 2, a(b) ] - writes [ 2 + 2, a(b) ] to textout.
Example: write(textout, 'Hello, world') - writes Hello, World (with no quotes) to textout.
 
 write_canonical / 1
Prototype: write_canonical(Term)
Writes Term to the current output stream, without using operator or list notation. Atoms that would need to be quoted to be accepted by read are quoted.
Example: write_canonical([2 + 2]) - writes '.'(+(2, 2), []) to the current output stream.
 
 write_canonical / 2
Prototype: write_canonical(StreamOrAlias, Term)
Writes Term to stream / stream having alias StreamOrAlias, without using operator or list notation. Atoms that would need to be quoted to be accepted by read are quoted.
Example: write_canonical(textout, [2 + 2]) - writes '.'(+(2, 2), []) to textout.
 
 write_term / 2
Prototype: write_term(Term, Options)
Writes a printed representation of Term to the current output stream, with formatting controlled by the list of options specified by Options. See below.
Example: write_term('a3' + 2, [ quoted(true), ignoreops(true) ]) - writes +('a3', 2) to the current output stream.
 
Possible options:
  • quoted Quote atoms that would need to be quoted to be accepted by read. Possible values:
    • false
    • true
  • ignore_ops Do not use operator or list notation. Possible values:
    • false
    • true
  • numbervars Convert terms of the form $VAR(number) to a generated variable name. Possible values:
    • false
    • true
  • escaped Escape characters that Java requires to be escaped. Possible values:
    • false
    • true
  • keep_variable_numbers Retain previous _number values for uninstantiated variables. Possible values:
    • false
    • true
 write_term / 3
Prototype: write_term(StreamOrAlias, Term, Options)
Writes a printed representation of Term to the stream / stream, having alias StreamOrAlias with formatting controlled by the list of options specified by Options. See below.
Example: write_term(textout, 'a3' + 2, [ quoted(true), ignoreops(true) ]) - writes +('a3', 2) to textout.
 
Possible options:
  • quoted Quote atoms that would need to be quoted to be accepted by read. Possible values:
    • false
    • true
  • ignore_ops Do not use operator or list notation. Possible values:
    • false
    • true
  • numbervars Convert terms of the form $VAR(number) to a generated variable name. Possible values:
    • false
    • true
  • escaped Escape characters that Java requires to be escaped. Possible values:
    • false
    • true
  • keep_variable_numbers Retain previous _number values for uninstantiated variables. Possible values:
    • false
    • true
 writeq / 2
Prototype: writeq(StreamOrAlias, Term)
Writes a printed representation of Term to the stream / stream having alias StreamOrAlias, but atoms that would need to be quoted to be accepted by read are quoted
Example: writeq(textout, 'Hello, world') - writes 'Hello, World' (with quotes) to textout.
Example: writeq(textout, (a, b)) - writes a ',' b to textout.
Example: writeq(textout, [ 2 + 2, a(b) ] - writes [ 2 + 2, a(b), ] to textout.