This function applies a query to each instance-set which matches the template. Each instance-set which satisfies the query is stored in a multifield value. This multifield value is returned when the query has been applied to all possible instance-sets. If there are n instances in each instance-set, and m instance-sets satisfied the query, then the length of the returned multifield value will be n * m. The first n fields correspond to the first instance-set, and so on. Each field of the multifield value is an instance-name representing an instance-set member. The multifield value can consume a large amount of memory due to permutational explosion, so this function should be used judiciously.
Syntax
(find-all-instances <instance-set-template> <query>)
Example
Find all pairs of a man and a woman who have the same age.
CLIPS> (find-all-instances ((?m MAN) (?w WOMAN)) (= ?m:age ?w:age)) ([Man-1] [Woman-1] [Man-2] [Woman-2]) CLIPS>
This function applies a query to each instance-set which matches the template. If an instance-set satisfies the query, the specified action is executed, and the function is immediately terminated. The return value is the evaluation of the action. If no instance-set satisfied the query, then the return value is the symbol FALSE.
Syntax
(do-for-instance <instance-set-template> <query> <action>)
Example
Print out the first triplet of different people that have the same age. The calls to neq in the query eliminate the permutations where two or more members of the instance-set are identical.
CLIPS>
(do-for-instance ((?p1 PERSON) (?p2 PERSON) (?p3 PERSON))
(and (= ?p1:age ?p2:age ?p3:age)
(neq ?p1 ?p2)
(neq ?p1 ?p3)
(neq ?p2 ?p3))
(printout t ?p1 " " ?p2 " " ?p3 crlf))
[Girl-2] [Boy-2] [Boy-3]
CLIPS>
This function applies a query to each instance-set which matches the template. If an instance-set satisfies the query, the specified action is executed. The return value is the evaluation of the action for the last instance-set which satisfied the query. If no instance-set satisfied the query, then the return value is the symbol FALSE.
Syntax
(do-for-all-instances <instance-set-template> <query> <action>)
Example
Print out all triplets of different people that have the same age. The calls to strcompare limit the instance-sets which satisfy the query to combinations instead of permutations. Without these restrictions, two instance-sets which differed only in the order of their members would both satisfy the query.
CLIPS>
(do-for-all-instances ((?p1 PERSON) (?p2 PERSON) (?p3 PERSON))
(and (= ?p1:age ?p2:age ?p3:age)
(> (str-compare ?p1 ?p2) 0)
(> (str-compare ?p2 ?p3) 0))
(printout t ?p1 " " ?p2 " " ?p3 crlf))
[Girl-2] [Boy-3] [Boy-2]
[Girl-2] [Boy-4] [Boy-2]
[Girl-2] [Boy-4] [Boy-3]
[Boy-4] [Boy-3] [Boy-2]
CLIPS>
This function is similar to do-for-all-instances except that it groups all instance-sets which satisfy the query into an intermediary multifield value. If there are no instance-sets which satisfy the query, then the function returns the symbol FALSE. Otherwise, the specified action is executed for each instance-set in the multifield value, and the return value is the evaluation of the action for the last instance-set to satisfy the query. The intermediary multifield value is discarded. This function can consume large amounts of memory in the same fashion as find-all-instances. This function should be used in lieu of do-for-all-instances when the action applied to one instance-set would change the result of the query for another instance-set (unless that is the desired effect).
Syntax
(delayed-do-for-all-instances <instance-set-template> <query> <action>)
Example
Delete all boys with the greatest age. The test in this case is another query function which determines if there are any older boys than the one currently being examined. The action needs to be delayed until all boys have been processed, or the greatest age will decrease as the older boys are deleted.
CLIPS> (watch instances)
CLIPS>
(delayed-do-for-all-instances ((?b1 BOY))
(not (any-instancep ((?b2 BOY))
(> ?b2:age ?b1:age)))
(send ?b1 delete))
<== instance [Boy-1] of BOY
TRUE
CLIPS> (unwatch instances)
CLIPS> (reset)
CLIPS> (watch instances)
CLIPS>
(do-for-all-instances ((?b1 BOY))
(not (any-instancep ((?b2 BOY))
(> ?b2:age ?b1:age)))
(send ?b1 delete))
<== instance [Boy-1] of BOY
<== instance [Boy-2] of BOY
<== instance [Boy-3] of BOY
<== instance [Boy-4] of BOY
TRUE
CLIPS> (unwatch instances)
CLIPS>