GBBopen 1.5 Reference -- do-instances-of-class

do-instances-of-class

do-instances-of-class

(var unit-classes-specifier) declaration* {tag | form}*

[Macro]

Purpose
Iterate over all unit instances of the specified unit classes.

Package :gbbopen

Module :gbbopen-core

Arguments and values

var		A variable symbol
unit-classes-specifier		An extended unit-classes specification (see below)
declaration		A declare expression (not evaluated)
tag		A `go` tag (not evaluated)
form		A form

Detailed syntax

`unit-classes-specifier` ::=	`t` \| `single-unit-class-specifier` \| `(single-unit-class-specifier`⁺`)`

`single-unit-class-specifier` ::=	`atomic-unit-class` \| `(atomic-unit-class subclassing-specifier)`

`atomic-unit-class` ::=	`unit-class` \| `unit-class-name`

`subclassing-specifier` ::=	`:plus-subclasses` \| `:no-subclasses` \| `+` \| `=`

The shorthand + subclasses specifier is equivalent to :plus-subclasses and = to :no-subclasses.

Description
The iteration over the unit instances of the specified unit classes is performed once for each unit instance, whether or not the instances reside on any space instances.

Examples
Delete all unit instances of the unit class hyp:

  (do-instances-of-class (instance 'hyp)
    (delete-instance instance))

Delete all unit instances of the unit class hyp and instances of subclasses of hyp:

  (do-instances-of-class (instance '(hyp :plus-subclasses))
    (delete-instance instance))

or simply:

  (do-instances-of-class (instance '(hyp +))
    (delete-instance instance))

Note
The consequences are unspecified if an attempt is made to add or delete a unit instance while do-instances-of-class is in progress. There is one exception to this restriction: the current unit instance in the iteration (bound to var) can be deleted, provided that the deletion does not trigger the deletion of any other unit instances. For example, the following form intended to delete all space instances violates this restriction:

   (do-instances-of-class (space-instance 
                             '(standard-space-instance :plus-subclasses))
     (delete-space-instance space-instance))

because deletion of a space instance with children automatically deletes those child space instances. The function delete-all-space-instances provides an efficient means of deleting all space instances without violating this rule.

REPL Note
The equivalent of (do-instances-of-class (instance arg) (print instance)) can be invoked using the REPL command :pic [arg]. If arg is omitted, t is assumed.

The GBBopen Project

do-instances-of-class