atomic

If the first use of a variable is preceded by the keyword atomic, that variable is an atomic variable:

    atomic X=4
    atomic Y="hello"

Inside of an ⊢ filter, atomic variables are treated transactionally in the sense that their values are restored following any failed match of a path.

Equivalently, at any point in the evaluation of a ⊢ filter, the value of an atomic variable would be the same as if the only moves evaluated by the ⊢ filter were those leading up to the current position. Any value set to that atomic variable along other sequences of moves would be ingored.

Furthermore, at the end of evaluation, the value of the atomic variables would be those at the end of the matching path of moves.

Examples

Suppose that variations is set, so that CQL considers variations:

cql (input hhdvi.pgn variations)

Now consider these two examples (which must be in different cql files)

Example 1: no atomic specified

    Count=0
    ⊢
     ―― Count+=1 *

If this is evaluated at the initial position, the value of Count will equal the total number of positions in the game. That is because the ⊢ filter is visiting each position and incrementing Count after each such visit.

Now suppose that atomic is specified:..

Example 2: atomic specified

    atomic Count=0
    ⊢
     ―― Count+=1 *

Now the value of Count will be the length of the longest sequence of consecutive moves in the game. That is because this sequence will be the matching sequence of moves that ⊢ looks for, and at the end of this sequence, Count will have value equal to the number of moves in this sequence. Hence, this will be the value of Count after evaluation of the ⊢ filter.

Limitations

At this time the atomic keyword does not support variables that are dictonaries.