CLI

The iris command checks reader specs and reads text input using Iris 0.1. It also formats reader specs, starts the language server, and runs the shared conformance suite.

Build from source

Use Rust 1.88 or newer with Cargo. In the repository’s rust/ directory, run:

cargo build --locked -p iris-cli --bin iris

The executable is rust/target/debug/iris relative to the repository root (iris.exe on Windows). If you set CARGO_TARGET_DIR, use that directory’s debug subdirectory instead. Add the executable’s directory to PATH for the commands below. All of them run from the repository root.

Building from source is the only installation path for now. The Rust packages are at version 0.1.0 and are not published; crates.io publication and binary releases are planned.

Check a reader spec

iris check formats/dimacs-cnf/dimacs-cnf.iris

formats/dimacs-cnf/dimacs-cnf.iris: ok (format dimacs-cnf)

A successful check means the reader spec parses and its names resolve. It does not execute expressions or parameter defaults, so read a sample as well: a name used in an expression can still fail at read time.

Read input

The default output is a summary: entry names, types, scalar values, and array shapes. This example reads the DIMACS formula:

iris read formats/dimacs-cnf/dimacs-cnf.iris formats/dimacs-cnf/cases/three-variables/input.txt

formats/dimacs-cnf/cases/three-variables/input.txt [dimacs-cnf]
  vars: int 3
  clauses: int 3
  clause: int array 3 x 1..3

You can request that summary explicitly:

iris read formats/dimacs-cnf/dimacs-cnf.iris formats/dimacs-cnf/cases/three-variables/input.txt --summary

formats/dimacs-cnf/cases/three-variables/input.txt [dimacs-cnf]
  vars: int 3
  clauses: int 3
  clause: int array 3 x 1..3

Use --json for canonical JSON. It retains entry names, types, depths, and values:

iris read formats/dimacs-cnf/dimacs-cnf.iris formats/dimacs-cnf/cases/three-variables/input.txt --json

{"iris":"0.1","entries":[{"name":"vars","type":"int","depth":0,"value":3},{"name":"clauses","type":"int","depth":0,"value":3},{"name":"clause","type":"int","depth":2,"value":[[1,-2],[2,3,-1],[-3]]}]}

Use --dzn for MiniZinc data:

iris read formats/dimacs-cnf/dimacs-cnf.iris formats/dimacs-cnf/cases/three-variables/input.txt --dzn

vars = 3;
clauses = 3;
% clause: array[int] of tuple(array[int] of int)
clause = [([1, -2],), ([2, 3, -1],), ([-3],)];

Choose one output option. A read accepts several input files; parameters apply to each. JSON and dzn documents concatenate without extra separators. Output is buffered until all files have been read successfully.

Supply parameters

Repeat --param NAME=VALUE for caller parameters. Values remain strings until the reader spec converts them. The first = separates name and value; later assignments to the same name replace earlier ones.

The instance parameter selects one instance by its number (starting at 1) or exact name. This job shop example selects a named instance:

iris read formats/jobshop/jobshop.iris formats/jobshop/cases/or-library/input.txt --summary --param instance=handmade-or

formats/jobshop/cases/or-library/input.txt [jobshop]
  name: string "handmade-or"
  n_jobs: int 3
  n_machines: int 3
  machine: int array 3 x 3
  duration: int array 3 x 3

See parameters and instances in the Specification.

List instances

A catalog traverses every instance, even if you supply a selector. The plain listing gives the count, names when all are usable, and first rejection messages:

iris list formats/jobshop/jobshop.iris formats/jobshop/cases/or-library/input.txt

formats/jobshop/cases/or-library/input.txt: 1 instance
  1 handmade-or

Add --dzn for the catalog as data:

iris list formats/jobshop/jobshop.iris formats/jobshop/cases/or-library/input.txt --dzn

instances = 1;
name = ["handmade-or"];

Format reader specs

Format a file in place:

iris fmt formats/dimacs-cnf/dimacs-cnf.iris

Directory operands recurse through .iris files, including hidden files and files matched by .gitignore. Symlinks are skipped. In CI, check without writing:

iris fmt --check formats/

Successful exit; no output.

Preview unified diffs and fail if changes are needed:

iris fmt --check --diff formats/

Successful exit; no output.

--diff alone prints diffs without changing files and exits successfully when the only difference is formatting. --check exits 1 if a file would change. Syntax errors leave that file unchanged; processing continues with other files. See the formatter for style, standard input, and EditorConfig.

Run conformance cases

The conformance runner compares an implementation’s driver with the language-neutral cases. Build the Rust driver in rust/:

cargo build --locked -p iris-cli --bin iris-driver

Then run from the repository root, with iris on PATH and the default Cargo target directory. If you changed CARGO_TARGET_DIR, adjust the driver path:

iris conformance rust/target/debug/iris-driver conformance/cases/0.1/smoke

Explicit roots are relative to the current directory. With no root, the default is conformance/cases/0.1. --filter selects a path substring; --version defaults to 0.1; --timeout defaults to 30 seconds per case. --driver-id selects precise known-failure annotations for that driver. Rust needs no exemptions. The driver argument is a command string parsed with shell quoting, without shell execution or expansion.

See the conformance suite for its driver protocol and case format.

Errors and exit status

Checks and reads exit 0 on success, 1 for language, file or resource errors, and 2 for incorrect usage. Diagnostics show a location, a source excerpt and a caret; read errors also identify the active reader-spec line. A failed read prints no partial data. The format library shows a real failed read; the Specification defines the error codes and their order.

For conformance, exit 1 means a failure or unexpected pass; exit 2 also covers configuration, case-loading and zero-selection errors.