Manual: Topical List of Prolog Built-ins
Quintus Prolog Manual
L-2: Topical List of Prolog Built-ins
Following is a complete list of Quintus Prolog built-in predicates, arranged by topic. A predicate may be included in more than one list.
L-2-1: Arithmetic
- Y is X
Y is the value of arithmetic expression X
- X =:= Y
the results of evaluating terms X and Y as arithmetic expressions are equal.
- X =\= Y
the results of evaluating terms X and Y as arithmetic expressions are not equal.
- X < Y
the result of evaluating X as an arithmetic expression is less than the result of evaluating Y as an arithmetic expression.
- X >= Y
the result of evaluating X as an arithmetic expression is not less than the result of evaluating Y as an arithmetic expression.
- X > Y
the result of evaluating X as an arithmetic expression X is greater than the result of evaluating Y as an arithmetic expression.
- X =< Y
the result of evaluating X as an arithmetic expression is not greater than the result of evaluating Y as an arithmetic expression.
L-2-2: Character I/O
- at_end_of_file
testing whether end of file is reached for current input stream
- at_end_of_file(S)
testing whether end of file is reached for the input stream S
- at_end_of_line
testing whether at end of line on current input stream
- at_end_of_line(S)
testing whether at end of line on input stream S
- get(C)
C is the next non-blank character on the current input stream
- get(S,C)
C is the next non-blank character on input stream S
- get0(C)
C is the next character on the current input stream
- get0(S,C)
C is the next character on input stream S
- nl
send a newline to the current output stream
- nl(S)
send a newline to stream S
- peek_char(C)
looks ahead for next input character on the current input stream
- peek_char(S,C)
looks ahead for next input character on the input stream S
- put(C)
write character C to the current output stream
- put(S,C)
write character C to stream S
- skip(C)
skip input on the current input stream until after character C
- skip(S,C)
skip input on stream S until after character C
- skip_line
skip the rest input characters of the current line (record) on the current input stream
- skip_line(S)
skip the rest input characters of the current line (record) on the input stream S
- tab(N)
send N spaces to the current output stream
- tab(S,N)
send N spaces to stream S
- ttyget(C)
the next non-blank character input from the terminal is C
- ttyget0(C)
the next character read in from the terminal is C
- ttynl
display a new line on the terminal
- ttyput(C)
the next character sent to the terminal is C
- ttyskip(C)
skip over terminal input until after character C
- ttytab(N)
send N spaces to the terminal
L-2-3: Control
- P,Q
prove P and Q
- P;Q
prove P or Q
- M:P
call P in module M
- P->Q;R
if P succeeds, prove Q; if not, prove R
- P->Q
if P succeeds, prove Q; if not, fail
- !
cut any choices taken in the current procedure
- \+ P
goal P is not provable
- X ^ P
there exists an X such that P is provable (used in setof and bagof)
- bagof(X,P,B)
B is the bag of instances of X such that P is provable
- call(P)
prove (execute) P
- fail
fail (start backtracking)
- false
same as fail
- findall(T,G,L)
L is the list of all solutions T for the goal G
- otherwise
same as true
- repeat
succeed repeatedly on backtracking
- setof(X,P,S)
S is the set of instances of X such that P is provable
- true
succeed
L-2-4: Database
- abolish(F)
abolish the predicate(s) specified by F
- abolish(F,N)
abolish the predicate named F of arity N
- assert(C)
clause C (for dynamic predicate) is added to data base
- assert(C,R)
clause C is asserted; reference R is returned
- asserta(C)
clause C is asserted before existing clauses
- asserta(C,R)
clause C is asserted before existing clauses; reference R is returned
- assertz(C)
clause C is asserted after existing clauses
- assertz(C,R)
clause C is asserted after existing clauses; reference R is returned
- clause(P,Q)
there is a clause for a dynamic predicate with head P and body Q
- clause(P,Q,R)
there is a clause for a dynamic predicate with head P, body Q, and reference R
- current_key(N, K)
N is the name and K is the key of a recorded term
- dynamic(P)
declaration that predicates specified by P are dynamic
- erase(R)
erase the clause or record with reference R
- instance(R,T)
T is an instance of the clause or term referenced by R
- multifile_assertz(C)
add clause C to the end of a (possibly compiled) multifile procedure
- recorda(K,T,R)
make term T the first record under key K; reference R is returned
- recorded(K,T,R)
term T is recorded under key K with reference R
- recordz(K,T,R)
make term T the last record under key K; reference R is returned
- retract(C)
erase the first dynamic clause that matches C
- retractall(H)
erase every clause whose head matches H
L-2-5: Debugging
- add_spypoint(P)
adds a spypoint to a procedure or to a particular call to a procedure
- add_advice(G,P,A)
associates advice with a port of Prolog predicate model
- check_advice
enables advice checking for all predicates with advice
- check_advice(P)
enables advice checking for the specified predicates
- current_advice(G,P,A)
find out what advice exists
- current_spypoint(L)
find out what spypoints exist
- debug
switch on debugging
- debugging
display debugging status information
- get_profile_results(B,N,L,T)
get the results of the last execution profile
- leash(M)
set the debugger's leashing mode to M
- nocheck_advice
disables all advice-checking
- nocheck_advice(P)
disables advice-checking from specified predicates
- nodebug
switch off debugging
- noprofile
switch off profiling
- nospy(P)
remove spypoints from the procedure(s) specified by P
- nospyall
remove all spypoints
- notrace
switch off debugging (same as nodebug/0)
- profile
switch on profiling
- profile(G)
switch on profiling and profile the execution of goal G
- remove_advice(G,P,A)
remove advice from a port/predicate
- remove_spypoint
removes a spypoint
- show_profile_results
show the results of the last execution profile by time
- show_profile_results(B)
show the results of the last execution profile by B
- show_profile_results(B,N)
show the results of the last execution profile by B, listing N predicates
- spy(P)
set spypoints on the procedure(s) specified by P
- trace
switch on debugging and start tracing immediately
- unknown_predicate_handler(G,M,N)
user-defined handle for unknown predicates.
L-2-6: Executables and QOF-Saving
- initialization(G)
G is to be run when program is started
- runtime_entry(S)
entry point for a runtime system
- save_modules(L,F)
save the modules specifed in L into file F
- save_predicates(L,F)
save the predicates specified in L into file F
- version
display system identification messages
- version(A)
add the atom A to the list of introductory messages
- volatile(P)
predicates specified by P are not to be included in saves.
- save_program
save all Prolog data
L-2-7: Execution State
- abort
abort execution of the program; return to current break level
- break
start a new break-level to interpret commands from the user
- halt
exit from Prolog
- on_exception(E,P,H)
specify a handler H for any exception E arising in the execution of the goal P
- raise_exception(E)
raise an exception
L-2-8: File Name Manipulation
- absolute_file_name(R,A)
A is the absolute name of file R
- absolute_file_name(R,O,A)
expand relative file name R to absolute file name A using options specified in O
- file_search_path(F,D)
user-extendible; directory D is included in file search path F
- library_directory(D)
user-extendible; D is a library directory that will be searched
L-2-9: File and Stream Handling
- character_count(S,N)
N is the number of characters read/written on stream S
- close(F)
close file or stream F
- current_input(S)
S is the current input stream
- current_output(S)
S is the current output stream
- current_stream(F,M,S)
S is a stream open on file F in mode M
- fileerrors
enable reporting of file errors
- flush_output(S)
flush the output buffer for stream S
- line_count(S,N)
N is the number of lines read/written on stream S
- line_position(S,N)
N is the number of characters read/written on the current line of S
- nofileerrors()
disable reporting of file errors
- open(F,M,S)
file F is opened in mode M returning stream S
- open(F,M,O,S)
creates a Prolog stream S by opening the file F in mode M with options O
- open_null_stream(S)
new output to stream S goes nowhere
- prompt(O,N)
queries or changes the prompt string of the current input stream
- prompt(S,O,N)
queries or changes the prompt string of the current input stream or an input stream S
- see(F)
make file F the current input stream
- seeing(N)
the current input stream is named N
- seek(S,O,M,N)
seek to an arbitrary byte position on the stream S
- seen
close the current input stream
- set_input(S)
select S as the current input stream
- set_output(S)
select S as the current output stream
- stream_code(S,C)
Converts between Prolog and C representations of a stream
- stream_position(S,P)
P is the current position of stream S
- stream_position(S,O,N)
O is the old position of stream S; N is the new position
- tell(F)
make file F the current output stream
- telling(N)
to file N
- told
close the current output stream
- ttyflush()
transmit all outstanding terminal output
L-2-10: Foreign Interface
- assign
poke into memory
- extern(P)
declares predicate P to be callable from foreign code
- foreign(F,P)
user-defined; C function F is attached to predicate P
- foreign(F,L,P)
user-defined; function F in language L is attached to P
- foreign_file(F,L)
user-defined; file F defines foreign functions in list L
- load_foreign_files(F,L)
load object files F using libraries L
- unix(T)
give access to UNIX facilities
L-2-11: Grammar Rules
- -->(Head, Body)
A possible form for Head is Body
- 'C'(S1,T,S2)
(in grammar rules) S1 is connected to S2 by the terminal T
- expand_term(T,X)
term T expands to term X using term_expansion/2 or grammar rule expansion
- phrase(P,L)
list L can be parsed as a phrase of type P
- phrase(P,L,R)
R is what remains of list L after phrase P has been found
- term_expansion(T,X)
hook called by expand_term/2
L-2-12: Help
- help
prints some help information
- help(Topic)
indexed access to the on-line manual
- manual
access the top level of the on-line manual
- manual(X)
access the specified manual section
- user_help
user-defined; tells help/1 what to do
L-2-13: Hook Predicates
- foreign/[2,3]
Describes the interface between Prolog and the foreign Routine
- foreign_file/2
Describes the foreign functions in ObjectFile to interface to.
- message_hook/3
Overrides the call to print_message_lines/3 in print_message/2.
- generate_message_hook/3
A way for the user to override the call to 'QU_messages':generate_message/3 in print_message/2.
- portray/1
A way for the user to over-ride the default behavior of print/1.
- query_hook/6
Provides a method of overriding Prolog's default keyboard based input requests.
- runtime_entry/1
This predicate is called upon start-up and exit of stand alone applications.
- term_expansion(T,X)
hook called by expand_term/2
- unknown_predicate_handler/3
User definable hook to trap calls to unknown predicates
- user_help/0
A hook for users to add more information when help/0 is called.
L-2-14: List Processing
- T =.. L
the functor and arguments of term T comprise the list L
- append(A,B,C)
The list C is the concatenation of lists A and B
- keysort(L,S)
the list L sorted by key yields S
- length(L,N)
the length of list L is N
- sort(L,S)
sorting the list L into order yields S
L-2-15: Loading Programs
- [F]
same as load_files(F)
- compile(F)
compile procedures from file (or list of files) F into the data base
- consult(F)
same as compile(F)
- reconsult(F)
same as compile(F)
- ensure_loaded(F)
load F if not already loaded
- load_files(F)
load the specified Prolog source and/or QOF files F into memory
- load_files(F,O)
load files according to options O
- meta_predicate(P)
declares predicates P that are dependent on the module from which they are called
- module(M,L)
declaration that module M exports predicates in L
- multifile(P)
declares that the clauses for P are in more than one file
- no_style_check(A)
switch off style checking of type A
- restore(F)
restart system and load file F
- style_check(A)
turn on style checking of type A
- use_module(F)
import the module-file(s) F, loading them if necessary
- use_module(F,I)
import the procedure(s) I from the module-file F
- use_module(M,F,I)
import I from module M, loading module-file F if necessary
- term_expansion(T,N)
user-defined; compile-time transformation of clauses
L-2-16: Memory
- garbage_collect
force an immediate garbage collection
- garbage_collect_atoms
garbage collect atom space
- gc
enable garbage collection
- nogc
disable garbage collection
- statistics
display various execution statistics
- statistics(K,V)
the execution statistic with key K has value V
- trimcore
reduce free stack space to a minimum
L-2-17: Messages
- message_hook(M,S,L)
user defined; intercept the printing of a message
- generate_message(M,SO,S)
in QU_messages: determines the mapping from a message term into a sequence of lines of text to be printed
- generate_message_hook(M,S0,S)
user defined; intercept message before it is given to QU_messages:generate_message
- print_message(S,M)
print a message M of severity S
- print_message_lines(S,P,L)
print the message lines L to stream S with prefix P
- query_abbreviation(T,P)
in QU_messages; specifies one letter abbreviations for responses to queries from the Prolog system
- query_hook(Q,A)
user-defined; intercept a system request for user input
L-2-18: Modules
- current_module(M)
M is the name of a current module
- current_module(M,F)
F is the name of the file in which M's module declaration appears
- meta_predicate(P)
declares predicates P that are dependent on the module from which they are called
- module(M)
makes M the type-in module
- module(M,L)
declaration that module M exports predicates in L
- save_modules(L,F)
save the modules specifed in L into file F
- use_module(F)
import the module-file(s) F, loading them if necessary
- use_module(F,I)
import the procedure(s) I from the module-file F
- use_module(M,F,I)
import I from module M, loading module-file F if necessary
L-2-19: Program State
- current_atom(A)
backtrack through all atoms
- current_module(M)
M is the name of a current module
- current_module(M,F)
F is the name of the file in which M's module declaration appears
- current_predicate(A,P)
A is the name of a predicate with most general goal P
- listing
list all dynamic procedures in the type-in module
- listing(P)
list the dynamic procedure(s) specified by P
- module(M)
make M the type-in module
- predicate_property(P,Prop)
Prop is a property of the loaded predicate P
- prolog_flag(F,V)
V is the current value of Prolog flag F
- prolog_flag(F,O,N)
O is the old value of Prolog flag F; N is the new value
- prolog_load_context(K,V)
find out the context of the current load
- source_file(F)
F is a source file which has been loaded into the data base
- source_file(P,F)
P is a predicate defined in the loaded file F
- source_file(P,F,N)
Clause number N of predicate P came from file F
L-2-20: Term Comparison
- compare(C,X,Y)
C is the result of comparing terms X and Y
- X == Y
terms X and Y are strictly identical
- X \== Y
terms X and Y are not strictly identical
- X @< Y
term X precedes term Y in standard order for terms
- X @>= Y
term X follows or is identical to term Y in standard order for terms
- X @> Y
term X follows term Y in standard order for terms
- X @=< Y
term X precedes or is identical to term Y in standard order for terms
L-2-21: Term Handling
- X = Y
terms X and Y are unified
- arg(N,T,A)
the Nth argument of term T is A
- atom_chars(A,L)
A is the atom containing the characters in list L
- copy_term(T,C)
C is a copy of T in which all variables have been replaced by new variables
- functor(T,F,N)
the principal functor of term T has name F and arity N
- ground(T)
term T is a nonvar, and all substructures are nonvar
- hash_term(T,H)
H is a hash-value for term T
- name(A,L)
the list of characters of atom or number A is L
- number_chars(N,L)
N is the numeric representation of list of characters L
- numbervars(T,M,N)
number the variables in term T from M to N-1
- subsumes_chk(G,S)
true when G(eneral) subsumes S(pecific); S and G are terms.
L-2-22: Term I/O
- current_op(P,T,A)
atom A is an operator of type T with precedence P
- display(T)
write term T to the user output stream in prefix notation
- format(C,A)
write arguments A according to control string C
- format(S,C,A)
write arguments A on stream S according to control string C
- op(P,T,A)
make atom A an operator of type T with precedence P
- portray(T)
hook which called when allows user to print(T).
- portray_clause(C)
write clause C to the current output stream
- print(T)
display the term T on the current output stream using portray/1 or write/1
- print(S,T)
display the term T on stream S using portray/1 or write/2
- read(T)
read term T from the current input stream
- read(S,T)
read term T from stream S
- read_term(O,T)
read term T according to options O
- read_term(S,O,T)
read T from stream S according to options O
- write(T)
write term T on the current output stream
- write(S,T)
write term T on stream S
- write_canonical(T)
write term T on the current output stream so that it can be read back by read/[1,2]
- write_canonical(S,T)
write term T on stream S so that it can be read back by read/[1,2]
- writeq(T)
write term T on the current output stream, quoting atoms where necessary
- writeq(S,T)
write term T on stream S, quoting atoms where necessary
- write_term(T,O)
writes Term to current output with options O
- write_term(S,T,O)
writes Term to S according to options O
L-2-23: Type Tests
- atom(T)
term T is an atom
- atomic(T)
term T is an atom, a number or a db_reference
- callable(T)
T is an atom or a compound term
- compound(T)
T is a compound term (a skeletal predicate specification, see section G-1-6)
- db_reference(D)
D is a data base reference
- float(N)
N is a floating-point number
- ground(T)
term T is a nonvar, and all substructures are nonvar
- integer(T)
term T is an integer
- nonvar(T)
term T is one of atom, db_reference, number, compound (that is, T is instantiated)
- number(N)
N is an integer or a float
- simple(T)
T is not a compound term; it is either atomic or a var
- var(T)
term T is a variable (that is, T is uninstantiated)
L-3: Built-in Predicates
The following reference pages, alphabetically arranged, describe the Quintus Prolog built-in predicates.
For a functional grouping of these predicates including brief descriptions, see section L-2.
In many cases the heading of a reference page will contain not only the name and arity of the predicate, but also the name of a major category to which the predicate belongs. These categories are
defined in section L-1-3.
Further information about categories of predicates and arguments, mode annotations, and the conventions observed in the reference pages is found in Chapter L-1.
L-3-1: !/0
- Synopsis:
-
!
-
-
Cut.
- Description:
-
When first encountered as a goal, cut succeeds immediately. If backtracking should later return to the cut, the parent goal will fail (the parent goal is the one which matched the head of
the clause containing the cut).
- See Also:
-
Chapter B-5-1
L-3-2: ;/2 - disjunction
- Synopsis:
-
+*P ; +*Q
-
-
Disjunction: Succeeds if P succeeds or Q succeeds.
- Arguments:
-
- P
-
<callable> MOD
- Q
-
<callable> MOD
-
-
- Description:
-
- This is normally regarded as part of the syntax of the language, but it is like a built-in predicate in that you can say call (P ; Q). The character "|" (vertical bar) can be used as
an alternative to ';'.
- Note that ;/2 has a distinct behaviour if the first argument is a ->/2 term. See ;/2 - if-then-else.
- See Also:
-
Chapter B-5-6 and Chapter G-2-3
L-3-3: ,/2
- Synopsis:
-
+*P , +*Q
-
-
Conjunction: Succeeds if P succeeds and then Q succeeds.
- Arguments:
-
- P
-
<callable> MOD
- Q
-
<callable> MOD
- Description:
-
This is not normally regarded as a built-in predicate, since it is part of the syntax of the language. However, it is like a built-in predicate in that you can say call((P , Q)) to
execute P and then Q.
- See Also:
-
Chapter G-2-3
L-3-4: ;/2 - if-then-else
- Synopsis:
-
+-P -> +*Q ; +*R
-
-
If P then Q else R, using first solution of P only.
- Arguments:
-
- P
-
<callable> MOD
- Q
-
<callable> MOD
- R
-
<callable> MOD
- Description:
-
- The character '|' can be used as an alternative to ';', giving the form:
P -> Q | R
The '|' is transformed into a ';' when the goal is read.
- First P is executed. If it succeeds, then Q is executed, and if Q fails, the whole conditional goal fails. If P fails, however, R is executed instead of Q.
- The operator precedences of the ';' and '->'/2 are both greater than 1000, so that they dominate commas.
- Backtracking:
-
If P succeeds and Q then fails, backtracking into P does not occur. P may not contain a cut. '->'/2 acts like a cut except that its range is restricted to within the disjunction: it
cuts away R and any choice points within P. '->' may be thought of as a "local cut".
- See Also:
-
Chapter B-5-6 and Chapter G-2-3
L-3-5: ->/2
- Synopsis:
-
+-P -> +*Q
-
-
"Local cut"
-
-
If P then Q else fail, using first solution of P only.
- Arguments:
-
- P
-
<callable> MOD
- Q
-
<callable> MOD
- Description:
-
- When occurring other than as the first argument of a disjunction operator (| or ;), this is equivalent to:
P -> Q | fail.
(For a definition of P -> Q | R, see section G-2-7.)
- '->'/2 cuts away any choice points in the execution of P
- Note that the operator precedence of '->'/2 is greater than 1000, so it dominates commas. Thus, in:
f :- p, q -> r, s.
f.
'->'/2 cuts away any choices in p or in q, but unlike cut (!) it does not cut away the alternative choice for f.
- Exceptions:
-
L-3-6: =/2
- Synopsis:
-
+-Term1 = +-Term2
-
-
unifies Term1 and Term2.
- Arguments:
-
- Term1
-
<term>
- Term2
-
<term>
- Description:
-
- This is defined as if by the clause 'Z = Z.'.
- If '='/2 is not able to unify Term1 and Term2, it will simply fail.
-
-
L-3-7: =../2
- Synopsis:
-
+-Term =.. +-List
-
-
Unifies List with a list whose head is the atom corresponding to the principal functor of Term and whose tail is a list of the arguments of Term.
- Arguments:
-
- Term
-
<term> any term
- List
-
<list> and not[]
- Description:
-
- Pronounced "univ".
- If Term is uninstantiated, then List must be instantiated either to a list of determinate length whose head is an atom, or to a list of length 1 whose head is a number.
-
-
- Exceptions:
-
- Domain error
- Instantiation error
Term and List are both uninstantiated
- Representation error
-
-
- See Also:
-
functor/3, arg/3
-
-
Chapter G-9-2
L-3-8: </2, =:=/2, =</2, =\=/2, >/2, >=/2
- Synopsis:
-
+Expr1 < +Expr2
-
-
Evaluates Expr1 and Expr2 as arithmetic expressions. The goal succeeds if the result of evaluating Expr1 is strictly less than the result of evaluating Expr2.
-
-
+Expr1 =:= +Expr2
-
-
Succeeds if the results of evaluating Expr1 and Expr2 are equal.
-
-
+Expr1 =< +Expr2
-
-
Succeeds if the result of evaluating Expr1 is less than or equal to the result of evaluating Expr2.
-
-
+Expr1 =\= +Expr2
-
-
Succeeds if the results of evaluating Expr1 and Expr2 are not equal.
-
-
+Expr1 > +Expr2
-
-
Succeeds if the result of evaluating Expr1 is strictly greater than the result of evaluating Expr2.
-
-
+Expr1 >= +Expr2
-
-
Succeeds if the result of evaluating Expr1 is greater than or equal to the result of evaluating Expr2.
- Arguments:
-
- Expr1
-
<expr> Arithmetic expression
- Expr2
-
<expr> Arithmetic expression
- Description:
-
All of these predicates evaluate Expr1 and Expr2 as arithmetic expressions and compare the results.
-
-
The possible values for Expr are spelled out in detail in section G-8-3.
- Exceptions:
-
- Instantiation error
- Type error
- Representation error
- Domain error
- Expr1) or Expr2) does not evaluate to a number.
-
-
- Examples:
-
| ?- 23 + 2.2 < 23 - 2.2.
yes
| ?- X = 31, Y = 25, X + Y < X - Y
no
| ?- 1.0 + 1.0 =:= 2.
yes
| ?- "a" =:= 97.
yes
| ?- 42 =< 42.
yes
| ?- "b" =< "a".
no
| ?- 7 =\= 14/2.
no
| ?- 7 =\= 15/2.
yes
| ?- "g" > "g".
no
| ?- 4*2 > 15/2.
yes
| ?- 42 >= 42.
yes
| ?- "b" >= "a".
yes
- Comments:
-
Note that the symbol '=<' is used here rather than '<=' which is used in some other languages. One way to remember this is that the inequality symbols in Prolog are the ones which cannot be
thought of as looking like arrows. The '<' or '>' always points at the '='.
- See Also:
-
Chapter G-8
L-3-9: \+ /1
- Synopsis:
-
\+ +P
-
-
Fails if the goal P has a solution, and succeeds otherwise.
- Arguments:
-
- P
-
<callable>
MOD
- Description:
-
This is not real negation ("P is false"), which is not possible in Prolog, but negation-by-failure meaning "P is not provable". P may not contain a cut. The goal \+ P behaves exactly
like
( P -> fail ; true)
- Exceptions:
-
- Tip:
-
Remember that with prefix operators such as this one, it is necessary to be careful about spaces if the argument starts with a '('. For example:
| ?- \+ (P, Q).
is the '\+'/1 operator applied to the conjunction of P and Q, but
| ?- \+(P, Q).
would require a predicate '\+'/2 for its solution. The prefix operator can, however, be written as a functor of one argument; thus
| ?- \+((P,Q)).
is also correct.
- See Also:
-
library(not) -- defines a safer form of negation as failure.
L-3-10: ==/2, \==/2
- Synopsis:
-
+Term1 == +Term2
-
-
Succeeds if the terms currently instantiating Term1 and Term2 are literally identical (in particular, variables in equivalent positions in the two terms must be identical).
-
-
+Term1 \== +Term2
-
-
Succeeds if the terms currently instantiating Term1 and Term2 are not literally identical.
- Arguments:
-
- Term1
-
<term>
- Term2
-
<term>
- Description:
-
Query (A) fails because Term1 and Term2 are distinct uninstantiated variables. However, query (B) succeeds because the first goal unifies the two variables:
-
-
| ?- Term1 == Term2. (A)
no
-
-
| ?- Term1 = Term2, Term1 == Term2. (B)
yes
-
-
Query (C) succeeds because Term1 and Term2 are distinct uninstantiated variables. However, query (D) fails because the first goal unifies the two variables.
-
-
| ?- Term1 \== Term2.
(C)
yes
-
-
| ?- Term1 = Term2, Term1 \== Term2. (D)
no
- See also:
-
compare/3, @</2, @=</2, @>/2, @>=/2
Chapter G-9
L-3-11: @</2, @=</2, @>/2, @>=/2
- Synopsis:
-
+Term1 @< +Term2
-
-
Succeeds if term Term1 is before term Term2 in the standard order.
-
-
+Term1 @=< +Term2
-
-
Succeeds if term Term1 is not after term Term2 in the standard order.
-
-
+Term1 @> +Term2
-
-
Succeeds if term Term1 is after term Term2 in the standard order.
-
-
+Term1 @>= +Term2
-
-
Succeeds if term Term1 is not before term Term2 in the standard order.
- Arguments:
-
- Term1
-
<term>
- Term2
-
<term>
-
-
- Description:
-
These predicates use a standard total order when comparing terms. The standard total order is:
variables @< database references @< numbers @< atoms
@< compound terms
-
-
For further details see section G-9-7-1.
- Examples:
-
| ?- foo(1) @< foo(2).
yes
| ?- chicken @< egg.
yes
| ?- a @< "a".
yes
-
-
| ?- liberty @=< pride.
yes
|?- 1 @=< 1.0.
yes
-
-
| ?- fie(1,1) @> fie(1).
yes
-
-
| ?- 1 @>= 1.0.
no
| ?- 1.0 @>= 1.
yes
- See Also:
-
compare/3, ==/2, \==/2
Chapter G-9
L-3-12: -->/2
- Synopsis:
-
+Head-->+Body
-
-
A possible form for Head is Body. Used primarily in grammar rules.
- Arguments:
-
- Head
-
Prolog term, or list of terms
- Body
-
Prolog term, or list of terms
- The formal description of grammar heads and grammar bodies is spelled out in section G-1-7-2.
-
-
-
- Description:
-
- Head and Body are translated into lists of Prolog terms by expand_term/2.
-
-
- Exceptions:
-
- Context error
Cannot call -->/2 as a predicate
- Examples:
-
See examples in section G-16-3 and section G-16-4.
- See Also:
-
expand_term/2, 'C'/3, term_expansion/2, phrase/[2,3]
Chapter G-16
L-3-13: ^/2
- Synopsis:
-
+X ^ +*P
-
-
Equivalent to "there exists an X such that P is true", thus X is normally an unbound variable. The use of the explicit existential quantifier outside setof/3 and bagof/3 is superfluous.
- Arguments:
-
- X
-
<term>
- P
-
<callable> MOD
- Description:
-
- Equivalent to simply calling P
- Exceptions:
-
As for call/1:
- type error
- context error
- instantiation error
- Examples:
-
- Using bagof/3 without and with the existential quantifier:
| ?- bagof(X, foo(X,Y), L).
X = _3342,
Y = 2,
L = [1,1] ;
X = _3342,
Y = 3,
L = [2] ;
no
| ?- bagof(X, Y^foo(X,Y), L).
X = _3342,
Y = _3361,
L = [1,1,2] ;
no
- section G-15-1-1
- See Also:
-
setof/3, bagof/3
L-3-14: abolish/[1,2]
- Synopsis:
-
-
-
abolish(+PredSpecTree)
-
-
abolish(+Name, +Arity)
-
-
Removes procedures from the Prolog database.
- Arguments:
-
- PredSpecTree
-
<pred_spec_tree> A procedure specification in the form Name/Arity, or a list of such procedure specifications. MOD
- Name
-
<atom> A string representing the name of a predicate. MOD
- Arity
-
<arity> An integer giving the arity of the predicate.
-
-
- Description:
-
- Removes all procedures specified. After this command is executed the current program functions as if the named procedures had never existed. That is, in addition to removing all the
clauses for each specified procedure, abolish removes any properties that the procedure might have had, such as being dynamic or multifile.
- You may abolish any of your own procedures, regardless of whether they are dynamic, static, compiled, interpreted, or foreign. You cannot abolish built-in procedures.
- It is important to note that retract/1, retractall/1, and erase/1 can only remove dynamic predicates. They cannot remove the predicates properties (such as being dynamic or multifile)
from the system. abolish[1,2], on the other hand, can remove both static and dynamic predicates. It removes the clauses of the predicates and its properties.
- The procedures which are abolished do not become invisible to a currently running procedure. See section G-14-6 for an example illustrating this point.
- Space occupied by abolished procedures is reclaimed. The space occupied by the procedures is reclaimed.
- Procedures must be defined in the source module before they can be abolished. An attempt to abolish a procedure that is imported into the source module will cause a permission error.
Using a module prefix, M:, clauses in any module may be abolished.
- Abolishing a foreign procedure destroys only the link between that Prolog procedure and the associated foreign code. The foreign code that was loaded remains in memory. This is necessary
because Prolog cannot tell which subsequently-loaded foreign files may have links to the foreign code. The Prolog part of the foreign procedure is destroyed and reclaimed.
- Specifying an undefined procedure is not an error.
- abolish/2 is an obsolete special case of abolish/1 maintained to provide compatibility with DEC-10 Prolog, C Prolog, and earlier versions of Quintus Prolog.
-
-
- Exceptions:
-
- instantiation_error
If one of the arguments is not ground.
- type_error
if PredSpecTree is not a valid procedure specification, or if a Name is not an atom or an Arity not an integer.
- domain_error
if an Arity is specified as an integer outside the range 0-255.
- permission_error
if a specified procedure is imported into the source module.
-
-
- See Also:
-
-
-
dynamic/1, erase/1, retract/1, retractall/1.
-
-
Chapter G-14-2
L-3-15: abort/0
- Synopsis:
-
abort
-
-
Abandons the current execution and returns to the beginning of the current break level.
- Description:
-
- Fairly drastic predicate that is normally only used when some error condition has occurred and there is no way of carrying on, or when debugging.
- Often used via the debugging option 'a' or the ^C interrupt option 'a'.
- If abort is called from initialization (see section H-1-6), then QP_initialize() returns. If user has not defined their own main(), this means that QP_toplevel() gets called and you
get the default top level loop. The same holds true for ^C followed by the 'a' option.
-
Note: The goal specified by save_program/2 is also run as an "initialization" when a saved file is restored.
-
Note: In the context of a runtime system, QP_toplevel() corresponds to calling runtime_entry(start).
-
-
- Tip:
-
Does not close any files which you may have opened. When using see/1 and tell/1, (rather than open/3, set_input/1, and set_output/1), close files yourself to avoid strange behavior
after your program is aborted and restarted.
- See Also:
-
halt/[0,1], break/0, QP_toplevel(), QP_initialize(), runtime_entry/1
-
-
Chapter G-11-1
L-3-16: absolute_file_name/[2,3]
- Synopsis:
-
absolute_file_name(+RelFileSpec, -AbsFileName)
-
-
absolute_file_name(+RelFileSpec, +Options, -AbsFileName)
-
-
absolute_file_name(+RelFileSpec, +Options, *AbsFileName)
-
-
Unifies AbsFileName with the the absolute file name that corresponds to the relative file specification RelFileSpec.
- Arguments:
-
- RelFileSpec
-
<file_spec> A valid file specification.
- AbsFileName
-
<atom> The first absolute file name derived from RelFileSpec that satisfies the access modes given by Options.
- Options
-
<list> A list of zero or more of the following:
-
-
- ignore_underscores(Bool). Bool =
-
- true
-
When constructing an absolute file name that matches the given access modes, two names are tried: First the absolute file name derived directly from RelFileSpec, and then
the file name obtained by first deleting all underscores from RelFileSpec.
- false
-
(default) Suppresses any deletion of underscores.
- extensions(Ext)
-
Has no effect if RelFileSpec contains a file extension. Ext is an atom or a list of atoms, each atom representing an extension that should be tried when constructing the
absolute file name. The extensions are tried in the order they appear in the list. Default value is Ext = [''], i.e. only the given RelFileSpec is tried, no extension is added.
To specify extensions('') or extensions([]) is equal not to give any extensions option at all.
- file_type(Type)
-
Has no effect if RelFileSpec contains a file extension. Picks an adequate extension for the operating system currently running, which means that programs using this option
instead of extensions(Ext) will be more portable between operating systems. Type must be one of the following atoms:
- text
-
implies extensions(['']).
RelFileSpec is a file without any extension. (Default)
- prolog
-
implies extensions(['pl','']).
RelFileSpec is a Prolog source file, maybe with a .pl extension.
- object
-
implies extensions(['o',''])
RelFileSpec is a foreign language object file, maybe with a .o extension.
- executable
-
implies extensions(['so',''])
RelFileSpec is a foreign executable (shared object file), maybe with a .so extension.
- qof
-
implies extensions(['qof','']).
RelFileSpec is a Prolog object code file, maybe with a .qof extension.
- directory
-
implies extensions(['']).
RelFileSpec is a directory, not a regular file. Only when this option is present can absolute_file_name/3 access directories without raising an exception.
- foreign
-
implies extensions(['o',''])
Same as object. Included for backward compatibility. Might be removed from future releases.
- ignore_version(Bool)
-
This switch has no effect on systems where files don't have version numbers. Bool =
-
-
- true
-
When looking for a file that obeys the specified access modes, the version numbers will be ignored. The returned absolute file name will not contain any version number. To
find a file name which includes a proper version number, use absolute_file_name/3 with the returned file as input, and the option ignore_version(false).
See description of access option.
- false
-
(default) Version numbers are significant.
-
-
- access(Mode)
-
Mode must be one of the following:
-
-
- read
-
AbsFileName must be readable.
- write
-
If AbsFileName exists, it must be writable. If it doesn't exist, it must be possible to create.
- append
-
If AbsFileName exists, it must be writable. If it doesn't exist, it must be possible to create.
- exist
-
The file represented by AbsFileName must exist.
- none
-
(default) The file system is not accessed. The first absolute file name that is derived from RelFileSpec is returned. Note that if this option is specified, no existence
exceptions can be raised.
- list of access modes
-
A list of one or more of the above options. If AbsFile exists, it must obey every specified option in the list. This makes it possible to combine a read and write, or write
and exist check, into one call to absolute_file_name/3.
-
-
-
-
NOTE: The following only applies to file systems with version numbered files. If the user explicitly has specified a version number, only that version is considered. If no
version number is supplied, the version number of AbsFileName is determined by:
-
-
- read
-
newest readable version.
- write
-
the file exists, the newest version plus one. If the file doesn't exist, a system dependent "youngest" version number.
- append
-
If the file exists, the newest version. If the file doesn't exist, a system dependent "youngest" version number.
- exist
-
newest version.
- none
-
A system dependent "youngest" version number. Note that this can be switched of with the ignore_version option.
- list of modes
-
newest version.
- file_errors(Val). Val =
-
- error
-
(default) Raise an exception if a file derived from RelFileSpec has the wrong permissions, that is, can't be accessed at all, or doesn't satisfy the the access modes
specified with the access option.
- fail
-
Fail if a file derived from RelFileSpec has the wrong permissions. Normally an exception is raised, which might not always be a desirable behavior, since files that do obey
the access options might be found later on in the search. When this option is given, the search space is guaranteed to be exhausted. Note that the effect of this option is
the same as having the global flag nofileerrors set.
- solutions(Val). Val =
-
- first
-
(default) As soon as a file derived from RelFileSpec is found, commit to that file. Makes absolute_file_name/3 deterministic.
- all
-
Return each file derived from RelFileSpec that is found. The files are returned through backtracking. This option is probably most useful in combination with the option
file_errors(fail).
-
-
- Description:
-
- We can restrict our description to absolute_file_name/3, because absolute_file_name/2 can be defined as:
absolute_file_name(RelFileSpec, AbsFileName) :-
Options = [ ignore_underscores(true),
file_type(prolog),
access(exist),
file_errors(fail) ],
( absolute_file_name(RelFileSpec,
Options,
AbsFileName)
-> true
; absolute_file_name(RelFileSpec,
[],
AbsFileName)
).
Note that the semantics of absolute_file_name/2 has changed slightly since previous releases. The difference is that absolute_file_name/2 now always succeeds and returns an absolute
path, also when the RelFileSpec is a compound term. For instance, if the relative file name is library(strings), you get an absolute file name, even if the library file strings.pl
doesn't exist. In previous releases, this would have raised an exception. If it's important that an error is raised when the file doesn't exist, absolute_file_name/3 with option
access(exist) can be used.
- Four phase process: The functionality of absolute_file_name/3 is most easily described as a four phase process, in which each phase gets an infile from the preceding phase, and
constructs one or more outfiles to be consumed by the succeeding phases. The phases are:
- Syntactic rewriting
- Underscore deletion
- Extension expansion
- Access checking
- Each of the three first phases modifies the infile and produces variants that will be fed into the succeeding phases. The functionality of all phases but the first are decided with the
option list. The last phase checks if the generated file exists, and if not asks for a new variant from the preceding phases. If the file exists, but doesn't obey the access mode option,
a permission exception is raised. If the file obeys the access mode option, absolute_file_name/3 commits to that solution, unifies AbsFileName with the file name, and succeeds
determinately. For a thorough description, see below.
- Note that the relative file name RelFileSpec may also be of the form PathAlias(FileSpec), in which case the absolute file name of the file FileSpec in one of the directories designated
by PathAlias is returned (see the description of each phase below, and section G-6-1).
- Description of each phase:
-
- (Phase 1) This phase translates the relative file specification given by RelFileSpec into the corresponding absolute file name.
If RelFileSpec is a term with one argument, it is interpreted as PathAlias(FileSpec) and outfile becomes the file as given by file_search_path/2. If file_search_path/2 has more than
one solution, outfile is unified with the solutions in the order they are generated. If the succeeding phase fails, and there is no more solutions, an existence exception is raised.
If RelFileSpec = '', outfile is unified with the current working directory. If absolute_file_name/3 is called from a goal in a file being loaded, the directory containing that file is
considered current working directory. If the succeeding phase fails, an existence exception is raised.
If RelFileSpec is an atom, other than '', it's divided into components. A component are defined to be those characters:
- Between the beginning of the file name and the end of the file name if there are no '/'s in the file name.
- Between the beginning of the file name and the first '/'.
- Between any two successive '/'-groups (where a '/'-group is defined to be a sequence of one or more '/'s with no non-'/' character interspersed.)
- Between the last '/' and the end of the file name.
To give the absolute file name, the following rules are applied to each component of RelFileSpec:
- The component '~<user>', if encountered as the first component of RelFileSpec, is replaced by the absolute path of the home directory of <user>. If <user> doesn't exist, a permission
exception is raised.
- The component '~', if encountered as the first component of RelFileSpec, is replaced by the absolute path of the home directory of the current user.
- If neither (1) nor (2) applies, then RelFileSpec is prefixed with the current working directory. If absolute_file_name/3 is called from a goal in a file being loaded, the directory
containing that file is considered current working directory.
- The component '.' is deleted.
- The component '..' is deleted together with the directory name syntactically preceding it. For example, 'a/b/../c' is rewritten as 'a/c'.
- Two or more consecutive '/'s are replaced with one '/'.
When these rules have been applied, the absolute file name is unified with outfile. If the succeeding phase fails, an existence exception is raised.
- (Phase 2) See ignore_underscores option.
- (Phase 3) See extensions and file_type options.
- (Phase 4) See access option.
-
-
- Exceptions:
-
- domain_error
Options contains an undefined option.
- instantiation_error
Any of the Options arguments or RelFileSpec is not ground.
- type_error
In Options or in RelFileSpec.
- existence_error
RelFileSpec is syntactically valid but does not correspond to any file.
- permission_error
RelFileSpec names an existing file but the file does not obey the given access mode.
-
-
- Comments:
-
-
-
- If an option is specified more than once the rightmost option takes precedence. This provides for a convenient way of adding default values by putting these defaults at the front of the list
of options.
- Note that the default behavior of absolute_file_name/3, that is when Options = [], does not mimic the behavior of absolute_file_name/2.
- If absolute_file_name/3 succeeds, and the file access option was one of {read, write, append}, it is guaranteed that the file can be opened with open/[3,4]. If the access option was
'exist', the file does exist, but might be both read and write protected.
- Note that absolute_file_name/3 signals a permission error if a specified file refers to a directory (unless the option access(none) is given.)
- absolute_file_name/[2,3] is sensitive to the 'nofileerrors' flag, which causes the predicate to fail rather than raising permission errors when reading files with wrong permission. This
has the effect that the search space always is exhausted.
- If RelFileSpec contains a '..' component, the constructed absolute file name might be wrong. This occurs if the parent directory is not the same as the directory preceding '..' in the
relative file name, which only can happen if a soft link is involved.
- Examples:
-
To check whether the file 'my_text' exists in the current user directory, with one of the extensions 'text' or 'txt', and is both writable and readable:
-
-
absolute_file_name('~/my_text',
[extensions(['text','txt']),
access([read,write])],
File).
-
-
To check if the Prolog file 'same_functor' exists in some library, and also check if it exists under the name 'samefunctor':
absolute_file_name(library(same_functor),
[file_type(prolog), access(exist),
ignore_underscores(true)],
File).
- See Also:
-
file_search_path/2, library_directory/2 nofileerrors/0, fileerrors/0
-
-
library(files) library(directory)
L-3-17: add_advice/3
- Synopsis:
-
add_advice(+Goal,+Port,+Action)
-
-
Associate an action with entry to a port of a procedure.
- Arguments:
-
- Goal
-
<callable> a term to be unified against a calling goal. MOD
- Port
-
one of {call, exit, done, redo, fail}; an atom indicating the port at which to check advice.
- Action
-
<callable> a goal to be called when advice is checked at the given port. MOD
- Description:
-
- add_advice/3 associates an advice action (a goal to be called) with a port of the standard Prolog debugger model (see section E-1-1). Variable bindings made when Goal matches the
incoming call carry across to the advice action, so incoming arguments can be verified or processed by advice checking. Any number of advice actions can be associated with a given Goal,
Port, or Goal-Port combination. Putting advice on a procedure does not automatically turn on checking of advice, so advice can be built into a program and checked only when necessary.
At each port, advice is checked before interaction with the Prolog debugger, so the advice action can be used to control the debugger. It is not currently possible to associate advice
with Prolog system built-in predicates.
- Advice added using a call to add_advice/3 will be checked after all preexisting advice for that predicate and port.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to add_advice/3 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Tips:
-
Using advice can streamline debugging of deep recursions and other situations where a given call is made correctly many times but eventually goes amiss. Use of the Prolog debugger's
spypoints is inconvenient because of the many calls before the error. If, for instance, it is known that a certain bad datum is present in the particular call producing the error, it is
possible to use advice to set a spypoint only when that datum is seen:
-
-
:- add_advice(recurse(X,Y), call,
(bad_data(X), spy recurse/2)).
-
-
When advice checking is enabled, this piece of advice will take effect only if the first argument passed to recurse/2 is bad. When that is so, a spypoint will be placed on recurse/2 and
execution will continue at the call port of recurse/2. Since advice is checked before debugger interaction at the port, the debugger will immediately stop. There is no need to interact
with the debugger for all the calls that have valid data.
-
-
Advice can also provide a simple and flexible profiling tool by associating a counter with various ports of each "interesting" predicate. The advice associated with each port and predicate
might map the name, arity, module and port to a counter value held in a dynamic table. When advice checking is on and an advised predicate port is reached, the advice action simply
increments the counter. The counter table can then be inspected to determine the number of times each predicate-port combination was reached.
- Advice can also be used to associate "pre-conditions" and "post-conditions" to predicates. "pre-conditions" can be associated with the "call" port of a predicate and "post-conditions" can be
-
associated with the "done" or "exit" port of a predicate. Checking for "pre" and "post" conditions will be done only when checking advice is turned on.
- See Also:
-
remove_advice/3, current_advice/3, check_advice/[0,1], nocheck_advice/[0,1]
-
-
Chapter E-4
L-3-18: add_spypoint/1
- Synopsis:
-
add_spypoint(+SpySpec)
-
-
sets a spypoint on the specified predicate or call.
- Arguments:
-
- SpySpec
-
<compound> a specification of an individual spypoint. Two forms of spyspec are allowed:
- predicate(Pred)
-
A spypoint on any call to Pred. Pred must be a skeletal predicate specification, and may be module qualified.
- call(Caller,Clausenum,Callee,Callnum)
-
A spypoint on the Callnum call to Callee in the body of the Clausenum clause of Caller. Callee and Caller must be skeletal predicate specifications. Callnum and
Clausenum must be integers, and begin counting from 1. Note that Callnum specifies a lexical position, that is, the number of the occurrence of Callee counting from the
beginning of the body of the clause, and ignoring any punctuation.
-
-
- Description:
-
- add_spypoint/1 is used to set spypoints on predicates or on specific calls to predicates while debugging.
- add_spypoint/1 does not turn on the debugger. You have to explicitly turn on the debugger with a call to debug/0 or trace/0.
- You can add spypoints to predicates or calls that do not exist. If they later get defined the spypoints get placed.
- Turning off the debugger does not remove spypoints. Use remove_spypoint/1 to remove these spypoints.
- If you are using QUI, the more convenient way to add these spypoints is to use the QUI based source debugger to select a particular goal or predicate and to use the Spypoints menu.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to add_spypoint/1 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Exceptions:
-
- instantiation_error
SpySpec is not sufficiently instantiated.
- type_error
SpySpec is not a compound term.
- domain_error
SpySpec is not a predicate/1 or call/4 term.
- See Also:
-
current_spypoint/1, remove_spypoint/1, spy/1, nospy/1, debugging/0,
-
-
Chapter E-1.
L-3-19: append/3
- Synopsis:
-
append(+*List1, +*List2, +*List3)
-
-
True when all three arguments are lists, and the members of List3 are the members of List1 followed by the members of List2.
- Arguments:
-
- List1
-
<term> a list
- List2
-
<term> a list
- List3
-
<term> a list consisting of List1 followed by List2
-
-
- Description:
-
- Appends lists List1 and List2 to form List3:
| ?- append([a,b], [a,d], X).
X = [a,b,a,d]
| ?- append([a], [a], [a]).
no
| ?- append(2, [a], X).
no
- Takes List3 apart:
| ?- append(X, [e], [b,e,e]).
X = [b,e]
| ?- append([b|X], [e,r], [b,o,r,e,r]).
X = [o,r]
| ?- append(X, Y, [h,i]).
X = [],
Y = [h,i] ;
X = [h],
Y = [i] ;
X = [h,i],
Y = [] ;
no
-
-
- Backtracking:
-
Suppose L is bound to a proper list (see section K-2-2). That is, it has the form [T1,...,Tn] for some n. In that instance, the following things apply:
- append(L, X, Y) has at most one solution, whatever X and Y are, and cannot backtrack at all.
- append(X, Y, L) has at most n+1 solutions, whatever X and Y are, and though it can backtrack over these it cannot run away without finding a solution.
- append(X, L, Y), however, can backtrack indefinitely if X and Y are variables.
- Examples:
-
The following examples are perfectly ordinary uses of append/3:
-
-
- To enumerate adjacent pairs of elements from a list:
next_to(X, Y, /*in*/ List3) :-
append(_, [X,Y|_], List3).
- To check whether Word1 and Word2 are the same except for a single transposition. (append/5 in library(lists) would be better for this task.)
one_transposition(Word1, Word2) :-
append(Prefix, [X,Y|Suffix], Word1),
append(Prefix, [Y,X|Suffix], Word2).
| ?- one_transposition("fred", X).
X = "rfed" ;
X = "ferd" ;
X = "frde" ;
no
- Given a list of words and commas, to backtrack through the phrases delimited by commas:
comma_phrase(List3, Phrase) :-
append(F, [','|Rest], List3),
!,
( Phrase = F
; comma_phrase(Rest, Phrase)
).
comma_phrase(List3, List3).
| ?- comma_phrase([this,is,',',um,',',an,
example], X).
X = [this,is] ;
X = [um] ;
X = [an,example] ;
no
-
-
- See Also:
-
length/2
Chapter K-2
library(lists)
L-3-20: arg/3 meta-logical
- Synopsis:
-
arg(+ArgNum, +Term, -Arg)
-
-
unifies Arg with the ArgNumth argument of term Term.
- Arguments:
-
- ArgNum
-
<integer> positive integer
- Term
-
<nonvar> compound term
- Arg
-
<term>
- Description:
-
The arguments are numbered from 1 upwards.
- Example:
-
| ?- arg(2, foo(a,b,c), X).
X = b
- See Also:
-
functor/3, =../2
-
-
Chapter G-9-2; Chapter K-3-3
L-3-21: assert/[1,2]
- Synopsis:
-
These predicates add a dynamic clause, Clause, to the Prolog data base. They optionally return a database reference in Ref:
-
-
assert(+Clause)
-
-
assert(+Clause, -Ref)
-
-
Undefined whether Clause will precede or follow the clauses already in the data base.
-
-
asserta(+Clause)
-
-
asserta(+Clause, -Ref)
-
-
Clause will precede all existing clauses in the data base.
-
-
assertz(+Clause)
-
-
assertz(+Clause, -Ref)
-
-
Clause will follow all existing clauses in the data base.
- Arguments:
-
- Clause
-
<callable> A valid dynamic Prolog clause. MOD
- Ref
-
<db_reference> a database reference which uniquely identifies the newly asserted Clause.
-
-
- Description:
-
- Clause must be of the form:
Head
or Head :- Body
or M:Clause
where Head is of type callable and Body is a valid clause body. If specified, M must be an atom.
assert(Head) means assert the unit-clause Head. The exact same effect can be achieved by assert((Head :- true)).
If Body is uninstantiated it is taken to mean call(Body). For example, (A) is equivalent to (B):
| ?- assert((p(X) :- X)). (A)
| ?- assert((p(X) :- call(X))). (B)
- Ref should be uninstantiated; a range exception is signalled if Ref does not unify with its return value. This exception is signalled after the assert has been completed.
- The procedure for Clause must be dynamic or undefined. If it is undefined, it is set to be dynamic.
- If you want to write a term of the form 'Head :- Body' as the argument to assert/1, you must put it in parentheses, because the operator precedence of the ':-'/2 functor is greater
than 1000 (see section G-1-4-3). For example, (C) will cause a syntax error; instead you should type (D):
| ?- assert(foo:-bar). (C)
| ?- assert((foo:-bar)). (D)
- When an assert takes place, the new clause is immediately seen by any subsequent call to the procedure. However, if there is a currently active call of the procedure at the time the
clause is asserted, the new clause is not encountered on backtracking by that call. See section G-14-6 for further explanation of what happens when currently running code is modified.
-
-
- Exceptions:
-
- instantiation_error
if Head (in Clause) or M is uninstantiated.
- type_error
if Head is not of type callable, or if M is not an atom, or if Body is not a valid clause body.
- permission_error
if the procedure corresponding to Head is built-in or has a static definition.
- context_error
if a cut appears in the if-part of an if-then-else.
- range_error
if Ref does not unify with the returned database reference.
-
-
- See Also:
-
abolish/[1,2], dynamic/1, erase/1, multifile_assertz/1 retract/1, retractall/1, clause/[2,3].
-
-
section G-14-2
L-3-22: assign/2
- Synopsis:
-
assign(+LHS, +Expr)
-
-
Evaluates Expr as an arithmetic expression, and stores the value in the memory location and format given by LHS.
- Arguments:
-
- LHS
-
<compound> One of the following terms
integer_8_at(L_Exp) integer_16_at(L_Exp)
unsigned_8_at(L_Exp) unsigned_16_at(L_Exp)
integer_at(L_Exp) address_at(L_Exp)
single_at(L_Exp) double_at(L_Exp)
L_Exp <expr> a valid arithmetic expression
- Expr
-
<expr> A valid arithmetic expression
-
-
- Description:
-
- Can be used to poke data directly into memory. Evaluates L_Exp in LHS and Expr as arithmetic expressions. The functor of the first argument describes the type of data to be stored:
integer_8_at/1 will store a signed 8 bit integer, single_at/1 will store a single precision floating point number, etc. For a more structured way of doing this, see the structs package.
- The only proper addresses that should be assigned to are ones that are obtained through the foreign interface. assign/2 is a very primitive built-in and users should have only very rare
occasions to use it. To directly access and change data structures represented in foreign languages (like C) users should look at using the structs library package.
- Both arguments can be unbound at compile time. But it is more efficient if LHS is bound at compile time. Also note that attempting to overwrite improper locations of memory can cause
"Segmentation faults" or "Bus errors" and overwriting Prolog memory can result in undesirable behaviour long after the assignment is done.
-
-
- Exceptions:
-
- instantiation_error
LHS or Expr is not ground.
- type_error
Expr is not a proper arithmetic expression or
L_Exp in LHS is not a proper arithmetic expressions or
Expr is of a different type than what is specified by LHS
- domain_error
LHS is not one of the above listed terms
- Examples:
-
IN THE C CODE:
static int counter;
int * init_counter()
{
counter = 0;
return &counter;
}
-
-
IN THE PROLOG CODE:
foreign(init_counter, c, init_counter([-address])).
get_counter(Counter, Count) :-
Count is integer_at(Counter).
incr_counter(Counter) :-
assign(integer_at(Counter),
integer_at(Counter)+1).
| ?- init_counter(C), incr_counter(C),
get_counter(C, Count1),
incr_counter(C), incr_counter(C),
get_counter(C, Count2).
C = 1418304,
Count1 = 1,
Count2 = 3
| ?-
- See Also:
-
section G-8-3
library(structs)
L-3-23: at_end_of_file/[0,1]
- Synopsis:
-
at_end_of_file
-
-
at_end_of_file(+Stream)
-
-
Tests whether end of file has been reached for the current input stream or for the input stream Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog input stream
-
-
- Description:
-
at_end_of_file/[0,1] checks if end of file has been reached for the specified input stream. An input stream reaches end of file when all characters except the file border code (-1 by
default) of the stream have been read. It remains at end of file after the file border code has been read.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- existence_error
Some operating system dependent error occurred in reading.
- Comments:
-
-
-
- at_end_of_file/[0,1] peeks ahead for next input character if there is no character available on the buffer of the specified input stream.
- Coding with at_end_of_file/[0,1] to check for end of file condition is more portable among different operating systems than checking end of file by the character code (for example,
peek_char(-1)).
- See Also:
-
at_end_of_line/[0,1].
L-3-24: at_end_of_line/[0,1]
- Synopsis:
-
at_end_of_line
-
-
at_end_of_line(+Stream)
-
-
Test whether end of line (record) has been reached for the current input stream or for the input stream Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog input stream
-
-
- Description:
-
- at_end_of_line/[0,1] succeeds when end of line (record) is reached for the specified input stream. An input stream reaches end of line when all the characters except the line border code
of the current line have been read.
- at_end_of_line/[0,1] is also true whenever at_end_of_file/[0,1] is true.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- existence_error
Some operating system dependent error occurred in reading.
- Comments:
-
-
-
- Coding with at_end_of_line/[0,1] to check for end of line is more portable among different operating systems than checking end of line by the input character code.
-
-
- See Also:
-
at_end_of_file/[0,1], skip_line/[0,1], get0/[1,2], set_input/1
L-3-25: atom/1 meta-logical
- Synopsis:
-
atom(+Term)
-
-
Term term is currently instantiated to an atom.
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- atom(pastor).
yes
| ?- atom(Term).
no
| ?- atom(1).
no
| ?- atom('Time').
yes
- See Also:
-
atomic/1, number/1, var/1, compound/1, callable/1, nonvar/1 simple/1
-
-
section G-1-1-3
L-3-26: atom_chars/2
- Synopsis:
-
atom_chars(+Atom, -Chars)
-
-
atom_chars(-Atom, +Chars)
-
-
Chars is the list of ASCII character codes comprising the printed representation of Atom.
- Arguments:
-
- Chars
-
<list of char> the list of ASCII character codes comprising the printed representation of Atom.
- Atom
-
<atom> will be instantiated to an atom containing exactly those characters, even if the characters look like the printed representation of a number.
- Description:
-
- Initially, either Atom must be instantiated to an atom, or Chars must be instantiated to a proper list of character codes (containing no variables).
- Any atom which can be read or written by Prolog can be constructed or decomposed by atom_chars/2.
- Comment:
-
If you deal with chars values often, you may find it useful to load library(printchars). Once this is done, a list of character codes will be written by print/1 as double-quoted text.
- Exceptions:
-
- Instantiation error
- Type error
- Representation error
- See Also:
-
print/1, library(printchars)
L-3-27: atomic/1
- Synopsis:
-
atomic(+Term)
-
-
Succeeds if Term is currently instantiated to either an atom number or a db_reference.
- Arguments:
-
- Term
-
<term>
- Example:
-
| ?- atomic(9).
yes
| ?- atomic(a).
yes
| ?- atomic("a").
no
| ?- assert(foo(1), Ref), atomic(Ref).
Ref = '$ref'(1195912,1)
- See Also:
-
atom/1, number/1, var/1, compound/1, callable/1, nonvar/1 simple/1
L-3-28: bagof/3
- Synopsis:
-
bagof(+Template, +*Generator, *Set)
-
-
Like setof/3 except that the list (or alternative lists) returned will not be ordered, and may contain duplicates. This relaxation saves time and space in execution.
- Arguments:
-
- Template
-
<term>
- Generator
-
<callable> a goal to be proved as if by call/1. MOD
- Set
-
<list of term> non-empty set
-
-
- Examples:
-
See findall/3 for examples that illustrate the differences among findall/3, setof/3, and bagof/3.
- Exceptions:
-
As for call/1:
- type error
- context error
- instantiation error
- See Also:
-
findall/3, setof/3, ^/2
-
-
Chapter G-15
L-3-29: break/0
- Synopsis:
-
break
-
-
causes the current execution to be interrupted; enters next break level.
- Description:
-
- The first time break/0 is called, it displays the message
[ Break level 1 ]
| ?-
- The system is then ready to accept input as though it were at top level. If another call to break/0 is encountered, it moves up to level 2, and so on. The break level is displayed in
the editor mode line when you are running under the editor interface; otherwise it is displayed on a separate line before each top-level prompt, as follows:
[1]
| ?-
- To close a break level and resume the execution which was suspended, type the end-of-file character applicable on your system (default ^D). break/0 then succeeds, and execution of the
interrupted program is resumed. Alternatively, the suspended execution can be abandoned by interrupting with a Control-C and using the 'q' option.
- Changes can be made to a running program while in a break level. Any change made to a procedure will take effect the next time that procedure is called. See section G-4-2, for details
of what happens if a procedure that is currently being executed is redefined. When a break level is entered, the debugger is turned off (although leashing and spypoints are retained).
When a break level is exited, the debugging state is restored to what it was before the break level was entered.
- Often used via the debugging option 'b'.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to break/0 as it would a call to any other undefined predicate, printing a warning.
If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
abort/0, halt/[0,1], QP_toplevel()
L-3-30: 'C'/3
- Synopsis:
-
'C'(+-List1, +-Terminal, +-List2)
-
-
In a grammar rule: Terminal connectsList1 and List2. It is defined by the clause 'C'([T|S], T, S).
- Arguments:
-
- List1
-
<term>
- List2
-
<term>
- Terminal
-
<term>
-
-
- Description:
-
Analyzes List1 into head and tail, and creates the tail, List2.
-
-
'C'/3 is not normally of direct use to the user. If its arguments are not of the expected form, it simply fails.
- Examples:
-
| ?- 'C'([the, slithy, toves, did, grob], Head, Tail).
Head = the,
Tail = [slithy,toves,did,grob] ;
no
-
-
See examples in section G-16-4.
- See Also:
-
Chapter G-16
L-3-31: call/1
- Synopsis:
-
call(+*P)
-
-
Proves(executes) P.
- Arguments:
-
- P
-
<callable> MOD
- Description:
-
- If P is instantiated to an atom or compound term, then the goal call(P) is executed exactly as if that term appeared textually in its place, except that any cut (!) occurring in P only
cuts alternatives in the execution of P.
-
-
- Exceptions:
-
- type error
- context error
- instantiation error
L-3-32: callable/1
- Synopsis:
-
callable(+Term)
-
-
Term is currently instantiated to a term that call/1 would take as an argument and not give a type error (an atom or a compound term).
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- callable(a).
yes
| ?- callable(a(1,2,3)).
yes
| ?- callable([1,2,3]).
yes
| ?- callable(1.1).
no
- See Also:
-
atom/1, atomic/1, number/1, var/1, compound/1, nonvar/1, simple/1
L-3-33: character_count/2
- Synopsis:
-
character_count(+Stream, -Count)
-
-
Obtains the total number of characters either input from or output to the open stream Stream and unifies it with Count.
- Arguments:
-
- Stream
-
<stream_object> a valid open Prolog stream
- Count
-
<integer> the resulting character count of the stream
-
-
- Description:
-
A freshly opened stream has a character count of 0. When a character is input from or output to a non-tty Prolog stream, the character count of the Prolog stream is increased by one.
Character count for a tty stream reflects the total character input from or output to the tty since the tty is opened to any stream. See section G-7-7-1, for details on the use of this
predicate on a stream which is directed to the user's terminal.
-
-
A nl/[0,1] operation also increases the character count of a stream by one unless the line border code (end_of_line option in open/4) is less than 0.
- Exceptions:
-
Stream errors (see section G-7-6-2).
- See Also:
-
line_count/2, line_position/2, stream_position/[2,3].
Chapter G-7
L-3-34: check_advice/[0,1]
- Synopsis:
-
check_advice
-
-
check_advice(+PredSpecs)
-
-
Enable advice checking.
- Arguments:
-
- PredSpecs
-
<gen_pred_spec_tree> A list of predicate specifications. MOD
-
-
- Description:
-
- check_advice/1 is used to enable advice checking on all predicates specified in PredSpecs. check_advice/0 enables advice checking on all predicates for which advice has been added.
When advice checking is enabled for a predicate, and execution of that predicate reaches an advised port, the term carrying the current instantiation of the Prolog call is unified against
the goal term of the advice. If the two unify, the action associated with the goal and port is executed then failed over. If there are multiple pieces of advice associated with the goal
and port, they are sequentially called and failed over.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to check_advice/[0,1] as it would a call to any other undefined predicate, printing
a warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Tips:
-
check_advice/0 behaves as though implemented by
-
-
check_advice :-
current_advice(Goal, Port, Action),
functor(Goal, Name, Arity),
check_advice(Name/Arity),
fail.
check_advice.
- See Also:
-
add_advice/3, remove_advice/3, current_advice/3, nocheck_advice/[0,1]
-
-
Chapter E-4
L-3-35: clause/[2,3]
- Synopsis:
-
clause(+*Head, *Body)
-
-
clause(-Head, -Body, +Ref)
-
-
clause(+*Head, *Body, *Ref)
-
-
Searches the data base for a clause whose head matches Head and whose body matches Body.
- Arguments:
-
- Head
-
<callable> a term whose functor names a dynamic procedure. MOD
- Body
-
<callable> compound term or true
- Ref
-
<db_reference> a database reference
- Description:
-
- In the case of unit-clauses, Body is unified with true.
- If a procedure consists entirely of unit-clauses then there is no point in calling clause/2 on it. It is simpler and faster to call the procedure.
- In clause/3, either Head or Ref must be instantiated. If Ref is instantiated, 'Head :- Body' is unified with the clause identified by Ref. (If this clause is a unit-clause, Body
is unified with 'true'.)
- If the functor of Head is a static predicate, clause/2 fails. If the predicate did not previously exist, then it is created as a dynamic predicate and clause/2 fails. If Ref is not
instantiated, clause/3 behaves exactly like clause/2 except that the database reference is returned.
- By default, clauses are accessed with respect to the source module.
- Backtracking:
-
Can be used to backtrack through all the clauses matching a given Head and Body. It fails when there are no (or no further) matching clauses in the database.
- Exceptions:
-
- instantiation error
Neither Head nor Ref is instantiated.
- type error
Head is not of type callable
Ref is not a syntactically valid database reference.
- permission error
Procedure is static (not dynamic).
- existence error
Ref is a well-formed database reference but does not correspond to an existing clause or record.
- Comments:
-
- If clause/[2,3] is called on an undefined procedure it fails, but before failing it makes the procedure dynamic. This can be useful if you wish to prevent unknown procedure catching from
happening on a call to that procedure.
- It is not a limitation that Head is required to be instantiated in clause(Head, Body), because if you want to backtrack through all clauses for all dynamic procedures this can be
achieved by:
| ?- predicate_property(P,(dynamic)), clause(P,B).
- If there are clauses with a given name and arity in several different modules, or if the module for some clauses is not known, the clauses can be accessed by first finding the module(s) by
means of current_predicate/2. For example, if the procedure is f/1:
| ?- current_predicate(_,M:f(_)), clause(M:f(X),B).
- clause/3 will only access clauses which are defined in, or imported into, the source module, except that the source module can be overridden by explicitly naming the appropriate module.
For example:
| ?- assert(foo:bar,R).
R = '$ref'(771292,1)
| ?- clause(H,B,'$ref'(771292,1)).
no
| ?- clause(foo:H,B,'$ref'(771292,1)).
H = bar,
B = true
| ?-
- Accessing a clause using clause/2 uses first argument indexing when possible, in just the same way that calling a procedure uses first argument indexing. See section B-5-2.
-
-
- See Also:
-
instance/2, assert/[1,2], dynamic/1, retract/1
-
-
Chapter G-14-2
L-3-36: close/1
- Synopsis:
-
close(+Stream)
-
-
closes the stream corresponding to Stream.
- Arguments:
-
- Stream
-
<stream_object> stream or file specification
-
-
- Description:
-
- If Stream is a stream object, then if the corresponding stream is open, it will be closed; otherwise, close/1 succeeds immediately, taking no action.
- If Stream is a file specification, the corresponding stream will be closed, provided that the file was opened by see/1 or tell/1.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Instantiation error
- Permission error
File not opened by see/1 or tell/1.
- Examples:
-
- See Also:
-
see/1, tell/1, open/[3,4], write_canonical/[1,2]
L-3-37: compare/3
- Synopsis:
-
compare(-Order, +Term1, +Term2)
-
-
succeeds if the result of comparing terms Term1 and Term2 is Order
- Arguments:
-
- Order
-
one of {=, <, >}
'=' if Term1 is identical to Term2,
'<' if Term1 is before Term2 in the standard order,
'>' if Term1 is after Term2 in the standard order.
- Term1
-
<term>
- Term2
-
<term>
- Description:
-
- The standard total order is as follows. For further details see section G-9-7-1.
variables @< database references @< numbers @< atoms
@< compound terms
- The goal (A) is equivalent to (B):
| ?- compare(=, Term1, Term2). (A)
|?- (Term1 == Term2). (B)
- The following query succeeds, binding R to <, because 1 comes before 2 in the standard order.
| ?- compare(R, 1, 2).
R = <
- If Order is supplied, and is not one of '<', '>', or '=', compare/3 simply fails.
-
-
- See Also:
-
@</2, @=</2, @>/2, @>=/2, QP_compare()
Chapter G-9
L-3-38: compile/1
- Synopsis:
-
compile(+Files)
-
-
Compiles the specified Prolog source file(s) into memory.
- Arguments:
-
- Files
-
<file_spec or list of file_spec> a file specification or a list of file specifications; a ".pl" extensions may be omitted in file specifications. MOD
- Description:
-
-
- Exceptions:
-
Same as for load_files/[1,2]
- See Also:
-
multifile/1, dynamic/1, no_style_check/1, style_check/1, nofileerrors/0, fileerrors/0, source_file/1, term_expansion/2, prolog_load_context/2, load_files/[1,2], ensure_loaded/1,
use_module/[1,2,3], volatile/1, initialization/1.
L-3-39: compound/1
- Synopsis:
-
compound(+Term)
-
-
Term is currently instantiated to a compound term.
- Arguments:
-
- Term
-
<term>
- Examples:
-
-
-
| ?- compound(9).
no
| ?- compound(a(1,2,3)).
yes
| ?- compound("a").
yes
| ?- compound([1,2]).
yes
- See Also:
-
atom/1, atomic/1, number/1, var/1, callable/1, nonvar/1, simple/1
L-3-40: consult/1
- Synopsis:
-
consult(+Files)
-
-
Same as compile/1
- Arguments:
-
- Files
-
<file_spec or list of file_spec> . MOD
- See Also:
-
compile/1, load_files/[1,2].
L-3-41: copy_term/2 meta-logical
-
-
-
-
- Synopsis:
-
copy_term(+Term, -Copy)
-
-
Makes a copy of +Term in which all variables have been replaced by new variables which occur nowhere outside the newly created term.
- Arguments:
-
- Term
-
<term>
- Copy
-
<term>
- Description:
-
-
This is precisely the effect which would have been obtained from the definition below, although the system implementation of copy_term/2 is more efficient.
copy_term(Term, Copy) :-
recorda(copy, copy(Term), DBref),
instance(DBref, copy(Temp)),
erase(DBref),
Copy = Temp.
- When you call clause/[2,3] or instance/2, you get a new copy of the term stored in the data base, in precisely the same sense that copy_term/2 gives you a new copy.
- Used in writing interpreters for logic-based languages.
- Example:
-
- A naive way to attempt to find out whether one term is a copy of another:
identical_but_for_variables(X, Y) :-
\+ \+ (
numbervars(X, 0, N),
numbervars(Y, 0, N),
X = Y
).
This solution is sometimes sufficient, but will not work if the two terms have any variables in common.
- If you want the test to succeed even when the two terms do have some variables in common, you need to copy one of them; for example,
identical_but_for_variables(X, Y) :-
\+ \+ (
copy_term(X, Z),
numbervars(Z, 0, N),
numbervars(Y, 0, N),
Z = Y
).
-
-
- See Also:
-
atomic/1, float/1, integer/1, nonvar/1, number/1, var/1, simple/1, compound/1, callable/1, ground/1, simple/1, db_reference/1.
L-3-42: current_advice/3
- Synopsis:
-
current_advice(*Goal, *Port, *Action)
-
-
Provides a means for checking what advice is present.
- Arguments:
-
- Goal
-
<callable> any term. MOD
- Port
-
one of {call, exit, done, redo, fail}; any term.
- Action
-
<callable> any term. MOD
-
-
- Description:
-
- Unifies Goal with the goal term, Port with the port, and Action with the action term of currently existing user-defined advice. None of the three arguments need to be instantiated.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to current_advice/3 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Tips:
-
To backtrack through all the advice that exists for a predicate mypred/2, you can use the goal
-
-
| ?- current_advice(mypred(_,_), Port, Action).
-
-
If you are only interested in the advice for mypred/2 on the call port, use
-
-
| ?- current_advice(mypred(_,_), call, Action).
-
-
To determine what predicates you told to call format/2, use
-
-
| ?- current_advice(Goal, Port, format(_,_)).
- See Also:
-
add_advice/3, remove_advice/3, check_advice/[0,1], nocheck_advice/[0,1]
L-3-43: current_atom/1 meta-logical
- Synopsis:
-
current_atom(+Atom)
-
-
current_atom(*Atom)
-
-
Atom is a currently existing atom.
- Arguments:
-
- Atom
-
<atom>
- Backtracking:
-
If Atom is uninstantiated, current_atom/1 can be used to enumerate all known atoms. The order in which atoms are bound to Atom on backtracking corresponds to the times of their creation.
- Comments:
-
- Note that the predicate atom/1 is recommended for determining whether a term is an atom, as current_atom/1 will succeed if Atom is uninstantiated as well.
- See Also:
-
atom/1
L-3-44: current_input/1
- Synopsis:
-
current_input(-Stream)
-
-
unifies Stream with the current input stream.
- Arguments:
-
- Stream
-
<stream_object>
- See Also:
-
open/[3,4], see/1, seeing/1
-
-
Chapter G-7-6-5
L-3-45: current_key/2
- Synopsis:
-
current_key(*KeyName, *KeyTerm)
-
-
Succeeds when KeyName is the name of KeyTerm, and KeyTerm is a recorded key.
- Arguments:
-
- KeyName
-
<atomic> either of:
- KeyTerm, if KeyTerm is an atom or an integer; or
- the principal functor of KeyTerm, if KeyTerm is a compound term.
- KeyTerm
-
<nonvar> is an integer, atom, or compound term which is the key for a currently recorded term.
-
-
- Description:
-
If KeyName is not an atom, an integer, or an unbound variable, current_key/2 fails. If KeyTerm is not a current key, current_key/2 simply fails.
- See Also:
-
recorda/3, recorded/3, recordz/3,
L-3-46: current_module/[1,2]
- Synopsis:
-
current_module(+ModuleName)
-
-
current_module(*ModuleName)
-
-
Queries whether a module is "current" or backtracks through all of the current modules.
-
-
current_module(+ModuleName, -AbsFile)
-
-
current_module(-ModuleName, +AbsFile)
-
-
current_module(*ModuleName, *AbsFile)
-
-
Associates modules with their module-files.
- Arguments:
-
- ModuleName
-
<atom>
- AbsFile
-
<atom> absolute file name
-
-
- Description:
-
- A loaded module becomes "current" as soon as some predicate is defined in it, and a module can never lose the property of being current.
- It is possible for a current module to have no associated file, in which case current_module/1 will succeed on it but current_module/2 will fail. This arises for the special module
'user' and for dynamically-created modules (see section G-13-8).
- If its arguments are not correct, or if Module has no associated file, current_module/2 simply fails.
-
-
- Backtracking:
-
current_module/1 backtracks through all of the current modules. The following command will print out all current modules:
| ?- current_module(Module), writeq(Module), nl, fail.
-
-
current_module/2 backtracks through all of the current modules and their associated files.
- Exceptions:
-
-
- See Also:
-
module/1, module/2
L-3-47: current_output/1
- Synopsis:
-
current_output(-Stream)
-
-
Unifies Stream with the current output stream.
- Arguments:
-
- Stream
-
<stream_object>
- See Also:
-
open/[3,4], tell/1, telling/1
L-3-48: current_op/3
- Synopsis:
-
current_op(+Precedence, +Type, +Name)
-
-
current_op(*Precedence, *Type, *Name)
-
-
Succeeds when the atom Name is currently an operator of type Type and precedence Precedence.
- Arguments:
-
- Precedence
-
<integer> if instantiated, must be an integer in the range 1 to 1200.
- Type
-
one of {xfx, xfy, yfx, fx,xf, yf} if instantiated.
- Name
-
<atom> atom or a list of atoms if instantiated.
- Description:
-
- None of the arguments need be instantiated at the time of the call; that is, this predicate can be used to find the precedence or type of an operator or to backtrack through all operators.
- To add or remove an operator, use op/3.
- Exceptions:
-
- Type Error
Name not an atom or Type not an atom or Precedence not an integer
- Domain Error
Precedence not between 1-1200
Type not one of listed atoms
-
-
- See Also:
-
op/3
-
-
section G-1-4.
L-3-49: current_predicate/2
- Synopsis:
-
current_predicate(-Name, +Term)
-
-
current_predicate(*Name, *Term)
-
-
Unifies Name with the name of a user-defined predicate, and Term with the most general term corresponding to that predicate.
- Arguments:
-
- Name
-
<atom>
- Term
-
<callable> MOD
- Description:
-
- Backtracking:
-
- The following goal can be used to backtrack through every predicate in your program.
| ?- current_predicate(Name, Module:Term).
- If a module is specified, current_predicate/2 only succeeds for those predicates which are defined in the module. It fails for those predicates which are imported into a module.
| ?- current_predicate(_, m:P).
will backtrack through all predicates P which are defined in module m. To backtrack through all predicates imported by a module use predicate_property/2 (section G-10).
-
-
- Tip:
-
To find out whether a predicate is built-in, use predicate_property/2.
Is there a callable predicate named
'gc'?
| ?- current_predicate(gc, Term).
no
| ?- predicate_property(gc, Prop)
Prop = built_in
- See Also:
-
predicate_property/2
L-3-50: current_spypoint/1
- Synopsis:
-
current_spypoint(*Spyspec)
-
-
Determines if there is currently a spypoint on a particular predicate or call, or enumerates all current spypoints.
- Arguments:
-
- Spyspec
-
<compound> can be any Prolog term. Prolog will try to unify it to terms of the form:
- predicate(Pred)
-
A spypoint on any call to Pred. Pred will be a skeletal predicate specification, and may be module qualified.
- call(Caller,Clausenum,Callee,Callnum)
-
A spypoint on the Callnum call to Callee in the body of the Clausenum clause of Caller. Callee and Callnum will be skeletal predicate specifications section E-1-3-2.
Callnum and Clausenum will be integers, and begin counting from 1. Note that Callnum specifies a lexical position, that is, the number of the occurrence of Callee counting
from the beginning of the body of the clause, and ignoring any punctuation.
-
-
- Description:
-
This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to current_spypoint/1 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Backtracking:
-
Can generate all current spypoints on backtracking.
- See Also:
-
add_spypoint/1, remove_spypoint/1, spy/1, nospy/1, debugging/0
-
-
Chapter E-1.
L-3-51: current_stream/3
- Synopsis:
-
current_stream(-AbsFile, -Mode, +Stream)
-
-
current_stream(*AbsFile, *Mode, *Stream)
-
-
Stream is a stream which is currently open on file AbsFile in mode Mode.
- Arguments:
-
- AbsFile
-
<atom> absolute file name.
- Mode
-
one of {read, write, append}
- Stream
-
<stream_object> a term which will be unifed with an open stream.
- Description:
-
- None of the arguments need be initially instantiated.
- Ignores the three special streams for the standard input, output, and error channels.
- Backtracking:
-
Can be used to backtrack through all open streams.
- See Also:
-
open/[3,4], see/1, tell/1
-
-
section G-7-6-7
L-3-52: db_reference/1
- Synopsis:
-
db_reference(+Term)
-
-
Term is a db_reference.
- Arguments:
-
- Term
-
<term>
- See Also:
-
recorda/3, assert/2, atom/1, atomic/1, number/1, var/1, compound/1, callable/1, nonvar/1, simple/1
L-3-53: debug/0
- Synopsis:
-
debug
-
-
Turns on the debugger in debug mode.
- Description:
-
- debug/0 turns the debugger on and sets it to debug mode. Turning the debugger on in debug mode means that it will stop at the next spypoint encountered in the current execution.
- The effect of this predicate can also be achieved by typing the letter 'd' after a ^c interrupt (see section G-11-1).
- If you are runnning Prolog with QUI then debug/0 will cause the debugger window to be popped open.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to debug/0 as it would a call to any other undefined predicate, printing a warning.
If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
spy/1,add_spypoint/1,trace/0, nodebug/0
L-3-54: debugging/0
- Synopsis:
-
debugging
-
-
Prints out current debugging state
- Description:
-
debugging/0 displays information on the terminal about the current debugging state. It shows
- the top-level state of the debugger, which is one of
- debug
-
The debugger is on but will not show anything or stop for user interaction until a spypoint is reached.
- trace
-
The debugger is on and will show everything. As soon as you type a goal, you will start seeing a debugging trace. After printing each trace message, the debugger may or may not
stop for user interaction: this depends on the type of leashing in force (see below).
- zip
-
The debugger is on but will not show anything or stop for user interaction until a spypoint is reached. The debugger does not even keep any information of the execution of the
goal till the spypoint is reached and hence you will not be able to see the ancestors of the goal when you reach the spypoint.
- off
-
The debugger is off.
The top-level state can be controlled by the predicates debug/0, nodebug/0, trace/0, notrace/0 and prolog_flag/3.
- The type of leashing in force. When the debugger prints a message saying that it is passing through a particular port (one of Call, Exit, Head, Done, Redo, or Fail) of a particular
procedure, it stops for user interaction only if that port is leashed. The predicate leash/1 can be used to select which of the seven ports you want to be leashed.
- All the current spypoints. Spypoints are controlled by the predicates spy/1, nospy/1, add_spypoint/1, remove_spypoint/1 and nospyall/0.
-
-
This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to debugging/0 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
L-3-55: discontiguous/1 declaration
- Synopsis:
-
:- discontiguous +PredSpec
-
-
Declares the clauses of the predicates defined by PredSpecs to be discontiguous in the source file (suppresses compile-time warnings).
- Arguments:
-
- PredSpec
-
<gen_pred_spec_tree> a skeletal predicate specification
-
-
- Exceptions:
-
- Type error
- context error
"declaration appeared in query"
-
-
- See Also:
-
Section section G-14-1.
L-3-56: display/1
- Synopsis:
-
display(+Term)
-
-
Displays Term on the standard output stream .
- Arguments:
-
- Term
-
<term>
- Description:
-
- Ignores operator declarations and shows all compound terms in standard prefix form.
- Tips:
-
- Example:
-
| ?- display(a+b).
+(a,b)
yes
-
-
read(X), display(X), nl.
|: a + b * c.
+(a,*(b,c))
X = a+b*c
| ?-
- See Also:
-
write/[1,2], write_term/[2,3]
L-3-57: dynamic/1 declaration
- Synopsis:
-
:-dynamic +PredSpecs
-
-
Declares the predicates in PredSpecs to be dynamic.
- Arguments:
-
- PredSpecs
-
<pred_spec_forest> A single predicate specification of the form Name/Arity, or a sequence of predicate specifications separated by commas. Name must be an atom and Arity an
integer in the range 0..255. MOD
-
-
- Description:
-
-
- Exceptions:
-
- Type error
- context error
If the declaration contradicts previous declaration or clauses for the same predicate in the file.
cannot call dynamic/1 as a goal.
- Permission error
Cannot redefine built-in predicate, dynamic/1.
- Comments:
-
To declare a grammar rule gram/n dynamic, the arity of PredSpec must be n+2.
- See Also:
-
Chapter G-14-1.
L-3-58: ensure_loaded/1
- Synopsis:
-
ensure_loaded(+Files)
-
-
Load the specified Prolog source and/or QOF file(s) into memory, if not already loaded and up to date.
- Arguments:
-
- Files
-
<file_spec or list of file_spec> a file specification or a list of file specifications; a ".pl" or ".qof" extension may be omitted in a file specification. MOD
- Description:
-
-
- Exceptions:
-
- instantiation_error
M or Files is not ground.
- type_error
In M or in Files.
- existence_error
A specified file does not exist. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
- permission_error
A specified file is protected. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
-
-
- See Also:
-
compile/1, load_files/[1,2].
L-3-59: erase/1
- Synopsis:
-
erase(+Ref)
-
-
Erases from the data base the dynamic clause or recorded term referenced by Ref.
- Arguments:
-
- Ref
-
<db_reference>
-
-
- Description:
-
- Erases from the database the dynamic clause or recorded term referenced by Ref. (Recorded terms are described in section G-14-7.)
- Ref must be a database reference to an existing clause or recorded term.
- erase/1 is not sensitive to the source module; that is, it can erase a clause even if that clause is neither defined in nor imported into the source module.
-
-
- Exceptions:
-
- instantiation_error
If Ref is not instantiated.
- type_error
If Ref is not a data base reference.
- existence_error
if Ref is not a database reference to an existing clause or recorded term.
-
-
- See Also:
-
-
-
abolish/[1,2], assert/2, dynamic/1, retract/1, retractall/1.
L-3-60: expand_term/2 hookable
- Synopsis:
-
expand_term(+Term1, -Term2)
-
-
Transforms grammar rules into Prolog clauses before they are compiled. Normally called by the compiler, but can be called directly. The transform can be customized by defining the hook
term_expansion/2.
- Arguments:
-
- Term1
-
<term>
- Term2
-
<term>
- Description:
-
- Usually called by the built-in Load Predicates and not directly by user programs.
- Normally used to translate grammar rules, written with -->/2, into ordinary Prolog clauses, written with :-/2. If Term1 is a grammar rule, then Term2 is the corresponding
clause. Otherwise Term2 is simply Term1 unchanged.
- If Term1 is not of the proper form, or if Term2 does not unify with its clausal form, expand_term/2 simply fails.
- Calls term_expansion/2.
- Exceptions:
-
Prints messages for exceptions raised by term_expansion/2.
- Examples:
-
See examples in section G-16-4.
- See Also:
-
term_expansion/2, phrase/[2,3], 'C'/3, -->/2
Chapter G-16
L-3-61: extern/1 declaration
- Synopsis:
-
:-extern(+ExternSpec)
-
-
Declares a Prolog predicate to be callable from functions written in other languages.
- Arguments:
-
- ExternSpec
-
<extern_spec> a term of the form Name(Argspec, Argspec, ...) MOD
-
-
- Name
-
the name of the Prolog predicate
- Argspec
-
an argument specification for each argument of the predicate. Each should be one of the following where T is a foreign type name.
+integer +float +single +double
-integer -float -single -double
+atom +term +string
-atom -term -string
+string +address(T)
-string -address(T)
-
-
-
-
- Description:
-
- extern/1 is used to make Prolog predicates callable from functions written in other languages. extern/1 must appear as a compile-time declaration; furthermore, it may not appear in
files loaded into runtime systems. The user has to declare as callable each Prolog predicate that is to be called from foreign functions. Any Prolog predicate can be declared to be
callable from foreign functions, including system built-ins and predicates that do not currently have definitions. Predicates must be declared callable before they can actually be called
from a function written in a foreign language.
- Arguments are passed to the foreign interface as specified in ExternSpec:
- +
-
indicates that an argument is to be passed to Prolog from a foreign function.
- -
-
indicates that an argument is to be passed from Prolog to the foreign function.
- Unlike the interface enabling Prolog to call functions written in other languages, when foreign functions call Prolog there are no return values or corresponding designators in
ExternSpec.
- When a Prolog predicate is declared to be callable, an interface predicate is created in the current module. The arity of the interface predicate is the same as that of the Prolog
predicate. The name of the interface predicate is that of the Prolog predicate with an underscore prepended. The interface predicate is made available to the user as a hook to the
"callability" of the Prolog predicate; for instance, the callability of the predicate can be saved by putting the interface predicate in a QOF file via save_predicates/2, then reloaded
like any other predicate. The interface predicate can also be abolished like any other predicate; this also has the effect of making the previously callable Prolog predicate no longer
available to foreign functions. A call to any interface predicate simply fails.
- For more details about passing arguments from the foreign interface, see the chapter on the foreign language interface.
- Exceptions:
-
- instantiation error
ExternSpec is uninstantiated
Some Argspec in ExternSpec is uninstantiated or is a term that is insufficiently instantiated
- type error
ExternSpec is instantiated but is not a callable term
Some Argspec in ExternSpec is not a callable term
- domain error
Some Argspec in ExternSpec is not one of the forms listed above
- Examples:
-
It can be quite useful to make the system built-in call/1 available to foreign functions. Combined with term manipulation in C, doing so provides an evaluator for arbitrary Prolog queries.
This can be done by loading a Prolog file containing the declaration
-
-
:- extern(call(+term)).
-
-
Prolog's call/1 is then available to C via a function like
-
-
call_prolog(term)
QP_term_ref term;
{
QP_pred_ref call;
call = QP_predicate("call",1,"user");
QP_query(call, term);
}
-
-
For the sake of brevity, this example does not check return values for failure or errors. Doing so is generally recommended. Of course, as is the case in Prolog, it is faster to call a
Prolog predicate directly.
L-3-62: fail/0
- Synopsis:
-
fail
-
-
Always fails.
L-3-63: false/0
- Synopsis:
-
false
-
-
Same as fail/0.
L-3-64: file_search_path/2 extendable
- Synopsis:
-
-
-
file_search_path(*PathAlias, *DirSpec)
-
-
Defines a symbolic name for a directory or a path. Used by predicates taking file_spec as input argument.
- Arguments:
-
- PathAlias
-
<atom> A string which represents the path given by DirSpec.
- DirSpec
-
<file_spec> Either a string giving the path to a file or directory, or PathAlias(DirSpec), where PathAlias is defined by another file_search_path/2 rule.
-
-
- Description:
-
-
- Examples:
-
| ?- assert(file_search_path(home, '/usr/joe_bob')).
yes
| ?- assert(file_search_path(review, home('movie/review'))).
yes
| ?- compile(review(blob)).
% compiling /usr/joe_bob/movie/review/blob.pl
- See Also:
-
absolute_file_name/[2,3], assert/[1,2], dynamic/1, library_directory/1, listing/1, load_files/[1,2],
-
-
Chapter G-6.
L-3-65: fileerrors/0
- Synopsis:
-
fileerrors
-
-
Cancels the effect of nofileerrors/0.
- Description:
-
- Sets the 'fileerrors' flag to its default state in which an exception is raised by see/1, tell/1, and open/3 if the specified file cannot be opened.
- The 'fileerrors' flag is only disabled by an explicit call to nofileerrors/0, or via prolog_flag/[2,3] which can also be used to obtain the current value of the fileerrors flag. See section G-10, for more information on the fileerrors flag.
- See Also:
-
nofileerrors/0, prolog_flag/[2,3]
L-3-66: findall/3
- Synopsis:
-
findall(+Template, +*Generator, -List)
-
-
Collects in List all the instances of Template for which the goal Generator succeeds. A special case of bagof/3, where all free variables in the generator are taken to be existentially
quantified.
- Arguments:
-
- Template
-
<term>
- Generator
-
<callable> a goal to be proved as if by call/1. MOD
- List
-
<list of terms>
- Description:
-
- A special case of bagof/3, where all free variables in the generator are taken to be existentially quantified, as if by means of the ^ operator.
- Because findall/3 avoids the relatively expensive variable analysis done by bagof/3, using findall/3 where appropriate rather than bagof/3 can be considerably more efficient.
- Examples:
-
To illustrate the differences among findall/3, setof/3, and bagof/3:
| ?- [user].
| foo(1,2).
| foo(1,2).
| foo(2,3).
|
% user compiled in module user, 0.100 sec 352 bytes
yes
| ?- bagof(X, foo(X,Y), L).
X = _3342,
Y = 2,
L = [1,1] ;
X = _3342,
Y = 3,
L = [2] ;
no
-
-
| ?- bagof(X, Y^foo(X,Y), L).
X = _3342,
Y = _3361,
L = [1,1,2] ;
no
-
-
| ?- findall(X, foo(X,Y), L).
X = _3342,
Y = _3384,
L = [1,1,2] ;
no
-
-
| ?- setof(X, foo(X,Y), L).
X = _3342,
Y = 2,
L = [1] ;
X = _3342,
Y = 3,
L = [2] ;
no
| ?-
- Exceptions:
-
As for call/1:
- type error
- context error
- instantiation error
- See Also:
-
setof/3, bagof/3, ^/2
-
-
Chapter G-15
L-3-67: float/1 meta-logical
- Synopsis:
-
float(+Term)
-
-
Term is currently instantiated to a float.
- Arguments:
-
- Term
-
<term>
- Example:
-
| ?- float(Term1).
no
| ?- float(5.2).
yes
- See Also:
-
atom/1, atomic/1, number/1, var/1, compound/1, callable/1, nonvar/1, simple/1
L-3-68: flush_output/1
- Synopsis:
-
flush_output(+Stream)
-
-
Forces the buffered output of the stream Stream to be sent to the associated device.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream
-
-
- Description:
-
- Sends the current buffered output of an output stream Stream to the actual output device which is usually a disk or a tty device. flush_output/1 fails if Stream does not permit
flushing or the bottom layer flushing function of Stream is not properly defined.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- type_error
- permission_error
An error occurred in flushing out the buffered output.
-
-
- Comments:
-
If the host operating system, such as UNIX, buffers an output file stream, the output may be written to the disk some time after flush_output/1 succeeds.
- See Also:
-
nl/[0,1], QP_flush(), QU_flush_output(), ttyflush/0
L-3-69: foreign/[2,3] hook
- Synopsis:
-
foreign(*Routine, *ForeignSpec)
-
-
foreign(*Routine, *Language, *ForeignSpec)
-
-
Describes the interface between Prolog and the foreign Routine. The user has to define a foreign/3 or the fact for every foreign function that is to be called from Prolog. Used by
load_foreign_files/2 and load_foreign_executable/2.
- Arguments:
-
- Routine
-
<atom> An atom that names a foreign code Routine
- Language
-
<atom> An atom that names the Language in which Routine is written. It must be one of 'c', 'pascal' or 'fortran'.
- ForeignSpec
-
<foreign_spec> A term of the form PredName(Argspec, Argspec, ...) where:
-
-
- PredName
-
the name of the Prolog predicate
- Argspec
-
an argument specification (for each argument of the predicate) One of the following:
+integer +float +single +double
-integer -float -single -double
[-integer] [-float] [-single] [-double]
+atom +term +string
-atom -term -string
[-atom] [-term] [-string]
+string(N) +address(T)
-string(N) -address(T)
[-string(N)] [-address(T)]
-
-
where N is a positive integer and T is a foreign type name.
-
-
- Description:
-
- foreign/2 is a special case of foreign/3 where Language is C. foreign/2 is for backward compatibility.
- The user has to define a foreign/3 fact for every foreign function that is to be called from Prolog. Note that Routine does not have to be the same as PredicateName. Arguments are
passed to the foreign function as specified in ForeignSpecs
- +type
-
specifies that an argument is to be passed to the foreign function.
- -type
-
specifies that an argument is to be received from the foreign function.
- [-type]
-
argument is used to obtain the return value of a foreign function call. At most one "return value" argument can be specified.
For more details about the passing arguments through the foreign interface, see Chapter I-4-2-1.
- The foreign/3 facts are used only in the context of a load_foreign_files/2 command and can be removed once the foreign files are loaded.
- If you have foreign/3 facts in different files, Prolog will warn you that foreign/3 has been previously defined in another file. This is generally not a problem if you are using the
module system.
- load_foreign_files/2 will only look for foreign/3 facts defined in its source module.
-
-
- Exceptions:
-
Errors in the specification of foreign/3 will only be detected at load_foreign_files/2 time. Otherwise defining a foreign/3 fact is just like defining any other Prolog fact.
- Tips:
-
A good practice in loading several foreign files is to insert the call to load_foreign_files/2 into the file which defines foreign/3 as an embedded command. For example,
foreign(f11, c, f11(+integer)).
foreign(f12, c, f12(+atom, -atom)).
foreign_file('f1.o', [f11, f12]).
:- load_foreign_files('f1.o', []),
abolish([foreign/3,foreign_file/2]).
- Examples:
-
Solve() is a C function that takes three integer coeffecients of a quadratic equation and returns the two solutions. We assume that the solutions are not imaginary numbers.
-
-
IN THE PROLOG CODE:
foreign(solve, c, solve(+integer, +integer, +integer,
-double, -double)).
foreign_file('a.o', [solve]).
:- load_foreign_files(['a.o'], ['-lm']),
abolish([foreign/3, foreign_file/2]).
-
-
IN THE C CODE:
-
-
void solve(a, b, c, f1, f2)
long int a, b, c;
double *f1;
double *f2;
{
*f1 = (-b + sqrt(b*b - 4*a*c)) / 2 * a;
*f2 = (-b - sqrt(b*b - 4*a*c)) / 2 * a;
}
- See Also:
-
load_foreign_files/2, foreign_file/2, extern/1
Chapter I-3
L-3-70: foreign_file/2 hook
- Synopsis:
-
foreign_file(+ObjectFile, +ForeignFunctions)
-
-
Describes the foreign functions in ObjectFile to interface to. The user has to define a foreign_file/2 fact for every object file that is to be loaded into Prolog.
- Arguments:
-
- ObjectFile
-
<file_spec> The foreign object (.o) file
- ForeignFunctions
-
<list of atoms> A list of foreign function symbols that will be obtained from ObjectFile.
- Description:
-
- The user has to define a foreign_file/2 fact for every object file that is to be loaded into Prolog. The ForeignFunctions gives the list of foreign symbols that are to be found in the
given object file. When a foreign file is loaded using load_foreign_files/2, Prolog looks for a foreign_file/2 fact for that object file and finds the address of each symbol listed in
the foreign_file/2 fact. Prolog also expects a foreign/3 definition for each symbol in the second argument of the foreign_file/2 fact.
- For more details about the foreign interface, see Chapter I-3-2-2.
- The foreign_file/2 facts are used only in the context of a load_foreign_files/2 command and can be removed once the foreign files are loaded.
- If you have foreign_file/2 facts in different files, Prolog will warn you that foreign_file/2 has been previously defined in another file.
- load_foreign_files/2 will only look for foreign_file/2 facts defined in its source module.
-
-
- Exceptions:
-
Errors in the specification of foreign_file/2 will only be detected when load_foreign_files/2 is called. Otherwise defining a foreign_file/2 fact is just like defining any other Prolog
fact.
- Examples:
-
See example under foreign/[2,3].
- Tips:
-
See Tip under foreign/[2,3]
- See Also:
-
load_foreign_files/2, foreign/[2,3]
L-3-71: format/[2,3]
- Synopsis:
-
format(+Control, +Arguments)
-
-
format(+Stream, +Control, +Arguments)
-
-
Interprets the Arguments according to the Control string and prints the result on the current or specified output stream.
- Arguments:
-
- Stream
-
<stream_object>
- Control
-
<list of char> or <atom> either an atom or a string which can contain control sequences of the form '~<n><c>'
-
-
- <c>
-
a format control option
- <n>
-
is its optional argument.
<n> must be a non-negative integer.
-
-
-
-
Any characters that are not part of a control sequence are written to the current output stream.
- Arguments
-
<term> list of arguments which will be interpreted and possibly printed by format control options. If there is only one argument then this argument need not be enclosed in a
list.
-
-
- Description:
-
- Note: In the case where there is only one argument and that argument is a list, then that argument must be enclosed in a list.
- If <n> can be specified, then it can be the character '*'. In this case <n> will be taken as the next argument from Arguments.
- The following control options cause formatted printing of the next element from Arguments to the current output stream. The argument must be of the type specified, or format/1 will
raise a consistency error.
- ~<n>a
-
argument is an atom which is printed without quoting. The maximum number of characters printed is <n>. If <n> is omitted the entire atom is printed.
| ?- format('~a', foo).
foo
- ~<n>c
-
argument is a numeric ASCII code (0 =< code =< 127) which is printed <n> times. If <n> is omitted, it defaults to 1.
| ?- format('~2c', 97).
aa
- ~<n>e
-
argument is a floating-point number which is printed in exponential notation with precision <n>. The form of output is (in left-to-right order):
an optional '-',
a digit,
a '.' if <n> is greater than 0,
<n> digits,
an 'e',
a '+' or a '-', and
two or more digits.
If <n> is omitted, it defaults to 6.
| ?- format('~3e', 1.33333).
1.333e+00
See section G-8 for detailed information on precision.
NOTES:
- '~<n>e' coerces integers to floats
- If n is greater than 60, only 60 digits will be printed.
- ~<n>E
-
same as ~<n>e, except 'E' is used for exponentiation instead of 'e'.
| ?- format('~3E', 1.33333).
1.333E+00
- ~<n>f
-
argument is a floating-point number which is printed in non-exponential format, with <n> digits to the right of the decimal point. If <n> is omitted, it defaults to 6. If <n> is
equal to 0, no decimal point is printed.
| ?- format('~3f', 1.33333).
1.333
NOTES:
- '~<n>f' coerces integers to floats
- If n is greater than 60, only 60 digits will be printed.
See the section on floating-point arithmetic for detailed information on precision.
- ~<n>g
-
argument is a floating-point number which is printed in either ~<n>e or ~<n>f form, whichever gives the best precision in minimal space, with the exception that no trailing zeroes
are printed unless one is necessary immediately after the decimal point to make the resultant number syntactically valid. At most <n> significant digits are printed. If <n> is
omitted, it defaults to 6.
| ?- format('~g', 1000000000.0).
1e+09
| ?- format('~20g', 1000000000.0).
1000000000
See the section on floating-point arithmetic for detailed information on precision.
- ~<n>G
-
same as ~<n>g, except 'E' is used for exponentiation instead of 'e'.
| ?- format('~G', 1000000.0).
1E+06
- ~<n>d
-
argument is an integer, which is printed as a signed decimal number, shifted right <n> decimal places. If <n> is omitted, it defaults to 0. If <n> is 0, the decimal point is not
printed.
| ?- format('~d', 29).
29
| ?- format('~1d', 29).
2.9
- ~<n>D
-
same as ~<n>d, except that commas are inserted to separate groups of three digits to the left of the decimal point.
| ?- format('~1D', 29876).
2,987.6
- ~<n>r
-
argument is an integer, which is printed in radix <n> (where 2 =< n =< 36) using the digits 0-9 and the letters a-z. If <n> is omitted, it defaults to 8.
| ?- format('~2r', 13).
1101
| ?- format('~r', 13).
15
| ?- format('~16r', 13).
d
- ~<n>R
-
same as ~<n>r, except it uses the digits 0-9 and the letters A-Z instead of a-z.
| ?- format('~16R', 13).
D
- ~<n>s
-
argument is a string (list of numeric ASCII codes), from which at most the first <n> codes are printed as ASCII characters. If <n> is zero or if <n> is omitted, it defaults to the
length of the string. If the string is shorter than <n> then all the ASCII codes which make up the string are printed.
| ?- format('~s', ["string"]).
string
| ?- format('~3s', ["string"]).
str
| ?- format('~a', "string").
! Consistency error: a and
[115,116,114,105,110,103] are inconsistent
! the argument for the format control
option "a" must be of type "atom".
! goal: format('~a',
[115,116,114,105,110,103])
- The following control options can take an argument of any type:
- ~i
-
argument is ignored.
| ?- format('~i', 10).
- ~k
-
argument is passed to write_canonical/[1,2].
| ?- format('~k', 'A'+'B').
+('A','B')
- ~p
-
argument is passed to print/[1,2].
| ?- asserta((portray(X+Y) :-
write(X), write(' plus '),
write(Y))).
| ?- format('~p', 'A'+'B').
A plus B
- ~q
-
argument is passed to writeq/[1,2].
| ?- format('~q', 'A'+'B').
'A'+'B'
- ~w
-
argument is passed to write/[1,2].
| ?- format('~w', 'A'+'B').
A+B
- The following control options do not have a corresponding argument:
- ~~
-
prints one ~.
| ?- format('~~', []).
~
- ~<n>n
-
prints <n> newline characters. If <n> is omitted, it defaults to 1.
| ?- format('begin~nend', []).
begin
end
- ~N
-
prints nothing if at the beginning of a line, otherwise prints one newline character.
| ?- format('~Nbegin~N~Nend', []).
begin
end
- The following control options manipulate column boundaries (tab positions). These column boundaries only apply to the line currently being written. A column boundary is initially assumed
to be in line position 0.
- ~<n>|
-
sets a column boundary at line position <n> and moves the cursor to that line position. If <n> is omitted, a column boundary is set at the current line position. See extended
example below (also see section G-7-5-4).
- ~<n>+
-
sets a column boundary at <n> positions past the previous column boundary and moves the cursor to that line position. If <n> is omitted, it defaults to 8. See extended example
below.
- ~<n>t
-
When fewer characters are written between two column boundaries than the width of the column, the space remaining in the column is divided equally amongst all the ~t's, if any, in
the column, and each ~t fills its allotted space with characters of ASCII code <n>. If <n> is omitted, it defaults to ASCII 32 (space). <n> can also be of the form `<c>, where <c>
is the fill character. See extended example below.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- consistency_error
wrong number of arguments
- domain_error
wrong format option type
- Examples:
-
1. The following is an extended example of the use of format/[2,3] and the character escaping facility.
| ?- prolog_flag(character_escapes, _, on).
yes
| ?- compile(user).
toc(Rel) :-
format('Table of Contents ~t ~a~72|~*n', [i,3]),
format('~tTable of Contents~t~72|~*n', 2),
format("1. Documentation supplement for ~s~1f \c
~`.t ~d~72|~*n", ["Quintus Prolog Release ",Rel,2,2]),
format("~t~*+~w Definition of the term \"loaded\" \c
~`.t ~d~72|~n", [3,1-1,2]),
format("~t~*+~w Finding all solutions ~`.t ~d~72|~n", [3,1-2,3]),
format("~t~*+~w Searching for a file in a library \c
~`.t ~d~72|~n", [3,1-3,4]),
format("~t~*+~w New Built-in Predicates ~`.t ~d~72|~n", [3,1-4,5]),
format("~t~*+~w write_canonical (?Term) ~`.t ~d~72|~n", [7,1-4-1,5]),
format("~*+.~n~*+.~n~*+.~n", [20,20,20]),
format("~t~*+~w File Specifications ~`.t ~d~72|~n", [3,1-7,17]),
format("~t~*+~w multifile(+PredSpec) ~`.t ~d~72|~n", [7,1-7-1,18]).
[user compiled (20.783 sec 4888 bytes)]
yes
| ?- toc(1.5).
Table of Contents
1. Documentation supplement for Quintus Prolog Release 1.5 ........... 2
1-1 Definition of the term "loaded" ............................... 2
1-2 Finding all solutions ......................................... 3
1-3 Searching for a file in a library ............................. 4
1-4 New Built-in Predicates ....................................... 5
1-4-1 write_canonical (?Term) ................................. 5
.
.
.
1-7 File Specifications .......................................... 17
1-7-1 multifile(+PredSpec) ................................... 18
yes
- 2. Misc. examples:
-
| ?- X=12, format('X =:= ~2d', X). % These three
| ?- X=12, format("X=:= ~2d", X). % have the
| ?- X=12, format('X =:= ~*d', [2,X]). % same results
| ?- format('~s', ["string"]). % These two have
| ?- format('string', []). % the same results
| ?- X=12, Y= 123, format('X = ~d, Y = ~d', [X,Y]).
- See Also:
-
write_canonical/[1,2], print/[1,2], write/[1,2]
Chapter G-7
L-3-72: functor/3 meta-logical
- Synopsis:
-
functor(+Term, -Name, -Arity)
-
-
functor(-Term, +Name, +Arity)
-
-
Succeeds if the principal functor of term Term has name Name and arity Arity.
- Arguments:
-
- Term
-
<term>
- Name
-
<atom>
- Arity
-
<arity>
- Description:
-
There are two ways of using this predicate:
- If Term is initially instantiated, then
- if Term is a compound term, Name and Arity are unified with the name and arity of its principal functor.
- if Term is an atom or number, Name is unified with Term, and Arity is unified with 0.
- If Term is initially uninstantiated, Name and Arity must both be instantiated, and
- if Arity is an integer in the range 1..255, then Name must be an atom, and Term becomes instantiated to the most general term having the specified Name and Arity; that is, a term
with distinct variables for all of its arguments.
- if Arity is 0, then Name must be an atom or a number, and it is unified with Term.
- Examples:
-
| ?- functor(foo(a,b), N, A).
N = foo,
A = 2
| ?- functor(X, foo, 2).
X = foo(_1,_2)
Note: "_1" and "_2" are anonymous variables. The term foo(_1,_2) is the "most general" term that has name foo and arity 2.
| ?- functor(X, 2, 0).
X = 2
- Exceptions:
-
- instantiation error
Term and Arity are both uninstantiated.
- type_error
- domain error
-
-
- See Also:
-
arg/3, name/2, =../2
-
-
Chapter G-9-2
L-3-73: garbage_collect/0
- Synopsis:
-
garbage_collect
-
-
Explicitly invokes the garbage collector.
- Description:
-
- This predicate invokes the garbage collector to reclaim data structures in the heap that are no longer accessible to the computation.
- No expansion of the heap is done, even if "gc_margin" kilobytes cannot be reclaimed (see section G-10-3-1). This means that calls to this predicate are effective only when the heap
contains a significant amount of garbage.
- The cut may be used in conjunction with garbage_collect/0 to allow code that works in cycles and builds up large data structures to run for more cycles without running out of memory. The
cut removes any alternatives that may be pending, thus potentially freeing up garbage that could not otherwise be collected.
- Example:
-
In the code fragment:
cycle(X) :- big_goal(X, X1), cycle(X1).
-
-
if cycle/1 is to run for a long time, and if big_goal /2 generates a lot of garbage, then rewrite the code like this:
cycle(X) :- big_goal(X, X1), !, garbage_collect, cycle(X1).
- Tip:
-
Use of the "!, garbage_collect" idiom is only desirable when you notice that your code does frequent garbage collections. It will allow the garbage collector to collect garbage more
effectively, and the cycle will run without demanding increasing amounts of memory.
- See Also:
-
gc/0, prolog_flag(gc_margin,_,_,_), nogc/0, statistics/2
L-3-74: garbage_collect_atoms/0
- Synopsis:
-
garbage_collect_atoms
-
-
Invokes the atom garbage collector.
- Description:
-
- This predicate invokes the atom garbage collector to discard atoms that are no longer accessible to the computation, reclaiming their space.
-
-
- Tips:
-
A program can use the atoms keyword to statistics/2 to determine if a call to garbage_collect_atoms would be appropriate.
- See Also:
-
garbage_collect/0, statistics/2
L-3-75: gc/0
- Synopsis:
-
gc
-
-
Enables the garbage collector.
- Description:
-
L-3-76: 'QU_messages':generate_message/3 extendable
- Synopsis:
-
generate_message(+MessageTerm, -S0, -S)
-
-
For a given MessageTerm, generates a list composed of Control-Arg pairs and the atom 'nl'. This can be translated into a nested list of Control-Arg pairs which can be used as input to
print_message_lines/3.
- Arguments:
-
- MessageTerm
-
<term> May be any term.
- S0
-
<list of pair> the resulting list of Control-Arg pairs.
- S
-
<list of pair> the remaining list.
-
-
- Description:
-
- Clauses for generate_message/3 underly all messages from Prolog. They may be examined and altered. They are found in messages(language('QU_messages')) which by default is
qplib('embed/english/QU_messages.pl').
- The purpose of this predicate is to allow you to totally redefine the content of Prolog's messages. In particular, it is possible to translate all the messages from English into some
other language.
- This predicate should not be modified if all you want to do is modify or add a few messages: user:generate_message_hook/3 is provided for that purpose.
- The Prolog system uses the built-in predicate print_message/2 to print all its messages. When print_message/2 is called, it calls
user:generate_message_hook(Message,L,[])
to generate the message. If that fails,
'QU_messages':generate_message(Message,L,[])
is called instead.
- If generate_message/3 succeeds, L is assumed to have been bound to a list whose elements are either Control-Args pairs or the atom 'nl'. Each Control-Arg pair should be such that the call
format(user_error, Control, Args)
is valid. The atom 'nl' is used for breaking the message into lines. Using the format specification '~n' (new-line) is discouraged, since the routine which actually prints the message
(see user:message_hook/3 and print_message_lines/3) may need to have control over newlines.
- 'QU_messages':generate_message/3 is not included by default in runtime systems, since end-users of application programs should probably not be seeing any messages from the Prolog system.
If a runtime system does require the messages facility its source code should include a goal such as:
:- ensure_loaded(library(
language('QU_messages'))).
- If there is a call to print_message/2 when 'QU_messages':generate_message/3 is undefined, or if generate_message/3 fails for some reason, the message term itself is printed. Here is an
example of what happens when generate_message fails.
| ?- print_message(error,unexpected_error(37)).
! unexpected_error(37)
generate_message/3 failed because the message term was not recognized. In the following example print_message/2 is being called by the default exception handler.
| ?- write(A,B).
! Instantiation error in argument 1 of write/2
! goal: write(_2107,_2108)
| ?- abolish('QU_messages':generate_message/3).
...
| ?- write(A,B).
! instantiation_error(write(_2187,_2188),1)
Note that a call to 'QU_messages':generate_message/3 simply fails if the predicate is undefined; an existence_error is never signalled.
-
-
- Examples:
-
The following example shows how the output of generate_message/3 is translated and passed to print_message_lines/3.
-
-
gen_message_and_print_lines(Msg, Stream, Prefix) :-
generate_message(Msg, L, []),
lines(L, Lines, []),
print_message_lines(Stream, Prefix, Lines)
lines([]) --> [].
lines([H|T]) --> line(H), [nl], lines(T).
line([]) --> [].
line([Control-Args|T]) --> [Control-Args], line(T).
- Errors:
-
When print_message/2 calls 'QU_messages':generate_message/3 it handles any exceptions that arise by printing out an error message. It then writes out the original message.
- See Also:
-
print_message/2, message_hook/3, format/[2,3], print_message_lines/3, user:generate_message_hook/3, QU_messages':query_abbreviation/2
-
-
Chapter G-20
L-3-77: user:generate_message_hook/3 hook
- Synopsis:
-
:- multifile generate_message_hook/3.
-
-
generate_message_hook(+MessageTerm, -S0, -S)
-
-
A way for the user to override the call to 'QU_messages':generate_message/3 in print_message/2.
- Arguments:
-
- MessageTerm
-
<term> May be any term.
- S0
-
<list of pair> the resulting list of Control-Arg pairs.
- S
-
<list of pair> the remaining list.
-
-
- Description:
-
- For a given MessageTerm, generates the list of Control-Arg pairs required for print_message_lines/3 to format the message for display.
- This is the same as 'QU_messages':generate_message/3 except that it is a hook. It is intended to be used when you want to override particular messages from the Prolog system, or when you
want to add some messages. If you are using your own exception classes (see raise_exception) it may be useful to provide generate_message_hook clauses for those exceptions so that the
print_message/2 (and thus the default exception handler which calls print_message/2) can print them out nicely.
- The Prolog system uses the built-in predicate print_message/2 to print all its messages. When print_message/2 is called, it calls
user:generate_message_hook(Message,L,[])
to generate the message. If that fails,
'QU_messages':generate_message(Message,L,[])
is called instead.
- If generate_message_hook/3 succeeds, L is assumed to have been bound to a list whose elements are either Control-Args pairs or the atom 'nl'. Each Control-Arg pair should be such that the
call
format(user_error, Control, Args)
is valid. The atom 'nl' is used for breaking the message into lines. Using the format specification '~n' (new-line) is discouraged, since the routine which actually prints the message
(see user:message_hook/3 and print_message_lines/3) may need to have control over newlines.
- It is recommended that you declare this predicate multifile when you define clauses for it so that different packages which define clauses for it can be used together.
- Examples:
-
- Tips:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See also::
-
'QU_messages':generate_message/3, print_message/2, message_hook/3, format/[2,3], print_message_lines/3
L-3-78: get/[1,2]
- Synopsis:
-
get(-Char)
-
-
get(+Stream, -Char)
-
-
unifies Char with the ASCII code of the next non-layout character from Stream or the current input stream.
- Arguments:
-
- Char
-
<char> integer; legal ASCII code
- Stream
-
<stream_object> valid Prolog input stream
- Description:
-
- Layout characters are all outside the inclusive range 33..126; this includes space, tab, linefeed, DEL, and all control characters.
- If there are no more non-layout characters in the stream, Char is unified with -1.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Existence error
Trying to read beyond end of Stream
-
-
- Comment:
-
If the stream is tty, trying to read beyond the end of the stream results in resetting the input stream and trying to read the next character. By using the eof_action option of
open/[3,4], it is possible to specify that it should not be an error to run off the end of a stream.
- See Also:
-
get0/[1,2], ttyget/1, prompt/[2,3], open/[3,4]
L-3-79: get0/[1,2]
- Synopsis:
-
get0(-Char)
-
-
get0(+Stream, -Char)
-
-
Same as get/[1,2] except that Char includes layout characters.
- Arguments:
-
- Char
-
<char>
- Stream
-
<stream_object>
- See Also:
-
get/[1,2], ttyget0/1, prompt/[2,3]
L-3-80: get_profile_results/4
- Synopsis:
-
get_profile_results(+By, +Num,-Results,-Total)
-
-
Returns the results of the last profiled execution.
- Arguments:
-
- By
-
<atom> must be one of the atoms:
by_time by_choice_points
by_calls by_redos
- Num
-
<integer> specifies the maximum length of the Results list
- Results
-
<list of term> the results list
- Total
-
<integer>
- Description:
-
- Returns profiling information accumulated from the last call to profile/1. The By argument specifies the display mode which determines how the list is sorted and what the Total
argument returns. The Num argument determines the maximum length of the Results list. This list is always sorted in descending order so that the top Num predicates are included in the
list.
- Results is a list of terms of the form proc(Name,Ncalls,Nchpts,Nredos,Time,Callers) where Name,Ncalls,Nchpts,Nredos,Time give call, choice point, redo counts and the execution time
spent in milliseconds, and Callers is a list of calledby(Time,Calls,Name,ClauseNo,CallNo) terms, where Time in this case is the percentage of time attributed to this caller, Calls is
the number of calls made from this caller and Name,ClauseNo,CallNo locate precisely the actual caller.
- If the display mode is by_time then Total is the total execution time in milliseconds. If the display mode is by_calls, by_choice_points or by_redos then Total returns the total
number of calls, choice points or redos respectively.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to get_profile_results/4 as it would a call to any other undefined predicate,
printing a warning. If it is called during the execution of a runtime system, an existence exception is raised.
-
-
- Example:
-
| ?- get_profile_results(by_time,3,List,Total).
List = [proc(user:setof/3,227,0,0,1980,
[calledby(61,152,user:satisfy/1,6,1),
calledby(20,27,user:satisfy/1,7,1),
calledby(18,48,user:seto/3,1,1)]),
proc(user:satisfy/1,35738,36782,14112,260,
[calledby(69,13857,user:satisfy/1,1,2),
calledby(15,12137,user:satisfy/1,2,1)]),
proc(user:write/1,2814,0,0,240,
[calledby(33,481,user:reply/1,3,1),
calledby(25,608,user:replies/1,3,1),
calledby(16,562,user:out/1,2,1),
calledby(8,203,user:reply/1,2,5),
calledby(8,34,user:replies/1,2,3)])],
Total = 6040
[profile]
- See Also:
-
profile/[0,1], show_profile_results/[0,1,2]
L-3-81: ground/1
- Synopsis:
-
ground(+Term)
-
-
Term is currently instantiated to a term that is completely bound (has no uninstantiated variables in it).
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- ground(9).
yes
| ?- ground(major(tom)).
yes
| ?- ground(a(1,Term,3)).
no
| ?- ground("a").
yes
| ?- ground([1,foo(Term)]).
no
- See Also:
-
atom/1, atomic/1, number/1, var/1, compound/1, callable/1, nonvar/1, simple/1
L-3-82: halt/[0,1]
- Synopsis:
-
halt
-
-
halt(+ExitCode)
-
-
Causes an exit from Prolog.
- Arguments:
-
- ExitCode
-
<integer> an exit status code
-
-
- Description:
-
- causes an exit from Prolog
- halt/0 exits with a "success" exit status (0 on unix).
- halt/1 exits with the exit status given by its ExitCode argument.
- See Also:
-
abort/0, break/0
-
-
Chapter G-11-1
L-3-83: hash_term/2
- Synopsis:
-
hash_term(+Term, -HashValue)
-
-
Provides an efficient way to calculate an integer hash value for the ground term Term.
- Arguments:
-
- Term
-
<term>
- HashValue
-
<term> is an integer or variable
- Description:
-
- If the first argument passed to hash_term/2 is ground, an integer hash value corresponding to that term is calculated and returned in the second argument. If the first argument is not
ground, a new variable is returned in the second argument.
- For example:
| ?- hash_term(foo(name,2,module), H).
H = 1391
| ?- hash_term(foo(X), H).
X = _4734,
H = _4755
| ?-
- Tips:
-
hash_term/2 is provided primarily as a tool for the construction of sophisticated Prolog clause access schemes. Its intended use is to generate hash values for ground terms that will be
used with first argument clause indexing, yielding compact and efficient multi-argument or deep argument indexing.
-
-
hash_term/2 is most easily used when a known pattern of access to a predicate is desired and both arguments of the call and arguments of the predicate are known to be ground. In the
following simple but typical example, hash_term/2 calls are used together with Prolog's database manipulation predicates (assert/1 and clause/2) to calculate and add an additional
argument to the clauses actually stored in the Prolog database:
-
-
add_pred_info(Name, Arity, Module, Info) :-
hash_term([Name,Arity,Module], Hash),
assert(info(Hash,Name,Arity,Module,Info)).
get_pred_info(Name, Arity, Module, Info) :-
hash_term([Name,Arity,Module], Hash),
clause(info(Hash,Name,Arity,Module,Info), _).
-
-
This example assumes that the name, arity and module to be stored in the Prolog database are ground when add_pred_info/4 is called, and that they are also ground when get_pred_info/4 is
called. The predicate that is actually asserted, info/5, has an additional argument calculated by hash_term/2; info/5 would not normally be called directly. A predicate using hash_term/2
to delete the stored information would also be straightforward.
-
-
If the first argument passed to hash_term/2 is not ground, hash_term/2 returns a variable. Thus, if add_pred_info/4 is called with the name, arity or module not ground, the info/5
information will be asserted with a variable as its first argument, so it will not be indexed. If get_pred_info/4 is called with the name, arity or module not ground, info/5 will simply be
searched sequentially. Prolog's normal semantics will be retained, although access will be considerably less efficient.
-
-
It is possible to use hash_term/2 in more complex indexing schemes as well by checking instantiation when adding, accessing, and deleting clauses; however, it is up to the user to ensure
appropriate instantiation patterns in calls. The tradeoff between run-time argument checking and reduced indexing effectiveness depends on the degree of discrimination otherwise afforded by
normal first argument indexing. The efficiency gained by fast multi-argument indexing can often more than make up for such additional run-time costs.
-
-
It is also possible to use such indexing techniques on compiled predicates using term expansion. Note that calculated hash values are not dependent on transitory information like atom
numbers or internal pointers. Hash values are consistent across saving and restoring or multiple invocations of an application.
-
-
Calculation of hash values is very fast, and indices constructed using the techniques sketched above are also very compact, as the only additional cost is for storing the additional (hash
value) argument. When a solution to a complex indexing problem can be constructed using hash_term/2 it will probably be preferable to solutions using other techniques.
L-3-84: help/[0,1] hookable
- Synopsis:
-
help
-
-
Gives basic information, such as how to start using the help system and how to exit from Prolog.
-
-
help(+Topic)
-
-
Displays help available on Topic.
- Arguments:
-
- Topic
-
<term> an atom
- Description:
-
- help(Topic) is the basic help command. It attempts to accept any argument you give it as a topic for which help may exist in the manual. The argument is converted into a character
string, and all the index entries that start with that string are combined into a menu which gives you a choice of entry points into the manual hierarchy.
- It is not necessary to type the whole of the word which is the topic you want information about. However, the fewer characters you type, the larger the menu is likely to be, because more
index entries will begin with that character sequence.
- A hook is provided so that users can add to or replace this information: help/0 first calls user_help/0, and if that succeeds help/0 does nothing else. Only if the call to
user_help/0 fails is the standard information displayed.
- With the emacs interface see Chapter D-2
- With QUI see Chapter C-2
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to help/[0,1] as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
user_help/0, manual/[0,1]
L-3-85: initialization/1 declaration
- Synopsis:
-
:-initialization(Goal)
-
-
Declares that Goal is to be run when the file in which the declaration appears is loaded into a running system, or when a stand-alone program or runtime system that contains the file is
started up.
- Arguments:
-
- Goal
-
<callable> A valid goal. MOD
- Description:
-
- Defined as built-in prefix operator, so a simplified syntax can be used when using initialization/1 as a directive. See examples.
- Callable at any point during compilation of a file. That is, it can be used as a directive, or as part of a goal called at compile-time. The initialization goal will be run as soon as the
loading of the file is completed. That is at the end of the load, and notably after all other directives appearing in the file have been run.
- qpc and save_program/[1,2] save initialization goals in the qof file, so that they will run when the qof file is loaded.
- Goal is associated with the file loaded, and with a module, if applicable. When a file, or module, is going to be reloaded, all goals earlier installed by that file or in that module,
are removed. This is done before the actual load, thus allowing a new initialization Goal to be specified, without creating duplicates.
- Exceptions:
-
- instantiation_error
The argument Goal is not instantiated.
- Examples:
-
To understand the examples fully, read the reference page on volatile/1 first.
-
-
- A common case is when the Prolog process at start up should connect itself to an external database. It should also make the connection when the file with the code for the connection is
loaded for the first time.
:- volatile db_connection/1.
:- initialization my_init.
my_init :-
( clause(db_connection(_), _) ->
true
; set_up_connection(Connection),
assert(db_connection(Connection))
).
In the above example, set_up_connection/1 is user defined. We do not declare db_connection/1 as dynamic in the file, since such a declaration would implicitly delete all clauses of the
predicate when the file is reloaded.
- It might not always be desirable to have the connection set up the first time the file is loaded, but only when a system is started up (for instance during the debugging of a database
application.) This can be achieved with the following code (note that we use the property that a dynamic declaration reinitiliazes/resets the declared predicate):
:- dynamic connect/0.
:- volatile db_connection/1.
:- initialization my_init.
my_init :-
( connect ->
set_up_connection(Connection),
assert(db_connection(Connection))
; assert(connect)
).
-
-
- See Also:
-
volatile/1, load_files/1, compile/1
-
-
See Chapter G-5
L-3-86: instance/2
- Synopsis:
-
instance(+Ref, -Term)
-
-
Unifies Term with the most general instance of the dynamic clause or recorded term indicated by the database reference Ref.
- Arguments:
-
- Ref
-
<db_reference>
- Term
-
<term>
- Description:
-
Ref must be instantiated to a database reference to an existing clause or recorded term. instance/2 is not sensitive to the source module and can be used to access any clause, regardless
of its module.
- Exceptions:
-
- instantiation error
if Ref is not instantiated
- Type error
if Ref is not a syntactically valid database reference
- Existence error
if Ref is a syntactically valid database reference but does not refer to an existing clause or recorded term.
- Comments:
-
instance/2 ignores the module of a clause. Because of this, accessing a clause with via instance/2 is different from accessing it via clause/3 with a given Ref.
-
-
If the reference is to a unit-clause C, then Term is unified with 'C :- true'.
- Examples:
-
| ?- assert(foo:bar,R).
R = '$ref'(771292,1)
| ?- instance('$ref'(771292,1),T).
T = (bar:-true)
| ?- clause(H,B,'$ref'(771292,1)).
no
| ?- clause(foo:H,B,'$ref'(771292,1)).
H = bar,
B = true
| ?-
- See Also:
-
clause/3, asserta/2, assertz/2
-
-
Chapter G-14
L-3-87: integer/1
- Synopsis:
-
integer(+Term)
-
-
Term is an integer.
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- integer(5).
yes
| ?- integer(5.0).
no
- See Also:
-
atom/1, atomic/1, number/1, var/1, compound/1, callable/1, nonvar/1, simple/1
L-3-88: is/2
- Synopsis:
-
-Term is +Expression
-
-
Evaluates Expression as an arithmetic expression (see Chapter G-8-3), and unifies the resulting number with Term.
- Arguments:
-
- Expression
-
<expr> an expression made up of:
- functors representing arithmetic operations
-
- numbers
-
- variables bound to numbers or arithmetic expressions
-
- Term
-
<number> a number
- Description:
-
The possible values for Expression are spelled out in detail in section G-8-3.
-
-
Character codes like "a" are arithmetic expressions.
- Exceptions:
-
- Instantiation error
- Type error
Expression is not an arithmetic expression
- Domain error
Attempting to divide by zero.
- Representation error
overflow during arithmetic evaluation
-
-
- Examples:
-
| ?- X is 2 * 3 + 4.
X = 10
| ?- Y = 32.1, X is Y * Y.
Y = 3.21E+01,
X = 1.03041E+03
| ?- Arity is 3 * 8, X is 4 + Arity +
(3 * Arity * Arity).
Arity = 24,
X = 1756
| ?- X is 6/0.
! Domain error in argument 2 of is/2
! non-zero number expected, but 6/0 found
! goal: _3211 is 6/0
| ?- X is 16' 7fffffff + 3.
! Syntax error
! between lines 64 and 65
! X is 0
! <<here>>
! 7 fffffff+3
| ?- X is "a".
X = 97
| ?- X is 4 * 5, Y is X * 4.
X = 20,
Y = 80
-
-
See example under assign/2 to see use of is/2 to peek at random memory addresses.
- Comments:
-
If a variable in an arithmetic expression is bound to another arithmetic expression (as opposed to a number) at runtime then the cost of evaluating that expression is much greater. It is
approximately equal to the cost of call/1 of an arithmetic goal.
- See Also:
-
assign/2, </2, =:=/2, =</2, =\=/2, >/2, >=/2
Chapter G-8
L-3-89: keysort/2
- Synopsis:
-
keysort(+List1, -List2)
-
-
Sorts the elements of the list List1 into ascending standard order (see section G-9-7-1 with respect to the key of the pair structure.
- Arguments:
-
- List1
-
<list of pair>
- List2
-
<list of pair>
- Description:
-
The list List1 must consist of terms of the form Key-Value. Multiple occurrences of any term are not removed.
-
-
(The time taken to do this is at worst order (N log N) where N is the length of the list.)
-
-
Note that the elements of List1 are sorted only according to the value of Key, not according to the value of Value.
-
-
keysort is stable in the sense that the relative position of elements with the same key maintained.
- Examples:
-
| ?- keysort([3-a,1-b,2-c,1-a,1-b], X).
X = [1-b,1-a,1-b,2-c,3-a]
|?- keysort([2-1, 1-2], [1-2, 2-1]).
yes
- Exceptions:
-
- Instantiation error
If List1 is not properly instantiated
- Type error
If List1 is not a list of key-value pair.
-
-
- See Also:
-
library(samsort)
L-3-90: leash/1
- Synopsis:
-
leash(+Mode)
-
-
Starts leashing on the ports given by Mode.
- Arguments:
-
- Mode
-
<all | list> either the atom 'all', or a list of the ports to be leashed. Valid port names are:
'call', 'exit', 'redo', 'fail', 'done', 'head' and 'exception.'
- Description:
-
- The leashing mode only applies to procedures that do not have spypoints on them, and it determines which ports of such procedures are leashed. By default, all seven ports are leashed.
On arrival at a leashed port, the debugger will stop to allow you to look at the execution state and decide what to do next. At unleashed ports, the goal is displayed but program
execution does not stop to allow user interaction.
- If you are using QUI, a more convenient way to set leashing is by using the "Leashing..." item in the "Options" menu. This brings up a dialog which allows you to choose which ports to
leash.
- In DEC-10 Prolog, a different form of argument was used for leash/1. This form, in which the argument is an integer from 0 to 127, is also supported by Quintus Prolog, but is not
recommended, since the new form is clearer.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to leash/1 as it would a call to any other undefined predicate, printing a warning.
If it is called during the execution of a runtime system, an existence exception is raised.
- Examples:
-
| ?- leash([]).
turns off all leashing; now when you creep you will get an exhaustive trace but no opportunity to interact with the debugger. You can get back to the debugger to interact with it by
pressing ^c "t". The command
| ?- leash([call,redo]).
leashes on the Call and Redo ports. When creeping, the debugger will now stop at every Call and Redo port to allow you to interact.
- Exceptions:
-
- instantiation_error
-
Mode is not ground
- domain_error
-
Mode is not a valid leash specification
-
-
- See Also:
-
Chapter E-1
L-3-91: length/2
- Synopsis:
-
length(-List, +Integer)
-
-
length(*List, *Integer)
-
-
Integer is the length of List. If List is instantiated to a proper list, the predicate is determinate, also when Integer is var.
- Arguments:
-
- List
-
<list> a list
- Integer
-
<integer> non-negative integer
- Description:
-
- If List is a list of indefinite length (that is, either a variable or of the form [...|X]) and if Integer is bound to an integer, then List is made to be a list of length Integer with
unique variables used to "pad" the list. If List cannot be made into a list of length Integer, the call fails.
| ?- List = [a,b|X], length(List, 4).
List = [a,b,_3473,_3475],
X = [_3473,_3475] ;
| ?-
- If Integer is unbound, then it is unified with all possible lengths for the list List.
- If List is bound, and is not a list, length/2 simply fails.
- Backtracking:
-
If both List and Integer are variables, the system will backtrack, generating lists of increasing length whose elements are anonymous variables.
- Exceptions:
-
- Type error
Integer integer
- Examples:
-
| ?- length([1,2], 2).
yes
| ?- length([1,2], 0).
no
| ?- length([1,2], X).
X = 2 ;
no
L-3-92: library_directory/1 extendable
- Synopsis:
-
library_directory(*DirSpec)
-
-
Defines a library directory. Used by predicates taking file_spec as input argument.
- Arguments:
-
- DirSpec
-
<file_spec> Either an atom giving the path to a file, or PathAlias(DirSpec), where PathAlias is defined by a file_search_path rule (see the reference page for
file_search_path/2).
-
-
- Description:
-
- The dynamic, multifile library_directory/1 facts reside in module user. They define directories to search when a file specification library(File) is expanded to the full path.
- There are a set of predefined library_directory/1 facts, but users may also define their own libraries simply by asserting the appropriate library_directory/1 facts into module user. To
locate a library file, the library_directory/1 facts are tried one by one in the same sequence they appear in the Prolog database.
- The file_search_path mechanism is an extension of the library_directory scheme. See file_search_path/2 and Chapter G-6.
-
-
- Examples:
-
| ?- assert(library_directory('/usr/joe_bob/prolog/libs')).
yes
| ?- ensure_loaded(library(flying)).
% loading file /usr/joe_bob/prolog/libs/flying.qof
...
- See Also:
-
absolute_file_name/[2,3], assert/[1,2], dynamic/1, file_search_path/2, listing/1, load_files/[1,2]
-
-
Chapter G-6.
L-3-93: line_count/2
-
-
-
-
- Synopsis:
-
line_count(+Stream, -N)
-
-
Unifies N with the total number of lines either read or written on the open stream Stream.
- Arguments:
-
- Stream
-
<stream_object>
- N
-
<integer>
- Description:
-
A freshly opened stream has a line count of 1. See section G-7-7-1, for details on the use of this predicate on a stream which is directed to the user's terminal.
- Exception:
-
Stream errors (see section G-7-6-2)
- See Also:
-
character_count/2, line_position/2, stream_position/3
Chapter G-7
L-3-94: line_position/2
- Synopsis:
-
line_position(+Stream, -N)
-
-
Unifies N with the total number of characters either read or written on the current line of Stream.
- Arguments:
-
- Stream
-
<stream_object> specifies an open stream
- N
-
<integer> current line position
- Description:
-
A fresh line has a line position of 0. See section G-7-7-1, for details on the use of this predicate on a stream which is directed to the user's terminal.
- Exception:
-
Stream errors (see section G-7-6-2)
- See Also:
-
character_count/2, line_count/2, stream_position/3
Chapter G-7
L-3-95: listing/[0,1]
- Synopsis:
-
listing
-
-
listing(+PredSpecs)
-
-
Prints the clauses of all the dynamic procedures currently in the Prolog data base, or of PredSpecs, to the current output stream, using portray_clause/1.
- Arguments:
-
- PredSpecs
-
<gen_pred_spec_tree_var> ; Name/Arity predicate specification
-
-
list of predicate specifications or atoms
- Description:
-
- Examples:
-
- Comments:
-
Under the Emacs interface, there is a facility for finding the source code definition for a specified compiled or dynamic procedure and reading it into an edit buffer. This is likely to be
more helpful than listing/1 in most cases. See section D-2-2 for more information.
L-3-96: load_files/[1,2]
- Synopsis:
-
load_files(+Files)
-
-
load_files(+Files, +Options)
-
-
[+File|+Files]
-
-
[]
-
-
Load the specified Prolog source and/or QOF files into memory. Subsumes all other load predicates.
- Arguments:
-
- Files
-
<file_spec> or <list of file_spec> a file specification or a list of file specifications; a ".pl" or ".qof" extension may be omitted in a file specification. MOD
- Options
-
<list> a list of zero or more options of the form:
- if(X)
-
-
-
- X=true
-
(default) always load
- X=changed
-
load file if it is not already loaded or if it has been changed since it was last loaded
-
- when(X)
-
-
-
- X=run_time
-
(default) The file does not define any predicates that will be called during compilation of other files.
- X=compile_time
-
the file only defines predicates that wil be called during compilation of other files; it does not define any predicates that will be called when the application is
running.
- X=both
-
the file defines some predicates that will be needed during compilation and some that will be needed during execution.
-
- load_type(X)
-
- X=compile
-
compile Prolog source code
- X=qof
-
load QOF code
- X=latest
-
(default) load QOF or compile source, whichever is newer. The latest option is effective only if Files are sepcified without extensions.
- must_be_module(X)
-
- X=true
-
the files are required to be module-files
- X=false
-
(default) the files need not be module-files
- imports(X)
-
- X=all
-
(default) if the file is a module-file, all exported predicates are imported
- X=List
-
list of predicates to be imported
-
-
Note that if the option imports is present, the option must_be_module(true) is enforced.
- all_dynamic(X)
-
- X=true
-
load all predicates as dynamic
- X=false
-
(default) load predicates as static unless they are declared dynamic
-
-
Note that the all_dynamic option has no effect when a QOF file is loaded. Thus it is not normally useful to use all_dynamic(true) in conjunction with load_type(latest),
since the file will be loaded in dynamic mode only if the source file is more recent than the QOF file.
- silent(X)
-
- X=true
-
loading information is printed as silent messages (see section G-20 for details).
- X=false
-
(default) loading information is printed as informational message.
-
-
-
-
- Description:
-
- load_files/2 is the most general predicate for loading Prolog files. Special cases of it are provided by the following predicates:
load_files(Files) :-
load_files(Files, []).
[].
[File|Files] :-
load_files([File|Files]).
compile(Files) :-
load_files(Files, [load_type(compile)]).
consult(Files) :- /*consult equivalent to
compile now*/
compile(Files).
ensure_loaded(Files) :-
load_files(Files, [if(changed)]).
use_module(Files) :-
load_files(Files, [if(changed),
must_be_module(true)]).
use_module(File, Imports) :-
load_files(File, [if(changed),
must_be_module(true),
imports(Imports)]).
- load_files/[1,2] reads Prolog clauses, in source or in compiled (QOF) form, and adds them to the Prolog database, after first deleting any previous versions of the predicates they define.
Clauses for a single predicate must all be in the same file unless that predicate is declared to be multifile.
- If the file contains directives, that is, terms with principal functor ':-'/1 or '?-'/1, then these are executed as they are encountered.
- Clauses and directives can be transformed as they are read from source files (not from QOF), by providing a definition for term_expansion/2. This is true in both the development system
and qpc, but in order for this to work properly in qpc, your definition of term_expansion/2 (and everything it calls) must be loaded into qpc. This is accomplished with the when option
to load_files/2, or the -i option to qpc.
- A non-module source file can be loaded into any module by load_files/[2,3], but the module of the predicates in a QOF-file is fixed at the time it is created (by QPC, save_predicates/2 or
save_program/[1,2]). It is thus not possible to qof save a predicate from say module 'foo', and reloaded it into module 'bar', or QPC the non-module file 'f1.pl' into 'f1.qof', and then
load 'f1.qof' into module 'mod' (qpc assumes module 'user' when non-module files are compiled separately). To avoid mistakes, load_files/[1,2] loads the corresponding source file, if such
exists, whenever a non-module file is loaded into module other than 'user'. If no corresponding source file exists, the QOF file is loaded; care should be taken in this case.
- Initialization goals specified with initialization/1 are executed after the load.
- When load_files/[1,2] is called from an embedded command in a file being compiled by qpc, the load_type and if options are ignored. The specfied files are compiled from source to QOF,
if the source is newer than the corresponding QOF file. If the option when(compile_time) is given, the file is instead compiled into QPC memory, and no QOF is generated (see above).
- When load_files/[1,2] is called in a runtime system, the all_dynamic option will be automatically set to true because the compiler is not available in runtime systems. This means that
the loaded code will run slower.
-
-
- Exceptions:
-
- instantiation_error
M, Files, or Options is not ground.
- type_error
In M, in Files, or in Options.
- domain_error
Illegal option in Options.
- existence_error
A specified file does not exist. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
- permission_error
A specified file is protected. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
-
-
- See Also:
-
compile/1, consult/1, dynamic/1, ensure_loaded/1, fileerrors/0, multifile/1, no_style_check/1, nofileerrors/0, prolog_load_context/2, source_file/[1,2], style_check/1,
term_expansion/2, use_module/[1,2,3], initialization/1, volatile/1.
-
-
Chapter G-4
L-3-97: load_foreign_executable/1 hookable
- Synopsis:
-
load_foreign_executable(+Executable)
-
-
Load the foreign executable (shared object file) Executable into Prolog. Relies on the hook predicates foreign_file/2 and foreign/[2,3].
- Arguments:
-
- Executable
-
<file_spec> The shared object (.so) file to be loaded.
- Description:
-
- load_foreign_executable/1 takes a shared object file and loads it into Prolog. If the file contains dependencies on other shared objects/libraries, then these are loaded automatically.
For details on how these are loaded see Chapter I-3-12.
- The '.so' extension can be omitted from the filename given in the Executable argument.
- Uses the foreign/3 and foreign_file/2 facts defined by the user to make the connection between a Prolog procedure and the foreign function. When loading the shared object file, it looks
for a foreign_file/2 fact for that file and for each symbol in the foreign_file/2 fact it looks for a foreign/3 fact which gives the name of the Prolog procedure associated with the
foreign symbol and the argument specification.
- Looks for foreign/3 and foreign_file/2 facts defined in its source module only.
- Before calling this predicate, use the UNIX "ld" command to generate the shared object file from object files (and libraries). If possible the object files generated by the foreign
language compiler should contain position independent code. The SunOS C compiler, for example, has a "-pic" option to do this.
-
-
- Exceptions:
-
Errors in the specification of foreign/3 will all be reported when load_foreign_executable/1 is called.
- Examples:
-
See example under foreign/[2,3]
- See Also:
-
foreign_file/2, foreign/[2,3], load_foreign_files/2
-
-
Chapter I-3
L-3-98: load_foreign_files/2 hookable
- Synopsis:
-
load_foreign_files(+ObjectFiles, +Libraries)
-
-
Loads foreign object files into Prolog. Relies on the hook predicates foreign_file/2 and foreign/[2,3].
- Arguments:
-
- ObjectFiles
-
<list of file_spec> A list of foreign object (.o) files to be loaded.
- Libraries
-
<list of atom> A list of UNIX libraries that need to be searched while loading ObjectFiles.
- Description:
-
- load_foreign_files/2 takes a list of object files and a list of standard UNIX libraries, links them and then loads the result into Prolog. The linking is done using the standard UNIX "ld"
command. For details on the call to "ld" see Chapter I-3-13.
- The '.o' extension can be omitted from the filenames given in the ObjectFiles argument.
- Uses the foreign/3 and foreign_file/2 facts defined by the user to make the connection between a Prolog procedure and the foreign function. When loading each object file, it looks for a
foreign_file/2 fact for the object file and for each symbol in the foreign_file/2 fact it looks for a foreign/3 fact which gives the name of the Prolog procedure associated with the
foreign symbol and the argument specification.
- Looks for foreign/3 and foreign_file/2 facts defined in its source module only.
- Looks at the environment variable TMPDIR for the directory to store all the temporary files created during the linking and loading process. The default directory is /tmp.
- Before calling this predicate, generate the object files for the foreign functions using the foreign language compiler.
- Exceptions:
-
Errors in the specification of foreign/3 will all be reported when load_foreign_files/2 is called.
- Examples:
-
See example under foreign/[2,3]
- See Also:
-
foreign_file/2, foreign/[2,3], load_foreign_executable/1
-
-
Chapter I-3
L-3-99: manual/[0,1]
- Synopsis:
-
manual
-
-
Displays a menu of the top layer of the manual hierarchy.
-
-
manual(+Term)
-
-
Goes directly to the point in the manual represented by Term.
- Arguments:
-
- Term
-
<term> a reference: of form
part-chapter-section-subsection. E.g. g-13-3-1
-
-
- part
-
a lower case letter representing a major part of the manual:
a Introduction
b User's Guide
c The Quintus User Interface
d The Emacs Interface
e The Debugger
f Glossary
g The Prolog Language
h Creating Executables
i Foreign Language Interface
j Inter-Process Communication
k Library
l Prolog Reference Pages
m C Reference Pages
n Command Reference Pages
o Release Notes and Installation Guide
- chapter, section, sub-sections, etc.
-
integers representing chapters, sections, sub-sections, etc.
-
-
-
-
a topic
- Description:
-
- Examples:
-
To view the text in G.17-2-1 type:
?- manual(g-17-2-1).
- To look up character escaping, type:
-
manual('character escaping').
This brings up a menu which contains reference terms enclosed in curly braces. Simply copy the one you want at the prompt.
- See Also:
-
help/1
-
-
Chapter G-17
L-3-100: message_hook/3 hook
- Synopsis:
-
message_hook(+MessageTerm, +Severity, +Lines)
-
-
Overrides the call to print_message_lines/3 in print_message/2. A way for the user to intercept the Message of type Severity, whose translations is Lines, before it is actually
printed.
- Arguments:
-
- MessageTerm
-
<term> any term
- Severity
-
one of {informational, warning, error, help, silent}
- Lines
-
<list of pair> is of the form [Line1, Line2, ...], where each Linen is of the form [Control_1-Args_1,Control_2-Args_2, ...].
-
-
- Description:
-
After a message is parsed, but before the message is written, print_message/2 calls
-
-
user:message_hook(+MsgTerm,+Severity,+Lines)
-
-
If the call to user:message_hook/3 succeeds, print_message succeeds without further processing. Otherwise the built-in message display is used. It is often useful to have a message hook
that performs some action and then fails, allowing other message hooks to run, and eventually allowing the message to be printed as usual. See section G-20-3-3 for an example.
- Exceptions:
-
An exception raised by this predicate causes an error message to be printed and then the original message is printed using the default message text and formatting. Since the user defines
message_hook/3, they can write code which might raise exceptions.
- Examples:
-
The following is the default, built-in message portrayal predicate:
-
-
message_hook(MessageTerm,Severity,Lines):-
( Severity == silent ->
true
/* Don't translate or print silent messages */
; severity_prefix(Severity,Prefix,Stream) ->
print_message_lines(Stream,Prefix,Lines)
; raise_exception(domain_error(
print_message(Severity,MessageTerm),1,
one_of([help,error,warning,
informational,silent]),
Severity)).
severity_prefix(silent, '' '', user_error).
severity_prefix(help, '' '', user_error).
severity_prefix(error, '! ', user_error).
severity_prefix(warning, '* ', user_error).
severity_prefix(informational,'% ', user_error).
-
-
The reasoning behind the assignment of streams is that all unsolicited output should go to user_error.
- Tips:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See Also:
-
print_message/2, generate_message/3, print_message_lines/3
-
-
Chapter G-20
L-3-101: meta_predicate/1 declaration
- Synopsis:
-
:-meta_predicate +MetaSpec
-
-
Provides for module name expansion of arguments in calls to the predicate given by MetaSpec. All meta_predicate/1 declarations must be at the beginning of a module.
- Arguments:
-
- MetaSpec
-
<callable> Goal template or list of goal templates, of the form:
functor(Arg1, Arg2,...)
Each Argn is one of:
: requires module name expansion
integer >0 same as ':'
+, -, ?,* ignored
-
-
- Description:
-
- All meta_predicate declarations must be at the beginning of a module, immediately after the module declaration, because the meta_predicate declarations need to be known at the time other
modules are loaded if those modules use the meta predicates.
- The reason for allowing a non-negative integer as an alternative to ':' is that this may be used in the future to supply additional information to the cross-referencer (library(xref)) and
to the Prolog compiler. An integer n is intended to mean that that that argument is a term which will be supplied n additional arguments.
- Represents DEC-10 Prolog-style 'mode' declaration.
Provides for module name expansion of arguments in MetaSpec.
- Exceptions:
-
- Context error
Declaration appears in query.
- Caveat:
-
When a meta_predicate declaration is added, removed or changed, the file containing it, as well as all the modules which import the predicate given by MetaSpec, must be reloaded.
- Examples:
-
- Consider a sort routine, mysort/3, to which the name of the comparison predicate is passed as an argument:
mysort(+CompareProc, +InputList, -OutputList)
If CompareProc is module sensitive, an appropriate meta_predicate declaration for mysort/3 is:
:- meta_predicate mysort(:, +, -).
This means that whenever a goal mysort(A, B, C) appears in a clause, it will be transformed at load time into mysort(M:A, B, C), where M is the source module. The transformation will
happen unless
- A is of the form MetaSpec.
- A is a variable and the same variable appears in the head of the clause in a module-name-expansion position.
- Many examples in library, eg, library(samsort).
- See Also:
-
module/2
-
-
Chapter G-13-16
L-3-102: mode/1 declaration
- Synopsis:
-
:-mode(+Mode)
-
-
Currently a dummy declaration.
- Arguments:
-
- Mode
-
<term> MOD
- Description:
-
- So that DEC-10 Prolog programs can be read in
L-3-103: module/1
- Synopsis:
-
module(+ModuleName)
-
-
Changes the type-in module (see section G-13-7) to ModuleName. Thus subsequent top-level goals use ModuleName as their source module.
- Arguments:
-
- ModuleName
-
<atom> atom, the name of a module
- Description:
-
- If ModuleName is not a current module, a warning message is printed, but the type-in module is changed nonetheless.
- ModuleName does not become a current module until predicates are loaded into it.
- Calling module/1 from a command embedded in a file that is being loaded does not affect the loading of clauses from that file. It only affects subsequent goals that are typed at top
level.
- Exceptions:
-
- See also:
-
module/2, current_module/[1,2]
L-3-104: module/2 declaration
- Synopsis:
-
:- module(+ModuleName, +PublicPred).
-
-
Declares the file in which the declaration appears to be a module-file named ModuleName, with public predicates PublicPred. Must appear as the first term in the file.
- Arguments:
-
- ModuleName
-
<atom> an atom
- PublicPred
-
<list of simple_pred_spec> List of predicate specifications of the form Name/Arity.
-
-
- Description:
-
- The definition of a module is not limited to a single file, because a module-file may contain commands to load other files. If 'myfile', a module-file for ModuleName, contains an
embedded command to load 'yourfile' and if 'yourfile' is not itself a module-file, then all the predicates in 'yourfile' are loaded into module ModuleName.
- If the export list is not properly specified, there will be a warning or error message at compile time.
-
-
- Exceptions:
-
At compile time:
- Context error
Declaration appears other than as the first term in a file being loaded.
- Instantiation error
ModuleName not instantiated.
- Type error
PredSpecList is not a list of simple_pred_spec
- See Also:
-
module/1
Chapter G-13
L-3-105: multifile/1 declaration
- Synopsis:
-
:- multifile +PredSpecs
-
-
Allows the clauses for the specified predicates to be in more than one file.
- Arguments:
-
- PredSpecs
-
<pred_spec_forest> A single predicate specification of the form Name/Arity, or a sequence of predicate specifications separated by commas. Name must be an atom and Arity an
integer in the range 0..255. MOD
-
-
- Description:
-
- A built-in prefix operator, so that declarations can be written as e.g.
:- multifile a/1, b/3.
- By default, all clauses for a predicate are expected to come from just one file. This assists with reloading and debugging of code. Declaring a predicate multifile means that its
clauses can be spread across several different files. This is independent of whether or not the predicate is declared dynamic.
- Should precede all the clauses for the specified predicates in the file.
- There should be a multifile declaration for a predicate P in every file that contains clauses for P. This restriction is not currently enforced in the Development System: for
compatibility with earlier releases it suffices to have a multifile declaration in the first file loaded that contains clauses for P. However, a warning is noted if the multifile
declaration is omitted in subsequent files. The multifile declarations must be included in every file when qpc is being used to compile files separately.
- If a multifile predicate is dynamic, there should be a dynamic declaration in every file containing clauses for the predicate. Again, this is not enforced in the Development System, for
backwards compatibility, but warnings are printed if the dynamic declarations are omitted. The dynamic declarations may not be omitted when qpc is being used to compile files
separately.
- When a file containing clauses for a multifile predicate (p) is reloaded, the clauses for P which previously came from that file are removed. Then the new clauses for P (which may be
the same as the old ones) are added to the end of the definition of the multifile predicate. An exception to this is when the file concerned is the pseudo-file 'user', meaning that
clauses are being entered from the terminal; in this case the clauses are always added to the end of the predicate without removing any previously defined clauses.
- If a multifile declaration is found for a predicate which has already been defined in another file (without a multifile declaration), then this is considered to be a redefinition of that
predicate. Normally this will result in a multiple-definition style-check warning (see style_check/1).
- The predicate source_file/2 can be used to find all the files containing clauses for a multifile predicate.
- multifile predicates can be extended at run-time using multifile_assertz/2.
- multifile/1 cannot be called as a built-in predicate. It can only be used as a declaration to the compiler in a Prolog source file.
- Exceptions:
-
- instantiation_error
PredSpecs not ground.
- type_error
Either name or arity in PredSpec has the wrong type
- domain_error
Arity not in the range 0..255.
- context_error
If the declaration contradicts previous declaration or clauses for the same predicate in the file.
-
-
- See Also:
-
multifile_assertz/1, source_file/[1,2], compile/1, load_files/[1,2], dynamic/1.
L-3-106: multifile_assertz/1
- Synopsis:
-
multifile_assertz(+Clause)
-
-
Adds a compiled clause to the database. The clause will be added at the end of all existing clauses in the database.
- Arguments:
-
- Clause
-
<callable> A valid Prolog clause. MOD
-
-
- Description:
-
- If a predicate is multifile (compiled, interpreted-static or dynamic) multifile_assertz/1 can be used to add a clause, Clause, to the end of the predicate. In a runtime system (see Chapter H-1), it is an error to multifile_assertz a compiled clause because the compiler is not available.
- If predicate is undefined at the time of the multifile_assertz, it is set to be compiled (in the Development System) or dynamic (in a Runtime System). In either case the predicate is
also set to be multifile.
[Note that in runtime systems compile(File) actually loads the file as all_dynamic.]
- Except for the case of a multifile dynamic predicate, the effect of multifile_assertz if used on a predicate that is currently running will not be well-defined. The new clause may or may
not be seen on backtracking. If you want the proper semantics, use assertz instead.
-
-
- Exceptions:
-
-
- See Also:
-
abolish/[1,2], assertz/1, dynamic/1, multifile/1, Chapter H-1
-
-
Chapter H-2
L-3-107: name/2
- Synopsis:
-
name(+Constant, -Chars)
-
-
name(-Constant, +Chars)
-
-
Chars is the list consisting of the ASCII character codes comprising the printed representation of Constant.
- Arguments:
-
- Constant
-
<atomic>
- Chars
-
<list of char>
- Description:
-
- Initially, either Constant must be instantiated to a number or an atom, or Chars must be instantiated to a proper list of character codes (containing no variables).
- If Constant is initially instantiated to an atom or number, Chars will be unified with the list of character codes that make up its printed representation.
- If Constant is uninstantiated and Chars is initially instantiated to a list of characters that corresponds to the correct syntax of a number (either integer or float), Constant will be
bound to that number; otherwise Constant will be instantiated to an atom containing exactly those characters.
- Examples:
-
| ?- name(foo, L).
L = [102,111,111]
| ?- name('Foo', L).
L = [70,111,111]
| ?- name(431, L).
L = [52,51,49]
| ?- name(X, [102,111,111]).
X = foo
| ?- name(X, [52,51,49]).
X = 431
| ?- name(X, "15.0e+12").
X = 1.5e+13
- There are atoms which can be read and written by Prolog, and which can be converted to chars by name/2, but which it can not construct. One example of this is the atom '0':
| ?- X = '0', atom(X), name(X, L).
X = '0',
L = [48]
| ?- name(X, [48]), atom(X).
no
| ?- name(X, [48]), integer(X).
X = 0
This anomaly is present in DEC-10 Prolog and C-Prolog. name/2 is retained for compatibility with them. New programs should mainly use atom_chars/2 (section G-9-4) or number_chars/2
(section G-9-4) as appropriate.
-
-
- Exceptions:
-
-
-
- instantiation error
If Constant and Chars are both uninstantiated
- type_error
If Constant is not a constant
- Domain error
Chars is not a list of ASCII codes
- See Also:
-
Chapter G-9-4
L-3-108: nl/[0,1]
- Synopsis:
-
nl
-
-
nl(+Stream)
-
-
Terminates the current output record on the current output stream or on Stream.
- Arguments:
-
- Stream
-
<stream_object> (optional) a valid Prolog stream
-
-
- Description:
-
- Wraps the current output record (line) and writes out the record. How the record is wrapped up depends on the format of the output stream. For Quintus Prolog running under Unix,
nl/[0,1] is equivalent to putting a linefeed character (ASCII code 10) for default text stream. For a binary stream, the record is simply written out.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- permission_error
Some operating system dependent error occurred in writing.
-
-
- Comments:
-
-
-
- How the wrapped record is written depends upon the bottom layer write function associated with the output stream. The default tty stream displays the wrapped output record to the terminal
immediately for each nl/[0,1] operation, while the default text stream under Unix does not send the wrapped record (line) to the disk unless the buffer for the output stream is full.
- See Also:
-
put/[1,2] flush_output/1.
L-3-109: no_style_check/1
- Synopsis:
-
no_style_check(+Type)
-
-
Turns off the specified Type of compile-time style checking.
- Arguments:
-
- Type is one of the following atoms:
-
- all
-
Turn off all style checking.
- single_var
-
Turn off checking for clauses containing a single instance of a named variable, where variables that start with a '_' are not considered named.
- discontiguous
-
Turn off checking for procedures whose clauses are not all adjacent to one another in the file.
- multiple
-
Turn off checking for multiple definitions of the same procedure in different files.
-
-
- Description:
-
-
- Exceptions:
-
- instantiation_error
Type is not bound.
- type_error
Type is not an atom.
- domain_error
Type is not a valid type of style checking.
-
-
- See Also:
-
style_check/1.
L-3-110: nocheck_advice/[0,1]
- Synopsis:
-
nocheck_advice
-
-
nocheck_advice(+PredSpecs)
-
-
Disable advice checking on all predicates given by PredSpecs.
- Arguments:
-
- PredSpecs
-
<gen_pred_spec_tree> A list of predicate specifications. MOD
-
-
- Description:
-
- nocheck_advice/1 is used to disable advice checking on all predicates specified in PredSpecs. nocheck_advice/0 disables advice checking on all predicates for which advice checking is
currently enabled. When advice checking is disabled for a predicate, and execution of that predicate reaches an advised port, execution will proceed as though the port wasn't advised.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to nocheck_advice/[0,1] as it would a call to any other undefined predicate,
printing a warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Tips:
-
nocheck_advice/0 behaves as though implemented by
-
-
nocheck_advice :-
current_advice(Goal, Port, Action),
functor(Goal, Name, Arity),
nocheck_advice(Name/Arity),
fail.
nocheck_advice.
- See Also:
-
add_advice/3, remove_advice/3, current_advice/3, check_advice/[0,1]
L-3-111: nodebug/0
- Synopsis:
-
nodebug
-
-
Turns the debugger off. Equivalent to notrace/0.
- Description:
-
- Does not remove any spypoints. Spypoints will remain where they were set, although they will have no effect while the debugger is off. When the debugger is turned on again, the
spypoints will again take effect.
- To remove all spypoints, use nospyall/0
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to nodebug/0 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
-
-
L-3-112: nofileerrors/0
- Synopsis:
-
nofileerrors
-
-
Disables the 'fileerrors' flag
- Description:
-
- The built-in predicates which open files simply fail, instead of raising an exception if the specified file cannot be opened.
- The 'fileerrors' flag is only enabled by an explicit call to fileerrors/0, or via prolog_flag/[2,3] which can also be used to obtain the current value of the 'fileerrors' flag. See section G-10, for more information on the 'fileerrors' flag.
- Tips:
-
nofileerrors is a drastic predicate, since it affects the use of all predicates that open files. You might be unintentionally changing the behaviour of calls to open/3 from other parts of
the system (written by other people or from libraries). A better way to detect and ignore file errors is to wrap specific calls to open/3 with on_exception/3 and ignore the types of
errors you want to ignore.
- See Also:
-
fileerrors/0, prolog_flag/[2,3]
L-3-113: nogc/0
- Synopsis:
-
nogc
-
-
Disables the garbage collector.
- Description:
-
As if defined by:
nogc :- prolog_flag(gc, _, off).
- See Also:
-
prolog_flag/[2,3]
-
-
Chapter G-12-3
L-3-114: nonvar/1
- Synopsis:
-
nonvar(+Term)
-
-
Term is currently instantiated. This is the opposite of var/1.
- Arguments:
-
- Term
-
<term>
- Example:
-
| ?- nonvar([X,Y]).
X = _288
Y = _303
| ?- nonvar(X).
no
- See Also:
-
atom/1, atomic/1, number/1, var/1, compound/1, callable/1, simple/1
L-3-115: noprofile/0
- Synopsis:
-
noprofile
-
-
Turns off the profiler.
- Description:
-
- Turns off the profiler and removes data structures containing profiling information associated with any predicates that have been profiled.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to profile/[0,1] as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
profile/[0,1]
L-3-116: nospy/1
- Synopsis:
-
nospy(+PredSpecs)
-
-
Removes spypoints on all the predicates represented by PredSpecs.
- Arguments:
-
- PredSpecs
-
<gen_pred_spec_tree> Single predicate specification of form
-
-
List of predicate specifications
-
-
- Description:
-
- See Also:
-
spy/1, nospyall/0, debug/0, add_spypoint/1, remove_spypoint/1
L-3-117: nospyall/0
- Synopsis:
-
nospyall
-
-
Removes all spypoints.
- Description:
-
The only way to remove all spypoints at once, since turning off debugging with nodebug/0 does not remove spypoints; they remain in place and are reactivated if the debugger is turned back
on using trace/0 or debug/0.
-
-
This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to nospyall/0 as it would a call to any other undefined predicate, printing a warning.
If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
nospy/1
L-3-118: notrace/0
- Synopsis:
-
notrace
-
-
Turns the debugger off. Equivalent to nodebug/0
- Description:
-
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to notrace/0 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
L-3-119: number/1
- Synopsis:
-
number(+Term)
-
-
Term is currently instantiated to either an integer or a float.
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- number(5.2).
yes
| ?- number(5).
yes
- See Also:
-
atom/1, atomic/1, var/1, compound/1, callable/1, nonvar/1, simple/1
L-3-120: number_chars/2
- Synopsis:
-
number_chars(+Number, -Chars)
-
-
number_chars(-Number, +Chars)
-
-
Chars is the list consisting of the ASCII character codes comprising the printed representation of Number.
- Arguments:
-
- Number
-
<number>
- Chars
-
<list of char>
- Description:
-
- Chars is the list of ASCII character codes comprising the printed representation of Number.
- Initially, either Number must be instantiated to a number, or Chars must be instantiated to a proper list of character codes (containing no variables).
- If Number is initially instantiated to a number, Chars will be unified with the list of character codes that make up its printed representation.
- If Number is uninstantiated and Chars is initially instantiated to a list of characters that corresponds to the correct syntax of a number (either integer or float), Number will be
bound to that number; otherwise number_chars/2 will simply fail.
- Exceptions:
-
- Instantiation error
Number and Chars are both uninstantiated
- Domain error
Chars is not a list of ASCII codes
- Type error
Number is not a number or Chars is not a list
- Representation error
Chars is a list corresponding to a number that can't be represented
-
-
- Examples:
-
| ?- number_chars(foo, L).
no
| ?- number_chars(431, L).
L = [52,51,49]
| ?- number_chars(X, [102,111,111]).
no
| ?- number_chars(X, [52,51,49]).
X = 431
| ?- number_chars(X, "15.0e+12").
X = 1.5e+13
- See Also:
-
atom_chars/2
L-3-121: numbervars/3 meta-logical
- Synopsis:
-
numbervars(+-Term, +FirstVar, -LastVar)
-
-
instantiates each of the variables in Term to a term of the form '$VAR'(N).
- Arguments:
-
- Term
-
<term>
- FirstVar
-
<integer> Integer
- LastVar
-
<integer>
- Description:
-
- FirstVar is used as the value of N for the first variable in Term (starting from the left). The second distinct variable in Term is given a value of N satisfying "N is FirstVar+1";
the third distinct variable gets the value FirstVar+2, and so on. The last variable in Term has the value LastVar-1.
- Notice that in the example below, display/1 is used rather than write/1. This is because write/1 treats terms of the form '$VAR'(N) specially; it writes 'A' if N=0, 'B' if N=1,
...'Z' if N=25, 'A1' if N=26, etc. That is why, if you type the goal in the example below, the variable bindings will also be printed out as follows:
Term = foo(W,W,X),
A = W,
B = X
- Exceptions:
-
- instantiation_error
Number and Chars are both instantiated
- Type error
Number is not a number or Char is not a list
-
-
- Example:
-
| ?- Term = foo(A, A, B), numbervars(Term, 22, _),
display(Term).
foo($VAR(22),$VAR(22),$VAR(23))
- See Also:
-
write_term/1, write_canonical/1
L-3-122: on_exception/3
- Synopsis:
-
on_exception(-Exception, +*ProtectedGoal, +*Handler)
-
-
Specify an exception handler for ProtectedGoal, and call ProtectedGoal.
- Arguments:
-
- Exception
-
<term> Any term.
- ProtectedGoal
-
<callable> A goal. MOD
- Handler
-
<callable> A goal. MOD
-
-
- Description:
-
ProtectedGoal is executed. This will behave just as if ProtectedGoal had been written without the on_exception/3 wrapper. If ProtectedGoal is determinate, then on_exception/3 will
also be determinate. ProtectedGoal can also be non-determinate. As a general rule, code is easier to read when ProtectedGoal is a simple goal, however a conjunction of goals
(Goal1,...GoalN) or any other form that call/1 accepts is allowed.
-
-
If an exception is raised while ProtectedGoal is running, Prolog will abandon ProtectedGoal entirely. Any bindings made by ProtectedGoal will be undone, just as if it had failed. Side
effects, such as data-base changes and input/output, are not undone, just as they are not undone when a goal fails. After undoing the bindings, Prolog then tries to unify an object called
an EXCEPTION CODE with the ExceptionCode argument. If this unification succeeds, Handler will be executed as if you had written
ErrorCode=the actual EXCEPTION CODE,
Handler
If this unification fails, Prolog will keep looking for a handler. It will always find a handler at the top level, which prints out a message corresponding to the exception.
-
-
In applications lacking a top level (C calling Prolog, where QP_toplevel() has not been called) exceptions are indicated by the return status QP_ERROR. For more details refer to Chapter
I-4.
- Exceptions:
-
Same as call/1.
- Tip:
-
More efficient code is generated when ProtectedGoal is a simple goal. In other cases, such as where ProtectedGoal is a conjunction of goals (Goal1,...GoalN), the compiler treats this as if
it were call((Goal1,..., GoalN)). This potential inefficiency does not apply to Handler.
- Examples:
-
Fail on exception:
:-meta_predicate fail_on_exception/1.
fail_on_exception(C):-
on_exception(E,C,print_exception_then_fail(C,E)).
print_exception_then_fail(C,E):-
format('Exception occured while calling ~q:~n',
[C]),
print_message(warning,E),
fail.
- See Also:
-
raise_exception/1, print_message/2.
-
-
Chapter EXCEPTIONHANDLING.
L-3-123: op/3
- Synopsis:
-
op(+Precedence, +Type, +Name)
-
-
declares Name to be an operator of the stated Type and Precedence.
- Arguments:
-
- Precedence
-
<integer> integer in the range 1-1200
- Type
-
must be one of the atoms
xfx xfy yfx fx fy xf yf
- Name
-
<atom> atom or a list of atoms.
- Description:
-
Operators are a notational convenience to read and write Prolog terms. You can define new operators using op/3.
-
-
The Precedence of an operator is used to disambiguate the way terms are parsed. The general rule is that the operator with the highest precedence is the principal functor.
-
-
The Type of an operator decides the position of an operator and its associativity. In the atom which represents the type the character f represents the position of the operator. For
example, a type fx says that the operator is a prefix operator. The character y indicates that the operator is associative in that direction. For example, an operator of type xfy is a
right-associative, infix operator.
-
-
To cancel the operator properties of Name (if any) set Precedence to 0.
-
-
For more details, see section G-1-4
- Exceptions:
-
- Instantiation error Precedence, Type or Name is a variable
- Type error Precedence is not an integer or Type is not an integer or Name is not an atom
- Domain error Precedence is not in the range 1-1200
-
-
- See Also:
-
current_op/3
-
-
Chapter G-1-4
L-3-124: open/[3,4]
- Synopsis:
-
open(+FileSpec, +Mode, -Stream)
-
-
open(+FileSpec, +Mode, +Options, -Stream)
-
-
Creates a Prolog stream by opening the file FileSpec in mode Mode with options Options.
- Arguments:
-
- FileSpec
-
<file_spec> a file specification (Chapter G-6).
- Mode
-
an atom specifying the open mode of the target file. One of:
- read
-
open FileSpec for input.
- write
-
open FileSpec for output. A new file is created if FileSpec does not exist. If the file already exists, then it is set to empty and its previous contents are lost.
- append
-
opens FileSpec for output. If FileSpec already exists, adds output to the end of it. If not, a new file is created.
-
-
- Options
-
<list> (optional) a list of zero or more of the following.
-
-
- text
-
Specifies that the file stream is a text stream. This sets the line border code to linefeed character, the file border code to -1, and turns on trimming. This is the default.
- binary
-
Specifies that the file stream is a binary stream. This sets the line border code to none, the file border code to -1, the format to variable, and turns off trimming.
- record(Size)
-
Size is a integer value to specify the maximum record (line) size in the file. This also sets the internal buffer size to be used for input/output options on the stream to
Size. If Size is 0, the opened stream operates in non-buffered mode. The value of Size should be greater than or equal to 0.
-
-
In UNIX, the default is 256 for tty streams and 8192 for other stream.
- end_of_line(EolCode)
-
EolCode is an integer value to specify the line (record) border code for the stream. EolCode is
-
-
- -1
-
Indicates there is no line border code.
- Charcode
-
ASCII code for EOL character. Default = linefeed character (ASCII code for linefeed char).
-
-
If an output predicate writes out the character whose code is the line border code of the stream, the Prolog system terminates the output record according to the format of the
stream.
- end_of_file(EofCode)
-
EofCode is an integer value to specify the file border code for an input stream.
-
-
- -2
-
Indicates there is no file border code for the stream. Reading at the end of file is same as reading past end of file.
-
-
-
-
The file border code is the value to be returned to an input predicate when an input stream reaches the end of file. The default file border code is -1.
- eof_action(Action)
-
Specifies what to do for reading past end of file. This option has no effect on an output stream. Action is one of the following.
- error
-
It's an error to read past end of file. This is the default for text binary streams.
- eof_code
-
Return file border code as set in end_of_file option for reading past end of file.
- reset
-
Reset the stream and make an attempt to read for input past end of file. This is the default for tty stream.
- overflow(OvAction)
-
Specifies what to do when output overflows the current record size. This option has no effect on an input stream. OvAction is one of the following.
- error
-
It's an error.
- truncate
-
Discard the overflow characters.
- flush
-
Write out the overflow partial record (line). No characters are discarded. This is the default on UNIX.
- seek(SeekOption)
-
Request seeking method that will be performed on the file. SeekOption is defined as follows:
- error
-
It's an error to issue a seeking command on the stream. This is the default for a tty stream.
- previous
-
The seeking request will be made only to a previous input/output position. stream_position/3 is the only predicate that can be used to seek on the stream. This is the
default for both text and binary streams.
- byte
-
Seeking to an arbitrary byte position on the stream. This option also permits seek(previous). Both stream_position/3 and seek/4 work on the stream.
- record
-
Seeking to the beginning of an arbitrary record in the file stream. This option is not available under UNIX.
- flush(FlushType)
-
Request flushing method for an output stream. This option has no effect on an input stream. It can be one of the following.
-
-
- error
-
It's an error to try to flush an output stream.
- flush
-
Write out all the characters buffered. This is the default on UNIX.
- trim
-
Turns on the trimming on the file stream. Trimming means that trailing blanks are deleted in input records. The default is no trimming. See format below.
- system(SysAttrs)
-
This option is provided to allow extensions.
- SysAttrs
-
must be an atom and is passed to the QU_open() function which can be redefined by the user. The default version of QU_open() will report an error, causing an
permission_error to be raised, if system(SysAttrs) is specified.
- format(Format)
-
Specifies the file format. For Prolog running under UNIX, the default format is format(delimited(lf)) for text stream, format(variable) for binary stream, and
format(delimited(tty)) for tty file. UNIX users will not normally need to use the format(Format) options directly. Format is one of:
-
-
- variable
-
Each record in the file has its own length. There are no delimiter characters between records. The Prolog system removes the trailing blank characters for each input record
it reads if the trim option is set.
- delimited(lf)
-
a single linefeed character (ASCII code 10) terminates each record in the file.
- delimited(tty)
-
FileSpec is a terminal device, a pseudo-terminal device, or a terminal emulator. The delimiter character depends on the host operating system and the particular tty
connected. On UNIX systems, it is the linefeed character.
-
-
If one of these delimiters is specified, the Prolog system removes the delimiter characters at the end of record for input. The line border code (specified by end_of_line
option) is returned instead as the character code at the end of the record. Prolog system also puts delimiter characters at the end of record when a record is written out.
-
-
On UNIX systems, when no format has been specified, the format is decided as follows: if there is no line border code and trimming is off, then format(variable) is used; otherwise
format(delimited(lf)) is used.
- Stream
-
<stream_object> the resulting opened Prolog stream.
-
-
- Description:
-
- open/3 is equivalent to open/4 with Options=[].
- open/4 is designed to work on various file systems under different operating systems.
- Stream is used as an argument to Prolog input and output predicates.
- Stream can also be converted to the corresponding foreign representation through stream_code/2 and used in foreign code to perform input/output operations.
- Exceptions:
-
- domain_error
Mode is not one of 'read', 'write' or 'append'. Options has an undefined option or an element in Options is out of the domain of the option.
- instantiation_error
FileSpec or Mode is not instantiated. Options argument is not ground.
- type_error
FileSpec or Mode is not an atom type. Options is not a list type or an element in Options is not a correct type for open options.
- existence_error
The specified FileSpec does not exist.
- permission_error
Can not open FileSpec with specified Mode and Options.
- resource_error
There are too many files opened.
-
-
- Comments:
-
-
-
- If an option is specified more than once the rightmost option takes precedence.
- Prolog streams are in general classified as tty streams, text streams, or binary streams. A Prolog stream is a tty stream if the format of the stream is set to format(delimited(tty)), or
if no format is specified and FileSpec refers to a terminal (if the UNIX function is a tty()). Prolog provides a special service to print prompts for a tty input stream. A text stream
corresponds to a text file. The Prolog system removes the control characters of the text stream. A binary stream is a stream of bytes; the Prolog system returns the actual characters
stored in the file. Specifying binary or text along with trim and end_of_line options will result in a hybrid of binary and text streams.
- Defaults are provided for Options in QU_stream_param() function. This description is based on those input/output defaults.
- Format is seldom set by the user. On UNIX systems, it is only useful in case the user has redefined QU_open().
- Examples:
-
- Opening a stream that behaves like a C standard I/O stream without maintaining correct line count and line position.
open(FileSpec, Mode, [binary, seek(byte),
eof_action(eof_code)], Stream).
- opening a non-buffered stream
open(FileSpec, Mode, [record(0)], Stream).
- On UNIX systems, if FileSpec is /dev/tty, it means that the file is the default tty for the Prolog system. Terminal is used interactively.
- See Also:
-
open_null_stream/1, close/1, QP_prepare_stream/[3,4] QP_fopen(), QP_fdopen(), QU_open()
-
-
Chapter I-2-2-3
L-3-125: open_null_stream/1
- Synopsis:
-
open_null_stream(-Stream)
-
-
opens an output stream which is not connected to any file and unifies its stream object with Stream.
- Arguments:
-
- Stream
-
<stream_object>
- Description:
-
- Characters or terms which are sent to this stream are thrown away. This predicate is useful because various pieces of local state are kept for null streams: the predicates
character_count/2, line_count/2, and line_position/2 can be used on these streams (see section G-7-7).
- If Stream is fully instantiated at the time of the call to open_null_stream/1, the call simply fails.
- See Also:
-
character_count/2, line_count/2, line_position/2
L-3-126: otherwise/0
- Synopsis:
-
otherwise
-
-
Always succeeds (same as true/0).
- Description:
-
otherwise/0 is useful for laying out conditionals (see section G-2-7) in a readable way.
- Examples:
-
( test1 ->
goal1
| test2 ->
goal2
| otherwise ->
goal3
)
L-3-127: peek_char/[1,2]
- Synopsis:
-
peek_char(-Char)
-
-
peek_char(+Stream, -Char)
-
-
looks ahead for next input character on the current input stream or on the input stream Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream.
- Char
-
<char> the resulting next input character available on the stream.
- Description:
-
- peek_char/[1,2] looks ahead of the next input character of the specified input stream and unifies the character with Char. The peeked character is still available for subsequent input
on the stream.
- Example:
-
<<NEEDS EXAMPLE>> depends on what next char is.]
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- existence_error
This is an attempt to read past end of file. OR,
Some operating system dependent error occurred in reading.
-
-
- Comments:
-
It is safe to call peek_char/[1,2] several times without actually inputting any character. For example:
| ?- peek_char(X), peek_char(X), get0(X).
|: a
X = 97
- See Also:
-
get0/[1,2], get/[1,2], open/[3,4]
-
-
Chapter G-7
L-3-128: phrase/[2,3]
- Synopsis:
-
phrase(+*PhraseType, +*List)
-
-
phrase(+*PhraseType, +*List, *Rest)
-
-
Used in conjunction with a grammar to parse or generate strings.
- Arguments:
-
- PhraseType
-
<callable> non-variable, name of a phrase type. MOD
- List
-
<term> a list of symbols -- tokens or character codes.
- Rest
-
<term> a tail of List; what remains of List after PhraseType has been found.
-
-
- Description:
-
- Runs through the grammar rules checking whether there is a path by which PhraseType can be rewritten as List.
If List is bound, this goal corresponds to using the grammar for parsing. If List is unbound, this goal corresponds to using the grammar for generation.
- phrase/2 succeeds when the list List is a phrase of type PhraseType (according to the current grammar rules), where PhraseType is either a non-terminal or, more generally, a grammar
rule body. This predicate is a convenient way to start execution of grammar rules.
- phrase/3 succeeds when the portion of List between the start of List and the start of Rest is a phrase of type PhraseType (according to the current grammar rules), where PhraseType
is either a non-terminal or, more generally, a grammar rule body.
- phrase/3 allows variables to occur as non-terminals in grammar rule bodies, just as call/1 allows variables to occur as goals in clause bodies.
-
-
- Exceptions:
-
- Instantiation error
PhraseType is not bound.
- Type error
PhraseType is not callable.
-
-
- Examples:
-
See example in section G-16-3.
- See also:
-
-->/2, 'C'/3, expand_term/2, term_expansion/2
Chapter G-16
L-3-129: portray/1 hook
- Synopsis:
-
portray(+Term)
-
-
A way for the user to over-ride the default behavior of print/1.
- Arguments:
-
- Term
-
<term>
- Description:
-
- Note that print/1 always calls portray in module 'user'. Therefore, to be visible to print/1, portray must either be defined in or imported into module 'user'. See the reference page
for print/1 for information on what happens if portray/1 fails.
- If you would like lists of character codes printed by print/1 using double-quote notation, you should include library(printchars) (see section K-13) as part of your version of
portray/1.
- If portray/1 is defined, it is called from:
- print/1 (default is write/1)
- to print the variable bindings after a question has succeeded (default is writeq/1. see QU_messages for full details)
- to print a goal during debugging (default is writeq/1. See QU_messages for full details)
- Tips:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See Also:
-
print/1
section G-7-3-5
L-3-130: portray_clause/1
- Synopsis:
-
portray_clause(+Clause)
-
-
Writes Clause to the current output stream. Used by listing/[1,2].
- Arguments:
-
- Clause
-
<term>
- Description:
-
- The operation used by listing/0 and listing/1. Clause is written to the current output stream in exactly the format in which listing/1 would have written it, including a terminating
full-stop.
- If you want to print a clause, this is almost certainly the command you want. By design, none of the other term output commands puts a full-stop after the written term. If you are
writing a file of facts to be loaded by the Load Predicates, use portray_clause/1, which attempts to ensure that the clauses it writes out can be read in again as clauses.
- The output format used by portray_clause/1 and listing/1 has been carefully designed to be clear. We recommend that you use a similar style. In particular, never put a semicolon
(disjunction symbol) at the end of a line in Prolog.
- Exceptions:
-
Always succeeds without error.
- Example:
-
| ?- portray_clause((X:- a -> b ; c)).
A :-
( a ->
b
; c
).
X = _3185
| ?- portray_clause((X:- a -> (b -> c ; d ; e); f)).
A :-
( a ->
( b ->
c
; d
; e
)
; f
).
X = _3295
| ?- portray_clause((a:-b)).
a :-
b.
yes
| ?- portray_clause((a:-b,c)).
a :-
b,
c.
yes
| ?- portray_clause((a:-(b,!,c))).
a :-
b,
!,
c.
yes
- See Also:
-
listing/1, read/[1,2]
-
-
section G-7-3-6
L-3-131: predicate_property/2
- Synopsis:
-
predicate_property(*Callable, *PredProperty)
-
-
Unifies PredProperty with a predicate property of an existing predicate, and Callable with the most general term that corresponds to that predicate.
- Arguments:
-
- Callable
-
<callable> the skeletal specification (see section G-1-6) of a loaded predicate
- PredProperty
-
<atom> the various properties associated with Callable. Each loaded predicate will have one or more of the properties:
-
-
- Property
-
Comments
- compiled
-
can have the 'multifile' property
- interpreted
-
can have either the 'dynamic' or 'multifile' property or both
- built_in
-
- multifile
-
- dynamic
-
- exported
-
on the public predicate list of its source module
- imported_from(Module)
-
imported into the source module from Module )
- foreign
-
- meta_predicate(Term)
-
Term was specified in a meta_predicate declaration. Thus Term consists of the principal functor name followed by mode declarations for its arguments. For example:
mysort(:, +, -)
See section G-13-16 for further information.
- volatile
-
not to be saved in QOF files
- locked
-
not visible in the debugger due to use of -h option to qpc
- has_advice
-
advice has been added for the predicate
- checking_advice
-
advice checking is enabled for the predicate
-
-
- Description:
-
- If Callable is instantiated then predicate_property/2 successively unifies PredProperty with the various properties associated with Callable.
- If PredProperty is bound to a valid predicate property, then predicate_property/2 successively unifies Callable with the skeletal specifications of all loaded predicates having
PredProperty.
- If Callable is not a loaded predicate or PredProperty is not a valid predicate property, the call fails.
- If both arguments are unbound, then predicate_property/2 can be used to backtrack through all currently defined predicates and their corresponding properties.
- Examples:
-
- Predicates acquire properties when they are defined:
| ?- [user.]
| :- dynamic p/1.
| p(a).
| end_of_file.
[user compiled 0.117 sec 296 bytes]
yes
| ?- predicate_property(p(_), Property).
Property = (dynamic) ;
Property = interpreted ;
no
- To backtrack through all the predicates P imported into module m from any module:
| ?- predicate_property(m:P, imported_from(_)).
- To backtrack through all the predicates P imported into module m1 from module m2:
| ?- predicate_property(m1:P, imported_from(m2)).
- To backtrack through all the predicates P exported by module m:
| ?- predicate_property(m:P, exported).
- A variable can also be used in place of a module atom to find the names of modules having a predicate and property association:
| ?- predicate_property(M:f, imported-from(m1)).
will return all modules M which import f/0 from m1.
-
-
-
-
NOTE: All dynamic predicates are currently interpreted.
- See Also:
-
fileerrors/0, nofileerrors/0, gc/0, compile/1, module/[1,2], foreign/[2,3], meta_predicate/1, volatile/1, add_advice/3, check_advice/[0,1], current_predicate/2
-
-
section G-13-13-2
L-3-132: print/1 hookable
- Synopsis:
-
print(+Term)
-
-
print(+Stream, +Term)
-
-
Writes Term to the current output stream, or Stream. Can be redefined with the hook portray/1.
- Arguments:
-
- Stream
-
<stream_object>
- Term
-
<term>
- Description:
-
- By default, the effect of this predicate is the same as that of write/1, but you can change its effect by providing clauses for the predicate portray/1.
- If Term is a variable, then it is printed using write(Term).
- Otherwise the user-definable procedure portray(Term) is called. If this succeeds, then it is assumed that Term has been printed and print/1 exits (succeeds). Note that print/1
always calls portray/1 in module 'user'. Therefore, to be visible to print/1, portray/1 must either be defined in or imported into module 'user'.
- If the call to portray/1 fails, and if Term is a compound term, then write/1 is used to write the principal functor of Term and print/1 is called recursively on its arguments. If
Term is atomic, it is written using write/1.
- When print/1 has to print a list, say [Term1,Term2,...,Term N], it passes the whole list to portray/1. As usual, if portray/1 succeeds, it is assumed to have printed the entire list,
and print/1 does nothing further with this term. Otherwise print/1 writes the list using bracket notation, calling print/1 on each element of the list in turn.
- Since [Term1,Term2,...,Term N] is simply a different way of writing .(Term1,[Term2,...,Term N]), one might expect print/1 to be called recursively on the two arguments Term1 and
[Term2,...,Term N], giving portray/1 a second chance at [Term2,...,Term N]. This does not happen; lists are a special case in which print/1 is called separately for each of
Term1,Term2,...Term N.
- If you would like lists of character codes printed by print/1 using double-quote notation, you should include library(printchars) (see section K-13) as part of your version of
portray/1.
-
-
- Exceptions:
-
Succeeds without error, except for any errors which may occur in the execution of portray/1.
- See Also:
-
portray/1, library(printchars)
L-3-133: print_message/2 hookable
- Synopsis:
-
print_message(+Severity, +MessageTerm)
-
-
Print a Message of a given Severity. The behavior can be customized using the two hooks generate_message_hook/3 and message_hook/3.
- Arguments:
-
- Severity
-
Unless the default system portrayal is overidden with message_hook/3, Severity must be one of
-
-
- Value
-
Prefix
- informational
-
%
- warning
-
*
- error
-
!
- help
-
no prefix
- silent
-
no prefix
-
-
- MessageTerm
-
<term> any term
-
-
- Description:
-
-
- See Also:
-
message_hook/3, generate_message/3, print_message_lines/3, generate_message_hook/3
-
-
Chapter G-20-2
L-3-134: print_message_lines/3
- Synopsis:
-
print_message_lines(+Stream, +Prefix, +Lines)
-
-
Print the Lines to Stream, preceding each line with Prefix. Note that print_message_lines/3 only succeeds if Lines is a list of pair.
- Arguments:
-
- Stream
-
<stream_object> Any valid output stream.
- Prefix
-
<term> Any term.
- Lines
-
<term> is of the form [Line1, Line2, ...], where each Linen is of the form [Control_1-Args_1,Control_2-Args_2, ...].
-
-
- Description:
-
- This command is intended to be used in conjunction with message_hook/3. After a message is intercepted using message_hook/3, this command is used to print the lines. If the hook has
not been defined, the arguments are those provided by the system.
- print_message_lines/3 is a simple failure driven loop over the Lines data structure, implemented as:
:-use_module(library(basics),[member/2]).
print_message_lines(Stream,Prefix,Lines):-
member(Line,Lines),
format(Stream,'~N~w',[Prefix]),
( member(C-A,Line),
format(Stream,C,A)
; nl(Stream)
),
fail.
print_message_lines(_,_,_).
-
-
- Exceptions:
-
Any exception that format/3 might raise.
- Examples:
-
A typical use of this would be when using the user defined predicate, message_hook/3 to redirect output. For example:
-
-
message_hook(_,_,Lines):-
my_stream(MyStream),
print_message_lines(MyStream,'',Lines).
- See Also::
-
message_hook/3, print_message/2, generate_message/3, query_hook/6
L-3-135: profile/[0,1]
- Synopsis:
-
profile
-
-
profile(+Goal)
-
-
Turns on the profiler and profiles the execution of Goal.
- Description:
-
- profile/0 turns the profiler on and resets all counts accumlated from previous runs of the profiler. Counts of the number of call, choice points created and redos tried are maintained by
the profiler.
- profile/1 performs this same action and then proceeds to execute Goal, in addition monitoring timing data. Once execution of the goal has completed, the profiling results can be
displayed with show_profile_results/[0,1,2].
- Note that the profiler cannot be used when in debugging mode.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to profile/[0,1] as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
noprofile/0, show_profile_results/[0,1,2]
L-3-136: prolog_flag/[2,3]
- Synopsis:
-
prolog_flag(*FlagName, *Value)
-
-
FlagName is a flag which currently is set to Value.
-
-
prolog_flag(+FlagName, -OldValue, +NewValue)
-
-
Unifies the current value of FlagName with OldValue and then sets the value of the flag to NewValue.
- Arguments:
-
- FlagName
-
<atom>
- Value
-
<atomic>
- OldValue
-
<atomic>
- NewValue
-
<atomic>
-
-
Currently, the supported FlagNames and Values for both prolog_flag/2 and prolog_flag/3 are:
-
-
FlagNames Values
character_escapes 'on' or 'off'
debugging 'trace', 'debug', 'zip', or 'off'
fileerrors 'on' or 'off'
gc 'on' or 'off'
gc_margin non-negative integer
in thousands of bytes
gc_trace 'on' or 'off'
unknown 'error' or 'fail'
syntax_errors (see section G-19-4-10)
single_var 'on' or 'off'
discontiguous\'on' or 'off'
multiple 'on' or 'off'
-
-
Values available only to prolog_flag/2 (query-only) are:
-
-
FlagNames Values
- add_ons
-
an atom containing the list of add-on products which are statically linked into the Prolog system. If no add-ons are part of the system, the empty atom '' is returned.
- host_type
-
the host type, which is generally a hardware-operating system combination. This prolog_flag is used to create the system file_search_path/2 facts (see section G-6-1-4, and
section G-6-1-5.
- quintus_directory
-
the absolute path of the Quintus directory. The Quintus directory is the root of the entire Quintus installation hierarchy.
- runtime_directory
-
the absolute path of the directory where all the Prolog executables reside.
- version
-
the version of the Prolog being run.
- system_type
-
development, runtime.
- Description:
-
- To inspect the value of a flag without changing it, use prolog_flag/2 or the following idiom, where FlagName is bound to one of the valid flags above.
| ?- prolog_flag(FlagName, Value, Value).
- Use prolog_flag/2 to query and prolog_flag/3 to set values.
- prolog_flag/3 can be used to save flag values so that one can return a flag to its previous state. For example:
...
prolog_flag(debugging,Old,on), % Save in Old and set
...
prolog_flag(debugging,_,Old), % Restore from Old
...
-
-
- The read-only prolog_flag/2 facts add_ons, host_type, quintus_directory, and runtime_directory represent information set by the qsetpath program. For more detail on the qsetpath and
qgetpath utilities, consult 'man qsetpath' and 'man qgetpath'.
-
-
- Backtracking:
-
prolog_flag/2 enumerates all valid flagnames of a given current value, or all pairs of flags and their current values. It is not a way to find out non-current values for a flag.
- Exceptions:
-
- Instantiation error
In prolog_flag/3, FlagName unbound, or
NewValue unbound and not identical to OldValue.
- Domain error
In prolog_flag/3, FlagName bound to an atom which does not represent a supported flag, or
NewValue bound to atom which does not represent a valid value for FlagName.
-
-
- See Also:
-
gc/0, nogc/0, style_check/1, no_style_check/1, unknown/2, fileerrors/0, nofileerrors/0
-
-
Chapter G-10
L-3-137: prolog_load_context/2
- Synopsis:
-
prolog_load_context(+Key, -Value)
-
-
prolog_load_context(*Key, *Value)
-
-
Finds out the context of the current load.
- Arguments:
-
- Key
-
<term>
- Value
-
<atom>
- Description:
-
You can call prolog_load_context/2 from an embedded command or by term_expansion/2 to find out the context of the current load. If called outside the context of a load, it simply fails.
-
-
- Key
-
Value
- module
-
the module you are compiling into
- file
-
absolute filename of the file being compiled
- stream
-
the stream you are compiling from
- directory
-
directory of the file on which the stream is open
- term_position
-
a stream position object referring to the position of the clause just read
-
-
- Backtracking:
-
This predicate is meant to be used in the mode (+, -), but it is also possible to backtrack through it.
- See Also:
-
load_files/[1,2]
-
-
Chapter G-10
L-3-138: prompt/[2,3]
- Synopsis:
-
prompt(-OldPrompt, +NewPrompt)
-
-
prompt(+Stream, -OldPrompt, +NewPrompt)
-
-
Queries or changes the prompt string of the current input stream or an input stream Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog input stream.
- OldPrompt
-
<atom> the old prompt atom of the stream.
- NewPrompt
-
<atom> the new prompt atom of the stream.
-
-
- Description:
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- instantiation_error
NewPrompt argument is not instantiated.
- type_error
NewPrompt is not an atom type.
- Comments:
-
-
-
- The 'Load' predicates change the prompt of the input stream during the time operations are performed: If a built-in loading predicate is performed on the module 'user' (such as
compile(user), etc.), the prompt string of the standard Prolog input stream, user_input (user) is set to '| '. This prompt is not affected by prompt/[2,3].
- prompt/3 succeeds for any valid input stream. If the input stream is not a tty format stream, the Prolog system does not print out the prompt string when it is waiting input from the
stream.
Normally prompts only appear on user_error when the system is waiting for input on user_input. These prompts are suppressed when user_input is not connected to a terminal, unless the
'+tty' command-line option to prolog(1) was specified. (See section I-5-4.)
For prompts to be used on streams other than user_input or user_error, the C function QP_add_tty() must be used.
-
-
- See Also:
-
QP_add_tty(), read/[1,2], read_term/[2,3], get/[1,2], get0/[1,2]
Chapter I-5
L-3-139: public/1 declaration
- Synopsis:
-
public+Term
-
-
Dummy declaration for backwards compatibility.
- Arguments:
-
- Term
-
<term> MOD
L-3-140: put/[1,2]
- Synopsis:
-
put(+Char)
-
-
put(+Stream, +Char)
-
-
Evaluates the integer expression Char, and writes the lower 8-bits to the current output stream or to Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog output stream
- Char
-
<expr> a legal character code or an integer expression. An useful form of integer expression for this argument is a single character following 0', such as 0'a, 0'b, etc.
-
-
- Description:
-
- put/[1,2] writes out the least significant 8 bits of the evaluated Char to the specified output stream unless Char is evaluated to be the line border code of the stream. The character
written out is usually stored in the buffer of the stream. If the buffer overflows, it is written out to the disk. If the evaluated Char is the same as the line border code of the
output stream, the operation works like nl/[0,1]. The default line border code for a text stream and a tty stream is the linefeed character (ASCII code 10).
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- instantiation_error
Char is not instantiated.
- type_error
Char is not an integer type.
- permission_error
There is an error in the bottom layer of write function of the stream.
-
-
- See Also:
-
nl/[0,1], skip_line/[0,1], open/[3,4]
-
-
Chapter G-7
L-3-141: query_abbreviation/3 extendable
- Synopsis:
-
query_abbreviation(+Tag, -Prompt, -Pairs)
-
-
A way to specify one letter abbreviations for responses to queries from the Prolog System.
- Arguments:
-
- Tag
-
<atom> This indicates which query type.
- Prompt
-
<atom> An atom indicating appropriate abbreviations.
- Pairs
-
<a list of pairs> A list of word-abbreviation pairs.
-
-
- Description:
-
-
-
Prolog only asks for keyboard input in a few different ways. These are enumerated in the clauses for query_abbreviation/3 in the module messages(language(('QU_messages'))). These clauses
specify valid abbreviations for a given key word. For example,
-
-
query_abbreviation(yes_or_no,'(y/n)',[yes-"yY",no-"nN"]).
-
-
a French translator might decide that the letters 'O' and 'o' are reasonable abreviations for 'oui' (yes), and therefore write
-
-
query_abbreviation(yes_or_no,'(o/n)',[yes-"oO",no-"nN"]).
-
-
For an example of how this is used with query_hook/6, see the reference page for query_hook_example.
- See Also::
-
section G-20-3-4, and the reference page for query_hook/6
L-3-142: query_hook/6 hook
- Synopsis:
-
query_hook(+QueryClass, +Prompt, +PromptLines, +Help, +HelpLines, -Answer)
-
-
Provides a method of overriding Prolog's default keyboard based input requests. The query hook is used by the Quintus User Interface.
- Arguments:
-
- QueryClass
-
determines the allowed values for the atom Answer.
-
-
- If QueryClass is:
-
Answer must be:
- yes_or_no(Question)
-
yes or no.
- toplevel
-
yes or no
- yes_no_proceed
-
yes, no, or proceed.
-
-
- Prompt
-
<list of pair> A message term.
- PromptLines
-
<list of pair> The message generated from the Prompt message term.
- Help
-
<term> A message term.
- HelpLines
-
<list of pair> The message generated from the Help message term.
- Answer
-
see QueryClass
- Description:
-
This provides a way of overriding Prolog's default method of interaction. If this predicate fails, Prolog's default method of interaction is invoked.
-
-
The default method first prints out the prompt, then if the response from the user is not one of the allowed values, the help message is printed.
-
-
It is useful to compare this predicate to message_hook/3, since this explains how you might use the Prompt, PromptLines, Help, HelpLines.
- Exceptions:
-
An exception raised by this predicate causes an error message to be printed and then the default method of interation is invoked. In other words, exceptions are treated as failures.
- Examples:
-
If Prolog is looking for a yes-no response to one question `Done?', as in the toplevel, this request for input can be captured
query_hook(toplevel,_,_,_,_,Answer):-
my_yes_no('Done?',Answer).
where my_yes_no/2 binds Answer to either yes or no.
-
-
Here is roughly how the default method works. Notice the interaction with query_abbreviation/3.
query_hook(QueryClass,_,PromptLines,_,HelpLines,Answer):-
'QU_messages':query_abbreviation(QueryClass,
AbbreviationPrompt,
Pairs),
repeat,
( print_message_lines(user_output,'',PromptLines),
( AbbreviationPrompt == ''
-> write(Stream,' ')
; format(Stream,' ~w ',[AbbreviationPrompt])
),
flush_output(Stream),
get0(C),
member(Answer-Abrv,Pairs),
member(C,Abrv),
!
; print_message_lines(Stream,'',HelpLines),
fail
).
- Tips:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See Also:
-
query_abbreviation/3, message_hook/3, print_message_lines/3
-
-
Chapter G-20
L-3-143: raise_exception/1
- Synopsis:
-
raise_exception(+Exception)
-
-
Raise an exception (that might be intercepted by on_exception/3).
- Arguments:
-
- Exception
-
<nonvar> Any term.
-
-
- Description:
-
A call to raise_exception/1 can never backtrack, fail or succeed. Rather, raise_exception/1 searches for an ancestor of the current goal, ProtectedGoal, which is of the form:
-
-
on_exception(E,ProtectedGoal,Handler)
-
-
The first argument, E, unifies with Exception. It then executes the Handler instead of the ProtectedGoal. It will always find a handler at the top level, which prints out a message
corresponding to the exception. See section G-20-2 for a discussion on how exceptions are printed.
- Exceptions:
-
- instantiation_error
when Exception is unbound. When a built-in predicate detects an error situation, it causes an exception to be raised.
-
See Also:
-
on_exception/3.
-
-
Chapter G-19
L-3-144: read/[1,2]
- Synopsis:
-
read(-Term)
-
-
read(+Stream, -Term)
-
-
Reads the next term from the current input stream or Stream and unifies it with Term.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream which is open for input
- Term
-
<term> the term to be read
- Description:
-
- Term must be followed by a full-stop. The full-stop is removed from the input stream and is not a part of the term which is read.
- For the syntax of Prolog terms see section G-1-7.
- The term is read with respect to current operator declarations. See section G-1-4, for a discussion of operators.
- Does not finish until the full-stop is encountered. Thus, if you type at top level
| ?- read(X)
you will keep getting prompts (first '|: ', and five spaces thereafter) every time you type the return key, but nothing else will happen, whatever you type, until you type a full-stop.
- When a syntax error is encountered, an error message is printed and then read/1 tries again, starting immediately after the full-stop which terminated the erroneous "term". That is,
read/1 does not fail on a syntax error, but perseveres until it eventually manages to read a term.
- If the end of the current input stream has been reached, then read(X) will cause X to be unified with the atom 'end_of_file'
-
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
-
- See Also:
-
read_term/[2,3], prompt/[2,3]
-
-
Chapter G-1-7
L-3-145: read_term/[2,3]
- Synopsis:
-
read_term(+Options, -Term)
-
-
read_term(+Stream, +-Options, -Term)
-
-
Read a term from the current input stream or from Stream, optionally returning extra information about the term.
- Arguments:
-
- Stream
-
<stream_object> A valid Prolog stream which is open for input
- Term
-
<term> the term that is read
- Options
-
<list of term> a list of zero or more of the following:
- syntax_errors(Val)
-
Val must be bound to one of the following, indicating what should be done when a syntax error is found:
- quiet
-
nothing is printed, and read_term/[2,3] fails
- dec10
-
a syntax error message is printed, and read_term/[2,3] tries to read the next term (this is compatible with DEC-10 Prolog and previous versions of Quintus Prolog)
- fail
-
a syntax error message is printed, and read_term/[2,3] fails
- error
-
an exception is raised.
The default value if this option is not specified is the current value of the syntax_errors prolog flag. The default value for this flag is dec10. See prolog_flag/2 for more
information on these flags.
- variable_names(Names)
-
On completion, Names is bound to a list of Name=Var pairs, where each Name is an atom indicating the spelling of the name of a variable in the term just read, and Var is the
corresponding variable. Note that anonymous variables, written as _, are not included in this list.
- singletons(Singletons)
-
On completion, Singletons is bound to a list of Name=Var pairs, one for each variable only appearing once in the term. Anonymous variables are not included on this list.
- term_position(Position)
-
On completion, Position is the position of the start of the actual term, as might be returned by stream_position/2. Any white space and comments before the actual term are
not reflected by the position. To find the position of the end of the term, you need only call stream_position/2; it will give you the position of the first character after
the period ending the term.
- subterm_positions(PositionTerm)
-
On completion, PositionTerm is bound to a position term that describes the position of the term just read and all of its subterms. A position term is of one of the forms
listed below. In all these forms, Start and End are the character positions of first character of the term and the character following the last character of the term,
respectively. Similarly FStart and FEnd specify the start and end of the principle functor of the term. Note that the positions are character positions, not position terms
as returned by stream_position/2.
- Start-End
-
The term corresponding to this position term is either atomic or a variable. Start and End are the character positions of the first character of the term and the
character following the last character of the term, respectively.
- list_position(Start,End,Elts,Tail)
-
The term corresponding to this position term is a list which was written using bracket notation (for example, [a,list]). Elts is a list of position terms for each proper
element of the list. Tail is the position of the tail of the list (the part following the |), or the atom 'none' if the list has no tail part.
- string_position(Start,End)
-
The term corresponding to this position term is a list of character codes written as a quoted string (for example, "a string"). The positions specified include the quote
characters.
- brace_term_position(Start,End,Arg)
-
The term corresponding to this position term is of the form {X}. Arg is a position term describing the argument of this term.
- term_position(Start,End,FStart,FEnd,Args)
-
The term corresponding to this position term is a compound term not specifically mentioned above. This includes terms written with operators. Args is a list of position
terms, one for each argument of the term.
-
-
- Exceptions:
-
- syntax_error
A syntax error is found
- permission_error
The input stream cannot be read
- domain_error
An illegal option or an invalid stream is specified
- instantiation_error
Either Stream or Options, or one of the elements of the option list, or the argument of the syntax_errors option is unbound
- type_error
The argument to the syntax_errors option is not an atom
-
-
- Examples:
-
| ?- read_term([variable_names(L)], T).
|: append([U|X],Y,[U|Z]) :- append(X,Y,Z).
L = ['U'=_1988,'X'=_2003,'Y'=_2020,'Z'=_2046],
T = (append([_1988|_2003],_2020,[_1988|_2046]):-
append(_2003,_2020,_2046))
| ?- read_term([subterm_positions(P)], T).
|: foo+bar+baz.
P = term_position(1642,1653,1649,1650,
[term_position(1642,1649,1645,1646,
[1642-1645,1646-1649]),
1650-1653]),
T = foo+bar+baz
- See Also:
-
read/[1,2], prompt/[2,3] prolog_flag/[2,3]
-
-
Chapter G-7
L-3-146: reconsult/1
- Synopsis:
-
reconsult(+Files)
-
-
Same as compile/1
- Arguments:
-
- Files
-
file_spec or <list of file_spec> MOD
L-3-147: recorda/3
- Synopsis:
-
recorda(+Key, +Term, -Ref)
-
-
records the Term in the internal database as the first item for the key Key; a database reference to the newly-recorded term is returned in Ref.
- Arguments:
-
- Key
-
<atomic>
- Term
-
<term>
- Ref
-
<db_reference>
- Description:
-
- If Key is a compound term, only its principal functor is significant. That is, foo(1) represents the same key as foo(n).
- Exceptions:
-
- Instantiation error
Key is not instantiated
- Range error
Ref is not a database reference or an unbound variable
- See Also:
-
recorded/3, recordz/3, current_key/2
-
-
Chapter G-14
L-3-148: recorded/3
- Synopsis:
-
recorded(-Key, -Term, +Ref)
-
-
recorded(+Key, *Term, *Ref)
-
-
searches the internal data base for a term recorded under the key Key which unifies with Term, and whose data base reference unifies with Ref.
- Arguments:
-
- Key
-
<atomic>
- Term
-
<term>
- Ref
-
<db_reference>
- Description:
-
- If Ref is instantiated, then Key and Term are unified with the key and term associated with Ref. Otherwise, If Key is a compound term, only its principal functor is significant.
That is, foo(1) represents the same key as foo(n).
- A call to recorded/3 of the form (-, ?, +) will succeed if the expected relation holds. Key need not be instantiated.
- Backtracking:
-
Can be used to backtrack through all the matching terms recorded under the specified key. Therefore, if you want to match only a single term you should use a cut to prevent backtracking.
Alternatively, use the library(not) predicate, once/1.
- Exceptions:
-
- Type error
Ref is not a database reference
Key is a float
- Instantiation error
- See Also:
-
record/3, recorda/3, current_key/3
L-3-149: recordz/3
- Synopsis:
-
recordz(+Key, +Term, -Ref)
-
-
Records the term Term in the internal data base as the last item for the key Key; a data base reference to the newly-recorded term is returned in Ref.
- Arguments:
-
- Key
-
<atomic>
- Term
-
<term>
- ref
-
<db_reference>
- Exceptions:
-
- Instantiation error
Key is not instantiated
- Range error
Ref is not a data base reference or an unbound variable
- See Also::
-
recorded/3, recorda/3, current_key/2
L-3-150: remove_advice/3
- Synopsis:
-
remove_advice(+Goal,+*Port,+*Action)
-
-
remove the association of an action with entry to a port of a procedure. remove_advice/3 will only succeed when Port is var or one of {call, exit, done, redo, fail}, and Action is var
or callable.
- Arguments:
-
- Goal
-
<callable> a term to be unified against a calling goal of existing advice. MOD
- Port
-
<term> any term.
- Action
-
<term> any term. MOD
- Description:
-
- remove_advice/3 removes the association of an advice action with a goal and port, undoing the effect of add_advice/3.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to remove_advice/3 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
add_advice/3, current_advice/3, check_advice/[0,1], nocheck_advice/[0,1]
L-3-151: remove_spypoint/1
- Synopsis:
-
remove_spypoint(+Spyspec)
-
-
removes a spypoint from the specified predicate or call.
- Arguments:
-
- Spyspec
-
<compound> a specification of an individual spypoint. Two forms of spyspec are allowed:
- predicate(Pred)
-
A spypoint on any call to Pred. Pred must be a skeletal predicate specification, and may be module qualified.
- call(Caller,Clausenum,Callee,Callnum)
-
A spypoint on the Callnum call to Callee in the body of the Clausenum clause of Caller. Callee and Callnum must be skeletal predicate specifications. Callnum and
Clausenum must be integers, and begin counting from 1. Note that Callnum specifies a lexical position, that is, the number of the occurrence of Callee counting from the
beginning of the body of the clause, and ignoring any punctuation.
-
-
- Description:
-
This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to remove_spypoint/1 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
current_spypoint/1, add_spypoint/1, spy/1, nospy/1, debugging/0
-
-
Chapter E-1
L-3-152: repeat/0
- Synopsis:
-
repeat
-
-
Succeeds immediately when called and whenever reentered by backtracking.
- Description:
-
- Generally used to simulate the looping constructs found in traditional procedural languages. The general form of a repeat loop is as follows:
repeat,
action1,
action2,
...,
action<n>,
test,
!,
... rest of clause body ...
The effect of this is to execute action1 through action<n> in sequence. The test is then executed. If it succeeds, the loop is (effectively) terminated by the cut (!) (which cuts away
any alternatives in the clause, including the one created by repeat/0). A failure of the test will cause backtracking that will be caught by repeat/0, which will succeed again and
re-execute the actions.
- The easiest way to understand the effect of repeat/0 is to think of failures as "bouncing" back off them causing re-execution of the later goals.
- Repeat loops are not often needed; usually recursive procedure calls will lead to code that is easier to understand as well as more efficient. There are certain circumstances, however, in
which repeat/0 will lead to greater efficiency. An important property of Quintus Prolog is that all run-time data is stored in stacks so that any storage that has been allocated during a
proof of a goal is recovered immediately on backtracking through that goal. Thus, in the above example, any space allocated by any of the actions is very efficiently reclaimed. When an
iterative construct is implemented using recursion, storage reclamation will only be done by the garbage collector.
- Tips:
-
- In the most common use of repeat loops, each of the calls succeeds determinately. It can be confusing if calls sometimes fail, so that backtracking starts before the test is reached, or
if calls are nondeterminate, so that backtracking does not always go right back to repeat/0.
- Note that the repeat loop can only be useful if one or more of the actions involves a side-effect -- either a change to the data base (such as an assertion) or an I/O operation.
Otherwise you would do the same thing each time around the loop (which would never terminate).
-
-
Examples:
repeat/0 could have been written in Prolog as follows:
repeat.
repeat :- repeat.
L-3-153: restore/1
- Synopsis:
-
restore(+FileSpec)
-
-
Restores a saved-state.
- Arguments:
-
- FileSpec
-
<file_spec> The name of a QOF file.
- Description:
-
- restore(file) terminates the currently running executable and restarts it with the command line arguments:
% +L <file> <old args>
where <old args> are the arguments specified when the executable was started. <file> is normally a file previously created by a call to save_program, but it can be any QOF file. The +L
option causes <file> to be loaded into the executable as it starts up.
- If <file> was created by save_program/[1,2], then it includes information about operator declarations, debugging and advice information, prolog_flags, and file_search_path and
library_directory tables, as well as the Prolog code that was saved. Thus restoring <file> will create the same Prolog state and database that existed at the time the save_program was
done (assuming that the same executable that was used for the save_program is used for the restore).
- It is also possible to give any QOF file to restore/1. In this case, the running executable is reinitialized, and then the QOF file is reloaded into the system. As such QOF files store
no state information, the state is the same as in a freshly started Prolog system.
- It is not normally useful to use restore/1 in a runtime system. In a runtime system, command-line arguments are not interpreted by the system, so the re-started runtime system will just
begin again at runtime_entry(start) and will not load the specified File automatically. An application could, if the programmer so chose, pick up the arguments with unix(argv(L)), and
then take some appropriate action. For example:
runtime_entry(start) :-
unix(argv(['+L',File|_])),
!,
load_files(File),
start_after_restore.
runtime_entry(start) :-
normal_start.
See section G-3-1 and section N-1-1 for a description of the +L option.
-
-
- Exceptions:
-
- instantiation fault
FileSpec is not bound.
- type error
FileSpec is not a valid file specification.
- domain error
FileSpec is not a QOF file.
- permission error
FileSpec is not readable.
-
-
- See Also:
-
load_files/[1,2], save_modules/2, save_predicates/2, save_program/[1,2]
-
-
Chapter G-5
L-3-154: retract/1
- Synopsis:
-
-
-
retract(+*Clause)
-
-
Removes the first occurrence of dynamic clause Clause from module M.
- Arguments:
-
- Clause
-
<callable> A valid Prolog clause. MOD
-
-
- Description:
-
- retract/1 erases the first clause in the database that matches Clause. Clause is retracted in module M if specified. Otherwise, Clause is retracted in calling module.
- retract/1 is nondeterminate. If control backtracks into the call to retract/1, successive clauses matching Clause are erased. If and when no clauses match, the call to retract/1
fails.
- Clause must be of the form:
Head
or Head :- Body
or Module:Clause
where Head is of type callable and the principal functor of Head is the name of a dynamic procedure. If specified, Module must be an atom.
- retract(Head) means retract the unit-clause Head. The exact same effect can be achieved by retract((Head :- true)).
- Body may be uninstantiated, in which case it will match any body. In the case of a unit-clause it will be bound to 'true'. Thus, for example,
| ?- retract((foo(X) :- Body)), fail.
is guaranteed to retract all the clauses for foo/1, including any unit-clauses, providing of course that foo/1 is dynamic.
- Since retract/1 is nondeterminate it is important if you only want to retract a single clause to use a cut to eliminate the alternatives generated. See section G-14-4-1 for more
information on the use of cuts with retract/1.
- retract/1 searches for the clause to remove in the same way that clause/2 does. (And, like clause/2, it uses first argument indexing to speed up this search when possible.) Therefore
it is redundant to call clause/2 immediately before calling retract/1 on the clause it returns. That is, the call to clause/2 in the following program fragment can be removed without
changing its effect.
... clause(H,B), retract((H:-B)), ...
- The space occupied by a clause which is retracted is reclaimed. The reclamation does not necessarily happen immediately, but is not delayed until backtracking past the call to retract/1,
as in some implementations.
- WARNING:
retract/1 is a non-determinate procedure. Thus, we can use
| ?- retract((foo(X) :- Body)), fail.
to retract all clauses for foo/1. However, when retract/1 is used determinately; for example, to retract a single clause, it is crucial that you cut away unintended chice points to
avoid "freezing" the retracted Clause, disabling tail recursion optimization, or runaway retraction on the unexpected failure of a subsequent goal. See section G-14-4-1 for further
discussion.
-
-
- Exceptions:
-
-
- See Also::
-
-
-
abolish/[1,2], assert/1, dynamic/1, erase/1, retractall/1.
L-3-155: retractall/1
- Synopsis:
-
-
-
retractall(+Head)
-
-
Removes every clause in module M whose head matches Head.
- Arguments:
-
- Head
-
<callable> Head of a Prolog clause. MOD
-
-
- Description:
-
- Head must be instantiated to a term which looks like a call to a dynamic procedure. For example, to retract all the clauses of foo/3, you would write
| ?- retractall(foo(_,_,_)).
Head may be preceded by a M: prefix, in which case the clauses are retracted from module M instead of the calling module.
- retractall/1 could be defined (less efficiently) as
retractall(Head) :-
clause(Head, _, Ref),
erase(Ref),
fail ; true.
or
retractall(Head) :-
retract((Head :- _Body)),
fail ; true.
- retractall/1 is useful for erasing all the clauses of a dynamic procedure without forgetting that it is dynamic; abolish/1 will not only erase all the clauses, but will also forget
absolutely everything about the procedure. retractall/1 only erases the clauses. This is important if the procedure is called later on.
- Since retractall/1 erases all the dynamic clauses whose heads match Head, it has no choices to make, and is determinate. If there are no such clauses, it succeeds trivially. None of
the variables in Head will be instantiated by this command. For example,
| ?- listing(baz/2).
baz(a,1).
baz(b,2).
baz(a,3).
baz(b,4).
yes
| ?- retractall(baz(a, X)).
X = _798
| ?- listing(baz/2).
baz(b,2).
baz(b,4).
yes
- The space previously occupied by a retracted clause is reclaimed. This reclamation is not necessarily immediate, but it is not delayed until backtracking past the call of retractall/1,
as in some implementations.
-
-
- Exceptions:
-
- instantiation_error
if Head or Module is uninstantiated.
- type_error
if Head is not of type callable.
- permission_error
if the procedure corresponding to Head is built-in or has a static definition.
-
-
- See Also:
-
abolish/[1,2], assert/1, dynamic/1, erase/1, retract/1
-
-
Chapter G-14
L-3-156: runtime_entry/1 hook
- Synopsis:
-
runtime_entry(+Event)
-
-
This predicate is called upon start-up and exit of stand alone applications.
- Arguments:
-
- Event
-
one of {start, abort}
- Description:
-
- In a default runtime system, the program starts by executing the goal,
runtime_entry(start)
When that goal terminates, either by succeeding or by failing, the runtime system terminates.
- Similarly, it is possible to specify what is to be done on an abort. An abort happens when a call is made either to the built-in predicate abort/0 or to the C routine
QP_action(QP_ABORT). (By default, a call of QP_action(QP_ABORT) happens when a user types ^c -- see section H-2-4). At this point, the current computation is abandoned and the program
is restarted with the goal
runtime_entry(abort)
Effectively this replaces the original call to runtime_entry(start), so that when this call succeeds or fails, the runtime system terminates.
- Users of the module system should ensure that the predicate runtime_entry/1 is defined in the module 'user', that is, not inside any user-defined module.
- See Also:
-
QP_toplevel()
-
-
section I-2-2-1
L-3-157: save_modules/2
- Synopsis:
-
save_modules(+Modules, +File)
-
-
Saves all predicates in Modules in QOF format to File.
- Arguments:
-
- Modules
-
atom or <list of atom> An atom representing a current module, or a list of such atoms representing a list of modules.
- File
-
<file_spec> An atom representing a file name
- Description:
-
- save_modules/2 saves the current definitions of all predicates in a module, or list of modules, in QOF format into a file. The modules imported by the saved modules are recorded as
dependencies in the QOF file. The foreign files loaded into that module are also recorded as foreign dependencies in the QOF file. The QOF file produced can be loaded into a
development system (using load_files/1) or it can be linked using qld.
- When multiple modules are saved into a file, loading that file will import only the first of those modules into the module in which the load occurred.
-
-
- Exceptions:
-
- instantiation fault
Modules or File is not bound.
- type error
Modules is not a valid list of module names, or a single module name, or File is not a valid file specification.
- permission error
File is not writable.
-
-
- See Also::
-
load_files/1, save_predicates/2, save_program/1, volatile/1
L-3-158: save_predicates/2
- Synopsis:
-
save_predicates(+PredSpecs, +File)
-
-
Saves the predicates specified by the PredSpecs in QOF format to File.
- Arguments:
-
- PredSpecs
-
<pred_spec_tree> A list of predicate specifications. MOD
- File
-
<file_spec> An atom representing a file name
-
-
- Description:
-
- save_predicates/2 saves the current definitions of all the predicates specified by the list of predicate specifications in QOF format into a file. The exported and meta_predicate
properties of the predicates are not stored in the QOF file. The module of the predicates saved in the QOF file is fixed, so it is not possible to save a predicate from any module
'foo', and reload it into module 'bar'. Likewise, the module dependencies or foreign file dependencies of these predicates are not saved into the QOF file. A typical use of this would
be to take a snapshot of a table of dynamic facts. The QOF file that is written out can be loaded into a development system (using load_files/1) or it can be linked with other qof
files using qld.
-
-
- Exceptions:
-
- instantiation fault
the list of predicate specifications or the file name is not ground.
- type error
in the list of predicate specifications or in the file name.
- permission error
the file is not writable
-
-
- See Also::
-
load_files/1, save_modules/2, save_program/1, volatile/1
L-3-159: save_program/[1,2]
- Synopsis:
-
save_program(+File)
-
-
save_program(+File, +Goal)
-
-
Saves the state of the current execution in QOF format to File. A goal, Goal, to be called upon execution/restoring of the saved state, may be specified.
- Arguments:
-
- File
-
<file_spec> An atom representing a file name.
- Goal
-
<callable> A goal.
- Description:
-
- save_program/[1,2] creates a QOF representation of all predicates in all modules existing in the system. However, it does not save the user's pre-linked code. It also saves such
states of the system as operator definitions, prolog_flags, debugging and advice state, and initializations. Object files dynamically loaded into the system are saved in the qof file as
object dependencies.
- The resulting file is executable, and can be started up as a unix command, or can be restored using restore/1.
- save_program/[1,2] saves module import/export information which gets reinstated when File is loaded. No new module-importation will be done when File is loaded, because it is assumed
that it was done before save_program/[1,2] was called. Thus if your program consists of one or more modules, and you save it with save_program/[1,2], loading the resulting File into
some new module will not import any of your predicates into that module. If you want to save out a module such that it will be imported automatically into any module from which it is
loaded, then use save_modules/2.
-
-
- Exceptions:
-
- instantiation fault
File or Goal is not bound
- type error
File is not a valid file specification, or Goal is not a valid goal.
- permission error
File is not writable.
-
-
- See Also:
-
load_files/[1,2], restore/1, save_modules/2, save_predicates/2, volatile/1
-
-
Chapter G-5
L-3-160: see/1
- Synopsis:
-
see(+FileOrStream)
-
-
Makes file FileOrStream the current input stream.
- Arguments:
-
- FileOrStream
-
file_spec or <stream_object> File specification or stream object.
-
-
- Description:
-
-
- Exceptions:
-
- Instantiation error
- Existence error
FileOrStream not currently open for input, and fileerrors flag is set.
- Type error
- See Also:
-
seen/0, close/1, abort/0, seeing/1
-
-
Chapter G-7-6-4
L-3-161: seeing/1
- Synopsis:
-
seeing(-FileOrStream)
-
-
Unifies FileOrStream with the current input stream or file.
- Arguments:
-
- FileOrStream
-
file_spec or <stream_object>
- Description:
-
- Exactly the same as current_input(FileOrStream), except that FileOrStream will be unified with a file name if the current input stream was opened by see/1 (section G-7-6-4).
- Can be used to verify that FileNameOrStream is still the current input stream as follows:
/* nonvar(FileNameOrStream), */
see(FileNameOrStream),
...
seeing(FileNameOrStream)
If the current input stream has not been changed (or if changed, then restored), the above sequence will succeed for all file names and all stream objects opened by open/[3,4]. However,
it will fail for all stream objects opened by see/1 (since only file name access to streams opened by see/1 is supported). This includes the stream object 'user_input' (since the
standard input stream is assumed to be opened by see/1, and so seeing/1 would return 'user' in this case).
- If FileOrStream is instantiated to a value that is not the identifier of the current input stream, seeing(FileOrStream) simply fails.
- Can be followed by see/1 to ensure that a section of code leaves the current input unchanged:
/* var(OldFileNameOrStream), */
seeing(OldFileNameOrStream),
...
see(OldFileNameOrStream)
The above is analogous to its stream-object-based counterpart,
/* var(OldStream), */
current_input(OldStream),
...
set_input(OldStream)
Both of these sequences will always succeed regardless of whether the current input stream was opened by see/1 or open/3 (section G-7-6-4).
- See Also:
-
see/1, open/[3,4], current_input/1
L-3-162: seek/4
- Synopsis:
-
seek(+Stream, +Offset, +Method, -NewLocation)
-
-
Seeks to an arbitrary byte position in Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream
- Offset
-
<integer> the offset in bytes to seek relative to Method specified.
- Method
-
specifies where to start seeking. It is one of the following.
- bof
-
Seek from beginning of the file stream.
- current
-
Seek from current position of the file stream.
- eof
-
Seek from end of the file stream.
- NewLocation
-
<integer> The byte offset from beginning of the file after seeking operation.
- Description:
-
- Sets the current position of the file stream Stream to a new position according to Offset and Method. If Method is
- bof
-
the new position is set to Offset bytes from beginning of the file stream.
- current
-
the new position is Offset bytes plus the current position of Stream.
- eof
-
the new position is Offset bytes, a negative integer, plus the size of the file.
If Offset is 0, seek/4 returns the current position from the beginning of Stream and sets the position to the same location.
- If Stream is an output stream permitting flushing output, the characters in the buffer of the stream are flushed before seek is performed. If the output stream Stream does not permit
flushing output and there are characters remaining in the buffer, then a permission error is raised.
- If Stream is an input stream, the characters in the input buffer of the stream are discarded before seek is performed. The input buffer is empty when the seek/4 call returns.
-
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- domain_error
Method is not one of 'bof', 'current' or 'eof'.
Offset is a negative value and Method is 'bof'.
Offset is a positive value and Method is 'eof'.
- instantiation_error
Offset or Method is not instantiated.
- type_error
Stream is not a stream object.
Offset is not an integer type.
Method is not an atom type.
- permission_error
Stream names an open stream but the stream is not open with seek(byte) permission. An error occurred while seeking in the file stream.
Flushing attempted but not permitted.
-
-
- See Also:
-
stream_position/[2,3], open/4, character_count/2, line_count/2, line_position/2.
-
-
Chapter G-7
L-3-163: seen/0
- Synopsis:
-
seen
-
-
Closes the current input stream.
- Description:
-
- Current input stream is set to be user_input; that is, the user's terminal.
- Always succeeds
- See Also:
-
close/1
L-3-164: set_input/1
- Synopsis:
-
set_input(+Stream)
-
-
makes Stream the current input stream.
- Arguments:
-
- Stream
-
<stream_object> a valid input stream
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Instantiation error
- Type error
- See Also:
-
read/1, get/1
L-3-165: set_output/1
- Synopsis:
-
set_output(+Stream)
-
-
makes Stream the current output stream.
- Arguments:
-
- Stream
-
<stream_object> a valid output stream
- Description:
-
Subsequent output predicates such as write/1 and put/1 will use this stream.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Instantiation error
- Type error
-
-
- See Also::
-
write/1, put/[1,2]
L-3-166: setof/3
- Synopsis:
-
setof(+Template, +*Generator, *Set)
-
-
Returns the set Set of all instances of Template such that Generator is provable.
- Arguments:
-
- Template
-
<term>
- Generator
-
<callable> a goal to be proved as if by call/1. MOD
- Set
-
<list of term> non-empty set
- Description:
-
- Set is a set of terms represented as a list of those terms, without duplicates, in the standard order for terms (see Chapter G-9-7). If there are no instances of Template such that
Generator is satisfied, then setof/3 simply fails.
- Obviously, the set to be enumerated should be finite, and should be enumerable by Prolog in finite time. It is possible for the provable instances to contain variables, but in this case
Set will only provide an imperfect representation of what is in reality an infinite set.
- If Generator is instantiated, but contains uninstantiated variables which do not also appear in Template, then setof/3 can succeed nondeterminately, generating alternative values for
Set corresponding to different instantiations of the free variables of Generator. (It is to allow for such usage that Set is constrained to be non-empty.)
- If Generator is of the form A^B then all the variables in A are treated as being existentially quantified.
- Examples:
-
See findall/3 for examples that illustrate the differences among findall/3, setof/3, and bagof/3.
- Exceptions:
-
As for call/1:
- type error
- context error
- instantiation error
- See Also:
-
bagof/3, ^/2
-
-
Chapter G-15
L-3-167: show_profile_results/[0,1,2]
- Synopsis:
-
show_profile_results
-
-
show_profile_results(+By)
-
-
show_profile_results(+By,+Num)
-
-
Displays the results of the last profiled execution.
- Arguments:
-
- By
-
<atom> must be one of the atoms
by_time by_choice_points
by_calls by_redos
- Num
-
<integer>
- Description:
-
- Displays profiling information accumulated from the last call to profile/1. The By argument specifies the display mode which determines how the list is sorted and what the percentage
figure included in the output refers to. The Num argument determines the maximum number of predicates displayed. This list is always sorted in descending order so that the top Num
predicates are displayed for a give display mode.
- The output lists the predicate name, number of calls, choice points and redos for the predicate, then the time in milliseconds and a percentage figure that depends on the display mode. For
example, if the display mode is by_calls then this is the percentage of the total calls during profiling made to this predicate.
- Then the callers are listed, showing for each caller the predicate name, clause number and call number within that clause of the call, followed by the number of calls made from here and
the percentage of time spent in the predicate attributed to this caller.
- show_profile_results/1 displays up to a maximum of 10 predicates.
- show_profile_results/0 displays up to a maximum of 10 predicates using the by_time display mode.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to show_profile_results/[0,1,2] as it would a call to any other undefined predicate,
printing a warning. If it is called during the execution of a runtime system, an existence exception is raised.
- Example:
-
| ?- show_profile_results(by_time, 3).
Proc Calls ChPts Redos Time %
Caller(proc,cl#,cll#,%)
user:setof/3 227 0 0 2.04 34.0
user:satisfy/1,6,1 152 61.0
user:seto/3,1,1 48 20.0
user:satisfy/1,7,1 27 17.0
user:satisfy/1 35738 36782 14112 0.32 5.3
user:satisfy/1,1,2 13857 43.0
user:satisfy/1,2,1 12137 31.0
user:satisfy/1,1,1 7315 18.0
user:satisfy/1,3,1 1155 6.0
user:inv_map_l/5 4732 4732 3115 0.20 3.3
user:inv_map_l/5,2,1 3115 60.0
user:inv_map/4,5,1 1617 40.0
- See Also:
-
profile/[0,1], get_profile_results/4, noprofile/0
L-3-168: simple/1 meta-logical
- Synopsis:
-
simple(+Term)
-
-
Term is currently instantiated to either an atom, a number, a data base or a variable.
- Arguments:
-
- Term
-
<term>
- Examples:
-
| ?- simple(9).
yes
| ?- simple(_X).
_X = _2487
| ?- simple("a").
no
- See Also:
-
atom/1, number/1, var/1, compound/1, callable/1, nonvar/1
L-3-169: skip/[1,2]
- Synopsis:
-
skip(+Char)
-
-
skip(+Stream, +Char)
-
-
Skips over characters from the current input stream, or Stream, through the first character whith an ASCII code that match the lower 8-bits of the value of the integer expression Char.
- Arguments:
-
- Stream
-
<stream_object>
- Char
-
<expr> an integer expression.
- Description:
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Instantiation error
- Type error
- Domain error
Char evaluates to a float, or an integer outside the range 0..255
- Existence error
If Char does not appear on the current input stream, an error message is given for reading beyond the end of the stream, and the computation is aborted.
The portion of the input following Char is not a valid Prolog term
- See Also:
-
tab/1
L-3-170: skip_line/[0,1]
- Synopsis:
-
skip_line
-
-
skip_line(+Stream)
-
-
Skip the remaining input characters on the current line on the current input stream, or on Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog input stream
-
-
- Exceptions:
-
- instantiation_error
Stream argument is not ground.
- type_error
Stream is not an input stream type.
- existence_error
Stream is syntactically valid but does not name an open stream, or
This is an attempt to read past the end of file, or
Some operating system dependent error occurred in reading.
- permission_error
Stream names an open stream but the stream is not open for input.
-
-
- Comments:
-
Coding with skip_line/[0,1] and at_end_of_line/[0,1] to handle line input is more portable among different operating systems than checking end of line by the input character code.
- See Also:
-
get0/[1,2], at_end_of_line/[0,1], at_end_of_file/[0,1].
L-3-171: sort/2
- Synopsis:
-
sort(+List1, -List2)
-
-
Sorts the elements of the list List1 into the ascending standard order, and removes any multiple occurrences of an element. The resulting sorted list is unified with the list
List2.
- Arguments:
-
- List1
-
<list of term>
- List2
-
<list of term>
- Examples:
-
| ?- sort([a,X,1,a(x),a,a(X)], L).
L = [X,1,a,a(X),a(x)]
(The time taken to do this is at worst order (N log N) where N is the length of the list.)
- Exceptions:
-
- instatiation error
List1) is not properly instantiated
- type error
List1) is not a proper list
- See Also:
-
keysort/2
Chapter G-9-7-2
L-3-172: source_file/[1,2,3]
- Synopsis:
-
source_file(+AbsFile)
-
-
source_file(*AbsFile)
-
-
source_file(*Pred, *AbsFile)
-
-
source_file(*Pred, *ClauseNumber, *AbsFile)
-
-
AbsFile is the absolute name of a loaded file, and ClauseNumber is the number of a clause for Pred in that file.
- Arguments:
-
- AbsFile
-
<atom> absolute file name
- Pred
-
<callable> selected predicate specification. MOD
- ClauseNumber
-
<integer> integer representing clause number
- Description:
-
- Loaded files include compiled, QOF loaded and pre-linked files.
- If AbsFile is not the name of a loaded file, then source_file(AbsFile) simply fails. If AbsFile is bound to an illegal file name, source_file/1 fails.
- If Pred is not a loaded predicate, then source_file/2 simply fails. If bound to an illegal predicate specification, it fails.Pred is assumed to refer to the source module. Thus, to
find ANY predicates defined in a given file, use the form:
source_file(M:P, <file>)
- source_file/3 is true if clause number ClauseNumber of predicate Pred comes from file AbsFile. source_file/3 is useful for handling multifile predicates, but it works for predicates
defined completely in one file, as well.
- Any combination of bound and unbound arguments is possible, and source_file/3 will generate the others.
-
-
- Backtracking:
-
- If AbsFile is unbound, it is successively unified with the absolute names of all currently loaded files. Files loaded through the foreign function interface are not reported by
source_file/1.
- If Pred is instantiated to the skeletal specification of a loaded predicate, then AbsFile will be successively unified with the absolute names of the files in which the Pred was
defined.
- If AbsFile is instantiated to the absolute name of a loaded file, then Pred will be successively unified with the skeletal specifications of all predicates defined in AbsFile.
- See Also:
-
absolute_file_name/[2,3], multifile/1
L-3-173: spy/1
- Synopsis:
-
spy(+PredSpecs)
-
-
Sets spypoints on all the predicates represented by PredSpecs
- Arguments:
-
- PredSpecs
-
<gen_pred_spec_tree> Single predicate specification of form MOD
-
-
List of predicate specifications
-
-
- Description:
-
- Turns debugger on in debug mode, so that it will stop as soon as it reaches a spypoint. Turning off the debugger does not remove spypoints. Use nospy/1 or nospyall/0) to explicitly
remove them.
- Note that since 'spy' is a built-in operator, the parentheses which usually surround the arguments to a predicate are not necessary (although they can be used if desired).
- If you use the predicate specification form Name but there are no clauses for Name (of any arity), then a warning message will be displayed and no spypoint will be set.
| ?- spy test.
% The debugger will first leap -- showing
spypoints (debug)
* There are no predicates with the name test in
module user
yes
[debug]
- To place a spypoint on a currently undefined procedure, use the full form Name/Arity; you will still get a warning message, but the spypoint will be set .
| ?- spy test/1.
* You have no clauses for user:test/1
% Spypoint placed on user:test/1
yes
[debug]
| ?-
- If spy/1 is given any invalid argument it prints a warning.
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to predname/1 as it would a call to any other undefined predicate, printing a
warning. If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
nospy/1, nospyall/0, debug/0, current_spypoint/1, add_spypoint/1, remove_spypoint/1
L-3-174: statistics/[0,2]
- Synopsis:
-
statistics
-
-
Displays statistics relating to memory usage and execution time.
-
-
statistics(+Keyword, -List)
-
-
statistics(*Keyword, *List)
-
-
Obtains individual statistics.
- Arguments:
-
- Keyword
-
<atom> atom - keyword such as 'runtime'
- List
-
<list of integer> list of statistics (see Example)
-
-
__________
Keyword List
Times are given in milliseconds and sizes are given
in bytes.
runtime [cpu time used by Prolog, cpu time since
last call to statistics/[0,2](in millisecs)]
system_time [cpu time used by the operating system,
cpu time used by the system since the last
call to statistics/2]
real_time [wall clock time since 00:00 GMT 1/1/1970,
wall clock time since the last call
to statistics/2]
memory [total virtual memory in use,
total virtual memory free]
stacks [total global stack memory,
total local stack memory]
program [program space, 0]
global_stack [global stack in use, global stack free]
local_stack [local stack in use, local stack free]
trail [size of trail, 0]
garbage_collection
[number of GCs, freed bytes, time spent]
stack_shifts [number of global stack area shifts, number of
local stack area shifts, time spent shifting]
atoms [number of atoms, atom space in use,
atom space free]
atom_garbage_collection
[number of AGCs, freed bytes, time spent]
core (same as memory)
heap (same as program)
__________
- Description:
-
statistics/0 displays various statistics relating to memory usage, runtime and garbage collection, including information about which areas of memory have overflowed and how much time has
been spent expanding them.
-
-
Garbage collection statistics are initialized to zero when a Prolog session starts (this includes sessions started from saved-states created by save_program/[1,2], and includes re-starts
caused when restore/1 is used). The statistics increase until the session is over.
-
-
statistics/2 is usually used with Keyword instantiated to a keyword such as 'runtime' and List unbound. The predicate then binds List to a list of statistics related to the keyword. It
can be used in programs which depend on current runtime statistical information for their control strategy, and in programs which choose to format and write out their own statistical
summaries.
-
-
If keyword is 'garbage_collection' the list returned contains three elements:
- the number of garbage collections performed since the beginning of the Prolog session.
- the number of bytes of heap space freed by those garbage collections.
- the number of milliseconds spent performing those garbage collections.
- Examples:
-
The output from statistics/0 looks like this:
__________
memory (total) 377000 bytes: 350636 in use, 26364 free
program space 219572 bytes
atom space (2804 atoms) 61024 in use, 43104 free
global space 65532 bytes: 9088 in use, 56444 free
global stack 6984 bytes
trail 16 bytes
system 2088 bytes
local stack 65532 bytes: 356 in use, 65176 free
local stack 332 bytes
system 24 bytes
0.000 sec. for 0 global and 0 local space shifts
0.000 sec. for 0 garbage collections
which collected 0 bytes
0.000 sec. for 0 atom garbage collections
which collected 0 bytes
0.233 sec. runtime
__________
-
-
To report information on the runtime of a predicate p/0, add the following to your program:
:- statistics(runtime, [T0|_]),
p,
statistics(runtime, [T1|_]),
T is T1 - T0,
format('p/0 took ~3d sec.~n', [T]).
- See Also:
-
Chapter DISPLAYINGSTATISTICS
L-3-175: stream_code/2
- Synopsis:
-
stream_code(-Stream, +CStream)
-
-
stream_code(+Stream, -CStream)
-
-
Converts between Prolog representation, Stream, and C representation, CStream, of a stream.
- Arguments:
-
- Stream
-
<stream_object> a variable or a valid Prolog stream
- CStream
-
<integer> a variable or a valid C stream
-
-
- Description:
-
- stream_code/2 is used when there are input/output related operations performed on the same stream in both Prolog code and foreign code.
- Stream argument is a valid type if it is user, user_input, user_output, user_error, a variable, or a value obtained through open/[3,4] or previous stream_code/2 call. Such a valid
Stream value can be used as the stream argument to any of the Prolog built-in I/O predicates taking a stream argument.
- CStream argument is a valid type if it is a variable, a value obtained through previous stream_code/2 call, a value obtained through QP_fopen(), QP_fdopen(), or a value of pointer to
QP_stream structure obtained through foreign function call. Such a valid CStream value can be used as the stream argument to any of the QP foreign function taking stream as an argument.
-
-
- Exceptions:
-
- instantiation_error
Stream argument or CStream argument is not ground.
- type_error
Stream or CStream is not a stream type or CStream is not an integer type.
- existence_error
Stream is syntactically valid but does not name an open stream or CStream is of integer type but does not name a pointer to a stream
-
-
- Comments:
-
The most frequent use of stream_code/2 is to get a stream value to be used in Prolog code for a stream created in foreign code. This is necessary when a desired stream can not be obtained
through open/[3,4]; e.g., a stream referring to a socket or an encrypted file.
- See Also::
-
open/[3,4], QP_fopen(), QP_fdopen()
L-3-176: stream_position/[2,3]
- Synopsis:
-
stream_position(+Stream, -Current)
-
-
True when Current represents the current position of Stream.
-
-
stream_position(+Stream, -Current, +New)
-
-
Unifies the current position of the read/write pointer for Stream with Current, then sets the position to New.
- Arguments:
-
- Stream
-
<stream_object> an open stream
- Current
-
<term> stream position object representing the current position of Stream.
- New
-
<term> stream position object
- Caution:
-
A stream position object is represented by a special Prolog term. The only safe way of obtaining such an object is via stream_position/3 or stream_position/2. You should not try to
construct, change, or rely on the form of this object. It may vary under different operating systems and/or change in subsequent versions of Quintus Prolog. On some systems, a stream
position object currently has the form:
'$stream_position'(CharCount, LineCount, LinePos, Magic1,
Magic2)
- Description:
-
- Character count, line count and line position determine the position of the pointer in the stream. Such information is found by using character_count/2, line_count/2 and
line_position/2.
- stream_position/2 may be used on any stream at all: streams which are connected to disk files, streams which are connected to sockets, streams which are connected to the terminal
(including the standard streams 'user_input', 'user_output', 'user_error'), and even streams defined using QP_make_stream().
stream_position/3 may only be used on streams that are connected to disk files.
- Standard term comparison of two stream position objects for the same stream will work as one expects. When SP1 and SP2 refer to positions in the same stream, SP1 @< SP2 if and only if
SP1 is before SP2 in the stream.
-
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Type error
Current, New are not valid stream position objects.
- Instantiation error
-
-
- Example:
-
To find the current position of a stream without changing it, one can ask
| ?- stream_position(Stream, Current).
- See Also:
-
seek/4, open/[3,4], character_count/2, line_count/2, line_position/2.
Chapter G-7
L-3-177: style_check/1
- Synopsis:
-
style_check(+Type)
-
-
Turns on the specified Type of compile-time style checking.
- Arguments:
-
- Type is one of the following atoms:
-
- all
-
Turn on all style checking.
- single_var
-
Turn on checking for clauses containing a single instance of a named variable, where variables that start with a '_' are not considered named.
- discontiguous
-
Turn on checking for procedures whose clauses are not all adjacent to one another in the file.
- multiple
-
Turn on checking for multiple definitions of the same procedure in different files.
-
-
- Description:
-
- Since all style checking is on by default, this predicate is only used to put back style checking after it has been turned off by no_style_check/1.
-
-
- Exceptions:
-
- instantiation_error
Type is not bound.
- type_error
Type is not an atom.
- domain_error
Type is not a valid type of style checking.
-
-
- See Also:
-
no_style_check/1.
L-3-178: subsumes_chk/2
- Synopsis:
-
subsumes_chk(+General, +Specific)
-
-
True when General subsumes Specific; that is, when Specific is an instance of General.
- Arguments:
-
- General
-
<term>
- Specific
-
<term>
- Description:
-
- In previous releases, subsumes_chk/2 was available as a library predicate. In release 2.5, it was made part of the system because it was found to be useful in applications such as
writing theorem provers. The built-in predicate behaves identically to the original version of subsumes_chk/2 but is much more efficient.
- Term subsumption is a sort of one-way unification. Term S and T unify if they have a common instance, and unification in Prolog instantiates both terms to that common instance. S
subsumes T if T is already an instance of S. For our purposes, T is an instance of S if there is a substitution that leaves T unchanged and makes S identical to T.
-
-
- Comments:
-
There are two other related predicates defined in library(subsumes), subsumes/2 and variant/2. These predicates are defined in terms of subsumes_chk/2, and they are still available in that
library package.
- See Also:
-
library(subsumes), library(occurs)
L-3-179: tab/[1,2]
- Synopsis:
-
tab(+Integer)
-
-
tab(+Stream, +Integer)
-
-
Writes Integer spaces to the current output stream, or Stream.
- Arguments:
-
- Stream
-
<stream_object>
- Integer
-
<expr> an integer expression.
- Description:
-
- If Integer evaluates to a negative integer, tab/1 simply succeeds without doing anything.
- If the current output device is the user's terminal, the spaces are not necessarily printed immediately; see ttyflush/0.
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Type error
N is not an integer
- Instantiation error
- See Also:
-
ttyflush/0
L-3-180: tell/1
- Synopsis:
-
tell(+FileOrStream)
-
-
makes FileOrStream the current output stream.
- Arguments:
-
- FileOrStream
-
file_spec or <stream_object> file specification or, stream object.
- Description:
-
- Exceptions:
-
- Permission error
FileOrStream exists but cannot be opened.
- Instantiation error
- Type error
- Existence error
FileOrStream not currently open for input, and fileerrors flag is set.
- See Also:
-
told/0, telling/1
L-3-181: telling/1
- Synopsis:
-
telling(-FileOrStream)
-
-
Unifies FileOrStream with the current output stream.
- Arguments:
-
- FileOrStream
-
file_spec or <stream_object>
- Description:
-
- Examples:
-
- WARNING: The following sequence will fail if the current output stream was opened by tell/1.
telling(File),
...
set_output(File),
- The only sequences that are guaranteed to succeed are
telling(FileOrStream),
...
tell(FileOrStream)
and
current_output(Stream),
...
set_output(Stream)
-
-
- See Also:
-
tell/1, open/[3,4], current_output/1
L-3-182: term_expansion/2 hook
- Synopsis:
-
term_expansion(+Term1, -Term2)
-
-
The user may override the standard transformations to be done by expand_term/2 by defining clauses for term_expansion/2.
- Arguments:
-
- Term1
-
<term>
- Term2
-
<term>
- Description:
-
- expand_term/2 calls term_expansion/2 first; if it succeeds, the standard grammar rule expansion is not tried.
- expand_term/2 always calls term_expansion/2 in module 'user'. Therefore, to be visible to expand_term/2, term_expansion/2 must either be defined in or imported into module 'user'.
Alternatively, you may define it in any module by using module prefixing; refer to section G-13-5.
- This hook predicate may now return a list of terms rather than a single term. Each of the terms in the list is then treated as a separate clause.
- Tip:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See Also:
-
expand_term/2, -->/2, phrase/[2,3], 'C', prolog_load_context/2.
Chapter G-16
L-3-183: told/0
- Synopsis:
-
told
-
-
Closes the current output stream.
- Description:
-
- Current output stream is set to be user_output; that is, the user's terminal.
- Always succeeds without error.
-
-
L-3-184: trace/0
- Synopsis:
-
trace
-
-
Turns the debugger on and starts it creeping; that is, it sets the debugger to trace mode.
- Description:
-
- The debugger will start showing goals as soon as the first call is reached, and it will stop to allow you to interact as soon as it reaches a leashed port (see leash/1, section L-3-90).
Setting the debugger to trace mode means that every time you type a query, the debugger will start by creeping.
- The effect of this predicate can also be achieved by typing the letter 't' after a ^c interrupt (see section G-11-1).
- This predicate is not supported in runtime systems. When building a runtime system, qld treats a call to trace/0 as it would a call to any other undefined predicate, printing a warning.
If it is called during the execution of a runtime system, an existence exception is raised.
- See Also:
-
debug/0, notrace/0
L-3-185: trimcore/0
- Synopsis:
-
trimcore/0
-
-
Force reclamation of memory in all of Prolog's data areas.
- Description:
-
Reduces the free space in all the data areas as much as possible, and gives the space no longer needed back to the operating system.
- Exceptions:
-
Automatically called after each directive at the top level.
- See Also:
-
Chapter G-12-1-1
L-3-186: true/0
- Synopsis:
-
true
-
-
Always succeeds. This could have been trivially defined in Prolog by the single clause:
true.
L-3-187: ttyflush/0, ttyget/1, ttyget0/1, ttynl/0, ttyput/1, ttyskip/1, ttytab/1
- Synopsis:
-
ttyflush
Equivalent to flush_output(user).
-
-
ttyget(-Char)
Equivalent to get(user, Char).
-
-
ttyget0(-Char)
Equivalent to get0(user, Char).
-
-
ttynl
Equivalent to nl(user).
-
-
ttyput(+Char)
Equivalent to put(user, Char).
-
-
ttyskip(+Char)
Equivalent to skip(user, Char).
-
-
ttytab(+Integer)
Equivalent to tab(user, Integer).
- Arguments:
-
- Char
-
<char>
- Integer
-
<expr>
- Description:
-
- For compatibility with DEC-10 Character I/O a set of predicates are provided which are similar to the primary ones except that they always use the standard input and output streams, which
normally refer to the user's terminal rather than to the current input stream or current output stream. They are easily recognizable as they all begin with "tty".
- Given stream-based input/output, these predicates are actually redundant. For example, you could write get0(user, C) instead of ttyget0(C).
L-3-188: unix/1
- Synopsis:
-
unix(shell(+UnixCommand))
Spawns a unix shell and executes UnixCommand.
-
-
unix(system(+UnixCommand))
Spawns a unix sh(1) process and executes UnixCommand.
-
-
unix(system(+UnixCommand, -Status))
Spawns a unix sh(1) process and executes UnixCommand. The exit status of the executed command is returned in Status.
-
-
unix(cd(+Path))
Changes working directory to Path.
-
-
unix(argv(-ArgList))
Returns in ArgList the list of commandline arguments as Prolog objects.
-
-
unix(args(-ArgList))
Returns in ArgList the list of commandline arguments as a list of atoms.
- Arguments:
-
- UnixCommand
-
<term> atom corresponding to a unix command (or null) Status
exit status of the unix command executed
- Path
-
atom corresponding to a legal directory (or null)
- ArgList
-
list of arguments used to start up current session.
- Description:
-
- unix(cd) changes the working directory of Prolog (and of Emacs if running under the editor interface) to your home directory. Note that the 'Escape x cd' command under Emacs has the same
effect as this, except that Emacs also provides filename completion.
- If the return status of UnixCommand is 0, unix(system(UnixCommand)) succeeds, otherwise it fails.
- unix(system(UnixCommand, Status)) returns the status of the executed command, similar to the unix command system(3). The low-order 8 bits of the Status is the value returned by the Unix
call wait(2V) and the next 8-bits higher up in the Status has the shell exit status if the shell was not interrupted by a signal. An exit status of 127 indicates that the shell could not
be executed.
- To start up an interactive shell, type unix(shell).
- If ArgList is instantiated to a term which does not unify with the result returned, unix(argv(ArgList)) or unix(args(ArgList)) will simply fail.
-
-
- Exceptions:
-
- Instantiation error
Argument to unix/1 is not sufficiently instantiated.
- Type error
Path is not an atom.
- Existence error
Path is a nonexistent directory.
-
-
- Examples:
-
- To list the QOF files in the current working directory:
| ?- unix(shell('ls -l *.qof')).
-rw-rw-r-- 1 joe 9152 Oct 20 1990 table.qof
-rw-rw-r-- 1 joe 576 Oct 25 1990 test.qof
yes
Alternatively, enter an interactive unix shell, execute commands, and type 'exit' to return to prolog:
| ?- unix(shell).
% ls -l *.qof
-rw-rw-r-- 1 joe 9152 Oct 20 1990 table.qof
-rw-rw-r-- 1 joe 576 Oct 25 1990 test.qof
% exit
yes
| ?-
- If Prolog was invoked using the command (A), the command line arguments can be retrieved as in (B):
% prolog screaming yellow + yellow.pl (A)
.
.
.
| ?- unix(argv(ArgList)). (B)
ArgList = [screaming, yellow]
-
-
- See Also:
-
QP_initialize(), QP_toplevel(), system/1 -- from library(strings)
-
-
Chapter G-18
L-3-189: unknown/2
- Synopsis:
-
unknown(-OldAction, +NewAction)
-
-
Unifies OldAction with the current action on unknown procedures, and then sets the current action to NewAction.
- Arguments:
-
- OldAction
-
one of {error, fail}
- NewAction
-
one of {error, fail}
- Description:
-
- See Also:
-
unknown_predicate_handler/3
L-3-190: unknown_predicate_handler/3 hook
- Synopsis:
-
unknown_predicate_handler(+Goal, +Module, -NewGoal)
-
-
User definable hook to trap calls to unknown predicates
- Arguments:
-
- Goal
-
<callable> Any Prolog term
- Module
-
<atom> Any atom that is a current module
- NewGoal
-
<callable> Any callable Prolog term
-
-
- Description:
-
When Prolog comes across a call to an unknown predicate and the unknown flag is set to 'error', Prolog makes a call to unknown_predicate_handler/3 in module user with the first two
arguments bound. Goal is bound to the call to the undefined predicate and Module is the module in which that predicate is supposed to be defined. If the call to
unknown_predicate_handler/3 succeeds then Prolog replaces the call to the undefined predicate with the call to NewGoal. By default NewGoal is called in module user. This can be
overridden by making NewGoal have the form Module:SomeGoal.
- Examples:
-
- The following clause gives the same behaviour as setting unknown(_,fail).
unknown_predicate_handler(_, _, fail).
- The following clause causes calls to undefined predicates whose names begin with "xyz_" in module "m" to be trapped to my_handler/1 in module "n". Predicates with names not beginning with
this character sequence are not affected.
unknown_predicate_handler(G, m, n:my_handler(G)) :-
functor(G,N,_),
atom_chars(N,Chars),
append("xyz_" _, Chars).
- Tips:
-
If you define clauses for this hook predicate, it should be declared multifile in each file containing clauses for it. Without this multifile declaration, it will be impossible to use this
code with other (possibly library) code that has clauses for this hook.
- See Also:
-
unknown/2, prolog_flag/3
L-3-191: use_module/[1,2,3]
- Synopsis:
-
use_module(+Files)
-
-
Loads the module file(s) Files, if not already loaded and up-to-date imports all exported predicates.
-
-
use_module(+File, +Imports)
-
-
Loads module file File, if not already loaded and up-to-date imports according to Imports.
-
-
use_module(+Module, -File, +Imports)
-
-
Module is already loaded and up-to-date. Imports according to Imports.
-
-
use_module(-Module, +File, +Imports)
- Module has not been loaded, or is out-of-date. Loads Module from File and imports according to Imports.
-
- Arguments:
-
- File
-
<file_spec> or <list of file_spec> Any legal file specification. Only use_module/1 accepts a list of file specifications. A ".pl" or ".qof" extension may be omitted in a file
specification. MOD
- Imports
-
<list of simple_pred_spec> A list of predicate specifications in the Name/Arity form to import into the calling module
- all
-
all predicates exported by the module are to be imported.
- Module
-
<atom> The module name in Files, or a variable, in which case the module name is returned.
-
-
- Description:
-
- Loads each specified file except the previously loaded files which have not been changed since last loaded. All files must be module files, and all the public predicates of the modules
are imported into the calling module (or module M if specified).
- use_module/2 imports only the predicates in Imports when loading Files.
- use_module/3 allows Module to be imported into another module without requiring that its source file (File) be known, as long as the Module already exists in the system. This
predicate is particularly useful when the module in question has been linked with the Development Kernel as described in Chapter H-1.
- Generally, use_module/3 is similar to use_module/[1,2], except that if Module is already in the system, Module, or predicates from Module, are simply imported into the calling module,
and File is not loaded again. If Module does not already exist in the system, File is loaded, and use_module/3 behaves like use_module/2, except that Module is unified, after the
file has been loaded, with the actual name of the module in File. If Module is a variable, File must exist, and the module name in File is returned.
- When use_module/3 is called from an embedded command in a file being compiled with qpc, and File is unbound, an initialization/1 fact is generated, so that the actual execution of the
use_module/3 command is delayed until the QOF file is loaded. This means that the module given must exist when the QOF file is loaded, but not when it is created.
- As File is not checked if Module already exists in the system, and File can even be left unnamed in that case, for example,
:- use_module(mod1, _, all).
In other words, the file name may be an unbound variable as long as Module is already in the system.
- Special case of load_files/2 and is defined as
use_module(Files) :-
load_files(Files, [if(changed),
load_type(latest),
must_be_module(true)]).
use_module(File, Imports) :-
load_files(File, [if(changed),
load_type(latest),
must_be_module(true),
imports(Imports)]).
- use_module/1 is similar to ensure_loaded/1 except that all files must be module-files.
- An attempt to import a predicate may fail or require intervention by the user because a predicate with the same name and arity has already been defined in, or imported into, the loading
module (or module M if specified). Details of what happens in the event of such a name clash are given in section G-13-12.
- After loading the module-file, the source module will attempt to import all the predicates in Imports. Imports must be a list of predicate specifications in Name/Arity form. If any of
the predicates in Imports are not public predicates, an error message is printed, but the predicates are imported nonetheless. This lack of strictness is for convenience; if you forget
to declare a predicate to be public, you can supply the necessary declaration and reload its module, without having to reload the module that has imported the predicate.
- While use_module/1 may be more convenient at the top level, use_module/2 is recommended in files because it helps document the interface between modules by making the list of imported
predicates explicit.
- For consistency, use_module/2 has also been extended so that the Imports may be specified as the term 'all', in which case it behaves the same as use_module/1, importing the entire
module into the caller.
- For further details on loading files, see Chapter G-4. On file specifications, see Chapter G-6.
-
-
- Exceptions:
-
- instantiation_error
M, Files, or Imports is not ground.
- type_error
One of the arguments is the wrong type.
- existence_error
A specified file does not exist. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
- permission_error
A specified file is protected. If the nofileerrors flag is on, the predicate fails instead of raising this exception.
-
-
- See Also:
-
compile/1, ensure_loaded/1, initialization/1, load_files/[1,2], volatile/1,
-
-
Chapter G-4, Chapter G-6
L-3-192: user_help/0 hook
- Synopsis:
-
user_help
-
-
A hook for users to add more information when help/0 is called.
- Description:
-
Useful when you want a standard way to tell users something, like how to run a demo.
-
-
help/0 always calls user_help/0 in module 'user'. Therefore, to be visible to help/0, user_help/0 must either be defined in or imported into module 'user'.
- Example:
-
The common test harness for many Quintus test suites includes the clause:
user_help :-
suite_type(_,Type), suite_host(Host),
write('You have loaded the Quintus test suite for '),
write(Type), write(' on '), write(Host), nl, nl,
write('You can invoke the suite as follows:'), nl, nl,
write(' ?- quiet. % run suite, concise output'), nl,
write(' ?- verbose. % run suite, verbose output'), nl,
write(' ?- quiet(+Pred). % run suite, concise output for'), nl,
write(' % tests of predicate Pred'), nl,
write(' ?- quiet(+Pred, +N). % similar to above, but runs the'),nl,
write(' % test specified by N'), nl,
write(' ?- verbose(+Pred). % run suite, verbose output for'), nl,
write(' % tests of predicate Pred'), nl,
write(' % (Pred a name, NOT name/arity!'),nl,
write(' ?- verbose(+Pred, +N). % similar to above, but runs the'),nl,
write(' % test specified by N'), nl,
write(' ?- help. % to get this message'), nl.
-
-
So if you compile the Prolog, C, Pascal or FORTRAN suites, you have a consistent help message telling you how to run the suites:
-
-
<run prolog>
<compile /ptg/suite/plsuite.pl>
| ?- help.
-
-
If You have loaded the Quintus test suite for Prolog on Sun ??? You can invoke the suite as follows:
-
-
?- quiet. % run suite, concise output
?- verbose. % run suite, verbose output
?- quiet(+Pred). % run suite, concise output for
% tests of predicate Pred
?- quiet(+Pred, +N). % similar to above, but runs the
% test specified by N
?- verbose(+Pred). % run suite, verbose output for
% tests of predicate Pred
% (Pred a name, NOT name/arity!
?- verbose(+Pred, +N). % similar to above, but runs the
% test specified by N
?- help. % to get this message
- See Also:
-
help/1
Chapter G-17
L-3-193: var/1 meta-logical
- Synopsis:
-
var(+Term)
-
-
Term is currently uninstantiated ('var' is short for variable).
- Arguments:
-
- Term
-
<term>
- Description:
-
An uninstantiated variable is one which has not been bound to anything, except possibly another uninstantiated variable. Note that a compound term with some arguments which are
uninstantiated is not itself considered to be uninstantiated.
- Examples:
-
| ?- var(foo(X,Y)).
no
| ?- var([X,Y]).
no
| ?- var(X).
X = _3437 ;
no
| ?- Term = foo(X,Y), var(Term).
no
- See Also:
-
atom/1, atomic/1, number/1, compound/1, callable/1, nonvar/1, simple/1
L-3-194: version/[0,1]
- Synopsis:
-
version
-
-
version(+Atom)
-
-
Display system identification messages
-
-
Add the atom A to the list of introductory messages.
- Arguments:
-
- Atom
-
<atom>
L-3-195: vms/[1,2]
- Synopsis:
-
vms(+-Command)
-
-
vms(+-Command, +Flag)
-
-
Issue a VMS specific system command (only available on VMS platforms).
- Arguments:
-
- Command
-
<term>
- Flag
-
n | i
L-3-196: volatile/1 declaration
- Synopsis:
-
:-volatile(+PredSpecs)
-
-
Declares PredSpecs to be volatile. Volatile predicates are not saved in QOF files by Prolog 'save' predicates.
- Arguments:
-
- PredSpecs
-
<pred_spec_forest> A single predicate specification of the form Name/Arity, or a sequence of predicate specifications separated by commas. Name must be an atom and Arity an
integer in the range 0..255. MOD
-
-
- Description:
-
- A built-in prefix operator, so that declarations can be written as e.g.
:- volatile a/1, b/3.
- callable both at compile-time and run-time. In both cases the predicate specified will, with immediate effect, be declared as volatile.
- When used as a compile-time directive, the volatile declaration of a predicate must appear before all clauses of that predicate. The predicate is reinitialized.
- When used as a callable goal, the only effect on the predicate is that it is set to be volatile.
-
-
- Exceptions:
-
- instantiation_error
If PredSpec is not ground.
- type_error
If PredSpec is not a proper predicate specification.
- permission_error
PredSpec names a non-volatile predicate which is already defined (This exception is only raised when volatile is used as a compile-time directive).
-
-
- Comments:
-
- Whether PredSpec is volatile can be checked with predicate_property/2.
- The properties, as well as the predicate, can be deleted with abolish/1.
- PredSpec clauses are saved by qpc.
-
-
- Examples:
-
see examples under initialization/1.
- See Also:
-
initialization/1, save_program/[1,2], save_modules/2, save_predicates/2
-
-
Chapter G-5-6-2
L-3-197: write/[1,2]
- Synopsis:
-
write(+Term)
-
-
write(+Stream, +Term)
-
-
Writes Term to the current output stream or Stream.
- Arguments:
-
- Stream
-
<stream_object> a valid output stream
- Term
-
<term> the term to be written
- Description:
-
- Equivalent to write_term/[2,3] with these options:
- quoted(false)
- ignore_ops(false)
- numbervars(true)
- If Term is uninstantiated, it is written as an anonymous variable (an underscore followed by a non-negative integer).
-
-
- Exceptions:
-
Stream errors (see section G-7-6-2), plus:
- Example:
-
| ?- write('a b').
a b
- See Also:
-
read[1,2], writeq/[1,2], write_canonical/[1,2] or write_term/[2,3].
L-3-198: write_canonical/[1,2]
- Synopsis:
-
write_canonical(+Term)
-
-
write_canonical(+Stream, +Term)
-
-
Writes Term to the current or specified output stream in standard syntax.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream which is open for output
- Term
-
<term> the term to be written
- Description:
-
- Equivalent to write_term/[2,3] with these options:
- quoted(true)
- ignore_ops(true)
- numbervars(false)
- char_escapes(false)
- This predicate is provided so that Term, if written to a file, can be read back by read/[1,2] regardless of special characters in Term or prevailing operator declarations.
- Does not terminate its output with a full-stop, which is required by read/[1,2].
- In general, one can only read (using read/[1,2]) a term written by write_canonical/1 if the value of the character_escapes flag is the same when the term is read as when it was written.
- Exceptions:
-
Stream errors (see section G-7-6-2).
- Examples:
-
- The following sequence will succeed:
...
open(FileName, write, StreamOut),
write_canonical(StreamOut, Term),
write(StreamOut, '.'),
nl(StreamOut),
close(StreamOut),
...
open(FileName, read, StreamIn),
read(StreamIn, Term),
close(StreamIn),
...
- To contrast write/[1,2] and write_canonical/[1,2]:
| ?- write({'A' + '$VAR'(0) + [a]}).
{A+A+[a]}
| ?- write_canonical({'A' + '$VAR'(0) + [a]}).
{}(+(+('A','$VAR'(0)),.(a,[])))
-
-
- See Also:
-
write_term/[2,3], write/[1,2], writeq/[1,2], read/[1,2]
-
-
Chapter G-7-3-2
L-3-199: write_term/[2,3]
- Synopsis:
-
write_term(+Term, +Options)
-
-
write_term(+Stream, +Term, +Options)
-
-
Writes Term to the current output stream or to Stream in a format given by the options.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream which is open for output
- Term
-
<term> the term to be written
- Options
-
<list of term> a list of zero or more of the following, where Bool must be true or false (false is the default).
-
-
- quoted(Bool)
-
Should atoms and functors be quoted as necessary to make them acceptable as input to read?
- ignore_ops(Bool)
-
Ignore current operator declarations? If Bool is true, compound terms are always written in the form,
<predicate name>(<arg1>,...,<argn>).
- portrayed(Bool)
-
Call user:portray/1 for each subterm. By default the behavior of write_term/[2,3] is controlled by Options, but you can change its effect by providing clauses for the
predicate portray/1.
- character_escapes(Bool)
-
Use character escapes. Bool must be true or false (the default depends on the value of the character_escapes flag as set by prolog_flag/3). If Bool is 'true' then
write_term/[2,3] tries to write layout characters (except ASCII 9 and ASCII 32) in the form \<lower-case-letter>, if possible; otherwise, write_term/[2,3] writes the
\^<control-char> form. If Bool is 'false' then it writes the actual character, without using an escape sequence.
- numbervars(Bool)
-
Should terms like '$VAR'(N) be treated specially? If Bool is true, write_term/[2,3] writes 'A' if N=0, 'B' if N=1, ...'Z' if N=25, 'A1' if N=26, etc. Terms of this form are
generated by numbervars/3.
- max_depth(N)
-
Depth limit on printing. N is any integer; 0 means no limit and approximately 33 million is the default.
-
-
-
-
- Description:
-
- write_term/[2,3] is the most general of the write family of predicates. Write_term/[2,3] subsumes all predicates in the family, with the exception of portray_clause/1. That is, all
write predicates can be written as calls to write_term/[2,3].
-
-
- Exceptions:
-
- domain_error
Options contains an undefined option.
- instantiation_error
Any of the Options arguments or Stream is not ground.
- type_error
In Stream or in Options.
- existence_error
Stream is syntactically valid but does not name an open stream.
- permission_error
Stream names an open stream but the stream is not open for output.
-
-
- Comments:
-
-
-
- Examples:
-
- How certain options affect the output of write_term/2:
| ?- write_term('a b', [quoted(true)]).
'a b'
| ?- write_term(a+b, [ignore_ops(true)]).
+(a,b)
| ?- write_term(f('$VAR'(2)),
[numbervars(true)].)
f(C)
| ?- write_term(f('$VAR'('C')),
[numbervars(true)]).
f(C)
- If your intention is to name variables such as that generated by read_term/2 with the variable_names option then this can be done by defining a predicate like:
var_to_names([]) :- !.
var_to_names([=(Name,Var)|RestofPairs]) :-
( var(Var) ->
Var = '$VAR'(Name)
; true
),
var_to_names(RestofPairs).
| ?- read_term([variable_names(Names)], X),
var_to_names(Names),
write_term(X, [numbervars(true)]),
nl,
fail.
|: a(X, Y).
a(X, Y).
no
- See Also:
-
write/[1,2], writeq/[1,2], write_canonical/[1,2], display/1, print/1, portray_clause/1
-
-
Chapter G-7-3-2
L-3-200: writeq/[1,2]
- Synopsis:
-
writeq(+Term)
-
-
writeq(+Stream, +Term)
-
-
Writes the term Term to Stream or the current output stream.
- Arguments:
-
- Stream
-
<stream_object> a valid Prolog stream which is open for output
- Term
-
<term> the term to be written
- Description:
-
- Equivalent to write_term/[2,3] with these options:
- quoted(true)
- ignore_ops(false)
- numbervars(true)
- Does not terminate its output with a full-stop. Therefore, if you want this term to be input to read/[1,2], you must explicitly write a full-stop to mark the end of the term.
-
-
- Comments:
-
- Depending upon whether character escaping is on or off, writeq/[1,2] and write_canonical/[1,2] behave differently when writing quoted atoms. If character escaping is on:
- The characters with ASCII codes 9 (horizontal tab), 32 (space), and 33 through 126 (non-layout characters) are written as themselves.
- The characters with ASCII codes 8, 10, 11, 12, 13, 27, and 127 are written in their '\<lowercase letter>' form (see above for the corresponding letter).
- The character with ASCII code 39 (single quote) is written as two consecutive single quotes.
- The character with ASCII code 92 (back slash) is written as two consecutive back slashes.
- All other characters are written in their '\^<control char>' form.
- If character escaping is off:
- The character with ASCII code 39 (single quote) is written as two consecutive single quotes.
- All other characters are written as themselves.
- Exceptions:
-
Stream errors (see section G-7-6-2)
- See Also:
-
write_term/[2,3], write/[1,2], write_canonical/[1,2]
-
-
section G-1-3 for information about character escaping.
M: C Reference Pages
Copyright (C) 1998 SICS
contact:
product support
sales information