flipcolor

flipcolor is the most important and most commonly used transform filter.

flipcolor F

matches a position if either F matches the position or if reversecolor F matches the position.

The reversecolor transform

The idea of reversecolor F is that the roles of the white and black players are switched in F.

reversecolor F is formed from F by performing the following operations on each filter contained in F:

• keywords white and black are interchanged
• wtm and btm are interchanged
• result 0-1 and result 1-0 are interchanged
• The color of any piecetype is inverted: K becomes k; k becomes K, a becomes A, and so on
• Any square designator is reflected about the horizontal bisector. Thus, a2 becomes a7; [b-d4,g8] becomes [b-d5,g1].
• light and dark are interchanged

Here are some examples of the effect of the reversecolor operation on different filters:

 reversecolor Ke1 ≡ ke8
 reversecolor 2==A attacks k 
     ≡ 2==a attacks K
 reversecolor {player white "Kasparov" result 1-0}
    ≡ {player black "Kasparov" result 0-1}
 reversecolor power A>power a + 10
    ≡ power a>power A + 10
 reversecolor [Kk]h1-8 ≡ [Kk]h1-8 //no change

Thus, Ke1 matches a position in which the white king is on e1, so flipcolor Ke1 matches a position in which either the white king is on e1 or the black king is on e8.

Likewise, 2==A attacks k matches a position in which the black king is in double check, so

 flipcolor 2 == A attacks k

matches a position in which either the white or the black king is in double check.

flipcolor as a set

If F is a set filter, then so is flipcolor F and its value is the union of the sets of squares represented by F and reversecolor F.

For example, A attacks q represents the set of white pieces that are attacking a black queen (in the current position). Therefore,

  flipcolor A attacks q

represents the set of pieces attacking an enemy queen, that is, the union of the set of white pieces attacking a black queen (A attacks q ) and the set of black pieces attacking a white queen (a attacks Q ).

flipcolor as a number

If F is a numeric filter, then so is flipcolor F and its value is the maximum of the values of F and reversecolor F. (If neither of these two filters match the position, neither does flipcolor F).

For example, #P represents the set of white pawns in the current position. Thus, reversecolor #P is #p and represents the number of black pawns in the current position. Hence

  flipcolor #P
    ≡
  max(#P #p)

the maximum of the number of white pawns and the number of black pawns in the position.

flipcolor count

The value of

  flipcolor count F

is the number of distinct filters in the set of filters consisting of F and reversecolor F that match the current position:

• If neither F nor reversecolor F match the current position, then the value of flipcolor count F is 0.
• If exactly one of F and reversecolor F match the current position, then the value of flipcolor count F is 1.
• If both F and reversecolor F match the current position (and if the two filters are distinct) then the value of flipcolor count F is 2

For example, A attacks q matches a position in which the black queen is under attack. Therefore,

   2==flipcolor count A attacks q

matches a position in which both the white and black queen are being attacked.

The -flipcolor command line option

flipcolor can be invoked from the command line as well. If the -flipcolor option is provided to the cql command line, then the entire body of the input CQL file is implicitly wrapped in a flipcolor. You can thus write a CQL file for one side, and experiment using the command line to see what happens from either side.

Examples

The flipcolor filter is used in many of the examples.

In excelsior-multiple.cql, the filter

  flipcolor Pa-h2

is used to get the set of pawns in their starting positions (second rank for white pawns; 7th rank for black pawns). It is equivalent to:

  Pa-h2 | pa-h7

A more common example is illustrated by immured.cql, which finds pieces that are not pinned and have no legal moves. The results are sorted by the number of such pieces by one side, if this number is at least 3.

First, the CQL file is written from the perspective of one side, say finding games with 3 white immured pieces. Then the entire body is wrapped in braces and flipcolor is applied, to search for games with 3 black immured pieces too. Note that the sort works perfectly well inside of flipcolor: sort will remember and sort by the maximum value it sees, whether the original or under reversecolor.

Other examples of flipcolor are in gameinfo.cql, idealstalemate.cql, long-sacrifice.cql, massivestalemate.cql, mirrormate.cql, multiple-discovered-checks.cql, passers.cql, pins.cql, pinstalemate.cql, powerdifference-stalemate.cql, quadrupled-pawns.cql, queentriangulation.cql, staircase-sort.cql.