kibi-swipl-linux-x64-gnu 1.0.0

package/lib/swipl/library/aggregate.pl

@@ -0,0 +1,755 @@
+/*  Part of SWI-Prolog
+
+    Author:        Jan Wielemaker
+    E-mail:        J.Wielemaker@vu.nl
+    WWW:           http://www.swi-prolog.org
+    Copyright (c)  2008-2024, University of Amsterdam
+                              VU University Amsterdam
+                              CWI Amsterdam
+                              SWI-Prolog Solutions b.v.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in
+       the documentation and/or other materials provided with the
+       distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+*/
+
+:- module(aggregate,
+          [ aggregate/3,                % +Templ, :Goal, -Result
+            aggregate/4,                % +Templ, +Discrim, :Goal, -Result
+            aggregate_all/3,            % +Templ, :Goal, -Result
+            aggregate_all/4,            % +Templ, +Discrim, :Goal, -Result
+            foldall/4,			% :Folder, :Goal, +V0, -V)
+            foreach/2,                  % :Generator, :Goal
+            free_variables/4            % :Generator, :Template, +Vars0, -Vars
+          ]).
+:- autoload(library(apply),[maplist/4,maplist/5]).
+:- autoload(library(error),
+	    [instantiation_error/1,type_error/2,domain_error/2]).
+:- autoload(library(lists),
+	    [append/3,member/2,sum_list/2,max_list/2,min_list/2]).
+:- autoload(library(ordsets),[ord_intersection/3]).
+:- autoload(library(pairs),[pairs_values/2]).
+:- autoload(library(prolog_code), [mkconj/3]).
+
+:- set_prolog_flag(generate_debug_info, false).
+
+:- meta_predicate
+    aggregate(?,^,-),
+    aggregate(?,?,^,-),
+    aggregate_all(?,0,-),
+    aggregate_all(?,?,0,-),
+    foldall(2,0,+,-),
+    foreach(0,0).
+
+/** <module> Aggregation operators on backtrackable predicates
+
+This library provides aggregating operators  over   the  solutions  of a
+predicate. The operations are a generalisation   of the bagof/3, setof/3
+and findall/3 built-in predicates.  Aggregations   that  can be computed
+incrementally avoid findall/3 and run in   constant  memory. The defined
+aggregation  operations  are  counting,  computing   the  sum,  minimum,
+maximum, a bag of solutions and a  set   of  solutions.  We first give a
+simple example, computing the country with the smallest area:
+
+```
+smallest_country(Name, Area) :-
+    aggregate(min(A, N), country(N, A), min(Area, Name)).
+```
+
+There  are  four  aggregation    predicates  (aggregate/3,  aggregate/4,
+aggregate_all/3 and aggregate/4), distinguished on two properties.
+
+    - aggregate vs. aggregate_all <br>
+      The aggregate predicates use setof/3 (aggregate/4) or bagof/3
+      (aggregate/3), dealing with existential qualified variables
+      (`Var^Goal`) and providing multiple solutions for the remaining
+      free variables in `Goal`. The aggregate_all/3 predicate uses
+      findall/3, implicitly qualifying all free variables and providing
+      exactly one solution, while aggregate_all/4 uses sort/2 over
+      solutions that Discriminator (see below) generated using
+      findall/3.
+
+    - The Discriminator argument <br>
+      The versions with 4 arguments deduplicate redundant solutions of
+      Goal. Solutions for which both the template variables and
+      Discriminator are identical will be treated as one solution. For
+      example, if we wish to compute the total population of all
+      countries, and for some reason =|country(belgium, 11000000)|= may
+      succeed twice, we can use the following to avoid counting the
+      population of Belgium twice:
+
+          aggregate(sum(P), Name, country(Name, P), Total)
+
+All aggregation predicates support  the   following  operators  below in
+Template. In addition, they allow for  an arbitrary named compound term,
+where each of the arguments is a term  from the list below. For example,
+the term r(min(X), max(X)) computes both the minimum and maximum binding
+for X.
+
+  - count
+    Count number of solutions.  Same as sum(1).
+  - sum(Expr)
+    Sum of Expr for all solutions.
+  - min(Expr)
+    Minimum of Expr for all solutions.
+  - min(Expr, Witness)
+    A term min(Min, Witness), where Min is the minimal version of
+    Expr over all solutions, and Witness is any other template
+    applied to solutions that produced Min. If multiple solutions
+    provide the same minimum, Witness corresponds to the first
+    solution.
+  - max(Expr)
+    Maximum of Expr for all solutions.
+  - max(Expr, Witness)
+    As min(Expr, Witness), but producing the maximum result.
+  - set(X)
+    An ordered set with all solutions for X.
+  - bag(X)
+    A list of all solutions for X.
+
+__Acknowledgements__
+
+_|The development of this library was sponsored by SecuritEase,
+  http://www.securitease.com
+|_
+
+@compat Quintus, SICStus 4. The forall/2 is a SWI-Prolog built-in and
+        term_variables/3 is a SWI-Prolog built-in with
+        __different semantics__.  The foldall/4 primitive is a
+        SWI-Prolog addition.
+@tbd    Analysing the aggregation template and compiling a predicate
+        for the list aggregation can be done at compile time.
+@tbd    aggregate_all/3 can be rewritten to run in constant space using
+        non-backtrackable assignment on a term.
+*/
+
+                 /*******************************
+                 *           AGGREGATE          *
+                 *******************************/
+
+%!  aggregate(+Template, :Goal, -Result) is nondet.
+%
+%   Aggregate bindings in Goal according to Template.  The aggregate/3
+%   version performs bagof/3 on Goal.
+
+aggregate(Template, Goal0, Result) :-
+    template_to_pattern(bag, Template, Pattern, Goal0, Goal, Aggregate),
+    bagof(Pattern, Goal, List),
+    aggregate_list(Aggregate, List, Result).
+
+%!  aggregate(+Template, +Discriminator, :Goal, -Result) is nondet.
+%
+%   Aggregate bindings in Goal according to Template.  The aggregate/4
+%   version performs setof/3 on Goal.
+
+aggregate(Template, Discriminator, Goal0, Result) :-
+    template_to_pattern(bag, Template, Pattern, Goal0, Goal, Aggregate),
+    setof(Discriminator-Pattern, Goal, Pairs),
+    pairs_values(Pairs, List),
+    aggregate_list(Aggregate, List, Result).
+
+%!  aggregate_all(+Template, :Goal, -Result) is semidet.
+%
+%   Aggregate   bindings   in   Goal   according    to   Template.   The
+%   aggregate_all/3 version performs findall/3 on   Goal. Note that this
+%   predicate fails if Template contains one  or more of min(X), max(X),
+%   min(X,Witness) or max(X,Witness) and Goal   has  no solutions, i.e.,
+%   the minimum and maximum of an empty set is undefined.
+%
+%   The Template values `count`, sum(X),   max(X),  min(X), max(X,W) and
+%   min(X,W) are processed incrementally rather than using findall/3 and
+%   run in constant memory.
+%
+%   @see foldall/4 to "fold" over all answers.
+
+aggregate_all(Var, _, _) :-
+    var(Var),
+    !,
+    instantiation_error(Var).
+aggregate_all(count, Goal, Count) :-
+    !,
+    aggregate_all(sum(1), Goal, Count).
+aggregate_all(sum(X), Goal, Sum) :-
+    !,
+    State = state(0),
+    (  call(Goal),
+           arg(1, State, S0),
+           S is S0 + X,
+           nb_setarg(1, State, S),
+           fail
+    ;  arg(1, State, Sum)
+    ).
+aggregate_all(max(X), Goal, Max) :-
+    !,
+    State = state(X),
+    (  call(Goal),
+           arg(1, State, M0),
+           M is max(M0,X),
+           nb_setarg(1, State, M),
+           fail
+    ;  arg(1, State, Max),
+       nonvar(Max)
+    ).
+aggregate_all(min(X), Goal, Min) :-
+    !,
+    State = state(X),
+    (  call(Goal),
+           arg(1, State, M0),
+           M is min(M0,X),
+           nb_setarg(1, State, M),
+           fail
+    ;  arg(1, State, Min),
+       nonvar(Min)
+    ).
+aggregate_all(max(X,W), Goal, max(Max,Witness)) :-
+    !,
+    State = state(false, _Max, _Witness),
+    (  call(Goal),
+           (   State = state(true, Max0, _)
+           ->  X > Max0,
+               nb_setarg(2, State, X),
+               nb_setarg(3, State, W)
+           ;   number(X)
+           ->  nb_setarg(1, State, true),
+               nb_setarg(2, State, X),
+               nb_setarg(3, State, W)
+           ;   type_error(number, X)
+           ),
+           fail
+    ;  State = state(true, Max, Witness)
+    ).
+aggregate_all(min(X,W), Goal, min(Min,Witness)) :-
+    !,
+    State = state(false, _Min, _Witness),
+    (  call(Goal),
+           (   State = state(true, Min0, _)
+           ->  X < Min0,
+               nb_setarg(2, State, X),
+               nb_setarg(3, State, W)
+           ;   number(X)
+           ->  nb_setarg(1, State, true),
+               nb_setarg(2, State, X),
+               nb_setarg(3, State, W)
+           ;   type_error(number, X)
+           ),
+           fail
+    ;  State = state(true, Min, Witness)
+    ).
+aggregate_all(Template, Goal0, Result) :-
+    template_to_pattern(all, Template, Pattern, Goal0, Goal, Aggregate),
+    findall(Pattern, Goal, List),
+    aggregate_list(Aggregate, List, Result).
+
+%!  aggregate_all(+Template, +Discriminator, :Goal, -Result) is semidet.
+%
+%   Aggregate  bindings  in  Goal   according    to   Template.  The
+%   aggregate_all/4 version performs findall/3 followed by sort/2 on
+%   Goal. See aggregate_all/3 to understand   why this predicate can
+%   fail.
+
+aggregate_all(Template, Discriminator, Goal0, Result) :-
+    template_to_pattern(all, Template, Pattern, Goal0, Goal, Aggregate),
+    findall(Discriminator-Pattern, Goal, Pairs0),
+    sort(Pairs0, Pairs),
+    pairs_values(Pairs, List),
+    aggregate_list(Aggregate, List, Result).
+
+template_to_pattern(All, Template, Pattern, Goal0, Goal, Aggregate) :-
+    template_to_pattern(Template, Pattern, Post, Vars, Aggregate),
+    existential_vars(Goal0, Goal1, AllVars, Vars),
+    clean_body((Goal1, Post), Goal2),
+    (   All == bag
+    ->  add_existential_vars(AllVars, Goal2, Goal)
+    ;   Goal = Goal2
+    ).
+
+existential_vars(Var, Var) -->
+    { var(Var) },
+    !.
+existential_vars(Var^G0, G) -->
+    !,
+    [Var],
+    existential_vars(G0, G).
+existential_vars(M:G0, M:G) -->
+    !,
+    existential_vars(G0, G).
+existential_vars(G, G) -->
+    [].
+
+add_existential_vars([], G, G).
+add_existential_vars([H|T], G0, H^G1) :-
+    add_existential_vars(T, G0, G1).
+
+
+%!  clean_body(+Goal0, -Goal) is det.
+%
+%   Remove redundant `true` from Goal0.
+
+clean_body((Goal0,Goal1), Goal) =>
+    clean_body(Goal0, GoalA),
+    clean_body(Goal1, GoalB),
+    mkconj(GoalA, GoalB, Goal).
+clean_body(Goal0, Goal) =>
+    Goal = Goal0.
+
+
+%!  template_to_pattern(+Template, -Pattern, -Post, -Vars, -Aggregate)
+%
+%   Determine which parts of the goal we must remember in the
+%   findall/3 pattern.
+%
+%   @arg Post is a body-term that evaluates expressions to reduce
+%               storage requirements.
+%   @arg Vars is a list of intermediate variables that must be
+%               added to the existential variables for bagof/3.
+%   @arg Aggregate defines the aggregation operation to execute.
+
+template_to_pattern(Term, Pattern, Goal, Vars, Aggregate) :-
+    templ_to_pattern(Term, Pattern, Goal, Vars, Aggregate),
+    !.
+template_to_pattern(Term, Pattern, Goal, Vars, term(MinNeeded, Functor, AggregateArgs)) :-
+    compound(Term),
+    !,
+    Term =.. [Functor|Args0],
+    templates_to_patterns(Args0, Args, Goal, Vars, AggregateArgs),
+    needs_one(AggregateArgs, MinNeeded),
+    Pattern =.. [Functor|Args].
+template_to_pattern(Term, _, _, _, _) :-
+    invalid_template(Term).
+
+templ_to_pattern(sum(X),           X,         true,    [],   sum) :- var(X), !.
+templ_to_pattern(sum(X0),          X,         X is X0, [X0], sum) :- !.
+templ_to_pattern(count,            1,         true,    [],   count) :- !.
+templ_to_pattern(min(X),           X,         true,    [],   min) :- var(X), !.
+templ_to_pattern(min(X0),          X,         X is X0, [X0], min) :- !.
+templ_to_pattern(min(X0, Witness), X-Witness, X is X0, [X0], min_witness) :- !.
+templ_to_pattern(max(X0),          X,         X is X0, [X0], max) :- !.
+templ_to_pattern(max(X0, Witness), X-Witness, X is X0, [X0], max_witness) :- !.
+templ_to_pattern(set(X),           X,         true,    [],   set) :- !.
+templ_to_pattern(bag(X),           X,         true,    [],   bag) :- !.
+
+templates_to_patterns([], [], true, [], []).
+templates_to_patterns([H0], [H], G, Vars, [A]) :-
+    !,
+    sub_template_to_pattern(H0, H, G, Vars, A).
+templates_to_patterns([H0|T0], [H|T], (G0,G), Vars, [A0|A]) :-
+    sub_template_to_pattern(H0, H, G0, V0, A0),
+    append(V0, RV, Vars),
+    templates_to_patterns(T0, T, G, RV, A).
+
+sub_template_to_pattern(Term, Pattern, Goal, Vars, Aggregate) :-
+    templ_to_pattern(Term, Pattern, Goal, Vars, Aggregate),
+    !.
+sub_template_to_pattern(Term, _, _, _, _) :-
+    invalid_template(Term).
+
+invalid_template(Term) :-
+    callable(Term),
+    !,
+    domain_error(aggregate_template, Term).
+invalid_template(Term) :-
+    type_error(aggregate_template, Term).
+
+%!  needs_one(+Ops, -OneOrZero)
+%
+%   If one of the operations in Ops needs at least one answer,
+%   unify OneOrZero to 1.  Else 0.
+
+needs_one(Ops, 1) :-
+    member(Op, Ops),
+    needs_one(Op),
+    !.
+needs_one(_, 0).
+
+needs_one(min).
+needs_one(min_witness).
+needs_one(max).
+needs_one(max_witness).
+
+%!  aggregate_list(+Op, +List, -Answer) is semidet.
+%
+%   Aggregate the answer  from  the   list  produced  by  findall/3,
+%   bagof/3 or setof/3. The latter  two   cases  deal  with compound
+%   answers.
+%
+%   @tbd    Compile code for incremental state update, which we will use
+%           for aggregate_all/3 as well.  We should be using goal_expansion
+%           to generate these clauses.
+
+aggregate_list(bag, List0, List) :-
+    !,
+    List = List0.
+aggregate_list(set, List, Set) :-
+    !,
+    sort(List, Set).
+aggregate_list(sum, List, Sum) :-
+    sum_list(List, Sum).
+aggregate_list(count, List, Count) :-
+    length(List, Count).
+aggregate_list(max, List, Sum) :-
+    max_list(List, Sum).
+aggregate_list(max_witness, List, max(Max, Witness)) :-
+    max_pair(List, Max, Witness).
+aggregate_list(min, List, Sum) :-
+    min_list(List, Sum).
+aggregate_list(min_witness, List, min(Min, Witness)) :-
+    min_pair(List, Min, Witness).
+aggregate_list(term(0, Functor, Ops), List, Result) :-
+    !,
+    maplist(state0, Ops, StateArgs, FinishArgs),
+    State0 =.. [Functor|StateArgs],
+    aggregate_term_list(List, Ops, State0, Result0),
+    finish_result(Ops, FinishArgs, Result0, Result).
+aggregate_list(term(1, Functor, Ops), [H|List], Result) :-
+    H =.. [Functor|Args],
+    maplist(state1, Ops, Args, StateArgs, FinishArgs),
+    State0 =.. [Functor|StateArgs],
+    aggregate_term_list(List, Ops, State0, Result0),
+    finish_result(Ops, FinishArgs, Result0, Result).
+
+aggregate_term_list([], _, State, State).
+aggregate_term_list([H|T], Ops, State0, State) :-
+    step_term(Ops, H, State0, State1),
+    aggregate_term_list(T, Ops, State1, State).
+
+
+%!  min_pair(+Pairs, -Key, -Value) is det.
+%!  max_pair(+Pairs, -Key, -Value) is det.
+%
+%   True if Key-Value has the  smallest/largest   key  in  Pairs. If
+%   multiple pairs share the smallest/largest key, the first pair is
+%   returned.
+
+min_pair([M0-W0|T], M, W) :-
+    min_pair(T, M0, W0, M, W).
+
+min_pair([], M, W, M, W).
+min_pair([M0-W0|T], M1, W1, M, W) :-
+    (   M0 < M1
+    ->  min_pair(T, M0, W0, M, W)
+    ;   min_pair(T, M1, W1, M, W)
+    ).
+
+max_pair([M0-W0|T], M, W) :-
+    max_pair(T, M0, W0, M, W).
+
+max_pair([], M, W, M, W).
+max_pair([M0-W0|T], M1, W1, M, W) :-
+    (   M0 > M1
+    ->  max_pair(T, M0, W0, M, W)
+    ;   max_pair(T, M1, W1, M, W)
+    ).
+
+%!  step(+AggregateAction, +New, +State0, -State1).
+
+step(bag,   X, [X|L], L).
+step(set,   X, [X|L], L).
+step(count, _, X0, X1) :-
+    succ(X0, X1).
+step(sum,   X, X0, X1) :-
+    X1 is X0+X.
+step(max,   X, X0, X1) :-
+    X1 is max(X0, X).
+step(min,   X, X0, X1) :-
+    X1 is min(X0, X).
+step(max_witness, X-W, X0-W0, X1-W1) :-
+    (   X > X0
+    ->  X1 = X, W1 = W
+    ;   X1 = X0, W1 = W0
+    ).
+step(min_witness, X-W, X0-W0, X1-W1) :-
+    (   X < X0
+    ->  X1 = X, W1 = W
+    ;   X1 = X0, W1 = W0
+    ).
+step(term(Ops), Row, Row0, Row1) :-
+    step_term(Ops, Row, Row0, Row1).
+
+step_term(Ops, Row, Row0, Row1) :-
+    functor(Row, Name, Arity),
+    functor(Row1, Name, Arity),
+    step_list(Ops, 1, Row, Row0, Row1).
+
+step_list([], _, _, _, _).
+step_list([Op|OpT], Arg, Row, Row0, Row1) :-
+    arg(Arg, Row, X),
+    arg(Arg, Row0, X0),
+    arg(Arg, Row1, X1),
+    step(Op, X, X0, X1),
+    succ(Arg, Arg1),
+    step_list(OpT, Arg1, Row, Row0, Row1).
+
+finish_result(Ops, Finish, R0, R) :-
+    functor(R0, Functor, Arity),
+    functor(R, Functor, Arity),
+    finish_result(Ops, Finish, 1, R0, R).
+
+finish_result([], _, _, _, _).
+finish_result([Op|OpT], [F|FT], I, R0, R) :-
+    arg(I, R0, A0),
+    arg(I, R, A),
+    finish_result1(Op, F, A0, A),
+    succ(I, I2),
+    finish_result(OpT, FT, I2, R0, R).
+
+finish_result1(bag, Bag0, [], Bag) :-
+    !,
+    Bag = Bag0.
+finish_result1(set, Bag,  [], Set) :-
+    !,
+    sort(Bag, Set).
+finish_result1(max_witness, _, M-W, R) :-
+    !,
+    R = max(M,W).
+finish_result1(min_witness, _, M-W, R) :-
+    !,
+    R = min(M,W).
+finish_result1(_, _, A, A).
+
+%!  state0(+Op, -State, -Finish)
+
+state0(bag,   L, L).
+state0(set,   L, L).
+state0(count, 0, _).
+state0(sum,   0, _).
+
+%!  state1(+Op, +First, -State, -Finish)
+
+state1(bag, X, L, [X|L]) :- !.
+state1(set, X, L, [X|L]) :- !.
+state1(_,   X, X, _).
+
+
+		 /*******************************
+		 *             FOLDALL		*
+		 *******************************/
+
+%!  foldall(:Folder, :Goal, +V0, -V) is det.
+%
+%   Use Folder to fold V0 to V using all answers of Goal. This predicate
+%   generates all answers  for  Goal  and   for  each  answer  it  calls
+%   call(Folder,V0,V1). This predicate  provides   behaviour  similar to
+%   aggregate_all/3-4, but operates in  constant   space  and allows for
+%   custom aggregation (Folder) operators. The example below uses plus/3
+%   to realise aggregate_all(sum(X), between(1,10,X), Sum).
+%
+%       ?- foldall(plus(X), between(1,10,X), 0, Sum).
+%       Sum = 55
+%
+%   The implementation uses  nb_setarg/3   for  non-backtrackable  state
+%   updates.
+%
+%   @see aggregate_all/3-4, foldl/4-7, nb_setarg/3.
+
+foldall(Op, Goal, V0, V) :-
+    State = state(V0),
+    (   call(Goal),
+          arg(1, State, S0),
+          call(Op, S0, S),
+          nb_setarg(1, State, S),
+          fail
+    ;   arg(1, State, V)
+    ).
+
+
+                 /*******************************
+                 *             FOREACH          *
+                 *******************************/
+
+%!  foreach(:Generator, :Goal)
+%
+%   True when the conjunction  of  _instances_   of  Goal  created  from
+%   solutions for Generator is true. Except for term copying, this could
+%   be implemented as below.
+%
+%   ```
+%   foreach(Generator, Goal) :-
+%       findall(Goal, Generator, Goals),
+%       maplist(call, Goals).
+%   ```
+%
+%   The actual implementation uses findall/3 on  a template created from
+%   the variables _shared_ between Generator  and Goal. Subsequently, it
+%   uses every instance of this template  to instantiate Goal, call Goal
+%   and undo _only_ the instantiation of   the  template and _not_ other
+%   instantiations created by running Goal.  Here is an example:
+%
+%   ```
+%   ?- foreach(between(1,4,X), dif(X,Y)), Y = 5.
+%   Y = 5.
+%   ?- foreach(between(1,4,X), dif(X,Y)), Y = 3.
+%   false.
+%   ```
+%
+%   The  predicate  foreach/2  is   mostly    used   if   Goal  performs
+%   backtrackable destructive assignment on  terms. Attributed variables
+%   (underlying constraints) are  an  example.   Another  example  of  a
+%   backtrackable data structure is in   library(hashtable).  If we care
+%   only about the side effects  (I/O,   dynamic  database, etc.) or the
+%   truth value of Goal,  forall/2 is  a faster and simpler alternative.
+%   If Goal instantiates its arguments it  is   will  often  fail as the
+%   argument cannot be instantiated to multiple   values. It is possible
+%   to incrementally _grow_ an argument:
+%
+%   ```
+%   ?- foreach(between(1,4,X), member(X, L)).
+%   L = [1,2,3,4|_].
+%   ```
+%
+%   Note that SWI-Prolog up to  version   8.3.4  created  copies of Goal
+%   using  copy_term/2  for  each  iteration,  this  makes  the  current
+%   implementation unable to properly handle   compound terms (in Goal's
+%   arguments) that share variables with the  Generator. As a workaround
+%   you can define a goal that does not use compound terms, like in this
+%   example:
+%
+%   ```
+%   mem(E,L) :-  % mem/2 hides the compound argument from foreach/2
+%      member(r(E),L).
+%
+%   ?- foreach(  between(1,5,N), mem(N,L)).
+%   ```
+
+foreach(Generator, Goal) :-
+    term_variables(Generator, GenVars0), sort(GenVars0, GenVars),
+    term_variables(Goal, GoalVars0), sort(GoalVars0, GoalVars),
+    ord_intersection(GenVars, GoalVars, SharedVars),
+    Templ =.. [v|SharedVars],
+    findall(Templ, Generator, List),
+    prove_list(List, Templ, Goal).
+
+prove_list([], _, _).
+prove_list([H|T], Templ, Goal) :-
+    Templ = H,
+    call(Goal),
+    '$unbind_template'(Templ),
+    prove_list(T, Templ, Goal).
+
+
+%!  free_variables(:Generator, +Template, +VarList0, -VarList) is det.
+%
+%   Find free variables in bagof/setof template.  In order to handle
+%   variables  properly,  we  have  to   find  all  the  universally
+%   quantified variables in the  Generator.   All  variables  as yet
+%   unbound are universally quantified, unless
+%
+%       1. they occur in the template
+%       2. they are bound by X^P, setof/3, or bagof/3
+%
+%   free_variables(Generator, Template, OldList, NewList) finds this
+%   set using OldList as an accumulator.
+%
+%   @author Richard O'Keefe
+%   @author Jan Wielemaker (made some SWI-Prolog enhancements)
+%   @license Public domain (from DEC10 library).
+%   @tbd Distinguish between control-structures and data terms.
+%   @tbd Exploit our built-in term_variables/2 at some places?
+
+free_variables(Term, Bound, VarList, [Term|VarList]) :-
+    var(Term),
+    term_is_free_of(Bound, Term),
+    list_is_free_of(VarList, Term),
+    !.
+free_variables(Term, _Bound, VarList, VarList) :-
+    var(Term),
+    !.
+free_variables(Term, Bound, OldList, NewList) :-
+    explicit_binding(Term, Bound, NewTerm, NewBound),
+    !,
+    free_variables(NewTerm, NewBound, OldList, NewList).
+free_variables(Term, Bound, OldList, NewList) :-
+    functor(Term, _, N),
+    free_variables(N, Term, Bound, OldList, NewList).
+
+free_variables(0, _, _, VarList, VarList) :- !.
+free_variables(N, Term, Bound, OldList, NewList) :-
+    arg(N, Term, Argument),
+    free_variables(Argument, Bound, OldList, MidList),
+    M is N-1,
+    !,
+    free_variables(M, Term, Bound, MidList, NewList).
+
+%   explicit_binding checks for goals known to existentially quantify
+%   one or more variables.  In particular \+ is quite common.
+
+explicit_binding(\+ _Goal,             Bound, fail,     Bound      ) :- !.
+explicit_binding(not(_Goal),           Bound, fail,     Bound      ) :- !.
+explicit_binding(Var^Goal,             Bound, Goal,     Bound+Var) :- !.
+explicit_binding(setof(Var,Goal,Set),  Bound, Goal-Set, Bound+Var) :- !.
+explicit_binding(bagof(Var,Goal,Bag),  Bound, Goal-Bag, Bound+Var) :- !.
+
+%!  term_is_free_of(+Term, +Var) is semidet.
+%
+%   True if Var does not appear  in   Term.  This has been rewritten
+%   from the DEC10 library source   to exploit our non-deterministic
+%   arg/3.
+
+term_is_free_of(Term, Var) :-
+    \+ var_in_term(Term, Var).
+
+var_in_term(Term, Var) :-
+    Var == Term,
+    !.
+var_in_term(Term, Var) :-
+    compound(Term),
+    arg(_, Term, Arg),
+    var_in_term(Arg, Var),
+    !.
+
+
+%!  list_is_free_of(+List, +Var) is semidet.
+%
+%   True if Var is not in List.
+
+list_is_free_of([Head|Tail], Var) :-
+    Head \== Var,
+    !,
+    list_is_free_of(Tail, Var).
+list_is_free_of([], _).
+
+
+%       term_variables(+Term, +Vars0, -Vars) is det.
+%
+%       True if Vars is the union of variables in Term and Vars0.
+%       We cannot have this as term_variables/3 is already defined
+%       as a difference-list version of term_variables/2.
+
+%term_variables(Term, Vars0, Vars) :-
+%       term_variables(Term+Vars0, Vars).
+
+
+%!  sandbox:safe_meta(+Goal, -Called) is semidet.
+%
+%   Declare the aggregate meta-calls safe. This cannot be proven due
+%   to the manipulations of the argument Goal.
+
+:- multifile sandbox:safe_meta_predicate/1.
+
+sandbox:safe_meta_predicate(aggregate:foreach/2).
+sandbox:safe_meta_predicate(aggregate:aggregate/3).
+sandbox:safe_meta_predicate(aggregate:aggregate/4).
+sandbox:safe_meta_predicate(aggregate:aggregate_all/3).
+sandbox:safe_meta_predicate(aggregate:aggregate_all/4).
+