Several instances

Use an instances block when one input file contains several separately selectable instances. Each pass through the block reads one instance into a fresh local frame. A read returns one instance’s data. A catalog reports the file’s instance count, the usable names, and the first rejection in each instance.

Describe one instance per pass

The block must be the last statement of the reader spec. Put checks inside it so they apply to each instance:

instances {
  line "instance {name:word}"
  n: 1..
  values[n]: int
  check min(values) >= 0 "values must be nonnegative"
}

instance small
2
4 7
instance broken
1
-1
instance large
3
2 5 8

The second instance has a negative value. Its check rejects it; the other two remain usable. See instance blocks and frames.

Inspect the catalog

The plain listing shows names and a rejection message:

iris list site/examples/guides/instances.iris site/examples/guides/instances.txt

site/examples/guides/instances.txt: 3 instances
  1 small
  2 broken (failed: values must be nonnegative)
  3 large

Use --dzn to get the catalog as data:

iris list site/examples/guides/instances.iris site/examples/guides/instances.txt --dzn

instances = 3;
name = ["small", "broken", "large"];
failed = ["", "values must be nonnegative", ""];

A catalog traverses every instance, even when given an instance parameter. It can retain a failed check as a rejection summary. A malformed numeric token, invalid UTF-8 or exhausted work budget still aborts the operation. See catalog results and deferred failures.

Select by number or name

Ordinals start at 1. Select the third instance:

iris read site/examples/guides/instances.iris site/examples/guides/instances.txt --dzn --param instance=3

name = "large";
n = 3;
values = [2, 5, 8];

Or select its exact, case-sensitive name:

iris read site/examples/guides/instances.iris site/examples/guides/instances.txt --dzn --param instance=large

name = "large";
n = 3;
values = [2, 5, 8];

The reader traverses earlier instances, defers eligible rejections in skipped ones, and stops after the selected body. It does not visit later instances. Integer-looking selectors choose ordinals before names; avoid numeric names when name selection matters. Duplicate names select the first match.

Read without a selector

A file with several instances needs an explicit selection. With no selector, the reader retains the first instance and traverses the rest to count them. The later rejected check is deferred:

iris read site/examples/guides/instances.iris site/examples/guides/instances.txt --dzn

site/examples/guides/instances.txt:10:1: the file has 3 instances; select one with the parameter instance (a number from 1, or a name)
    10 | 
       | ^
spec: site/examples/guides/instances.iris:1

This is E-INSTANCE-SELECTION. Selecting the rejected instance instead reports its check failure:

iris read site/examples/guides/instances.iris site/examples/guides/instances.txt --dzn --param instance=broken

site/examples/guides/instances.txt:6:3: check failed: values must be nonnegative
     6 | -1
       |   ^
while reading: instance [2]
spec: site/examples/guides/instances.iris:5

That is E-CHECK-FAILED. A rejected first instance would fail immediately even without a selector. No read returns partial data.

See the exact selection rules. The job shop reader applies this structure to a real format.