API Reference

API Reference

Boards

Chess.BoardType.
Board

Type representing a chess board.

A chess board is most commonly obtained from a FEN string (using the fromfen() function), from the startboard() function (which returns a board in the usual chess starting position), or by making a move on some other chess board.

source
Chess.startboardFunction.
startboard()

Returns a Board object with the standard chess initial position.

source
@startboard

A macro for initializing a board from the initial position with some moves.

Castling moves must be indicated without a hyphen (i.e. "OO" or "OOO") in order to satisfy Julia's parser.

Examples

julia> @startboard e4 e5 Nf3 Nc6 Bb5 a6 Ba4 Nf6 OO
Board (r1bqkb1r/1ppp1ppp/p1n2n2/4p3/B3P3/5N2/PPPP1PPP/RNBQ1RK1 b kq -):
 r  -  b  q  k  b  -  r
 -  p  p  p  -  p  p  p
 p  -  n  -  -  n  -  -
 -  -  -  -  p  -  -  -
 B  -  -  -  P  -  -  -
 -  -  -  -  -  N  -  -
 P  P  P  P  -  P  P  P
 R  N  B  Q  -  R  K  -
source
Chess.fromfenFunction.
fromfen(fen::String)

Try to create a Board value from a FEN string.

If the supplied string doesn't represent a valid board position, this function returns nothing.

source
Chess.fenFunction.
fen(b::Board)

Convert a board to a FEN string.

source
Chess.pprintMethod.
pprint(b::Board, color = false, highlight = SS_EMPTY, unicode = false)

Pretty-print a Board to the standard output.

On terminals with 24-bit color support, use color = true for a colored board. Use the parameter highlight to include a SquareSet you want to be highlighted.

Use unicode = true for Unicode piece output, if your font and terminal supports it.

Examples

julia> pprint(startboard(), highlight = SquareSet(SQ_D4, SQ_E4, SQ_D5, SQ_E5))
+---+---+---+---+---+---+---+---+
| r | n | b | q | k | b | n | r |
+---+---+---+---+---+---+---+---+
| p | p | p | p | p | p | p | p |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | * | * |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | * | * |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
| P | P | P | P | P | P | P | P |
+---+---+---+---+---+---+---+---+
| R | N | B | Q | K | B | N | R |
+---+---+---+---+---+---+---+---+
rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -
source
Chess.lichessurlFunction.
lichessurl(b::Board)

Returns an URL for opening the board in lichess.

source
Chess.lichessMethod.
lichess(b::Board)

Opens the board in lichess.

source
Chess.pieceonFunction.
pieceon(b::Board, s::Square)
pieceon(b::Board, f::SquareFile, r::SquareRank)
pieceon(b::Board, s::String)

Find the piece on the given square of the board.

Examples

julia> b = startboard();

julia> pieceon(b, SQ_E1)
PIECE_WK

julia> pieceon(b, FILE_B, RANK_8)
PIECE_BN

julia> pieceon(b, SQ_B5)
EMPTY

julia> pieceon(b, "d8")
PIECE_BQ
source
Chess.sidetomoveFunction.
sidetomove(b::Board)

The current side to move, WHITE or BLACK.

Examples

julia> b = startboard();

julia> b2 = domove(b, "e4");

julia> sidetomove(b)
WHITE

julia> sidetomove(b2)
BLACK
source
Chess.epsquareFunction.
epsquare(b::Board)

The square on which an en passant capture is possible, or SQ_NONE.

source
Chess.kingsquareFunction.
kingsquare(b::Board, c::PieceColor)

The square of the king for the given side.

Examples

julia> b = startboard();

julia> kingsquare(b, WHITE)
SQ_E1

julia> kingsquare(b, BLACK)
SQ_E8
source
Chess.piecesFunction.
pieces(b::Board, c::PieceColor)
pieces(b::Board, t::PieceType)
pieces(b::Board, c::PieceColor, t::PieceType)
pieces(b::Board, p::Piece)

Obtain the set of squares containing various kinds of pieces.

Examples

julia> b = startboard();

julia> pieces(b, WHITE) == SS_RANK_1 ∪ SS_RANK_2
true

julia> pieces(b, ROOK) == SquareSet(SQ_A1, SQ_H1, SQ_A8, SQ_H8)
true

julia> pieces(b, BLACK, PAWN) == SS_RANK_7
true

julia> pieces(b, PIECE_WB)
SquareSet:
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  #  -  -  #  -  -
source
Chess.pawnsFunction.
pawns(b::Board)

The set of squares containing pawns of either color.

Examples

julia> b = startboard();

julia> pawns(b) == SS_RANK_2 ∪ SS_RANK_7
true
source
pawns(b::Board, c::PieceColor)

The set of squares containing pawns of the given color.

Examples

julia> b = startboard();

julia> pawns(b, WHITE) == SS_RANK_2
true

julia> pawns(b, BLACK) == SS_RANK_7
true
source
Chess.knightsFunction.
knights(b::Board)

The set of squares containing knights of either color.

Examples

julia> b = startboard();

julia> knights(b) == SquareSet(SQ_B1, SQ_G1, SQ_B8, SQ_G8)
true
source
knights(b::Board, c::PieceColor)

The set of squares containing knights of the given color.

Examples

julia> b = startboard();

julia> knights(b, WHITE) == SquareSet(SQ_B1, SQ_G1)
true

julia> knights(b, BLACK) == SquareSet(SQ_B8, SQ_G8)
true
source
Chess.bishopsFunction.
bishops(b::Board)

The set of squares containing bishops of either color.

Examples

julia> b = startboard();

julia> bishops(b) == SquareSet(SQ_C1, SQ_F1, SQ_C8, SQ_F8)
true
source
bishops(b::Board, c::PieceColor)

The set of squares containing bishops of the given color.

Examples

julia> b = startboard();

julia> bishops(b, WHITE) == SquareSet(SQ_C1, SQ_F1)
true

julia> bishops(b, BLACK) == SquareSet(SQ_C8, SQ_F8)
true
source
Chess.rooksFunction.
rooks(b::Board)

The set of squares containing rooks of either color.

Examples

julia> b = startboard();

julia> rooks(b) == SquareSet(SQ_A1, SQ_H1, SQ_A8, SQ_H8)
true
source
rooks(b::Board, c::PieceColor)

The set of squares containing rooks of the given color.

Examples

julia> b = startboard();

julia> rooks(b, WHITE) == SquareSet(SQ_A1, SQ_H1)
true

julia> rooks(b, BLACK) == SquareSet(SQ_A8, SQ_H8)
true
source
Chess.queensFunction.
queens(b::Board)

The set of squares containing queens of either color.

Examples

julia> b = startboard();

julia> queens(b) == SquareSet(SQ_D1, SQ_D8)
true
source
queens(b::Board, c::PieceColor)

The set of squares containing queens of the given color.

Examples

julia> b = startboard();

julia> queens(b, WHITE) == SquareSet(SQ_D1)
true

julia> queens(b, BLACK) == SquareSet(SQ_D8)
true
source
Chess.kingsFunction.
kings(b::Board)

The set of squares containing kings of either color.

Examples

julia> b = startboard();

julia> kings(b) == SquareSet(SQ_E1, SQ_E8)
true
source
kings(b::Board, c::PieceColor)

The set of squares containing kings of the given color.

Unless something is very wrong, this set should always contain exactly one square.

Examples

julia> b = startboard();

julia> kings(b, WHITE) == SquareSet(SQ_E1)
true

julia> kings(b, BLACK) == SquareSet(SQ_E8)
true
source
Chess.bishoplikeFunction.
bishoplike(b::Board)

The set of squares containing bishoplike pieces of either color.

The bishoplike pieces are the pieces that can move like a bishop, i.e. bishops and queens.

Examples

julia> b = startboard();

julia> bishoplike(b) == SquareSet(SQ_C1, SQ_D1, SQ_F1, SQ_C8, SQ_D8, SQ_F8)
true
source
bishoplike(b::Board, c::PieceColor)

The set of squares containing bishoplike pieces of the given color.

The bishoplike pieces are the pieces that can move like a bishop, i.e. bishops and queens.

Examples

julia> b = startboard();

julia> bishoplike(b, WHITE) == SquareSet(SQ_C1, SQ_D1, SQ_F1)
true

julia> bishoplike(b, BLACK) == SquareSet(SQ_C8, SQ_D8, SQ_F8)
true
source
Chess.rooklikeFunction.
rooklike(b::Board)

The set of squares containing rooklike pieces of either color.

The rooklike pieces are the pieces that can move like a rook, i.e. rooks and queens.

Examples

julia> b = startboard();

julia> rooklike(b) == SquareSet(SQ_A1, SQ_D1, SQ_H1, SQ_A8, SQ_D8, SQ_H8)
true
source
rooklike(b::Board, c::PieceColor)

The set of squares containing rooklike pieces of the given color.

The rooklike pieces are the pieces that can move like a rook, i.e. rooks and queens.

Examples

julia> b = startboard();

julia> rooklike(b, WHITE) == SquareSet(SQ_A1, SQ_D1, SQ_H1)
true

julia> rooklike(b, BLACK) == SquareSet(SQ_A8, SQ_D8, SQ_H8)
true
source
Chess.occupiedsquaresFunction.
occupiedsquares(b::Board)

The set of all occupied squares on the board.

Examples

julia> b = startboard();

julia> occupiedsquares(b) == pieces(b, WHITE) ∪ pieces(b, BLACK)
true

julia> isempty(emptysquares(b) ∩ occupiedsquares(b))
true
source
Chess.emptysquaresFunction.
emptysquares(b::Board)

The set of all empty squares on the board.

Examples

julia> emptysquares(startboard())
SquareSet:
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 #  #  #  #  #  #  #  #
 #  #  #  #  #  #  #  #
 #  #  #  #  #  #  #  #
 #  #  #  #  #  #  #  #
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
source
cancastlekingside(b::Board, c::PieceColor)

Determine whether the given side still has the right to castle kingside.

source
cancastlequeenside(b::Board, c::PieceColor)

Determine whether the given side still has the right to castle queenside.

source
bishopattacks(b::Board, s::Square)

The set of squares a bishop on square s would attack on this board.

Both empty squares and squares occupied by enemy or friendly pieces are included in the set.

Examples

julia> b = fromfen("5k2/8/4q3/8/2B5/8/4P3/3K4 w - -");

julia> pprint(b, highlight=bishopattacks(b, SQ_C4))
+---+---+---+---+---+---+---+---+
|   |   |   |   |   | k |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
| * |   |   |   |*q*|   |   |   |
+---+---+---+---+---+---+---+---+
|   | * |   | * |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | B |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   | * |   | * |   |   |   |   |
+---+---+---+---+---+---+---+---+
| * |   |   |   |*P*|   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | K |   |   |   |   |
+---+---+---+---+---+---+---+---+
5k2/8/4q3/8/2B5/8/4P3/3K4 w - -
source
Chess.rookattacksMethod.
rookattacks(b::Board, s::Square)

The set of squares a rook on square s would attack on this board.

Both empty squares and squares occupied by enemy or friendly pieces are included in the set.

Examples

julia> b = fromfen("2r2k2/8/8/8/2R3P1/8/4P3/3K4 w - -");

julia> pprint(b, highlight=rookattacks(b, SQ_C4))
+---+---+---+---+---+---+---+---+
|   |   |*r*|   |   | k |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
| * | * | R | * | * | * |*P*|   |
+---+---+---+---+---+---+---+---+
|   |   | * |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * |   | P |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * | K |   |   |   |   |
+---+---+---+---+---+---+---+---+
2r2k2/8/8/8/2R3P1/8/4P3/3K4 w - -
source
Chess.queenattacksMethod.
queenattacks(b::Board, s::Square)

The set of squares a queen on square s would attack on this board.

Both empty squares and squares occupied by enemy or friendly pieces are included in the set.

Examples

julia> b = fromfen("2r2k2/8/8/8/2Q3P1/8/4P3/3K4 w - -");

julia> pprint(b, highlight=queenattacks(b, SQ_C4))
+---+---+---+---+---+---+---+---+
|   |   |*r*|   |   | k | * |   |
+---+---+---+---+---+---+---+---+
|   |   | * |   |   | * |   |   |
+---+---+---+---+---+---+---+---+
| * |   | * |   | * |   |   |   |
+---+---+---+---+---+---+---+---+
|   | * | * | * |   |   |   |   |
+---+---+---+---+---+---+---+---+
| * | * | Q | * | * | * |*P*|   |
+---+---+---+---+---+---+---+---+
|   | * | * | * |   |   |   |   |
+---+---+---+---+---+---+---+---+
| * |   | * |   |*P*|   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * | K |   |   |   |   |
+---+---+---+---+---+---+---+---+
2r2k2/8/8/8/2Q3P1/8/4P3/3K4 w - -
source
Chess.isattackedFunction.
isattacked(b::Board, s::Square, side::PieceColor)

Determine whether the given square is attacked by the given side.

Examples

julia> b = startboard();

julia> isattacked(b, SQ_F3, WHITE)
true

julia> isattacked(b, SQ_F3, BLACK)
false
source
Chess.attackstoFunction.
attacksto(b::Board, s::Square)

The set of squares containing pieces of either color which attack square s.

Examples

julia> b = fromfen("r1bqkbnr/pppp1ppp/2n5/4p3/3PP3/5N2/PPP2PPP/RNBQKB1R b KQkq - 0 3");

julia> pprint(b, highlight=attacksto(b, SQ_D4))
+---+---+---+---+---+---+---+---+
| r |   | b | q | k | b | n | r |
+---+---+---+---+---+---+---+---+
| p | p | p | p |   | p | p | p |
+---+---+---+---+---+---+---+---+
|   |   |*n*|   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |*p*|   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | P | P |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |*N*|   |   |
+---+---+---+---+---+---+---+---+
| P | P | P |   |   | P | P | P |
+---+---+---+---+---+---+---+---+
| R | N | B |*Q*| K | B |   | R |
+---+---+---+---+---+---+---+---+
r1bqkbnr/pppp1ppp/2n5/4p3/3PP3/5N2/PPP2PPP/RNBQKB1R b KQkq -
source
Chess.attacksfromFunction.
attacksfrom(b::Board, s::Square)

The set of squares attacked by the piece on s.

Both empty squares, squares containing enemy pieces, and squares containing friendly pieces are included.

Examples

julia> b = fromfen("r1bqkbnr/pppp1ppp/2n5/4p3/3PP3/5N2/PPP2PPP/RNBQKB1R b KQkq - 0 3");

julia> pprint(b, highlight=attacksfrom(b, SQ_F1))
+---+---+---+---+---+---+---+---+
| r |   | b | q | k | b | n | r |
+---+---+---+---+---+---+---+---+
| p | p | p | p |   | p | p | p |
+---+---+---+---+---+---+---+---+
| * |   | n |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   | * |   |   | p |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | * | P | P |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   | * |   | N |   |   |
+---+---+---+---+---+---+---+---+
| P | P | P |   | * | P |*P*| P |
+---+---+---+---+---+---+---+---+
| R | N | B | Q | K | B |   | R |
+---+---+---+---+---+---+---+---+
r1bqkbnr/pppp1ppp/2n5/4p3/3PP3/5N2/PPP2PPP/RNBQKB1R b KQkq -
source
Chess.seeFunction.
see(b::Board, m::Move)::Int
see(b::Board, m::String)::Int

Static exchange evaluator.

This function estimates the material gain/loss of a move without doing any search, just looking at the attackers and defenders of the destination square, including X-ray attackers and defenders. It does not consider pins, overloaded pieces, etc., and is therefore only reliable as a very rough guess.

Examples

julia> b = fromfen("8/4k3/8/4p3/8/2BK4/8/q7 w - - 0 1")
Board (8/4k3/8/4p3/8/2BK4/8/q7 w - -):
 -  -  -  -  -  -  -  -
 -  -  -  -  k  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  p  -  -  -
 -  -  -  -  -  -  -  -
 -  -  B  K  -  -  -  -
 -  -  -  -  -  -  -  -
 q  -  -  -  -  -  -  -

julia> see(b, "Bxe5")
-2

julia> b = fromfen("7q/4k1b1/3p4/4n3/8/2BK1N2/4R3/4R3 w - - 0 1")
Board (7q/4k1b1/3p4/4n3/8/2BK1N2/4R3/4R3 w - -):
 -  -  -  -  -  -  -  q
 -  -  -  -  k  -  b  -
 -  -  -  p  -  -  -  -
 -  -  -  -  n  -  -  -
 -  -  -  -  -  -  -  -
 -  -  B  K  -  N  -  -
 -  -  -  -  R  -  -  -
 -  -  -  -  R  -  -  -

julia> see(b, "Nxe5")
1
source
Chess.lastmoveFunction.
lastmove(b::Board)

The last move that was played to reach this board position.

source
Chess.ischeckFunction.
ischeck(b::Board)

Determine whether the current side to move is in check.

source
Chess.ischeckmateMethod.
ischeckmate(b::Board)::Bool

Returns true if the side to move is checkmated.

source
Chess.isstalemateFunction.
isstalemate(b::Board)::Bool

Returns true if the board is a stalemate position.

source
Chess.ismaterialdrawFunction.
ismaterialdraw(b::Board)::Bool

Returns true if the position is a draw by material.

source
Chess.isrule50drawFunction.
isrule50draw(b::Board)::Bool

Returns true if the position is drawn by the 50 moves rule.

source
Chess.isdrawMethod.
isdraw(b::Board)::Bool

Returns true if the position is an immediate draw.

source
Chess.isterminalMethod.
isterminal(b::Board)::Bool

Returns true if the game position is terminal, i.e. mate or immediate draw.

source
Chess.pinnedFunction.
pinned(b::Board)

The set of squares containing pinned pieces for the current side to move.

Examples

julia> b = fromfen("2r4b/1kp5/8/2P1Q3/1P6/2K1P2r/8/8 w - -");

julia> pprint(b, highlight=pinned(b))
+---+---+---+---+---+---+---+---+
|   |   | r |   |   |   |   | b |
+---+---+---+---+---+---+---+---+
|   | k | p |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | P |   |*Q*|   |   |   |
+---+---+---+---+---+---+---+---+
|   | P |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   | K |   |*P*|   |   | r |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
|   |   |   |   |   |   |   |   |
+---+---+---+---+---+---+---+---+
2r4b/1kp5/8/2P1Q3/1P6/2K1P2r/8/8 w - -
source
Chess.domoveMethod.
domove(b::Board, m::Move)
domove(b::Board, m::String)

Do the move m on the board b, and return the new board.

The board b itself is left unchanged, a new board is returned. There is a much faster destructive function domove!() that should be called instead when high performance is required.

If the supplied move is a string, this function tries to parse the move as a UCI move first, then as a SAN move.

It's the caller's responsibility to make sure m is a legal move on this board.

Examples

julia> b = startboard();

julia> domove(b, "Nf3")
Board (rnbqkbnr/pppppppp/8/8/8/5N2/PPPPPPPP/RNBQKB1R b KQkq -):
 r  n  b  q  k  b  n  r
 p  p  p  p  p  p  p  p
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  N  -  -
 P  P  P  P  P  P  P  P
 R  N  B  Q  K  B  -  R
source
Chess.domove!Method.
domove!(b::Board, m::Move)
domove!(b::Board, m::String)

Destructively modify the board b by making the move m.

If the supplied move is a string, this function tries to parse the move as a UCI move first, then as a SAN move.

It's the caller's responsibility to make sure the move m is legal.

The function returns a value of type UndoInfo. You'll need this if you want to later call undomove!() to take back the move and get the original position back.

Examples

julia> b = startboard();

julia> domove!(b, "d4");

julia> b
Board (rnbqkbnr/pppppppp/8/8/3P4/8/PPP1PPPP/RNBQKBNR b KQkq -):
 r  n  b  q  k  b  n  r
 p  p  p  p  p  p  p  p
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  P  -  -  -  -
 -  -  -  -  -  -  -  -
 P  P  P  -  P  P  P  P
 R  N  B  Q  K  B  N  R
source
Chess.donullmoveMethod.
donullmove(b::Board)

Returns an identical board with the side to move switched.

The board b itself is left unchanged. A new board is returned that is identical in every way except that the side to move is the opposite. In other words, the function has the effect of "passing" and giving the other player the chance to move.

Note that this will result in an illegal position if the side to move at b is in check. It's the caller's responsibility to make sure donullmove is not used in that case.

There is a much faster destructive function donullmove! that should be called instead when high performance is required.

source
Chess.donullmove!Method.
donullmove!(b::Board)

Destructively modify the board b by swapping the side to move.

The board is left unchanged except that the side to move is changed. In other words, the function has the effect of "passing" and giving the other player the chance to move.

Note that this will result in an illegal position if the side to move at b is in check. It's the caller's responsibility to make sure donullmove is not used in that case.

The function returns a value of type UndoInfo. You'll need this if you want to later call undomove!() to take back the move and get the original position back.

source
Chess.undomove!Function.
undomove!(b::Board, u::UndoInfo)

Undo a move earlier done by domove!().

The second parameter is the UndoInfo value returned by the earlier call to domove!().

Examples

julia> b = startboard();

julia> u = domove!(b, "c4");

julia> b
Board (rnbqkbnr/pppppppp/8/8/2P5/8/PP1PPPPP/RNBQKBNR b KQkq -):
 r  n  b  q  k  b  n  r
 p  p  p  p  p  p  p  p
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  P  -  -  -  -  -
 -  -  -  -  -  -  -  -
 P  P  -  P  P  P  P  P
 R  N  B  Q  K  B  N  R

julia> undomove!(b, u);

julia> b
Board (rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -):
 r  n  b  q  k  b  n  r
 p  p  p  p  p  p  p  p
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 P  P  P  P  P  P  P  P
 R  N  B  Q  K  B  N  R
source
Chess.domovesMethod.
domoves(b::Board, moves::Vararg{Move})
domoves(b::Board, moves::Vararg{String})

Return the board achieved from a starting board b by making a sequence of moves.

The input board b is left unchanged.

If the supplied moves are strings, this function tries to parse the moves as UCI moves first, and as SAN moves if UCI move parsing fails.

It's the caller's responsibility to make sure all moves are legal. If a plain move is illegal, the consequences are undefined. If a move string cannot be parsed as an unambiguous legal move, the function throws an exception.

There is also a destructive version of this version, named domoves!

Examples

julia> b = startboard();

julia> domoves(b, "d4", "Nf6", "c4", "e6", "Nc3", "Bb4")
Board (rnbqk2r/pppp1ppp/4pn2/8/1bPP4/2N5/PP2PPPP/R1BQKBNR w KQkq -):
 r  n  b  q  k  -  -  r
 p  p  p  p  -  p  p  p
 -  -  -  -  p  n  -  -
 -  -  -  -  -  -  -  -
 -  b  P  P  -  -  -  -
 -  -  N  -  -  -  -  -
 P  P  -  -  P  P  P  P
 R  -  B  Q  K  B  N  R

julia> domoves(b, "d4", "Nf6", "c5")
ERROR: "Illegal or ambiguous move: c5"
source
Chess.domoves!Method.
domoves!(b::Board, moves::Vararg{Move})
domoves!(b::Board, moves::Vararg{String})

Destructively modify the board b by making a sequence of moves.

If the supplied moves are strings, this function tries to parse the moves as UCI moves first, and as SAN moves if UCI move parsing fails.

It's the caller's responsibility to make sure all moves are legal. If a plain move is illegal, the consequences are undefined. If a move string cannot be parsed as an unambiguous legal move, the function throws an exception.

There is also a non-destructive version of this version, named domoves.

Examples

julia> b = startboard();

julia> domoves!(b, "e4", "c5", "Nf3", "d6", "d4", "cxd4", "Nxd4", "Nf6", "Nc3");

julia> b
Board (rnbqkb1r/pp2pppp/3p1n2/8/3NP3/2N5/PPP2PPP/R1BQKB1R b KQkq -):
 r  n  b  q  k  b  -  r
 p  p  -  -  p  p  p  p
 -  -  -  p  -  n  -  -
 -  -  -  -  -  -  -  -
 -  -  -  N  P  -  -  -
 -  -  N  -  -  -  -  -
 P  P  P  -  -  P  P  P
 R  -  B  Q  K  B  -  R

julia> b = startboard();

julia> domoves!(b, "e4", "Qxe4+")
ERROR: "Illegal or ambiguous move: Qxe4+"
source
Chess.MoveListType.
MoveList

An iterable type containing a a list of moves, as produced by legal move generators.

source
Base.push!Method.
push!(list::MoveList, m::Move)

Add a new move to the move list.

source
Chess.recycle!Function.
recycle!(list::MoveList)

Recycle the move list in order to re-use for generating new moves.

This is useful when you want to avoid allocating too much heap memory. If you have a MoveList lying around that you no longer need, consider reusing it instead of creating a new one the next time you need to generate some moves.

source
Chess.movesFunction.
moves(b::Board, list::MoveList)
moves(b::Board)

Obtain a list of all legal moves from this board.

When performance is important, consider using the two-argument method that supplies a pre-allocated move list.

source
Chess.movecountFunction.
movecount(b::Board)::Int

The number of legal moves from this board.

source
Chess.haslegalmovesFunction.
haslegalmoves(b::Board)::Bool

Returns true if the side to move has at least one legal move.

source
Chess.perftFunction.
perft(b::Board, depth::Int)

Do a perft search to the given depth.

See https://www.chessprogramming.org/Perft.

source
Chess.divideFunction.
divide(b::Board, depth::Int)

Do a divide search to debug the perft() function.

See https://www.chessprogramming.org/Perft.

source
Chess.flipFunction.
flip(b::Board)

Returns an identical board, but flipped vertically, and with the opposite side to move.

Examples

julia> b = @startboard d4 Nf6 c4 e6 Nc3 Bb4 e3 OO
Board (rnbq1rk1/pppp1ppp/4pn2/8/1bPP4/2N1P3/PP3PPP/R1BQKBNR w KQ -):
 r  n  b  q  -  r  k  -
 p  p  p  p  -  p  p  p
 -  -  -  -  p  n  -  -
 -  -  -  -  -  -  -  -
 -  b  P  P  -  -  -  -
 -  -  N  -  P  -  -  -
 P  P  -  -  -  P  P  P
 R  -  B  Q  K  B  N  R

julia> flip(b)
Board (r1bqkbnr/pp3ppp/2n1p3/1Bpp4/8/4PN2/PPPP1PPP/RNBQ1RK1 b kq -):
 r  -  b  q  k  b  n  r
 p  p  -  -  -  p  p  p
 -  -  n  -  p  -  -  -
 -  B  p  p  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  P  N  -  -
 P  P  P  P  -  P  P  P
 R  N  B  Q  -  R  K  -
source
Chess.flopFunction.
flop(b::Board)

Returns an identical board, but flipped horizontally.

All castling rights will be deleted.

Examples

julia> b = @startboard d4 Nf6 c4 e6 Nc3 Bb4 e3 OO
Board (rnbq1rk1/pppp1ppp/4pn2/8/1bPP4/2N1P3/PP3PPP/R1BQKBNR w KQ -):
 r  n  b  q  -  r  k  -
 p  p  p  p  -  p  p  p
 -  -  -  -  p  n  -  -
 -  -  -  -  -  -  -  -
 -  b  P  P  -  -  -  -
 -  -  N  -  P  -  -  -
 P  P  -  -  -  P  P  P
 R  -  B  Q  K  B  N  R

julia> flop(b)
Board (1kr1qbnr/ppp1pppp/2np4/8/4PPb1/3P1N2/PPP3PP/RNBKQB1R w - -):
 -  k  r  -  q  b  n  r
 p  p  p  -  p  p  p  p
 -  -  n  p  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  P  P  b  -
 -  -  -  P  -  N  -  -
 P  P  P  -  -  -  P  P
 R  N  B  K  Q  B  -  R
source
Chess.rotateFunction.
rotate(b::Board)

Returns an identical board, but rotated 180 degrees.

All castling rights will be deleted.

Examples

julia> b = @startboard d4 Nf6 c4 e6 Nc3 Bb4 e3 OO
Board (rnbq1rk1/pppp1ppp/4pn2/8/1bPP4/2N1P3/PP3PPP/R1BQKBNR w KQ -):
 r  n  b  q  -  r  k  -
 p  p  p  p  -  p  p  p
 -  -  -  -  p  n  -  -
 -  -  -  -  -  -  -  -
 -  b  P  P  -  -  -  -
 -  -  N  -  P  -  -  -
 P  P  -  -  -  P  P  P
 R  -  B  Q  K  B  N  R

julia> rotate(b)
Board (rnbkqb1r/ppp3pp/3p1n2/4ppB1/8/2NP4/PPP1PPPP/1KR1QBNR b - -):
 r  n  b  k  q  b  -  r
 p  p  p  -  -  -  p  p
 -  -  -  p  -  n  -  -
 -  -  -  -  p  p  B  -
 -  -  -  -  -  -  -  -
 -  -  N  P  -  -  -  -
 P  P  P  -  P  P  P  P
 -  K  R  -  Q  B  N  R
source
Chess.compressFunction.
compress(b::Board)

Compresses a board into a byte array of maximum 26 bytes.

Use the inverse function decompress to recover a compressed board.

source
Chess.decompressFunction.
decompress(bytes::Vector{UInt8})

Decompresses a Board previously compressed by the compress function.

source
Chess.START_FENConstant.
START_FEN

The FEN string of the standard chess opening position.

source

Games

SimpleGame

A type representing a simple game, with no support for comments or variations.

source
SimpleGame(startboard::Board=startboard())

Constructor that creates a SimpleGame from the provided starting position.

source
Chess.SimpleGameMethod.
SimpleGame(startfen::String)

Constructor that creates a SimpleGame from the position given by the provided FEN string.

source
Chess.GameType.
Game

Type representing a chess game, with support for comments and variations.

source
Chess.GameMethod.
Game()

Constructor that creates a new Game from the regular starting position.

source
Chess.GameMethod.
Game(startboard::Board)

Constructor that creates a Game from the provided starting position.

source
Chess.GameMethod.
Game(startfen::String)

Constructor that creates a Game from the position given by the provided FEN string.

source
@simplegame

A macro for initializing a SimpleGame with a number of moves.

Castling moves must be indicated without a hyphen (i.e. "OO" or "OOO") in order to satisfy Julia's parser.

Examples

julia> @simplegame d4 Nf6 c4 e6 Nc3 Bb4 Qc2 OO
SimpleGame:
 1. d4 Nf6 2. c4 e6 3. Nc3 Bb4 4. Qc2 O-O *
source
Chess.@gameMacro.
@game

A macro for initializing a Game with a number of moves.

Castling moves must be indicated without a hyphen (i.e. "OO" or "OOO") in order to satisfy Julia's parser.

Examples

julia> @game d4 Nf6 c4 e6 Nc3 Bb4 Qc2 OO
Game:
 1. d4 Nf6 2. c4 e6 3. Nc3 Bb4 4. Qc2 O-O *
source
GameHeader

Type representing a PGN header tag.

Contains name and value slots, both of which are strings.

source
GameHeaders

Type representing the PGN header tags for a game.

Contains a slot for each the seven required PGN tags event, site, date, round, white, black and result, all of which are strings. Remaining tags are included in the othertags slot, which contains a vector of GameHeaders.

source
Chess.GameNodeType.
GameNode

Type representing a node in a Game.

Game can contain variations, so this type actually represents a node in a tree-like structure.

A GameNode is a mutable struct with the following slots:

  • parent: The parent GameNode, or nothing if this node is the root of the game.
  • board: The board position at this node.
  • children: A vector of GameNodes, the children of the current node. The first entry is the main continuation, the remaining entries are alternative variations.
  • data: A Dict{String, Any} used to store information about this node. This is used for comments and numeric annotation glyphs, but can also be used to store other data.
  • id: An Int, used to look up this node in a Game, which contains a dictionary mapping ids to GameNodes.
source
Chess.headervalueFunction.
headervalue(ghs::GameHeaders, name::String)
headervalue(g::SimpleGame, name::String)
headervalue(g::Game, name::String)

Looks up the value for the header with the given name.

Returns the value as a String, or nothing if no header with the provided name exists.

source
Chess.whiteplayerFunction.
whiteplayer(g::SimpleGame)
whiteplayer(g::Game)

The white player of the game, or nothing.

source
Chess.blackplayerFunction.
blackplayer(g::SimpleGame)
blackplayer(g::Game)

The black player of the game, or nothing.

source
Chess.siteFunction.
site(g::SimpleGame)
site(g::Game)

The site of the game, or nothing.

source
Chess.dateplayedFunction.
dateplayed(g::SimpleGame)::Union{Date, Nothing}
dateplayed(g::Game)::Union{Date, Nothing}

The date at which the game was played, or nothing.

This function makes use of the PGN date tag, trying to behave robustly with sensible defaults when the date is incomplete or incorrectly formatted. It handles both ISO format YYYY-MM-DD dates and PGN format YYYY.MM.DD dates. If either the month or the day is missing, they are replaced with 1. On failure, returns nothing.

Examples

julia> g = Game();

julia> setheadervalue!(g, "Date", "2019.09.20");

julia> dateplayed(g)
2019-09-20

julia> setheadervalue!(g, "Date", "2019.09.??");

julia> dateplayed(g)
2019-09-01

julia> setheadervalue!(g, "Date", "2019.??.??");

julia> dateplayed(g)
2019-01-01

julia> setheadervalue!(g, "Date", "*");

julia> dateplayed(g) == nothing
true
source
Chess.whiteeloFunction.
whiteelo(g::SimpeGame)
whiteelo(g::Game)

The Elo of the white player (as given by the "WhiteElo" tag), or nothing.

source
Chess.blackeloFunction.
blackelo(g::SimpeGame)
blackelo(g::Game)

The Elo of the black player (as given by the "BlackElo" tag), or nothing.

source
Chess.setheadervalue!Function.
setheadervalue!(ghs::GameHeaders, name::String, value::String)
setheadervalue!(g::SimpleGame, name::String, value::String)
setheadervalue!(g::Game, name::String, value::String)

Sets a header value, creating the header if it doesn't exist.

source
Chess.setdateplayed!Function.
setdateplayed!(g::SimpleGame, date::Date)
setdateplayed!(g::Game, date::Date)

Set the "Date" header to the given date, using the standard PGN date format.

Examples

julia> using Dates

julia> g = Game();

julia> setdateplayed!(g, Date(2020, 10, 08));

julia> headervalue(g, "Date")
"2020.10.08"

julia> dateplayed(g)
2020-10-08
source
Chess.boardFunction.
board(g::SimpleGame)
board(g::Game)

The board position at the current node in a game.

source
Chess.boardsFunction.
boards(g::Game)
boards(g::SimpleGame)

Returns a vector of all the boards along the main line of the game.

source
Chess.domove!Method.
domove!(g::SimpleGame, m::Move)
domove!(g::SimpleGame, m::String)
domove!(g::Game, m::Move)
domove!(g::Game, m::String)

Adds a new move at the current location in the game move list.

If the supplied move is a string, this function tries to parse the move as a UCI move first, then as a SAN move.

If we are at the end of the game, all previous moves are kept, and the new move is added at the end. If we are at any earlier point in the game (because we have taken back one or more moves), the existing game continuation will be deleted and replaced by the new move. All variations starting at this point in the game will also be deleted. If you want to add the new move as a variation instead, make sure you use the Game type instead of SimpleGame, and use addmove! instead of domove!.

The move m is assumed to be a legal move. It's the caller's responsibility to ensure that this is the case.

source
Chess.domoves!Method.
domoves!(g::SimpleGame, moves::Vararg{Union{Move, String}})
domoves!(g::Game, moves::Vararg{Union{Move, String}})

Adds a sequence of new moves at the current location in the game move list.

The moves can be either Move values or strings. In the case of strings, the function tries to parse them first as UCI moves, then as SAN moves.

If we are at the end of the game, all previous moves are kept, and the new moves are added at the end. If we are at any earlier point in the game (because we have taken back one or more moves), the existing game continuation will be deleted and replaced by the new moves. All variations starting at this point in the game will also be deleted. If you want to add the new moves as a variation instead, make sure you use the Game type instead of SimpleGame, and use addmoves! instead of domoves!.

source
Chess.addmove!Function.
addmove!(g::Game, m::Move)
addmove!(g::Game, m::String)

Adds the move m to the game g at the current node.

If the supplied move is a string, this function tries to parse the move as a UCI move first, then as a SAN move.

The move m must be a legal move from the current node board position. A new game node with the board position after the move has been made is added to the end of the current node's children vector, and that node becomes the current node of the game.

The move m is assumed to be a legal move. It's the caller's responsibility to ensure that this is the case.

source
Chess.addmoves!Function.
addmoves!(g::Game, moves::Vararg{Union{Move, String}})

Adds a sequence of moves to the game g at the current node.

The moves can be either Move values or strings. In the case of strings, the function tries to parse them first as UCI moves, then as SAN moves.

This function works by calling addmove! repeatedly for all input moves. It's the caller's responsibility to ensure that all moves are legal and unambiguous.

source
Chess.nextmoveFunction.
nextmove(g::SimpleGame)
nextmove(g::Game)

The next move in the game, or nothing if we're at the end of the game.

source
Chess.plyFunction.
ply(g::SimpleGame)
ply(g::Game)

The ply count of the current node.

Returns 1 for the root node, 2 for children of the root node, etc.

Examples

julia> g = Game();

julia> addmoves!(g, "d4", "Nf6", "c4", "g6", "Nc3", "Bg7");

julia> ply(g)
7

julia> back!(g);

julia> ply(g)
6

julia> tobeginning!(g);

julia> ply(g)
1
source
Chess.isatbeginningFunction.
isatbeginning(g::SimpleGame)::Bool
isatbeginning(g::Game)::Bool

Return true if we are at the beginning of the game, and false otherwise.

We can be at the beginning of the game either because we haven't yet added any moves to the game, or because we have stepped back to the beginning.

Examples

julia> g = SimpleGame();

julia> isatbeginning(g)
true

julia> domove!(g, "e4");

julia> isatbeginning(g)
false

julia> back!(g);

julia> isatbeginning(g)
true
source
Chess.isatendFunction.
isatend(g::SimpleGame)::Bool
isatend(g::Game)::Bool

Return true if we are at the end of the game, and false otherwise.

Examples

julia> g = SimpleGame();

julia> isatend(g)
true

julia> domove!(g, "Nf3");

julia> isatend(g)
true

julia> back!(g);

julia> isatend(g)
false
source
Chess.back!Function.
back!(g::SimpleGame)
back!(g::Game)

Go one step back in the game by retracting a move.

If we're already at the beginning of the game, the game is unchanged.

source
Chess.forward!Function.
forward!(g::SimpleGame)
forward!(g::Game)
forward!(g::Game, m::Move)
forward!(g::Game, m::String)

Go one step forward in the game by replaying a previously retracted move.

If we're already at the end of the game, the game is unchanged. If the current node has multiple children, we always pick the first child (i.e. the main line). If any child other than the first child is desired, supply the move leading to the child node as the second argument. It's the caller's responsibility that the move supplied leads to one of the existing child nodes.

source
Chess.tobeginning!Function.
tobeginning!(g::SimpleGame)
tobeginning!(g::Game)

Go back to the beginning of a game by taking back all moves.

If we're already at the beginning of the game, the game is unchanged.

source
Chess.toend!Function.
toend!(g::SimpleGame)
toend!(g::Game)

Go forward to the end of a game by replaying all moves, following the main line.

If we're already at the end of the game, the game is unchanged.

source
tobeginningofvariation!(g::Game)

Go to the beginning of the variation containing the current node of the game.

Steps back up the game tree until we reach the point where the first child node (i.e. the main line) is not contained in the current variation.

source
Chess.tonode!Function.
tonode!(g::Game, id::Int)

Go to the game tree node with the given node id, if it exists.

source
Chess.isleafFunction.
isleaf(n::GameNode)::Bool

Tests whether a GameNode is a leaf, i.e. that it has no children.

source
Chess.commentFunction.
comment(n::GameNode)

The comment after the move leading to this node, or nothing.

source
Chess.precommentFunction.
precomment(n::GameNode)

The comment before the move leading to this node, or nothing.

source
Chess.nagFunction.
nag(n::GameNode)

The numeric annotation glyph for the move leading to this node, or nothing.

source
Chess.addcomment!Function.
addcomment!(g::Game, comment::String)

Adds a comment to the current game node.

In PGN and other text ouput formats, the comment is printed after the move leading to the node.

source
Chess.addprecomment!Function.
addprecomment!(g::Game, comment::String)

Adds a pre-comment to the current game node.

In PGN and other text ouput formats, the comment is printed before the move leading to the node.

source
Chess.addnag!Function.
addnag!(g::Game, nag::Int)

Adds a Numeric Annotation Glyph (NAG) to the current game node.

source
removeallchildren!(g::Game, node::GameNode = g.node)

Recursively remove all children of the given node in the game.

If no node is supplied, removes the children of the current node.

source
Chess.removenode!Function.
removenode!(g::Game, node::GameNode = g.node)

Remove a node (by default, the current node) in a Game, and go to the parent node.

All children of the node are also recursively deleted.

source
Chess.adddata!Function.
adddata!(n::GameNode, key::String, value)

Add a piece of data to the given node's data dictionary.

This is a low-level function that is mainly used to add comments and NAGs, but can also be used to add any type of custom annotation data to a game node.

source
adddata!(g::Game, key::String, value)

Add a piece of data to the current game node's data dictionary.

This is a low-level function that is mainly used to add comments and NAGs, but can also be used to add any type of custom annotation data to a game node.

source
Chess.removedata!Function.
removedata!(n::GameNode, key::String)

Remove a piece of data from the game node's data dictionary.

This is a low-level function that is mainly used to delete comments and NAGs.

source
removedata!(n::GameNode, key::String)

Remove a piece of data from the current game node's data dictionary.

This is a low-level function that is mainly used to delete comments and NAGs.

source
Chess.continuationsFunction.
continuations(n::GameNode)::Vector{Move}
continuations(g::Game)::Vector{Move}

All moves at this node in the game tree.

One move for each child node of the current node. The first element is the main line.

Examples

julia> g = Game();

julia> addmoves!(g, "e4", "e5");

julia> back!(g);

julia> addmove!(g, "c5");

julia> back!(g);

julia> continuations(g)
2-element Array{Move,1}:
 Move(e7e5)
 Move(c7c5)
source
Chess.isdrawMethod.
isdraw(g::SimpleGame)
isdraw(g::Game)

Checks whether the current game position is drawn.

source
Chess.ischeckmateMethod.
ischeckmate(g::SimpleGame)
ischeckmate(g::Game)

Checks whether the current game position is a checkmate.

source
Chess.isterminalMethod.
isterminal(g::SimpleGame)
isterminal(g::Game)

Checks whether the current game position is terminal, i.e. mate or drawn.

source

Opening Books

BookEntry

A struct representing an opening book entry.

Book entries contain the following slots:

  • key: The hash key of the board position this book entry represents.
  • move: The move played, encoded as an Int32. In order to get the actual Move value representing the move stored in a book entry e, you should do Move(e.move).
  • elo: The highest Elo rating of a player who played this move.
  • oppelo: The highest Elo of the opponent in a game where this move was played.
  • wins: The number of times the player who played this move won the game.
  • draws: The number of times the player who played this move drew the game.
  • losses: The number of times the player who played this move lost the game.
  • firstyear: The year this move was first played.
  • lastyear: The year this move was last played.
  • score: The score of this move, used to obtain a probability distribution when picking a book move for a position. The score is computed based on the W/L/D stats for the move, the ratings of the players who have played it, and on its popularity in more recent games.
source
Chess.Book.createbookFunction.
createbook(pgnfiles::Vararg{String};
           scorewhitewin = 8.0,
           scorewhitedraw = 4.0,
           scorewhiteloss = 1.0,
           scoreblackwin = 8.0,
           scoreblackdraw = 5.0,
           scoreblackloss = 1.0,
           scoreunknown = 0.0,
           highelofactor = 6.0,
           yearlydecay = 0.85,
           maxply = 60,
           minelo = 0,
           maxelo = 10_000,
           maxgames = nothing,
           maxentries = nothing,
)

Creates an opening book tree from one or more PGN files.

The opening tree is stored in RAM. You will probably want to save it to disk using writebooktofile afterwards, for instance like this:

julia> bk = createbook("my-pgn-file.pgn");

julia> writebooktofile(bk, "my-book.obk")

The createbook function takes a number of optional named parameters that can be used to control what moves are included in the opening tree, and the scoring of the moves (which is used to produce move probabilities when picking a move using pickbookmove). These are:

  • scorewhitewin: The base score for all white moves in a game won by white.
  • scorewhitedraw: The base score for all white moves in a drawn game.
  • scorewhiteloss: The base score for all black moves in a game won by black.
  • scoreblackwin: The base score for all black moves in a game won by black.
  • scoreblackdraw: The base score for all black moves in a drawn game.
  • scoreblackloss: The base score for all black moves in a game won by white.
  • scoreunknown: The base score for all moves in a game with an unknown result.
  • highelofactor: Score multiplier for moves played by a player with high rating. The base score is multiplied by max(1.0, 0.01 * highelofactor * (2300 - elo))
  • yearlydecay: Controls exponential yearly reduction of scores. If a game was played n years ago, all scores are multiplied by n^yearlydecay.
  • maxply: Maximum depth of the opening tree. If maxply equals 60 (the default), no moves after move 30 are included in the opening tree.
  • minelo: Minimum Elo for book moves. Moves played by players below this number are not included in the opening tree.
  • maxelo: Maximum Elo for book moves. Moves played by players above this number are not included in the opening tree.
  • maxgames: Maximum number of games to include. If no value is supplied, all games in the input PGNs will be used.
  • maxentries: Maximum number of book entries to include. If no value is supplied, all entries will be included.
source
writebooktofile(entries::Vector{BookEntry}, filename::String,
                compact = false)

Writes a book (as created by createbookfile) to a binary file.

If the optional parameter compact is true, the book is written in a more compact format that does not include W/L/D counts, Elo numbers and years.

source
Chess.Book.purgebookFunction.
purgebook(infilename::String, outfilename::String;
          minscore = 0, mingamecount = 5, compact = false)

Creates a smaller version of an opening book file by removing unimportant lines.

Book moves with score lower than minscore or which have been played in fewer than mingamecount games are not included in the output file.

If the optional parameter compact is true, the output file is written in a more compact format that does not include W/L/D counts, Elo numbers and years.

source
findbookentries(b::Board, bookfile = nothing)
findbookentries(key::UInt64, bookfile = nothing)

Returns all book entries for the given board or key.

If bookfile is nothing, use the default built-in opening book.

The return value is a (possibly empty) Vector{BookEntry}, sorted by descending scores.

source
pickbookmove(
    b::Board;
    bookfile = nothing,
    minscore = 0,
    mingamecount = 1
)

Picks a book move for the board b, returning nothing when out of book.

If bookfile is nothing, uses the built-in default book.

The move is selected with probabilities given by the score slots in the BookEntry objects. The minscore and mingamecount parameters can be used to exclude moves with low score or low play counts.

source
printbookentries(b::Board, bookfile = nothing)

Pretty-print the book entries for the provided board.

If bookfile is nothing, use the default built-in opening book.

The output columns have the following meanings:

  • move: The move.
  • prob: Probability that this move will be played when calling pickbookmove.
  • score: Percentage score of this move in the games used to produce this book file.
  • won: Number of games won with this move.
  • drawn: Number of games drawn with this move.
  • lost: Number of games lost with this move.
  • elo: Maximum Elo of players that played this move.
  • oelo: Maximum Elo of opponents against which this move was played.
  • first: The first year this move was played.
  • last: The last year this move was played.

Examples

julia> printbookentries(@startboard d4 Nf6 c4 e6 Nc3)
move     prob   score     won   drawn    lost    elo oelo  first last
Bb4    71.92%  48.18%   32327   35691   36120   3936 3936   1854 2020
d5     20.82%  40.46%    4481    6545    8137   3796 3796   1880 2020
c5      4.20%  43.13%    1560    1192    2247   3794 3851   1922 2020
b6      2.16%  34.51%     217     170     488   2652 2762   1902 2020
Be7     0.51%  27.47%      28      33     101   2585 2640   1911 2020
c6      0.20%  36.05%      13       5      25   2448 2670   1932 2020
g6      0.12%  31.94%       9       5      22   2289 2405   1943 2020
Nc6     0.06%  33.33%       6      10      17   3809 3809   1938 2020
source

PGN Files

PGNReader

A type for reading PGN data from a stream.

source
PGNReader(io::IO)

Initializes a PGNReader from an IO object.

source
Chess.PGN.readgameFunction.
readgame(p::PGNReader; annotations=false)

Attempts to parse a PGN game and use it to create a Game or a SimpleGame.

If the optional parameter annotations is true, the return value will be a Game containing all comments, variations and numeric annotation glyphs in the PGN. Otherwise, it will be a SimpleGame with only the game moves.

This function assumes that the PGNReader is pointed at the beginning of a game. If you are not sure this is the case, call gotonextgame! on the PGNReader first.

If parsing fails or the notation contains illegal or ambiguous moves, the function raises a PGNException.

source
gamefromstring(s::String; annotations=false)

Attempts to create a Game or SimpleGame object from the provided PGN string.

If the optional parameter annotations is true, the return value will be a Game containing all comments, variations and numeric annotation glyphs in the PGN. Otherwise, it will be a SimpleGame with only the game moves.

If the string does not parse as valid PGN, or if the notation contains illegal or ambiguous moves, the function raises a PGNException

source
Chess.PGN.gametopgnFunction.
gametopgn(g)::String

Exports a Game or a SimpleGame to a PGN string.

Limitations

  • The movetext section is written in a single long line, with no line breaks.
source
Chess.PGN.gamesinfileFunction.
gamesinfile(filename::String; annotations=false, skip=0)

Creates a Channel of Game/SimpleGame objects read from the PGN file with the provided file name.

If the optional parameter annotations is true, the return value will be a channel of Game objects containing all comments, variations and numeric annotation glyphs in the PGN. Otherwise, it will consist of SimpleGame objects with only the game moves.

The optional parameter skip makes the function skip the first skip games of the file.

source
gotonextgame!(p::PGNReader)::Bool

Tries to go to the next game, returns true on success.

source

UCI Chess Engines

Engine

Type representing a UCI chess engine.

This is a struct with the following slots:

  • name: The engine name, as provided by the engine in response to the uci command.
  • author: The engine author name, as provided by the engine in response to the uci command.
  • options: The UCI options for this engine. This is a dictionary mapping option names (Strings) to options (instances of the Option type).
  • io: A Base.Process object used to communicate with the engine.

Engines are created by calling the runengine function, which takes a pathname for an UCI engine as input, runs the engine, and returns an Engine object.

Examples

The below is a typical interaction with a UCI engine. The example assumes that you have a UCI engine with the file name stockfish somewhere in your PATH.

julia> sf = runengine("stockfish");

julia> setoption(sf, "Hash", 128)

julia> setboard(sf, fromfen("1kbr3r/pp6/8/P1n2ppq/2N3n1/R3Q1P1/3B1P2/2R2BK1 w - -"))

julia> search(sf, "go depth 18", infoaction=println)
info depth 1 seldepth 1 multipv 1 score cp -842 nodes 88 nps 88000 tbhits 0 time 1 pv f1g2 g4e3 d2e3
info depth 2 seldepth 2 multipv 1 score cp -842 nodes 207 nps 103500 tbhits 0 time 2 pv f1g2 g4e3
info depth 3 seldepth 3 multipv 1 score cp -844 nodes 270 nps 135000 tbhits 0 time 2 pv f1g2 g4e3 d2e3 d8d1 c1d1 h5d1 g2f1
info depth 4 seldepth 5 multipv 1 score cp -844 nodes 367 nps 183500 tbhits 0 time 2 pv f1g2 g4e3 d2e3 d8d1 c1d1
info depth 5 seldepth 7 multipv 1 score cp -953 nodes 866 nps 433000 tbhits 0 time 2 pv f1g2 h5h2 g1f1 g4e3 d2e3 c5d3 e3g5
info depth 6 seldepth 8 multipv 1 score cp -1060 nodes 1507 nps 753500 tbhits 0 time 2 pv f1g2 g4e3 d2e3 c5d3 e3d2 d3c1
info depth 7 seldepth 11 multipv 1 score cp -876 nodes 1995 nps 665000 tbhits 0 time 3 pv f1g2 g4e3
info depth 8 seldepth 10 multipv 1 score cp -882 nodes 2771 nps 923666 tbhits 0 time 3 pv f1g2 g4e3 d2e3 c8e6 e3c5 d8d1 c1d1 h5d1 g2f1 e6c4
info depth 9 seldepth 15 multipv 1 score cp -1068 nodes 12059 nps 1339888 tbhits 0 time 9 pv f1g2 g4e3 a3e3 c8e6 e3e6 c5e6 d2e1 d8d1 c1d1 h5d1
info depth 10 seldepth 15 multipv 1 score cp -1050 nodes 17558 nps 1463166 tbhits 0 time 12 pv f1g2 g4e3 a3e3 c8e6 g1f1 h5g4 e3e6 c5e6 c4e3 g4a4 d2c3
info depth 11 seldepth 17 multipv 1 score cp -1013 nodes 23543 nps 1569533 tbhits 0 time 15 pv f1g2 g4e3 a3e3 c8e6 g1f1 h5g4 e3e6 c5e6 c4e3 g4a4 d2c3
info depth 12 seldepth 20 multipv 1 score cp -995 nodes 48497 nps 1672310 tbhits 0 time 29 pv f1g2 g4e3 a3e3 c8e6 g1f1 c5e4 d2e1 d8c8 g3g4 h5g4 c4e5 g4h4 c1c8 h8c8
info depth 13 seldepth 29 multipv 1 score cp -1116 nodes 205726 nps 1959295 tbhits 0 time 105 pv f1g2 g4e3 f2e3 c5e4 a3a2 h5h2 g1f1 e4g3 f1f2 g3e4 f2f1 e4d2 c4d2 h2g3 d2f3 d8d3 f1g1 d3e3 f3d4 e3e8 a2e2
info depth 14 seldepth 28 multipv 1 score cp -148 nodes 247247 nps 1993927 tbhits 0 time 124 pv e3f4 g5f4 d2f4 b8a8 c4b6 a7b6 a5b6 c5a6
info depth 15 seldepth 16 multipv 1 score cp 120 nodes 248911 nps 1991288 tbhits 0 time 125 pv e3f4 g5f4 d2f4 g4e5 f4e5 d8d6 e5d6 b8a8 f1g2 c8e6 d6c5
info depth 16 seldepth 24 multipv 1 score cp 1117 nodes 251829 nps 1982905 tbhits 0 time 127 pv e3f4 g4e5 f4e5 d8d6 e5d6 b8a8 f1g2 h5h2 g1f1 c5e4 g2e4 f5e4 d2g5 c8h3 f1e2
info depth 17 seldepth 22 multipv 1 score cp 1500 nodes 258707 nps 1990053 tbhits 0 time 130 pv e3f4 g4e5 f4e5 d8d6 e5d6 b8a8 f1g2 h5h2 g1f1 c5e4 g2e4 h2h3 e4g2
info depth 18 seldepth 22 multipv 1 score mate 11 nodes 281736 nps 1984056 tbhits 0 time 142 pv e3f4 g5f4 d2f4 g4e5 f4e5 d8d6 e5d6 b8a8 c4b6 a7b6 a5b6 c5a6 c1c8 h8c8
BestMoveInfo (best=e3f4, ponder=g5f4)
source
Chess.UCI.runengineFunction.
function runengine(path::String)::Engine

Runs the engine at the specified path, returning an Engine.

source
Chess.UCI.newgameFunction.
newgame(e::Engine)

Instructs the engine that a new game is about to begin.

source
Chess.UCI.quitFunction.
function quit(e::Engine)

Sends the UCI engine e the "quit" command.

source
Chess.UCI.setoptionFunction.
function setoption(e::Engine, name::String, value::OptionValue = nothing)

Sets the UCI option named name to the new value value.

Throws an error if the engine e does not have an option with the provided name, or if the value is incompatible with the type of the option.

source
Chess.UCI.sendisreadyFunction.
sendisready(e::Engine)::Bool

Sends the engine e an "isready" command and waits for the "readyok" response.

Returns true on success, false on failure (i.e. if the engine replies with anything other than "readyok").

source
Chess.UCI.sendcommandFunction.
sendcommand(e::Engine, cmd::String)

Sends the UCI command cmd to the engine e.

source
Chess.UCI.setboardFunction.
setboard(e::Engine, b::Board)
setboard(e::Engine, g::SimpleGame)
setboard(e::Engine, g::Game)

Set the engine's current board position to the given board/game state.

source
Chess.UCI.searchFunction.
function search(e::Engine, gocmd::String; infoaction = nothing)

Tells a UCI engine to start searching.

The parameter gocmd is the actual command you want to send to the engine; e.g. "go movetime 10000" or "go infinite". The named parameter infoaction is a function accepting the output of the engine's "info" commands and doing something with the output. Usually, it will be some function making internal use of parsesearchinfo().

The return value is of type BestMoveInfo.

source
Chess.UCI.mpvsearchFunction.
mpvsearch(game, engine; nodes, depth, pvs)::Vector{SearchInfo}

Performs a multi-PV search and returns the result as a vector of SearchInfo.

Parameters:

  • game: A Game, a SimpleGame or a Board.
  • engine: An Engine.
  • nodes: A named parameter instructing the engine to search to the desired tree size.
  • depth: A named parameter instructing the engine to search to the given depth.
  • pvs: The number of desired lines. Analysis for the pvs best moves is returned. If pvs is greater than the number of legal moves, analysis for all legal moves is returned.

At least one of nodes and depth must be supplied. If both are supplied, the function will use depth and ignore nodes.

The function returns a vector of SearchInfo values, one for each of the pvs best moves.

source
BestMoveInfo

A struct representing the contents of a UCI engine's bestmove output.

Contains the following slots:

  • bestmove: The Move returned by the engine as the best move.
  • ponder: The engine's expected reply to the best move, a Move or nothing.
source
parsebestmove(line::String)::BestMoveInfo

Parses a bestmove line printed by a UCI engine to a BestMoveInfo object.

source
SearchInfo

A struct representing the contents of a UCI engine's info output.

Contains the following slots, all of which can be nothing for a given line of search output:

  • depth: The current search depth.
  • seldepth: The current selective search depth.
  • time: The time spent searching so far, in milliseconds.
  • nodes: The number of nodes searched so far.
  • pv: The main line, as a vector of Move values.
  • multipv: The multipv index of the line currently printed.
  • score: The score, a value of type Score.
  • currmove: The move currently searched, a value of type Move.
  • currmovenumber: The index of the move currently searched in the move list.
  • hashfull: A number in the range 0–100, indicating the transposition table saturation percentage.
  • nps: Nodes/second count.
  • tbhits: Number of tablebase hits.
  • cpuload: CPU load percentage.
  • string: An arbitrary string sent by the engine.
source
parsesearchinfo(line::String)::SearchInfo

Parses an info line printed by a UCI engine to a SearchInfo object.

See the documentation for SearchInfo for information about how to inspect and use the return value.

source
Chess.UCI.touciFunction.
touci(b::Board)
touci(g::SimpleGame)
touci(g::Game)

Create a UCI string representation of a board or a game.

Examples

julia> touci(startboard())
"position fen rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq -"

julia> sg = SimpleGame(); domove!(sg, "e4"); domove!(sg, "c5"); domove!(sg, "Nf3");

julia> touci(sg)
"position fen rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - moves e2e4 c7c5 g1f3"

julia> g = Game(); domove!(g, "d4"); domove!(g, "Nf6"); domove!(g, "c4");

julia> touci(g)
"position fen rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - moves d2d4 g8f6 c2c4"
source
Chess.UCI.ScoreType.
Score

A struct type representing a score returned by a UCI engine.

The struct has the following slots:

  • value: An Int representing the score value.
  • ismate: A Bool that tells whether this is a mate score.
  • bound: A BoundType, indicating whether this score is a lower bound, an upper bound, or an exact value.
source
BoundType

An enum type representing the score bound types lower, upper and exact.

source
Option

Type representing a UCI option. This is a mutable struct with the following slots:

  • name: A String, the name of the option, as provided by the engine.
  • type: An OptionType, the type of the option, as provided by the engine.
  • defaultValue: An OptionValue, as provided by the engine.
  • value: An OptionValue, the current value of the option.
  • min: The minimum value of this option. Only used for options of type spin.
  • max: The maximum value of this option. Only used for options of type spin.
  • combovals: Vector of the possible values for this option. Only used for options of type Combo.
source
OptionType

Type representing an UCI option type. This is an enum with values corresponding to the option types defined in the UCI protocol: check, spin, combo, button and string.

source
Chess.UCI.OptionValueConstant.
OptionValue

Type representing the value of a UCI option. This is a union type containing the types Nothing (for options of type button), Bool (for options of type check, Int (for options of type spin) and String (for options of type combo or string).)

source

Pieces, Piece Types and Piece Colors

Chess.PieceType.
Piece

Type representing a chess piece.

The possible values are PIECE_WP, PIECE_WN, PIECE_WB, PIECE_WR, PIECE_WQ, PIECE_WK, PIECE_BP, PIECE_BN, PIECE_BB, PIECE_BR, PIECE_BQ, PIECE_BK and EMPTY. The reason for the existence of the value EMPTY is that we represent a chess board as an array of pieces, and we need a value to indicate an empty square on the board.

source
Chess.PieceMethod.
Piece(c::PieceColor, t::PieceType)

Construct a piece with the given color and type.

Examples

julia> Piece(BLACK, QUEEN)
PIECE_BQ
source
PieceColor

Type representing the color of a chess piece.

The possible values are WHITE, BLACK and COLOR_NONE. The reason for the existence of the value COLOR_NONE is that we represent a chess board as an array of pieces, and we need a special Piece value EMPTY to indicate an empty square on the board. The color of the EMPTY piece is COLOR_NONE.

source
Chess.PieceTypeType.
PieceType

Type representing the type of a chess piece.

This is essentially a piece without color. The possible values are PAWN, KNIGHT, BISHOP, ROOK, QUEEN, KING and PIECE_TYPE_NONE. The reason for the existence of the value PIECE_TYPE_NONE is that we represent a chess board as an array of pieces, and we need a special Piece value EMPTY to indicate an empty square on the board. The type of the EMPTY piece is PIECE_TYPE_NONE

source
Chess.pcolorFunction.
pcolor(p::Piece)

Find the color of a Piece.

Examples

julia> pcolor(PIECE_WB)
WHITE

julia> pcolor(EMPTY)
COLOR_NONE
source
Chess.ptypeFunction.
ptype(p::Piece)

Find the type of a Piece.

Examples

julia> ptype(PIECE_BQ)
QUEEN

julia> ptype(EMPTY)
PIECE_TYPE_NONE
source
Chess.coloroppFunction.
coloropp(c::PieceColor)

Returns the opposite of a color.

Examples

julia> coloropp(WHITE) == BLACK
true

julia> coloropp(BLACK) == WHITE
true
source
Chess.issliderFunction.
isslider(t::PieceType)
isslider(p::Piece)

Determine whether a piece is a sliding piece.

source
Chess.colorfromcharFunction.
colorfromchar(c::Char)

Tries to convert a character to a PieceColor.

The return value is a Union{PieceColor, Nothing}. If the input character is one of the four characters 'w', 'b', 'W', 'B', the function returns the obvious corresponding color (WHITE or BLACK). For all other input characters, the function returns nothing.

Examples

julia> colorfromchar('w') == WHITE
true

julia> colorfromchar('B') == BLACK
true

julia> colorfromchar('x') == nothing
true
source
piecetypefromchar(c::Chars)

Tries to convert a character to a PieceType.

The return value is a Union{PieceType, Nothing}. If the input character is a valid upper- or lowercase English piece letter (PNBRQK), the function returns the corresponding piece type. For all other input characters, the function returns nothing.

Examples

julia> piecetypefromchar('n') == KNIGHT
true

julia> piecetypefromchar('B') == BISHOP
true

julia> piecetypefromchar('a') == nothing
true
source
Chess.piecefromcharFunction.
piecefromchar(ch::Char)

Tries to convert a character to a Piece.

The return value is a Union{Piece, Nothing}. If the input character is a valid English piece letter, the corresponding piece is returned. If the piece letter is uppercase, the piece is white. If the piece letter is lowercase, the piece is black.

If the input value is not a valid English piece letter, the function returns nothing.

Examples

julia> piecefromchar('Q')
PIECE_WQ

julia> piecefromchar('n')
PIECE_BN

julia> piecefromchar('-') == nothing
true
source
Chess.tocharMethod.
tochar(c::PieceColor)

Converts a color to a character.

Examples

julia> tochar(WHITE)
'w': ASCII/Unicode U+0077 (category Ll: Letter, lowercase)

julia> tochar(BLACK)
'b': ASCII/Unicode U+0062 (category Ll: Letter, lowercase)

julia> tochar(COLOR_NONE)
'?': ASCII/Unicode U+003f (category Po: Punctuation, other)
source
Chess.tocharFunction.
tochar(t::PieceType, uppercase = false)

Converts a PieceType value to a character.

A valid piece type value is converted to its standard English algebraic notation piece letter. Any invalid piece type value is converted to a '?' character. The optional parameter uppercase controls whether the character is an upper- or lower-case letter.

Examples

julia> tochar(PAWN)
'p': ASCII/Unicode U+0070 (category Ll: Letter, lowercase)

julia> tochar(ROOK, true)
'R': ASCII/Unicode U+0052 (category Lu: Letter, uppercase)

julia> tochar(PIECE_TYPE_NONE)
'?': ASCII/Unicode U+003f (category Po: Punctuation, other)
source
Chess.tocharMethod.
tochar(p::Piece)

Converts a piece to a character.

Examples

julia> tochar(PIECE_WN)
'N': ASCII/Unicode U+004e (category Lu: Letter, uppercase)

julia> tochar(PIECE_BK)
'k': ASCII/Unicode U+006b (category Ll: Letter, lowercase)

julia> tochar(EMPTY)
'?': ASCII/Unicode U+003f (category Po: Punctuation, other)
source

Squares

Chess.SquareType.
Square

Type representing a square on a chess board.

A Square can be constructed either with an Int (with the convention a8=1, a7=2, ..., a1=8, b8=9, b7=10, ..., h1=64) or with a SquareFile and a SquareRank. There are also constants SQ_A1, ..., SQ_H8 for all 64 squares on the board.

Examples

julia> Square(FILE_G, RANK_6)
SQ_G6

julia> Square(8)
SQ_A1
source
Chess.SquareMethod.
Square(f::SquareFile, r::SquareRank)

Construct a square with the given file and rank.

Examples

julia> Square(FILE_D, RANK_5)
SQ_D5
source
SquareFile

Type representing the file of a square on a chess board.

Usually, a SquareFile is obtained either by calling the function file() on a Square or through one of the constants FILE_A, FILE_B, ..., FILE_H.

source
SquareRank

Type representing the rank of a square on a chess board.

Usually, a SquareRank is obtained either by calling the function rank() on a Square or through one of the constants RANK_1, RANK_2, ..., RANK_8.

source
SquareDelta

A type representing the delta or vector between two squares.

A SquareDelta value is usually obtained either through one of the constants DELTA_N, DELTA_S, DELTA_E, DELTA_W, DELTA_NW, DELTA_NE, DELTA_SW, DELTA_SE, or by subtracting two square values.

It is possible to add or subtract two SquareDeltas, to multiply a SquareDelta by an integer scalar, or to add or subtract a SquareDelta to a Square.

Examples

julia> DELTA_N + DELTA_W == DELTA_NW
true

julia> SQ_D3 - SQ_C3 == DELTA_E
true

julia> SQ_G8 - 3 * DELTA_N
SQ_G5
source
Chess.fileFunction.
file(s::Square)

Compute the file of the square s.

Examples

julia> file(SQ_C4)
FILE_C
source
Chess.rankFunction.
rank(s::Square)

Compute the rank of the square s.

Examples

julia> rank(SQ_C4)
RANK_4
source
Chess.distanceMethod.
distance(s1::Square, s2::Square)

The distance between two squares, counted by number of king moves.

source
Chess.distanceMethod.
distance(f1::SquareFile, f2::SquareFile)

The horizontal distance between two files.

source
Chess.distanceMethod.
distance(r1::SquareRank, r2::SquareRank)

The vertical distance between two ranks.

source
Chess.filefromcharFunction.
filefromchar(c::Char)

Tries to convert a character to a file.

The return value is a Union{SquareFile, Nothing}. The nothing is returned in case the character does not represent a valid file.

Examples

julia> filefromchar('c')
FILE_C

julia> filefromchar('2') == nothing
true
source
Chess.rankfromcharFunction.
rankfromchar(c::Char)

Tries to convert a character to a rank.

The return value is a Union{SquareRank, Nothing}. The nothing is returned in case the character does not represent a valid rank.

Examples

julia> rankfromchar('2')
RANK_2

julia> rankfromchar('x') == nothing
true
source
Chess.tocharMethod.
tochar(f::SquareFile)

Converts a SquareFile to a character.

Examples

julia> tochar(FILE_E)
'e': ASCII/Unicode U+0065 (category Ll: Letter, lowercase)
source
Chess.tocharMethod.
tochar(r::SquareRank)

Converts SquareRank to a character.

Examples

julia> tochar(RANK_3)
'3': ASCII/Unicode U+0033 (category Nd: Number, decimal digit)
source
squarefromstring(s::String)

Tries to convert a string to a Square.

The return value is of type Union{Square, Nothing}.

If the input string is too short, or if the two first characters do not represent a square in standard algebraic notation, returns nothing. If the first two characters do represent avalid square, that square is returned, even if there are additional characters.

Examples

julia> squarefromstring("d6")
SQ_D6

julia> squarefromstring("xy") == nothing
true

julia> squarefromstring("") == nothing
true

julia> squarefromstring("g1f3")
SQ_G1
source
Chess.tostringMethod.
tostring(s::Square)

Converts a square to a string in standard algebraic notation. If the square has an invalid value, the returned string is "??".

Examples

julia> tostring(SQ_E4)
"e4"

julia> tostring(Square(100))
"??"
source

Moves

Chess.MoveType.
Move

Type representing a chess move.

A Move value is usually obtained by asking a chess board for moves, or by parsing a move string in UCI or SAN format (in the latter case, we also need a board).

source
Chess.MoveMethod.
Move(from::Square, to::Square)

Low-level constructor for creating a move with the given from and to squares.

source
Chess.MoveMethod.
Move(from::Square, to::Square, promotion::PieceType)

Low-level constructor for creating a move with the given from and to squares and promotion piece type.

source
Chess.fromMethod.
from(m::Move)

The source square of a move.

Examples

julia> Move(SQ_D2, SQ_D4)
Move(d2d4)

julia> from(Move(SQ_G1, SQ_F3))
SQ_G1

julia> from(Move(SQ_C7, SQ_C8, QUEEN))
SQ_C7
source
Chess.toMethod.
to(m::Move)

The destination square of a move.

Examples

julia> to(Move(SQ_G1, SQ_F3))
SQ_F3

julia> to(Move(SQ_C7, SQ_C8, QUEEN))
SQ_C8
true
source
Chess.ispromotionMethod.
ispromotion(m::Move)

Determine whether a move is a promotion move.

Examples

julia> ispromotion(Move(SQ_G1, SQ_F3))
false

julia> ispromotion(Move(SQ_C7, SQ_C8, QUEEN))
true
source
Chess.promotionMethod.
promotion(m::Move)

Find the promotion piece type of a move.

Use this function only after first using ispromotion to determine whether the move is a promotion move at all.

Examples

julia> promotion(Move(SQ_C7, SQ_C8, QUEEN))
QUEEN

julia> promotion(Move(SQ_B2, SQ_B1, KNIGHT))
KNIGHT
source
Chess.tostringMethod.
tostring(m::Move)

Convert a move to a string in UCI notation.

Examples

julia> tostring(Move(SQ_G1, SQ_F3))
"g1f3"

julia> tostring(Move(SQ_E2, SQ_E1, KNIGHT))
"e2e1n"
source
movefromstring(s::String)

Convert a UCI move string to a move.

Returns nothing if the input string is not a valid UCI move.

Examples

julia> movefromstring("d2d4") == Move(SQ_D2, SQ_D4)
true

julia> movefromstring("h7h8q") == Move(SQ_H7, SQ_H8, QUEEN)
true

julia> movefromstring("f7f9") == nothing
true

julia> movefromstring("") == nothing
true
source
Chess.movefromsanFunction.
movefromsan((b::Board, san::String))::Union{Move, Nothing}

Tries to read a move in Short Algebraic Notation.

Returns nothing if the provided string is an impossible or ambiguous move.

Examples

julia> movefromsan(b, "Nf3")
Move(g1f3)

julia> movefromsan(b, "???") == nothing
true
source
Chess.movetosanFunction.
function movetosan(b::Board, m::Move)

Converts a move to a string in short algebraic notation.

Examples

julia> b = startboard();

julia> movetosan(b, Move(SQ_D2, SQ_D4))
"d4"
source
variationtosan(board::Board, v::Vector{Move};
               startply=1, movenumbers=true)::String

Converts a variation to a string in short algebraic notation.

The vector of moves v should be a sequence of legal moves from the board position. If movenumbers is true, move numbers will be included in the string. The moves are numbered from 1, unless some other variable is supplied through the startply parameter.

Examples

julia> b = startboard();

julia> variationtosan(b, map(movefromstring, ["e2e4", "e7e5", "g1f3", "b8c6"]))
"1. e4 e5 2. Nf3 Nc6"
source
variationtosan(g::SimpleGame, v::Vector{Move}; movenumbers=true)::String
variationtosan(g::Game, v::Vector{Move}; movenumbers=true)::String

Converts a variation to a string in short algebraic notation.

The vector of moves v should be a sequence of legal moves from the current board position of the game. If movenumbers is true, move numbers will be included in the string.

Examples

julia> g = Game();

julia> domoves!(g, "d4", "Nf6", "c4", "e6", "Nf3");

julia> variationtosan(g, map(movefromstring, ["f8b4", "c1d2", "d8e7"]))
"3... Bb4+ 4. Bd2 Qe7"
source

Square Sets

Chess.SquareSetType.
SquareSet

A type representing a set of squares on the chess board.

The most common ways of obtaining a square set are:

  • Initializing it with one or more squares, for instance SquareSet(SQ_D4, SQ_E4, SQ_D5, SQ_E5).

  • From one of the predefined square set constants, like SS_FILE_C (the squares on the C file) or SS_RANK_7 (the squares on the 7th rank).

  • By extracting it from a chess board. See the Board type for details about this.

  • By performing operations transforming or combining one or more square sets to a new square set.

The union or intersection of two sets can be computed by the functions union and intersect, or by the corresponding binary operators and . The complement of a square set is denoted by the unary - operator. The difference between two set is obtained by the setdiff function or by the binary - operator. Subset relationships can be tested by the issubset function or the binary operator .

To add or remove a square to a square set, use the + or - operators with the square set as the left operand and the square as the right operand. To test whether a square set contains a square, use s in ss or s ∈ ss.

source
Base.isemptyFunction.
isempty(ss::SquareSet)

Determine whether a square set is the empty set.

Examples

julia> isempty(SS_RANK_1)
false

julia> isempty(SS_EMPTY)
true

julia> isempty(SS_RANK_1 ∩ SS_RANK_2)
true
source
Base.inFunction.
in(s::Square, ss::SquareSet)
∈(s::Square, ss::SquareSet)

Determine whether a square is a member of a square set.

Examples

julia> SQ_D7 ∈ SS_RANK_8
false

julia> SQ_D8 ∈ SS_RANK_8
true
source
Chess.squaresFunction.
squares(ss::SquareSet)

Convert a square set to a vector of squares.

Examples

julia> tostring.(squares(SS_RANK_1))
8-element Array{String,1}:
 "a1"
 "b1"
 "c1"
 "d1"
 "e1"
 "f1"
 "g1"
 "h1"
source
Base.unionFunction.
union(ss1::SquareSet, ss2::SquareSet)
∪(ss1::SquareSet, ss2::SquareSet)

Compute the union of two square sets.

The binary operator can be used instead of the named function.

Examples

julia> SS_FILE_C ∪ SS_RANK_3
SquareSet:
 -  -  #  -  -  -  -  -
 -  -  #  -  -  -  -  -
 -  -  #  -  -  -  -  -
 -  -  #  -  -  -  -  -
 -  -  #  -  -  -  -  -
 #  #  #  #  #  #  #  #
 -  -  #  -  -  -  -  -
 -  -  #  -  -  -  -  -
source
Base.intersectFunction.
intersect(ss1::SquareSet, ss2::SquareSet)
∩(ss1::SquareSet, ss2::SquareSet)

Compute the intersection of two square sets.

The binary operator can be used instead of the named function.

Examples

julia> SS_FILE_D ∩ SS_RANK_7
SquareSet:
 -  -  -  -  -  -  -  -
 -  -  -  #  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
source
Base.:-Function.
-(c::PieceColor)

Returns the opposite of a color. Synonymous to coloropp.

Examples

julia> -WHITE
BLACK

julia> -BLACK
WHITE
source
-(ss::SquareSet)

The complement of a square set.

Examples

julia> ss = SquareSet(SQ_C4);

julia> SQ_C4 ∈ ss
true

julia> SQ_D4 ∈ ss
false

julia> SQ_C4 ∈ -ss
false

julia> SQ_D4 ∈ -ss
true
source
setdiff(ss1::SquareSet, ss2::SquareSet)
-(ss1::SquareSet, ss2::SquareSet)

The set of all squares that are in ss1, but not in ss2.

Examples

julia> SquareSet(SQ_A1, SQ_A2, SQ_A3, SQ_B1, SQ_B2, SQ_B3) - SS_RANK_2
SquareSet:
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 #  #  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 #  #  -  -  -  -  -  -
source
-(ss::SquareSet, s::Square)

Remove a square from a square set.

If a non-member square is removed, the set is returned unchanged.

Examples

julia> SquareSet(SQ_A1, SQ_B1) - SQ_B1 == SquareSet(SQ_A1)
true

julia> SS_FILE_A - SQ_H8 == SS_FILE_A
true
source
Base.:+Function.
+(ss::SquareSet, s::Square)

Add a square to a square set.

If a square is added that is already a member is added to the set, the set is returned unchanged.

Examples

julia> SquareSet(SQ_A1) + SQ_H8 == SquareSet(SQ_A1, SQ_H8)
true

julia> SS_FILE_A + SQ_A1 == SS_FILE_A
true
source
Base.issubsetFunction.
issubset(ss1::SquareSet, ss2::SquareSet)
⊆(ss1::SquareSet, ss2::SquareSet)

Determine whether ss1 is a subset of ss2.

Examples

julia> SquareSet(SQ_A1, SQ_A2) ⊆ SS_FILE_A
true

julia> SquareSet(SQ_A1, SQ_B1) ⊆ SS_FILE_A
false
source
Chess.toarrayFunction.
toarray(ss::SquareSet, T::Type{<:Number}=Float32)

Convert a square set to a two-dimensional array of the specified element type.

The returned array's columns corresponds to the files, and the rows to the ranks. The array entries are 1 for the members of the square set, and 0 for non-members.

Examples

julia> toarray(SS_FILE_C ∪ SS_RANK_5, Int)
8×8 Array{Int64,2}:
 0  0  1  0  0  0  0  0
 0  0  1  0  0  0  0  0
 0  0  1  0  0  0  0  0
 1  1  1  1  1  1  1  1
 0  0  1  0  0  0  0  0
 0  0  1  0  0  0  0  0
 0  0  1  0  0  0  0  0
 0  0  1  0  0  0  0  0
source
Chess.squarecountFunction.
squarecount(ss::SquareSet)

The number of members of a square set.

source
Base.firstFunction.
first(ss::SquareSet)

The first square in a square set.

Returns SQ_NONE for an empty square set.

source
Chess.removefirstFunction.
removefirst(ss::SquareSet)

Remove the first member of a square set.

Examples

julia> removefirst(SquareSet(SQ_A4, SQ_D5, SQ_F6)) == SquareSet(SQ_D5, SQ_F6)
true
source
Chess.issingletonFunction.
issingleton(ss::SquareSet)

Determine whether ss contains exactly one square.

Examples

julia> issingleton(SquareSet(SQ_D5))
true

julia> issingleton(SquareSet(SQ_D5, SQ_C5))
false

julia> issingleton(SS_EMPTY)
false
source
Chess.onlyfirstFunction.
onlyfirst(ss::SquareSet)

Return a square set with all squares except the first removed.

Examples

julia> onlyfirst(SquareSet(SQ_A4, SQ_D5, SQ_F6)) == SquareSet(SQ_A4)
true
source
Chess.shift_nFunction.
shift_n(ss::SquareSet)

Shift the square set one step in the 'north' direction.

Squares that are shifted off the edge of the board disappear.

julia> shift_n(SS_RANK_2) == SS_RANK_3
true

julia> shift_n(SquareSet(SQ_D3, SQ_E4, SQ_F8)) == SquareSet(SQ_D4, SQ_E5)
true
source
Chess.shift_sFunction.
shift_s(ss::SquareSet)

Shift the square set one step in the 'south' direction.

Squares that are shifted off the edge of the board disappear.

Examples

julia> shift_s(SS_RANK_3) == SS_RANK_2
true

julia> shift_s(SquareSet(SQ_C3, SQ_D2, SQ_E1)) == SquareSet(SQ_C2, SQ_D1)
true
source
Chess.shift_eFunction.
shift_e(ss::SquareSet)

Shift the square set one step in the 'east' direction.

Squares that are shifted off the edge of the board disappear.

Examples

julia> shift_e(SS_FILE_F) == SS_FILE_G
true

julia> shift_e(SquareSet(SQ_F5, SQ_G6, SQ_H7)) == SquareSet(SQ_G5, SQ_H6)
true
source
Chess.shift_wFunction.
shift_w(ss::SquareSet)

Shift the square set one step in the 'west' direction.

Squares that are shifted off the edge of the board disappear.

julia> shift_w(SS_FILE_C) == SS_FILE_B
true

julia> shift_w(SquareSet(SQ_C5, SQ_B6, SQ_A7)) == SquareSet(SQ_B5, SQ_A6)
true
source
Chess.pawnshift_nFunction.
pawnshift_n(ss::SquareSet)

Shift a square set of pawns one step in the 'north' direction.

This is identical to the shift_n function except that pawnshift_n is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnshift_sFunction.
pawnshift_s(ss::SquareSet)

Shift a square set of pawns one step in the 'south' direction.

This is identical to the shift_s function except that pawnshift_s is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnshift_nwFunction.
pawnshift_nw(ss::SquareSet)

Shift a square set of pawns one step in the 'north west' direction.

This is identical to calling shift_n followed by shift_w, except that pawnshift_nw is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnshift_neFunction.
pawnshift_ne(ss::SquareSet)

Shift a square set of pawns one step in the 'north east' direction.

This is identical to calling shift_n followed by shift_e, except that pawnshift_ne is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnshift_swFunction.
pawnshift_sw(ss::SquareSet)

Shift a square set of pawns one step in the 'south west' direction.

This is identical to calling shift_s followed by shift_w, except that pawnshift_sw is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnshift_seFunction.
pawnshift_se(ss::SquareSet)

Shift a square set of pawns one step in the 'south east' direction.

This is identical to calling shift_s followed by shift_e, except that pawnshift_se is a little faster, but will not work for square sets containing squares on the 1st or 8th rank.

source
Chess.pawnattacksFunction.
pawnttacks(c::PieceColor, s::square)

the set of squares attacked by a pawn of color c on the square s.

source
Chess.knightattacksFunction.
knightattacks(s::Square)

The set of squares attacked by a knight on the square s.

source
bishopattacks(blockers::SquareSet, s::Square)

The squares attacked by a bishop on s, with blockers being the occupied squares.

source
bishopattacksempty(s::Square)

The set of squares a bishop on s would attack on an otherwise empty board.

source
Chess.rookattacksMethod.
rookattacks(blockers::SquareSet, s::Square)

The squares attacked by a rook on s, with blockers being the occupied squares.

source
rookattacksempty(s::Square)

The set of squares a rook on s would attack on an otherwise empty board.

source
Chess.queenattacksMethod.
queenattacks(blockers::SquareSet, s::Square)

The squares attacked by a queen on s, with blockers being the occupied squares.

source
queenattacksempty(s::Square)

The set of squares a queen on s would attack on an otherwise empty board.

source
Chess.kingattacksFunction.
kingattacks(s::square)

the set of squares attacked by a king on the square s.

source
Chess.squaresbetweenFunction.
squaresbetween(s1::Square, s2::Square)

The set of squares on the line, file or diagonal between s1 and s2.

When a queen on s1 would attack s2 on an otherwise empty board, this function returns the set of squares where a piece would block the queen on s1 from attacking s2.

Examples

julia> squaresbetween(SQ_A4, SQ_D4) == SquareSet(SQ_B4, SQ_C4)
true

julia> squaresbetween(SQ_F7, SQ_A2)
SquareSet:
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  #  -  -  -
 -  -  -  #  -  -  -  -
 -  -  #  -  -  -  -  -
 -  #  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
 -  -  -  -  -  -  -  -
source
Chess.pprintMethod.
pprint(ss::SquareSet)

Pretty-print a square set to the standard output.

source
Chess.filesquaresFunction.
filesquares(f::SquareFile)
filesquares(s::Square)

The set of all squares on the provided file.

Examples

julia> filesquares(FILE_G) == SS_FILE_G
true

julia> filesquares(SQ_C5) == SS_FILE_C
true
source
Chess.ranksquaresFunction.
ranksquares(r::SquareRank)
ranksquares(s::Square)

The set of all squares on the provided rank.

Examples

julia> ranksquares(RANK_2) == SS_RANK_2
true

julia> ranksquares(SQ_C5) == SS_RANK_5
true
source
Chess.SS_EMPTYConstant.
SS_EMPTY

An empty square set, containing no squares.

source
Chess.SS_FILE_AConstant.
SS_FILE_A

The square set containing all the squares along the A file.

source
Chess.SS_FILE_BConstant.
SS_FILE_B

The square set containing all the squares along the B file.

source
Chess.SS_FILE_CConstant.
SS_FILE_C

The square set containing all the squares along the C file.

source
Chess.SS_FILE_DConstant.
SS_FILE_D

The square set containing all the squares along the D file.

source
Chess.SS_FILE_EConstant.
SS_FILE_E

The square set containing all the squares along the E file.

source
Chess.SS_FILE_FConstant.
SS_FILE_F

The square set containing all the squares along the F file.

source
Chess.SS_FILE_GConstant.
SS_FILE_G

The square set containing all the squares along the G file.

source
Chess.SS_FILE_HConstant.
SS_FILE_H

The square set containing all the squares along the H file.

source
Chess.SS_RANK_1Constant.
SS_RANK_1

The square set containing all the squares along the 1st rank.

source
Chess.SS_RANK_2Constant.
SS_RANK_2

The square set containing all the squares along the 2nd rank.

source
Chess.SS_RANK_3Constant.
SS_RANK_3

The square set containing all the squares along the 3rd rank.

source
Chess.SS_RANK_4Constant.
SS_RANK_4

The square set containing all the squares along the 4th rank.

source
Chess.SS_RANK_5Constant.
SS_RANK_5

The square set containing all the squares along the 5th rank.

source
Chess.SS_RANK_6Constant.
SS_RANK_6

The square set containing all the squares along the 6th rank.

source
Chess.SS_RANK_7Constant.
SS_RANK_7

The square set containing all the squares along the 7th rank.

source
Chess.SS_RANK_8Constant.
SS_RANK_8

The square set containing all the squares along the 8th rank.

source