chess

This is the main module which provides all of the necessary functionality to play chess.

Refer to the README page for an introduction and some example code.

Types

AvailableMove

Represents a move a figure can do.

Directly maps to a Move.

Use get_moves or get_all_moves to generate.

pub type AvailableMove {
  StdMoveAvailable(to: Coordinate)
  PawnPromotionAvailable(to: Coordinate)
  EnPassantAvailable(to: Coordinate)
  ShortCastleAvailable
  LongCastleAvailable
}

Constructors

```
StdMoveAvailable(to: Coordinate)
```
The figure can go to to.

To execute this move use StdMove.
```
PawnPromotionAvailable(to: Coordinate)
```
The figure is a pawn and can go to to and promote to another figure (Queen, Rook, Bishop or Knight).

To execute this move use PawnPromotion.
```
EnPassantAvailable(to: Coordinate)
```
The figure is a pawn and can do an En Passant move, ending at to while capturing the opponent’s passing pawn on the side.

To execute this move use EnPassant.
```
ShortCastleAvailable
```
The figure is a king and can castle on the king-side.

To execute this move use ShortCastle.
```
LongCastleAvailable
```
The figure is a king and can castle on the queen-side.

To execute this move use LongCastle.

Board

Represents all figure positions on a chess board.

other_figures contains all figures which are not kings.

Use get_board to retrieve.

pub type Board {
  Board(
    white_king: Coordinate,
    black_king: Coordinate,
    other_figures: dict.Dict(Coordinate, #(Figure, Player)),
  )
}

Constructors

Board(
  white_king: Coordinate,
  black_king: Coordinate,
  other_figures: dict.Dict(Coordinate, #(Figure, Player)),
)

Coordinate

Represents a coordinate referring to a square on the chess board.

You may use the predefined constants in the module chess/coordinates to quickly reference all possible chess squares.

pub type Coordinate {
  Coordinate(file: File, row: Row)
}

Constructors

```
Coordinate(file: File, row: Row)
```

DrawCondition

Represents a way of drawing the game

pub type DrawCondition {
  MutualAgreement
  Stalemated
  InsufficientMaterial
  ThreefoldRepition
  FiftyMoveRule
}

Constructors

```
MutualAgreement
```
Both players agreed to end the game in a draw.

Use draw to end the game like this.
```
Stalemated
```
A player has no legal moves left, while his king is not in check. See here for more info.
```
InsufficientMaterial
```
Both players are missing enough figures to checkmate the enemy king. See here for more info.
```
ThreefoldRepition
```
The same position has been reached three times. See here for more info.
```
FiftyMoveRule
```
No pawns have been moved and no figures have been captured in 50 full-moves (which equate to 100 calls to player_move as in chess-tmers a full-move consists of one move for each player).

See here for more info.

EndCondition

Represents a way of ending the game.

pub type EndCondition {
  Victory(winner: Player, by: WinCondition)
  Draw(by: DrawCondition)
}

Constructors

Victory(winner: Player, by: WinCondition)

```
Draw(by: DrawCondition)
```

Figure

Represents a chess figure.

pub type Figure {
  Pawn
  Knight
  Bishop
  Rook
  Queen
  King
}

Constructors

```
Pawn
```
```
Knight
```
```
Bishop
```
```
Rook
```
```
Queen
```
```
King
```

File

Represents a file (vertical line of squares) of a chess board.

From white’s perspective is FileA is on the left side and FileH on the right side.

pub type File {
  FileA
  FileB
  FileC
  FileD
  FileE
  FileF
  FileG
  FileH
}

Constructors

```
FileA
```
```
FileB
```
```
FileC
```
```
FileD
```
```
FileE
```
```
FileF
```
```
FileG
```
```
FileH
```

GameState

opaque

Represents entire game state.

Use new_game or new_custom_game to generate.

Update with player_move.

pub opaque type GameState

GameStatus

Represents if the is game still ongoing or over.

Use get_status to retrieve.

pub type GameStatus {
  GameEnded(info: EndCondition)
  GameOngoing(next_player: Player)
}

Constructors

```
GameEnded(info: EndCondition)
```
See info to see how the game ended.
```
GameOngoing(next_player: Player)
```
Waiting for the next move by next_player.

GetMovesError

Represents an error returned by get_moves.

pub type GetMovesError {
  GetMovesWhileGameAlreadyOver
  GetMovesWithInvalidFigure(reason: SelectFigureError)
}

Constructors

```
GetMovesWhileGameAlreadyOver
```
Tried getting moves while the game is already over.
```
GetMovesWithInvalidFigure(reason: SelectFigureError)
```
Tried making a move with an invalid figure. See reason for extra info.

GetPastPositionError

Represent an error returned by get_past_position.

pub type GetPastPositionError {
  GetPastPositionWithNegativeMoveNumber(passed_move_number: Int)
  GetPastPositionWithMoveNumberExceedingHistory(
    passed_move_number: Int,
    allowed_maximum_move_number: Int,
  )
}

Constructors

GetPastPositionWithNegativeMoveNumber(passed_move_number: Int)

Tried to get a past position with a negative move number.

GetPastPositionWithMoveNumberExceedingHistory(
  passed_move_number: Int,
  allowed_maximum_move_number: Int,
)

Tried to get a past position with a move number that exceeds the length of the current game’s history.

Move

Represents a player move that moves a figure on the chess board.

To be used with player_move.

Use get_moves or get_all_moves to get a set of AvailableMove which directly map to this.

pub type Move {
  StdMove(from: Coordinate, to: Coordinate)
  PawnPromotion(
    from: Coordinate,
    to: Coordinate,
    new_figure: Figure,
  )
  EnPassant(from: Coordinate, to: Coordinate)
  ShortCastle
  LongCastle
}

Constructors

StdMove(from: Coordinate, to: Coordinate)

Used to move a figure from from to to.

```
PawnPromotion(
  from: Coordinate,
  to: Coordinate,
  new_figure: Figure,
)
```
Used to move and promote a pawn from from to to as new_figure.

new_figure may only be Queen, Rook, Bishop or Knight.
```
EnPassant(from: Coordinate, to: Coordinate)
```
Used to do an En Passant pawn move.

For to use the destination of the pawn, not the square of the oppsing passing pawn that will be captured.
```
ShortCastle
```
Used to castle the king on the king-side.
```
LongCastle
```
Used to castle the king on the queen-side.

NewCustomGameError

Represents an error returned by new_custom_game.

pub type NewCustomGameError {
  PawnsOnFinalRank(pawns: set.Set(Coordinate))
  EnemyIsInCheck
}

Constructors

```
PawnsOnFinalRank(pawns: set.Set(Coordinate))
```
Tried to create a game, where pawns are on the final row.

This is illegal, as these pawns would have promoted and are now stuck instead.

See pawns for a list of coordinates pointing to the culprits.
```
EnemyIsInCheck
```
Tried to create a game, where the first-moving player is already checking the enemy king.

This is illegal as it would allow the first-moving player to “capture” the king.

Player

Represents one of the two chess players.

pub type Player {
  White
  Black
}

Constructors

```
White
```
```
Black
```

PlayerMoveError

Represents an error returned by player_move.

pub type PlayerMoveError {
  PlayerMoveWhileGameAlreadyOver
  PlayerMoveWithInvalidFigure(reason: SelectFigureError)
  PlayerMoveIsIllegal
}

Constructors

```
PlayerMoveWhileGameAlreadyOver
```
Tried making a move while the game is already over.
```
PlayerMoveWithInvalidFigure(reason: SelectFigureError)
```
Tried making a move with an invalid figure. See reason for extra info.
```
PlayerMoveIsIllegal
```
Tried making a move which is not legal.

Row

Represents a row (horizontal line of squares) of a chess board.

From white’s perspective is Row1 on the bottom and Row8 at the top.

pub type Row {
  Row1
  Row2
  Row3
  Row4
  Row5
  Row6
  Row7
  Row8
}

Constructors

```
Row1
```
```
Row2
```
```
Row3
```
```
Row4
```
```
Row5
```
```
Row6
```
```
Row7
```
```
Row8
```

SelectFigureError

Represents an error when trying to select a figure.

pub type SelectFigureError {
  SelectedFigureDoesntExist
  SelectedFigureIsNotFriendly
}

Constructors

```
SelectedFigureDoesntExist
```
Tried selecting a figure from a coordinate which points to an empty square.
```
SelectedFigureIsNotFriendly
```
Tried selecting a figure which doesn’t belong to the player.

WinCondition

Represents a way of winning the game.

pub type WinCondition {
  Checkmated
  Forfeited
}

Constructors

```
Checkmated
```
The loser has no legal moves left, while his king is in check.
```
Forfeited
```
The loser forfeited the game.

Use the forfeit to end the game like this.

Values

draw

pub fn draw(game game: GameState) -> Result(GameState, Nil)

Draw the game through mutual agreement of both players.

Note: The user of this package is responsible for coordinating the actual draw agreement between both players.

Errors if the game was already over.

forfeit

pub fn forfeit(game game: GameState) -> Result(GameState, Nil)

Let the moving player forfeit the game and give victory to the opposing player.

Errors if the game was already over.

get_all_moves

pub fn get_all_moves(
  game game: GameState,
) -> Result(dict.Dict(Coordinate, set.Set(AvailableMove)), Nil)

Return a list of all legal moves of all figures of the moving player.

To execute a move see player_move.

Returns pairs of Coordinate and multiple AvailableMove. Coordinate refers to the figure and the set of AvailableMove to the moves that this figure can do.

Errors if the game was already over.

get_board

pub fn get_board(game game: GameState) -> Board

Return a Board from a GameState.

get_history

pub fn get_history(game game: GameState) -> List(#(Move, Player))

Returns a history of moves along with which player did them.

The first element is the first move played in the game and the last element is the previously played move.

get_moves

pub fn get_moves(
  game game: GameState,
  from coord: Coordinate,
) -> Result(set.Set(AvailableMove), GetMovesError)

Return a list of all legal moves of a figure on from.

To execute a move see player_move.

Errors if the game was already over or the selected figure doesn’t exist or doesn’t belong to the player.

get_past_position

pub fn get_past_position(
  game game: GameState,
  move_number move_number: Int,
) -> Result(GameState, GetPastPositionError)

Retrieve a past board position from a game according to its move history.

Note that the term move does not apply to the chess term full-move, rather it is a half-move or a ply, which are done by one player only.

A move_number of 0 returns the initial starting position.

A move_number of 1 returns the position after the first half-move.

Errors if move_number is negative or larger than the game’s history.

get_status

pub fn get_status(game game: GameState) -> GameStatus

Return a GameStatus from a GameState.

is_in_check

pub fn is_in_check(game game: GameState) -> Bool

Determines whether the player’s king is in check by the opponent.

new_custom_game

pub fn new_custom_game(
  board board: Board,
  first_player player: Player,
) -> Result(GameState, NewCustomGameError)

Create a new game in the given position.

first_player decides which player goes first.

Allows for castling if kings and rooks are in their standard positions.

Errors if the provided position is an illegal starting position.

new_game

pub fn new_game() -> GameState

Creates a new game in the standard starting chess position.

player_move

pub fn player_move(
  game game: GameState,
  move move: Move,
) -> Result(GameState, PlayerMoveError)

Let a player move a figure and return the new state.

move is to be constructed by yourself.

Use get_moves or get_all_moves to get a set of AvailableMove which provide you with enough information to construct your own Move for move.

Errors if the provided move is not valid/legal or the game was already over.