transform filters

Note: for a more detailed and precise description of transform filters, see formal definition of transforms.

We often want to repeat the same CQL filter but just changing some things: we might want to change the side to move, or shift all the pieces one square up the board.

Transform filters are a filters that allow for this behavior.

A transform filter has the following syntax:

  transform_filter argument

For example:

  shift {♚a1 ♔a3}
  ⬓ △→♚
  ✵ {♚a1 stalemate}

A transform filter can also include the keyword count before its argument, which counts the number of transforms for which it matches:

  4==✵count ♖♜a1

By far the most important and widely used transform filter is ⬓. If F is a filter, then

  ⬓F

matches a position if either

• F itself matches the position; or
• when the roles of white and black are swapped in F, and all square designators are reflected about the horizontal bisector, then the new filter matches the position

More details on each transform can be found in the links in the table below.

list of transform filters

The specific transforms and their meaning are:

Name	Meaning
✵	rotations and reflections
⬓	reverse colors
fliphorizontal	reflection about horizontal bisector
flipvertical	reflection about vertical bisector
reversecolor	reverse colors (without identity)
rotate45	rotations by multiples of 45°
rotate90	rotations by multiples of 90°
shift	vertical and horizontal shifts
shifthorizontal	horizontal shifts
shiftvertical	vertical shifts

All of the above transforms include the original argument filter as a match option, except for reversecolor. That is, if τ is some transform filter other than reversecolor, and if F matches the current position, then τ F will also match the current position.

Notes on transforms

• Transform filters do not modify function definitions, but they do modify the function invocation. In practice, this means that transforms work as expected with functions.
• The sort filter works as expected under a transform.
• Transform filters with many constituent transforms, like shift ✵ are generally less efficient than using other CQL filters. Usually such filters can be rewritten using direction filters although it is sometimes a hassle to do so.
• Transform filters do not modify rank, file, or makesquare filters.
• Transform filters never modify the board itself. If x is a set variable and if τ is a transform filter, then τ x ≡ x.
• The currenttransform keyword argument to comment or message can help debug some transform-related issues.
• The notransform filter can be used to prevent a transform filter from transforming a particular filter.
• Each transform filter only affects the next filter following it. Thus, ⬓ check ♖a1 is exactly the same as check Ra1 (the user probably intended ⬓ {check ♖a1}.