Parameters

A param introduces a value supplied by the caller. It consumes no input. The CLI accepts repeated --param NAME=VALUE options; the reader spec converts the supplied strings when their declarations execute.

Choose a default and check the result

This reader sums a weight array once and compares the total with a capacity:

site/examples/guides/parameters.iris

param capacity = 10
n: 0..
weight[n]: 0..
let total = sum(weight)
check total <= capacity "the weights exceed capacity"

site/examples/guides/parameters.txt

3
2 4 5

Supply a capacity of 12:

iris read site/examples/guides/parameters.iris site/examples/guides/parameters.txt --dzn --param capacity=12

capacity = 12;
n = 3;
weight = [2, 4, 5];
total = 11;

capacity is an ordinary entry in the returned data. Its integer default requires caller values to convert to integers. The parameter does not get a range from the default; add a check if your application also requires a nonnegative capacity.

See caller parameters and parameter evaluation and conversion.

Use or override the default

With no caller value, capacity is 10, so these weights fail:

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

site/examples/guides/parameters.txt:2:6: check failed: the weights exceed capacity
     2 | 2 4 5
       |      ^
spec: site/examples/guides/parameters.iris:5

This is E-CHECK-FAILED. The let calculation uses the whole array, and this check has no repeated record witness. The input location is therefore the cursor after the array.

Defaults execute even when the caller overrides them. A default with a bad index or an undefined name still fails before the supplied string is converted. Keep default expressions valid for every reached execution.

Match the supplied type

A decimal value does not convert to an integer parameter:

iris read site/examples/guides/parameters.iris site/examples/guides/parameters.txt --dzn --param capacity=12.5

site/examples/guides/parameters.txt:1:1: parameter 'capacity' must be an integer, not '12.5'
     1 | 3
       | ^
spec: site/examples/guides/parameters.iris:1

This is E-PARAM-TYPE. A float default converts numeric strings to floats, including integer spellings. A string default keeps the supplied text as a string. Without a default, a supplied value tries integer conversion, then float conversion, then remains a string. With neither a default nor a supplied value, the parameter reports E-PARAM-MISSING.

Names are case-sensitive. An undeclared caller key reports E-PARAM-UNKNOWN before reading input. The CLI splits an assignment at its first = and later assignments replace earlier ones. Parameter strings are not Iris expressions.

The instance parameter is special: an instances block admits it without a declaration. See several instances for its ordinal and name rules.