Patterns

Use a line pattern for a header or record whose punctuation matters. A pattern contains literal text, captures and references to values already read. Matching is case-sensitive and deterministic. A line pattern is not a regular expression.

Capture fields and match a reference

This reader captures a count and a label, reads that many point lines, then requires a matching end label:

site/examples/guides/patterns.iris

line "points = {n:1..} {label:rest}"
repeat n {
  line "({x:int}, {y:int})"
}
line "end {$label}"

site/examples/guides/patterns.txt

points=2 morning route
(1, 2)
(3,4)
end morning route

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

n = 2;
label = "morning route";
x = [1, 3];
y = [2, 4];

{n:1..} captures and bounds an integer. {label:rest} captures the remaining text, so the label can contain spaces. {x:int} and {y:int} capture signed integers. {$label} matches an existing value without defining another entry. Use {name} for a word capture and {_:int} to validate and discard an integer.

Pattern blanks can match zero blanks beside punctuation. That is why both points=2 and (3,4) match these patterns. Between word-like items, a blank is required. A rest capture takes all remaining matching text; put it last. Captures must be nonempty.

See line patterns and captures and reading types in the Specification.

Read a mismatch

The third line below omits the literal parentheses:

site/examples/guides/patterns-invalid.txt

points=2 morning route
(1, 2)
3,4
end morning route

iris read site/examples/guides/patterns.iris site/examples/guides/patterns-invalid.txt --dzn

site/examples/guides/patterns-invalid.txt:3:1: expected a line matching "({x:int}, {y:int})"
     3 | 3,4
       | ^
while reading: repeat [2 of 2]
spec: site/examples/guides/patterns.iris:3

This is E-LINE-MATCH. The active repeat tells you which point failed. Compare that line’s punctuation and case with the pattern before changing the reading types.

Choose how to find the line

line requires the next remaining data line to match. find discards lines until it finds a match; use it when preceding text is irrelevant. sections tries several patterns at the same position. End a pattern with ... only when any remaining suffix is allowed. A selected capture’s range failure is a hard error: find will not search for a later in-range line.

These operations are defined under line, find, skip and expect. For a set of keyword headers, continue with sections.