# ⬓

`⬓` (or `flipcolor`) is the most important and most commonly used transform filter.

`⬓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: `♔` becomes `♚`; `♚` becomes `♔`, `▲` becomes `△`, 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 ♔e1 ≡ ♚e8
reversecolor 2==△→♚
≡ 2==▲→♔
reversecolor {player white "Kasparov" result 1-0}
≡ {player black "Kasparov" result 0-1}
reversecolor power △>= power ▲ + 10
≡ power ▲>= power △ + 10
reversecolor ♔♚h1-8 ≡ ♔♚h1-8 //no change```

Thus, `♔e1` matches a position in which the white king is on `e1`, so `⬓♔e1` matches a position in which either the white king is on `e1` or the black king is on `e8`.

Likewise, `2==△→♚` matches a position in which the black king is in double check, so

` ⬓2==△→♚`
matches a position in which either the white or the black king is in double check.

## `⬓` as a set

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

For example, `△→♛` represents the set of white pieces that are attacking a black queen (in the current position). Therefore,

`  ⬓△→♛`

represents the set of pieces attacking an enemy queen, that is, the union of the set of white pieces attacking a black queen (`△→♛` ) and the set of black pieces attacking a white queen (`▲→♕` ).

## `⬓` as a number

If F is a numeric filter, then so is `⬓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 `⬓F`).

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

```  ⬓#♙
≡
max(#♙ #♟)```

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

## `⬓count`

The value of
`  ⬓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 `⬓count F` is `0`.
• If exactly one of `F` and `reversecolor F` match the current position, then the value of `⬓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 `⬓count F` is `2`

For example, `△→♛` matches a position in which the black queen is under attack. Therefore,

`   2==⬓count△→q`
matches a position in which both the white and black queen are being attacked.

## The `-flipcolor` command line option

`⬓` 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 `⬓`. 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 `⬓` filter is used in many of the examples.

In excelsior-multiple.cql, the filter

`  ⬓♙a-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:
`  ♙a-h2 | ♟a-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 `⬓` is applied, to search for games with 3 black immured pieces too. Note that the sort works perfectly well inside of `⬓`: `sort` will remember and sort by the maximum value it sees, whether the original or under reversecolor.