Did you know ... Search Documentation:
intercept.pl -- Intercept and signal interface
PublicShow source

This library allows for creating an execution context (goal) which defines how calls to send_signal/1 are handled. This library is typically used to fetch values from the context or process results depending on the context.

For example, assume we parse a (large) file using a grammar (see phrase_from_file/3) that has some sort of record structure. What should we do with the recognised records? We can return them in a list, but if the input is large this is a huge overhead if the records are to be asserted or written to a file. Using this interface we can use

document -->
    record(Record),
    !,
    { send_signal(record(Record)) },
    document.
document -->
    [].

Given the above, we can assert all records into the database using the following query:

    ...,
    intercept(phrase_from_file(File, document),
              record(Record),
              assertz(Record)).

Or, we can collect all records in a list using intercept_all/4:

    ...,
    intercept_all(Record,
                  phrase_from_file(File, document), record(Record),
                  Records).
Source intercept(:Goal, ?Ball, :Handler)
Run Goal as call/1. If somewhere during the execution of Goal send_signal/1 is called with a Signal that unifies with Ball, run Handler and continue the execution.

This predicate is related to catch/3, but rather than aborting the execution of Goal and running Handler it continues the execution of Goal. This construct is also related to delimited continuations (see reset/3 and shift/1). It only covers one (common) use case for delimited continuations, but does so with a simpler interface, at lower overhead and without suffering from poor interaction with the cut.

Note that Ball and Handler are copied before calling the (copy) of Handler to avoid instantiation of Ball and/or Handler which can make a subsequent signal fail.

See also
- intercept/4, reset/3, catch/4, broadcast_request/1.
Compatibility
- Ciao
Source intercept(:Goal, ?Ball, :Handler, +Arg)
Similar to intercept/3, but the copy of Handler is called as call(Copy,Arg), which allows passing large context arguments or arguments subject to unification or destructive assignment. For example:
?- intercept(send_signal(x), X, Y=X).
true.

?- intercept(send_signal(x), X, =(X), Y).
Y = x.
Source intercept_all(+Template, :Goal, ?Ball, -List)
True when List contains all instances of Template that have been sent using send_signal/1 where the argument unifies with Ball. Note that backtracking in Goal resets the List. For example, given
enum(I, Max) :- I =< Max, !, send_signal(emit(I)),
                I2 is I+1, enum(I2, Max).
enum(_, _).

Consider the following queries

?- intercept_all(I, enum(1,6), emit(I), List).
List = [1, 2, 3, 4, 5, 6].

?- intercept_all(I, (between(1,3,Max),enum(1,Max)),
                 emit(I), List).
Max = 1, List = [1] ;
Max = 2, List = [1, 2] ;
Max = 3, List = [1, 2, 3].
See also
- nb_intercept_all/4
Source nb_intercept_all(+Template, :Goal, ?Ball, -List)
As intercept_all/4, but backtracing inside Goal does not reset List. Consider this program and the subsequent queries
enum_b(F, T) :- forall(between(F, T, I), send_signal(emit(I))).
?- intercept_all(I, enum_b(1, 6), emit(I), List).
List = [].

?- nb_intercept_all(I, enum_b(1, 6), emit(I), List).
List = [1, 2, 3, 4, 5, 6].
Source send_signal(+Signal)
If this predicate is called from a sub-goal of intercept/3, execute the associated Handler of the intercept/3 environment.
Errors
- unintercepted_signal(Signal) if there is no matching intercept environment.
Source send_silent_signal(+Signal)
As send_signal/1, but succeed silently if there is no matching intercept environment.