if

The if filter has one of two forms:
    if condition consequent
    if condition consequent else alternative

Each of condition, consequent and alternative can be any filter. For example,

    if (R>2) check
    if (A attacks k) mate else Q

The meaning of the if filter in a position is as follows:

  1. If condition matches the position then consequent is evaluated in the position.
  2. If condition does not match and alternative is present, then alternative is evaluated.

the 'then' keyword: syntax changes since CQL 6.0

Versions of CQL earlier than CQL 6.1 used a slightly different syntax for the if filter. In those versions,the keyword then was required before consequent. CQL 6.1 still supports this syntax, but it is now deprecated.
    if R>2 then check
    if A attacks k then mate else Q

Effectively, the then keyword is now optional.

when an if filter matches a position

An if filter matches a position if one of the following is true:
  1. condition and consequent both match the position
  2. condition does not match the position and there is no alternative
  3. condition does not match the position and alternative matches the position

Note that point 2 above might be suprising: an if filter without an else matches a position if the condition does not match:

       if (check) R>2
will match the current position if either
  • The current position is not a check, or
  • The current position is a check and there are at least three white rooks in the position

The value associated with an if filter

An if filter has an associated value if
  1. it has both consequent and alternative
  2. it matches the position
  3. Its consequent and alternative are both numeric filters, both position filters, or both set filters.
When an if filter matches a position, its value is the value of its consequent or its alternative , depending on whether its condition matched or failed to match the position.

Examples

The if filter is used in idealmate.cql, modelmate.cql, persistent.cql, puremate.cql.