Documentation of builtins:findall/3

[dcnorris]

Currently, this documentation reads:

%% findall(Template, Goal, Solutions).
%
% Unify Solutions with a list of all values that variables in Template can take in Goal.
% findall/3 is equivalent to bagof/3 with all free variables scoped to the Goal (^ operator)
% except that bagof/3 fails when no solutions are found and findall/3 unifies with an empty list.

It seems to me this isn't exactly right. Rather, Solutions gets unified with a list of all values which the term Template acquires when its variables are instantiated in the course of repeated instantiations of Goal.

Compare the language from Sterling & Shapiro Ch. 16, p.302:

A basic all-solutions predicate is findall(Term,Goal,Bag).
The predicate is true if and only if Bag unifies with the list of values
to which a variable X not occurring in Term or Goal would be bound
by successive resatisfaction of call(Goal) , X=Term? after systematic
replacement of all variables in X by new variables.

[triska]

For comparison, quoting the Prolog standard:

8.10.1 findall/3

8.10.1.1 Description

findall(Template, Goal, Instances) is true iff
Instances unifies with the list of values to which a
variable X not occurring in Template or Goal would be
instantiated by successive re-executions of
    call(Goal), X=Template
after systematic replacement of all variables in X by new
variables.

[UWN]

There is still an inherent problem here, calling 8.10 All solutions. When we have here rather copied answers.