PLOGHELP FINDALL                               Robert Duncan, April 1992

Finding all solutions of a goal.


    ?- findall(Term, Goal, Bag).


Unifies Bag with a list of all the instances of Term for which Goal
succeeds. Terms in Bag are in solution order, i.e. the first term
corresponds to the first solution found, and so on.

For example, given the database:

    parents(jane, bill, alison).
    parents(jane, bill, mark).
    parents(susan, paul, john).
    parents(alison, john, sam).

we can find all of Jane's and Bill's children with the goal:

    ?- findall(C, parents(jane, bill, C), Cs).
    C = _1
    Cs = [alison, mark] ?

The first argument to findall/3 need not be a simple variable. We could
find all known pairs of parents with the goal:

    ?- findall(M+F, parents(M, F, C), Ps).
    M = _1
    F = _2
    C = _3
    Ps = [jane + bill, jane + bill, susan + paul, alison + john] ?

Note how Jane and Bill are listed twice: this is because there are two
solutions to the goal

    parents(jane, bill, C)

for different bindings of C. C is called a "free" variable of the
findall goal (meaning that it occurs in Goal but not in Term) and
findall/3 treats all instantiations of free variables alike. For a more
sophisticated treatment, see PLOGHELP * BAGOF.

findall/3 always succeeds, even if the Goal doesn't, in which case the
Bag of solutions will be empty:

    ?- findall(C, parents(_, sam, C), Cs).
    C = _1
    Cs = [] ?

Of course, this assumes that the evaluation of Goal terminates normally:
if it goes on for ever, or raises an error, then so will the call to
findall/3.

findall/3 never binds variables occurring in Term or Goal, and solutions
in Bag are always copies of the template Term with no sharing. This is
demonstrated by the following (rather pointless) example:

    ?- findall(p(X), parents(jane, bill, C), Bag).
    X = _1
    C = _2
    Bag = [p(_3), p(_4)] ?

Note how X and C remain uninstantiated after the call (as in all the
previous examples) and how the resulting Bag contains one copy of p(X)
for each solution of the Goal, but with a different variable in each
case.


-- See Also -----------------------------------------------------------

PLOGHELP * BAGOF, * SETOF
    All-solutions predicates with a more logical interpretation of free
    variables.


--- C.all/plog/help/findall
--- Copyright University of Sussex 1992. All rights reserved. ----------