Sections

Use sections for lines identified by keywords. Arms match in whatever order the lines appear, and an arm’s body runs as soon as it matches. This suits headers whose order varies, as in TSPLIB.

Read headers and a body

This coordinate reader requires a dimension, an edge-weight type and a coordinate section. Only the name is optional.

site/examples/tutorial/tsplib-coordinates.iris

comment "COMMENT"
sections until "EOF" {
  "NAME : {name:rest}" optional
  "DIMENSION : {n:2..46340}"
  "EDGE_WEIGHT_TYPE : {edge_weight_type:word}"
  "NODE_COORD_SECTION" {
    repeat n {
      node: int
      x: float
      y: float
    }
  }
}
check edge_weight_type == "EUC_2D" "this reader requires EUC_2D coordinates"
check x >= -1e9 && x <= 1e9 && y >= -1e9 && y <= 1e9 "coordinates must be between -1e9 and 1e9"

site/examples/tutorial/tsplib-coordinates.txt

NAME : triangle
EDGE_WEIGHT_TYPE : EUC_2D
DIMENSION:3
NODE_COORD_SECTION
1 0 0
2 3 0
3 3 4
EOF

iris read site/examples/tutorial/tsplib-coordinates.iris site/examples/tutorial/tsplib-coordinates.txt --dzn

name = "triangle";
edge_weight_type = "EUC_2D";
n = 3;
node = [1, 2, 3];
x = [0.0, 3.0, 3.0];
y = [0.0, 0.0, 4.0];

The coordinate body uses n, so DIMENSION must occur before NODE_COORD_SECTION. Other header arms may occur in either order. Names are defined when their arms run; sections do not rearrange input or defer bodies.

Required, optional and last arms

An ordinary arm must match exactly once. optional changes that to zero or one, so guard an optional capture with defined before using it. last ends sections after the selected arm’s body runs. It still checks for missing required arms. The job shop tutorial uses a last arm to leave the next instance header for the next pass.

A terminator is tested before arms. Actual end of input also ends sections, even with until "EOF". On completion, a missing required arm reports E-LINE-MATCH.

Repeated and unknown lines

A repeated dimension is an error even when its value is unchanged:

site/examples/guides/sections-repeated.txt

NAME : triangle
DIMENSION : 3
DIMENSION : 3
EDGE_WEIGHT_TYPE : EUC_2D
NODE_COORD_SECTION
1 0 0
2 3 0
3 3 4
EOF

iris read site/examples/tutorial/tsplib-coordinates.iris site/examples/guides/sections-repeated.txt --dzn

site/examples/guides/sections-repeated.txt:3:1: a second line matching "DIMENSION : {n:2..46340}" (the first is on line 2)
     3 | DIMENSION : 3
       | ^
spec: site/examples/tutorial/tsplib-coordinates.iris:2

This is E-SECTIONS-REPEATED. Optional arms also reject a second match. Use a repeat for repeated records; a sections arm does not collect repeated headers into an array.

Unknown lines report E-SECTIONS-UNEXPECTED. skip other discards unmatched lines when the format permits irrelevant text. Keep sections strict when an unknown keyword is likely to be a spelling error. If two patterns could match, the first complete match wins.

The Specification defines the full sections execution order. The TSPLIB tutorial grows this example into the library reader.