From f1306b981e0098bc853a021de924a54c7d9c5614 Mon Sep 17 00:00:00 2001 From: Mariano Gappa Date: Sun, 29 Mar 2020 17:45:19 +0100 Subject: [PATCH] Adds docs for all exported methods. --- api/api.go | 36 +++++++++++++++++ api/api_entities.go | 97 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) diff --git a/api/api.go b/api/api.go index 1c9b896..d42a259 100644 --- a/api/api.go +++ b/api/api.go @@ -2,8 +2,10 @@ package api import "errors" +// API represents the cheesse API. All cheesse API methods are exported methods of this struct. type API struct{} +// New constructs an API. func New() API { return API{} } var ( @@ -13,11 +15,20 @@ var ( errInvalidActionForGivenGame = errors.New("the specified action is invalid for the specified game") ) +// DefaultGame returns the initial game of chess, with all pieces on their default positions +// and before any action has taken place. func (a API) DefaultGame() OutputGame { var defaultGame, _ = newGameFromFEN("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1") return mapGameToOutputGame(defaultGame) } +// ParseGame takes any valid input game and parses it, returning an OutputGame, which contains +// a lot of useful information about it, like possible actions, locations of pieces, game state +// in terms of threats, is the game over, etc. +// +// If the input game is invalid, an error will be returned with a description of the problem. +// +// Please refer to InputGame's and OutputGame's docs for format details. func (a API) ParseGame(game InputGame) (OutputGame, error) { parsedGame, err := a.parseGame(game) if err != nil { @@ -26,6 +37,15 @@ func (a API) ParseGame(game InputGame) (OutputGame, error) { return mapGameToOutputGame(parsedGame), nil } +// DoAction takes any valid input game and any valid input action, parses them and attempts +// to apply the action on the given game. If parsing any of the entities fails or applying +// the action on the parsed game fails an error will be returned. +// +// If applying the action succeeds, it returns the parsed action and the resulting game +// AFTER applying the action. +// +// Please refer to InputGame's, InputAction's, OutputGame's and OutputAction's docs for +// format details. func (a API) DoAction(game InputGame, action InputAction) (OutputGame, OutputAction, error) { parsedGame, err := a.parseGame(game) if err != nil { @@ -38,6 +58,22 @@ func (a API) DoAction(game InputGame, action InputAction) (OutputGame, OutputAct return mapGameToOutputGame(parsedGame.doAction(parsedAction)), mapInternalActionToAction(parsedAction), nil } +// ParseNotation takes any valid input game and a string representing a match in some +// notation, parses them and attempts to play the match starting from the supplied +// game. If it fails, it returns an error describing the problem. +// +// If parsing the match succeeds, it returns the parsed initial game and a list of +// steps, one per action in the `notationString`. +// +// An example `notationString` (Scholar's mate): +// +// `1. e4 e5\n2. Bc4 Nc6\n3. Qh5 Nf6??\n4. Qxf7#` +// +// At the moment, only Algebraic Notation is supported, but support for most +// notations is planned at a later release. +// +// Please refer to InputGame's, OutputGame's and OutputGameStep's docs for format +// details. func (a API) ParseNotation(game InputGame, notationString string) (OutputGame, []OutputGameStep, error) { parsedGame, err := a.parseGame(game) if err != nil { diff --git a/api/api_entities.go b/api/api_entities.go index d285657..7eb72a1 100644 --- a/api/api_entities.go +++ b/api/api_entities.go @@ -1,16 +1,49 @@ package api +// InputGame is the input interface to supply a chess game. +// +// There are 3 different ways to supply the chess game: +// +// 1. via `fenString`: supply a FEN Notation string. +// +// 2. via `board`: supply the board, together with required aspects of the game state. +// +// 3. via empty struct: assumes the defaultGame. +// +// If you supply both the `fenString` and the `board`, `board` is ignored silently. type InputGame struct { FENString string `json:"fenString"` Board Board `json:"board"` } +// InputAction is the input interface to supply a chess action. +// +// - `fromSquare` and `toSquare` are required, and must be board cells described in +// Algebraic Notation (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts. +// +// - `promotionPieceType` is only required if the action is a promotion. +// +// - `promotionPieceType` must be one of: `{Queen|King|Bishop|Knight|Rook|Pawn}`. type InputAction struct { FromSquare string `json:"fromSquare"` ToSquare string `json:"toSquare"` PromotionPieceType string `json:"promotionPieceType"` } +// Board is one of the input interfaces to supply a chess game. +// +// The `board` struct member must consist of 8 strings of length 8, containing the +// representation of the chess board using unicode characters. For the empty cells, +// any character may be used, but the output board will use spaces. +// +// The other struct members represent all required game state as described in the +// FEN notation. +// +// - `enPassantTargetSquare` must be a board cell described in Algebraic Notation +// (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts. If there's +// no en passant target square, it must be an empty string. +// +// - `turn` must be one of: `{Black|White}`. type Board struct { Board []string `json:"board"` CanWhiteKingsideCastle bool `json:"canWhiteKingsideCastle"` @@ -23,6 +56,34 @@ type Board struct { Turn string `json:"turn"` // "Black" or "White" } +// OutputGame is the output interface that describes a chess game. +// All API calls that return a chess game represent it with an OutputGame. +// +// - `fenString` represents the chess game as a FEN Notation string. +// +// - `actions` is the exhaustive list of actions that can follow from this game. +// +// - `enPassantTargetSquare` is a board cell described in Algebraic Notation +// (e.g. `e2`). Note that `a1` is where the White Queen's Rook starts. If there's +// no en passant target square, it's an empty string. +// +// - `blackPieces` and `whitePieces` are maps from cells to piece names. The cells +// are represented in Algebraic Notation (e.g `e2`), and the piece names are one +// of `{Queen|King|Bishop|Knight|Rook|Pawn}`. +// +// - `blackKing` and `whiteKing` are the cells where the Kings are located. The +// cells are represented in Algebraic Notation (e.g `e2`). +// +// - `gameOverWinner` is one of `{Black|White|Unknown}`, and represents the winner +// of the game, when `isGameOver` is true. `Unknown` otherwise. +// +// - `inCheckBy` is a list of cells whose pieces are threatening the player whose +// turn it is to move. `board.turn` dictates who this player is. The cells are +// represented in Algebraic Notation (e.g `e2`). To find out which piece is in a +// cell, inspect `blackPieces` and `whitePieces`. +// +// Because OutputGame is a superset of InputGame, you may supply an OutputGame to +// any API call that expects an InputGame. type OutputGame struct { FENString string `json:"fenString"` Board Board `json:"board"` @@ -51,6 +112,25 @@ type OutputGame struct { InCheckBy []string `json:"inCheckBy"` } +// OutputAction is the output interface that describes a chess action. +// All API calls that return a chess action represent it with an OutputAction. +// +// - `fromPieceOwner` is one of `{Black|White}`. The owner of the piece doing +// the action. +// +// - `fromPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`. +// +// - `fromPieceSquare` and `toSquare` are the source and destination board +// cells for the action, described in Algebraic Notation (e.g. `e2`). Note +// that `a1` is where the White Queen's Rook starts. +// +// - `promotionPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`, +// and represents the piece that a Pawn promotes to, if the action is a +// promotion. If the action is not a promotion, it's an empty string. +// +// - `capturedPieceType` is one of `{Queen|King|Bishop|Knight|Rook|Pawn}`, +// and represents the piece that was captured, if the action is a capture. +// If the action is not a capture, it's an empty string. type OutputAction struct { FromPieceOwner string `json:"fromPieceOwner"` FromPieceType string `json:"fromPieceType"` @@ -68,6 +148,23 @@ type OutputAction struct { CapturedPieceType string `json:"capturedPieceType"` } +// OutputGameStep is the output interface that describes a step in a parsed +// or converted match in a given notation string. +// +// A given notation string is parsed into a list of "action strings", each +// one representing each action in the match. There will be an OutputGameStep +// for each one of these "action strings". +// +// Please refer to the docs for the OutputGame and OutputAction formats. +// +// - `actionString` is a string representing a chess action as supplied by the +// client, so it could be in any of the supported notations, and is not +// modified by the API. It could be incorrectly sliced, though. +// +// - `action` represents the action that the API inferred from the +// `actionString`. +// +// - `game` represents the chess game AFTER applying the inferred action. type OutputGameStep struct { Game OutputGame `json:"game"` Action OutputAction `json:"action"`