# Structured INPUT availability

## Purpose

Input item availability metadata describes when an INPUT parameter is
applicable. It is used by documentation and tooling; it does not reject or
alter a user's INPUT based on this condition. Runtime diagnostics, if added,
must define how explicitly supplied parameters whose conditions are false are
handled.

## Invariants

- The C++ `Input_Item` registration is the source of truth. YAML and Markdown
  are generated artifacts.
- Every non-empty registration is canonical. `set_availability()` rejects
  syntax errors and non-canonical spelling.
- The AST is the stored representation; the exported string is serialized from
  it, so the two forms cannot diverge.
- Every expression is a complete, independently evaluable predicate. It must
  include enclosing requirements rather than inheriting them implicitly from a
  referenced parameter.
- After all INPUT items are registered, every referenced label, operator and
  literal is checked against machine-readable parameter type information.

## Grammar and meaning

```text
expression := condition | compound
compound := operand " and " operand (" and " operand)*
          | operand " or " operand (" or " operand)*
operand := condition | "(" compound ")"
condition := parameter comparison value
           | parameter " in [" value ", " value (", " value)* "]"
           | parameter " contains " value
comparison := "==" | "!=" | ">" | ">=" | "<" | "<="
value := bare-value | '"' quote-required-value '"'
```

The grammar describes the canonical form of a non-empty expression. A compound
expression contains only one kind of Boolean operator. When a compound
expression is used as an operand of another compound expression, it must be
parenthesized, even when operator precedence would make the grouping
unambiguous. A single condition must not be parenthesized. For example,
`(basis_type==pw and calculation==scf) or esolver_type==sdft` is canonical,
while `basis_type==pw and calculation==scf or esolver_type==sdft` and
`(basis_type==pw)` are not.

Canonical formatting is required: comparison operators have no surrounding
spaces; `and`, `or`, `in`, and `contains` have one space on each side; and list
items are separated by a comma followed by one space. For example,
`mode in [a, b]` is valid, while `mode in [a,b]` is rejected. Leading or
trailing whitespace is not allowed, and a comma is not an alternative spelling
of `and`. The parser accepts only the spelling produced by the AST serializer,
so forms such as `basis_type == pw` and
`basis_type==pw,calculation==scf` are also rejected.

`bare-value` is a non-empty value containing no whitespace or any of
`()[],=<>!`. A value containing at least one of those characters must use the
non-empty double-quoted form, and a value that does not require quotes must not
use them. Thus `basis_type==pw` and `relax_method==cg` are canonical, while
`basis_type=="pw"` is not. `==` compares one complete value. Two or more
alternatives use `in [...]`, while `parameter contains value` tests whether a
vector contains one element, such as `td_ttype contains 0`. `/` is an ordinary
value character, not another spelling of membership. Ordered comparisons
require a numeric scalar.

A path that references a parameter must imply that parameter's availability.
Every `and` operand is required, while satisfying either branch of an `or` is
sufficient. Repeated `and` or `or` groups are order-independent. Different leaf
conditions are not related; for example, `mode==a` does not satisfy
`mode in [a, b]`.

Examples:

```cpp
item.set_availability("basis_type==pw");
item.set_availability("vdw_method in [d2, d3_0]");
item.set_availability("td_ttype contains 2");
item.set_availability("esolver_type==sdft and method_sto==2");
```

## Registration and validation workflow

1. Parse and require canonical spelling in `set_availability()`.
2. Finish registering all `Input_Item` objects.
3. Validate referenced parameter names, operator compatibility, literal values, and that every referenced parameter carries its own enclosing requirements on the referencing path.
4. Serialize the AST to YAML as part of the documentation build.
5. Generate the INPUT reference documentation from that YAML.

Runtime evaluation is outside this metadata contract. Any implementation must
define evaluation timing, treatment of defaults and reset values, and warning
behavior for explicitly supplied parameters.