A specification language for structured text formats
A program in Iris is a reader spec. It describes one format: which values a file contains, how they are laid out, how they are collected into arrays, and which conditions they must satisfy. Given a reader spec and an input file, Iris either returns the file’s contents as named, typed data or rejects the file with the position and the statement that failed.
Iris began as the instance reader introduced in Gecode 6.5.0, a constraint solver, but any line- and token-oriented text format is a candidate. The same reader spec works in the command-line tool, in a program that embeds an implementation, and in the playground.
A DIMACS CNF file, the reader spec for that format, and the data Iris reads from it.
Input
input.txt
Reader spec
dimacs-cnf.irisformat dimacs-cnf
# SATLIB files end with "%" and "0"
{
# the terminating 0 is not stored
}
Data
typed entriesvars int
clauses int
clause int · depth 2
Point at or focus a part to see how the input, the reader spec, and the data connect. Click to keep a connection; Escape clears it.
All three clauses read; terminating zeros are consumed without being stored.
Examples from the format library
Choose a format to see a sample input, its reader spec, and the data Iris reads. The output comes from the Iris command-line tool, run when the site is built.
Zero terminators end each clause and are discarded from the data.
iris read formats/dimacs-cnf/dimacs-cnf.iris formats/dimacs-cnf/cases/three-variables/input.txt --dznvars = 3;
clauses = 3;
% clause: array[int] of tuple(array[int] of int)
clause = [([1, -2],), ([2, 3, -1],), ([-3],)];
Read succeeded
Coordinates remain coordinates; distance construction belongs to the host.
iris read formats/tsplib/tsplib.iris formats/tsplib/cases/euc-2d-five/input.txt --dznname = "handmade-euc-2d-five";
'type' = "TSP";
n = 5;
edge_weight_type = "EUC_2D";
node_coord_type = "TWOD_COORDS";
node = [1, 2, 3, 4, 5];
x = [0.0, 3.0, 3.0, 0.0, 1.5];
y = [0.0, 0.0, 4.0, 4.0, 2.0];
Read succeeded
Row and column clues become ragged arrays, with one array per line.
iris read formats/nonogram/nonogram.iris formats/nonogram/cases/five-by-five/input.txt --dznwidth = 5;
height = 5;
% row: array[int] of tuple(array[int] of int)
row = [([1, 1],), ([1, 1],), ([1],), ([1, 1],), ([1, 1],)];
% col: array[int] of tuple(array[int] of int)
col = [([1, 1],), ([1, 1],), ([1],), ([1, 1],), ([1, 1],)];
Read succeeded
Each job’s operations yield machine and duration arrays.
iris read formats/jobshop/jobshop.iris formats/jobshop/cases/jsplib/input.txt --dznn_jobs = 3;
n_machines = 3;
machine = [| 0, 2, 1
| 1, 0, 2
| 2, 1, 0 |];
duration = [| 3, 2, 4
| 2, 1, 3
| 4, 3, 2 |];
Read succeeded
Blank cells become zero. Solving the puzzle belongs to the host.
iris read formats/sudoku/sudoku.iris formats/sudoku/cases/four-by-four/input.txt --dznn = 4;
box_width = 2;
box_height = 2;
cells = [| 1, 0, 0, 4
| 0, 4, 1, 0
| 0, 1, 4, 0
| 4, 0, 0, 1 |];
Read succeeded
Travel times form a matrix; checks require ordered time windows.
iris read formats/tsptw/tsptw.iris formats/tsptw/cases/three-nodes/input.txt --dznn = 3;
dist = [| 0, 2, 4
| 3, 0, 2
| 4, 3, 0 |];
ready = [0, 2, 5];
due = [20, 8, 12];
Read succeeded
Introduction
How a reader spec describes a format, shown on a small file read from the command line.
Read the introductionFormat library
Reader specs for benchmark formats, with sample inputs, the data they produce, and rejected inputs. Each case can be downloaded.
Browse the formatsCommand-line tool
Check a reader spec, read an input as JSON or MiniZinc data, or list the instances in a file.
CLI documentationThe Iris Language Specification defines the language.