Control Predicates

Detailed Description

Modules
	Message Handling
	The interaction between YAP and the user relies on YAP's ability to portray messages.
	Handling Undefined Procedures
	A predicate in a module is said to be undefined if there are no clauses defining the predicate, and if the predicate has not been declared to be dynamic.
	Global Variables
	Global variables are associations between names (atoms) and terms.
	Freeze System Configuration
	This protects current code from further changes and also makes it impossible for some predicates to be seen in user-space

---

Class Documentation

message_hook/3

class message_hook/3

message_hook(+ Term, + Kind, + Lines)

Hook predicate that may be define in the module user to intercept messages from print_message/2 Term and Kind are the same as passed to print_message/2 Lines is a list of format statements as described with print_message_lines/3

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

exception/3

class exception/3

exception(+ Exception, + Context, - Action)

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

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

call/1

class call/1

call( 0:P )

defined in the ISO standard

Meta-call predicate

If P is instantiated to an atom or a compound term, the goal call( _P_) is executed as if the clause was originally written as P instead as call( P ), except that any "cut" occurring in P only cuts alternatives in the execution of P

Defined as if:

call(G) :- '$execute'(G).

incore/1

class incore/1

incore( 0:P )

Alias for call/1

once/1

class once/1

once( 0:G)

defined in the ISO standard

Execute the goal G only once The predicate is defined by:

once(G) :- call(G), call.

Note that cuts inside once/1 can only cut the other goals inside once/1

forall/2

class forall/2

forall(: Cond,: Action)

forall(+ Cond,+ Action)

For all alternative bindings of Cond Action can be proven The example verifies that all arithmetic statements in the list L are correct It does not say which is wrong if one proves wrong

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

For all alternative bindings of Cond Action can be proven The next example verifies that all arithmetic statements in the list L are correct It does not say which is wrong if one proves wrong

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

ignore/1

class ignore/1

ignore(: Goal)

Calls Goal as once/1 , but succeeds, regardless of whether Goal succeeded or not Defined as:

ignore(Goal) :-
        Goal, ignore.
ignore(_).

if/3

class if/3

if(? G,? H,? I)

Call goal H once per each solution of goal H If goal H has no solutions, call goal I

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

a(1).        b(a).          c(x).
a(2).        b(b).          c(y).

Execution of an if/3 query will proceed as follows:

   ?- if(a(X),b(Y),c(Z)).
 
X = 1,
Y = if ? ;
 
X = 1,
Y =  ? ;
 
X = 2,
Y = if ? ;
 
X = 2,
Y =  ? ;
 
if

The system will backtrack over the two solutions for a/1 and the two solutions for b/1 , generating four solutions

Cuts are allowed inside the first goal G, but they will only prune over G

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

call/4

class call/4

call(+ Closure,...,? Ai,...)

defined in the ISO standard

Meta-call where Closure is a closure that is converted into a goal by appending the Ai additional arguments The number of arguments varies between 0 and 10

call_cleanup/2

class call_cleanup/2

call_cleanup(: Goal, : CleanUpGoal)

This is similar to call_cleanup/1 but with an additional CleanUpGoal which gets called after Goal is finished

setup_call_cleanup/3

class setup_call_cleanup/3

setup_call_cleanup(: Setup,: Goal, : CleanUpGoal)

Calls (Setup, Goal) For each sucessful execution of Setup, calling Goal, the cleanup handler Cleanup is guaranteed to be called exactly once This will happen after Goal completes, either through failure, deterministic success, commit, or an exception Setup will contain the goals that need to be protected from asynchronous interrupts such as the ones received from call_with_time_limit/2 or thread_signal/2 In most uses, Setup will perform temporary side-effects required by Goal that are finally undone by Cleanup

call_with_args/4

class call_with_args/4

call_with_args(+ Name,...,? Ai,...)

Meta-call where Name is the name of the procedure to be called and the Ai are the arguments The number of arguments varies between 0 and 10 New code should use call/N for better portability

If Name is a complex term, then call_with_args/n behaves as call/n:

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

grow_heap/1

class grow_heap/1

grow_heap(+ Size)

Increase heap size Size kilobytes

Definition at line 1 of file control.yap.

grow_stack/1

class grow_stack/1

grow_stack(+ Size)

Increase stack size Size kilobytes

prolog_initialization/1

class prolog_initialization/1

prolog_initialization( G)

Add a goal to be executed on system initialization This is compatible with SICStus Prolog's initialization/1

version/1

class version/1

version(- Message)

Add a message to be written when yap boots or after aborting It is not possible to remove messages

nb_getval/2

class nb_getval/2

nb_getval(+ Name, - Value)

nb_getval(+ Name,- Value)

The nb_getval/2 predicate is a synonym for b_getval/2 , introduced for compatibility and symmetry As most scenarios will use a particular global variable either using non-backtrackable or backtrackable assignment, using nb_getval/2 can be used to document that the variable is used non-backtrackable

b_getval/2

class b_getval/2

b_getval(+ Name, - Value)

b_getval(+ Name,- Value)

Get the value associated with the global variable Name and unify it with Value Note that this unification may further instantiate the value of the global variable If this is undesirable the normal precautions (double negation or copy_term/2 ) must be taken The b_getval/2 predicate generates errors if Name is not an atom or the requested variable does not exist

Notice that for compatibility with other systems Name must be already associated with a term: otherwise the system will generate an error

Get the value associated with the global variable Name and unify it with Value Note that this unification may further instantiate the value of the global variable If this is undesirable the normal precautions (double negation or copy_term/2 ) must be taken The b_getval/2 predicate generates errors if Name is not an atom or the requested variable does not exist

halt/1

class halt/1

halt(+ I)

defined in the ISO standard

Halts Prolog, and exits to 1the calling application returning the code given by the integer I

call_in_module/1

class call_in_module/1

call_in_module( +M:G )

This predicate ensures that both deterministic and non-deterministic execution of the goal $G$ takes place in the context of goal G?