libchess/chess.h

   1 /* vim:tw=78:ts=8:sw=4:set ft=c:  */
   2 /*
   3     Copyright (C) 2002-2024 Ben Kibbey <bjk@luxsci.net>
   4
   5     This program is free software; you can redistribute it and/or modify
   6     it under the terms of the GNU General Public License as published by
   7     the Free Software Foundation; either version 2 of the License, or
   8     (at your option) any later version.
   9
  10     This program is distributed in the hope that it will be useful,
  11     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13     GNU General Public License for more details.
  14
  15     You should have received a copy of the GNU General Public License
  16     along with this program; if not, write to the Free Software
  17     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 */
  19 #ifndef CHESS_H
  20 #define CHESS_H
  21
  22 #define PGN_TIME_FORMAT "%Y.%m.%d"
  23 #define MAX_PGN_LINE_LEN 255
  24 #define MAX_SAN_MOVE_LEN 7
  25 #define MAX_PGN_NAG 8
  26
  27 #define VALIDRANK       VALIDFILE
  28 #define VALIDFILE(f)    (f >= 1 && f <= 8)
  29 #define RANKTOBOARD(r)  (8 - r)
  30 #define FILETOBOARD(c)  (c - 1)
  31 #define RANKTOINT(r)    (r - '0')
  32 #define FILETOINT(c)    (c - ('a' - 1))
  33 #define VALIDROW(r)     (r >= '1' && r <= '8')
  34 #define VALIDCOL(c)     (c >= 'a' && c <= 'h')
  35 #define INTTORANK(r)    (r + '0')
  36 #define INTTOFILE(f)    (f + ('a' - 1))
  37
  38 #define SET_FLAG(var, f)        (var |= f)
  39 #define CLEAR_FLAG(var, f)      (var &= ~(f))
  40 #define TOGGLE_FLAG(var, f)     (var ^= (f))
  41 #define TEST_FLAG(var, f)       (var & f)
  42
  43 enum
  44 {
  45   OPEN_SQUARE, PAWN, BISHOP, ROOK, KNIGHT, QUEEN, KING
  46 };
  47
  48 enum
  49 {
  50   WHITE, BLACK
  51 };
  52
  53 /* Game flags. */
  54 #define GF_PERROR               0x0001  /* Parse error for this game. */
  55 #define GF_ENPASSANT            0x0002  /* For En Passant validation. */
  56 #define GF_GAMEOVER             0x0004  /* End of game. */
  57 #define GF_WK_CASTLE            0x0008
  58 #define GF_WQ_CASTLE            0x0010
  59 #define GF_BK_CASTLE            0x0020
  60 #define GF_BQ_CASTLE            0x0040
  61 #define GF_BLACK_OPENING        0x0080
  62
  63 /*
  64  * The chess board.
  65  */
  66 typedef struct
  67 {
  68   unsigned char icon;           // The piece.
  69   unsigned char valid:1,        /* != 0 if this square is a valid move for the
  70                                   selected piece. */
  71   enpassant:1;
  72 } BOARD[8][8];
  73
  74 /*
  75  * PGN Roster tags.
  76  */
  77 typedef struct tags
  78 {
  79   char *name;                   // Tag name.
  80   char *value;                  // Tag value.
  81 } __attribute__ ((packed)) TAG;
  82
  83 /*
  84  * Move history.
  85  *
  86  * g.hp is the pointer to the current history which may be .rav for
  87  * Recursive Annotated Variations. The depth of recursion is kept track of in
  88  * g.ravlevel.
  89  */
  90 typedef struct history
  91 {
  92   char *move;                           // The SAN move text.
  93   char *comment;                        // Annotation for this move.
  94   unsigned char nag[MAX_PGN_NAG];       // Numeric Annotation Glyph.
  95   char *fen;                            // Of the current board.
  96   struct history **rav;                 // Variation of the current move.
  97 } HISTORY;
  98
  99 /*
 100  * Keeps game state history for the root move.
 101  */
 102 typedef struct
 103 {
 104   char *fen;                    // Game board state.
 105   unsigned short flags;
 106   unsigned short hindex;
 107   HISTORY **hp;                 // Pointer to the root move.
 108 } RAV;
 109
 110 /*
 111  * This is an array of 'games' structures. One for each game in a file, or
 112  * the current game.
 113  */
 114 typedef struct game_s
 115 {
 116   TAG **tag;                    // Roster tags.
 117   HISTORY **history;            // Move history for this game.
 118   HISTORY **hp;                 /* History pointer pointing to the location
 119                                    in *history used mainly for RAV. */
 120   RAV *rav;                     // Saved game states for the root move of RAV.
 121   int ravlevel;                 // An index to *rav.
 122   unsigned short hindex;        // Current move in *hp.
 123   unsigned short flags;         // Game flags.
 124   unsigned short oflags;        // Game flags for the previous move.
 125   unsigned char side:1,         // This playing side. BLACK or WHITE.
 126     turn:1;                     // BLACK or WHITE.
 127   unsigned short ply;           // Move count.
 128   void *data;                   /* User data associated with this game. Must
 129                                  * be freed by the user. */
 130   // internal validation state
 131   int validate;
 132   int done_fen_tag;
 133   int pgn_fen_tag;
 134   int capture;
 135   int castle;
 136   int check;
 137   int check_testing;
 138   int kfile;
 139   int krank;
 140   int okfile;
 141   int okrank;
 142   int validate_find;
 143 } *GAME;
 144
 145 /*
 146  * Global GAME array. pgn_new_game() appends to this array.
 147  */
 148 extern GAME *game;
 149
 150 /*
 151  * 'gindex' and 'gtotal' are the current and total number of games in 'game'.
 152  */
 153 extern int gindex, gtotal;
 154
 155 /*
 156  * Library configuration flags. These will affect all games.
 157  */
 158 typedef enum
 159 {
 160   /*
 161    * When pgn_write() is called to write a game, write reduced PGN format.
 162    * This will only write the seven tag roster and move text skipping any
 163    * annotation. The type for this flag is an int.
 164    */
 165   PGN_REDUCED,
 166
 167   /*
 168    * The number of full moves to write per line. If 0 then pgn_write() will
 169    * write as many as possible within 80 columns. The type for this flag
 170    * is an int.
 171    */
 172   PGN_MPL,
 173
 174   /*
 175    * Normally when a parse error occurs in a game the game is flagged with
 176    * GF_PERROR and the rest of the game is discarded and processing of the
 177    * next game is done. When set and a parse error occurs the rest of the
 178    * entire file will be discarded. The type for this flag is an int.
 179    */
 180   PGN_STOP_ON_ERROR,
 181
 182 #ifdef DEBUG
 183   /*
 184    * If the following is set to a value > 0 and DEBUG was defined
 185    * at compile time then debugging output will be written to
 186    * "libchess.debug" in the current directory.
 187    */
 188   PGN_DEBUG,
 189 #endif
 190
 191   /*
 192    * After PGN_PROGRESS amount of bytes have been read from a file, call
 193    * PGN_PROGRESS_FUNC. The type for PGN_PROGRESS is a long.
 194    * PGN_PROGRESS_FUNC is of type pgn_progress.
 195    */
 196   PGN_PROGRESS,
 197   PGN_PROGRESS_FUNC,
 198
 199   /*
 200    * If set to 1 and an opponent can attack a castling square the castling
 201    * move will not be a valid one.
 202    */
 203   PGN_STRICT_CASTLING,
 204 } pgn_config_flag;
 205
 206 /*
 207  * Errors returned from the following functions.
 208  */
 209 typedef enum
 210 {
 211   E_PGN_ERR = -1,
 212   E_PGN_OK,
 213   E_PGN_PARSE,
 214   E_PGN_AMBIGUOUS,
 215   E_PGN_INVALID
 216 } pgn_error_t;
 217
 218 typedef struct
 219 {
 220   FILE *fp;
 221   char *filename;
 222   char *tmpfile;                /* For appending. */
 223   int pipe;
 224 } PGN_FILE;
 225
 226 /*
 227  * The prototype of the PGN_PROGRESS_FUNC function pointer.
 228  */
 229 typedef void (*pgn_progress) (long size, long offset);
 230
 231 /*
 232  * Sets config flag 'f' to the next argument. Returns E_PGN_OK on success or
 233  * E_PGN_ERR if 'f' is an invalid flag or E_PGN_INVALID if 'val' is an invalid
 234  * flag value.
 235  */
 236 pgn_error_t pgn_config_set (pgn_config_flag f, ...);
 237
 238 /*
 239  * Gets the value of config flag 'f'. The next argument should be a pointer of
 240  * the config type which is set to the value of 'f'. Returns E_PGN_ERR if 'f'
 241  * is an invalid flag or E_PGN_OK on success.
 242  */
 243 pgn_error_t pgn_config_get (pgn_config_flag f, ...);
 244
 245 /*
 246  * Returns E_PGN_OK if 'filename' is a recognized compressed filetype or
 247  * E_PGN_ERR if not.
 248  */
 249 pgn_error_t pgn_is_compressed (const char *filename);
 250
 251 /*
 252  * Opens a file 'filename' with the given 'mode'. 'mode' should be "r" for
 253  * reading, "w" for writing (will truncate if the file exists) or "a" for
 254  * appending to an existing file or creating a new one. Returns E_PGN_OK on
 255  * success and sets 'result' to a file handle for use will the other file
 256  * functions or E_PGN_ERR if there is an error opening the file in which case
 257  * errno will be set to the error or E_PGN_INVALID if 'mode' is an invalid
 258  * mode or if 'filename' is not a regular file.
 259  */
 260 pgn_error_t pgn_open (const char *filename, const char *mode,
 261                       PGN_FILE ** result);
 262
 263 /*
 264  * Closes and free's a PGN file handle. Returns E_PGN_OK on success,
 265  * E_PGN_INVALID if 'pgn' is NULL, or E_PGN_ERR if rename() failed.
 266  */
 267 pgn_error_t pgn_close (PGN_FILE * pgn);
 268
 269 /*
 270  * Parses a PGN_FILE which was opened with pgn_open(). If 'pgn' is NULL then a
 271  * single empty game will be allocated. If there is a parsing error
 272  * E_PGN_PARSE is returned, if there was a memory allocation error E_PGN_ERR
 273  * is returned, otherwise E_PGN_OK is returned and the global 'gindex' is set
 274  * to the last parsed game in the file and the global 'gtotal' is set to the
 275  * total number of games in the file. The file should be closed with
 276  * pgn_close() after processing.
 277  */
 278 pgn_error_t pgn_parse (PGN_FILE * pgn);
 279
 280 /*
 281  * Allocates a new game and increments 'gtotal'. 'gindex' is then set to the
 282  * new game. Returns E_PGN_ERR if there was a memory allocation error or
 283  * E_PGN_OK on success.
 284  */
 285 pgn_error_t pgn_new_game ();
 286
 287 /*
 288  * Writes a PGN formatted game 'g' to a file which was opened with pgn_open().
 289  * See 'pgn_config_flag' for output options. Returns E_PGN_ERR if there was a
 290  * memory allocation or write error and E_PGN_OK on success.
 291  */
 292 pgn_error_t pgn_write (PGN_FILE * pgn, GAME g);
 293
 294 /*
 295  * Frees all games in the global 'game' array. Returns nothing.
 296  */
 297 void pgn_free_all (void);
 298
 299 /*
 300  * Frees a single game 'g'. Returns nothing.
 301  */
 302 void pgn_free (GAME g);
 303
 304 /*
 305  * Adds a tag 'name' with value 'value' to the pointer to array of TAG
 306  * pointers 'dst'. If a duplicate tag 'name' was found then the existing tag
 307  * is updated to the new 'value'. If 'value' is NULL, the tag is removed.
 308  * Returns E_PGN_ERR if there was a memory allocation error or E_PGN_OK on
 309  * success.
 310  */
 311 pgn_error_t pgn_tag_add (TAG *** dst, char *name, char *value);
 312
 313 /*
 314  * Returns the total number of tags in 't' or 0 if 't' is NULL.
 315  */
 316 int pgn_tag_total (TAG ** t);
 317
 318 /*
 319  * Finds a tag 'name' in the structure array 't'. Returns the location in the
 320  * array of the found tag or E_PGN_ERR if the tag could not be found.
 321  */
 322 pgn_error_t pgn_tag_find (TAG ** t, const char *name);
 323
 324 /*
 325  * Sorts a tag array. The first seven tags are in order of the PGN standard so
 326  * don't sort'em. Returns nothing.
 327  */
 328 void pgn_tag_sort (TAG ** t);
 329
 330 /*
 331  * Frees a TAG array. Returns nothing.
 332  */
 333 void pgn_tag_free (TAG **);
 334
 335 /*
 336  * It initializes the board (b) to the FEN tag (if found) and sets the
 337  * castling and enpassant info for the game 'g'. If 'fen' is set it should be
 338  * a fen tag and will be parsed rather than the game 'g'.tag FEN tag. Returns
 339  * E_PGN_OK on success or if there was both a FEN and SetUp tag with the SetUp
 340  * tag set to 0. Returns E_PGN_PARSE if there was a FEN parse error, E_PGN_ERR
 341  * if there was no FEN tag or there was a SetUp tag with a value of 0. Returns
 342  * E_PGN_OK on success.
 343  */
 344 pgn_error_t pgn_board_init_fen (GAME g, BOARD b, char *fen);
 345
 346 /*
 347  * Creates a FEN tag from the current game 'g', history move (g.hindex) and
 348  * board 'b'. Returns a FEN tag.
 349  */
 350 char *pgn_game_to_fen (GAME g, BOARD b);
 351
 352 /*
 353  * Resets or initializes a new game board 'b'. Returns nothing.
 354  */
 355 void pgn_board_init (BOARD b);
 356
 357 /*
 358  * Valididate move 'm' against the game state 'g' and game board 'b' and
 359  * update board 'b'. 'm' is ensured to be in SAN format and 'frfr' will the
 360  * file/rank representation of 'm' and should be freed. Returns E_PGN_PARSE if
 361  * there was a move text parsing error, E_PGN_INVALID if the move is invalid,
 362  * E_PGN_AMBIGUOUS if the move is invalid with ambiguities or E_PGN_OK if
 363  * successful.
 364  */
 365 pgn_error_t pgn_parse_move (GAME g, BOARD b, char **m, char **frfr);
 366
 367 /*
 368  * Like pgn_parse_move() but don't modify game flags in 'g' or board 'b'.
 369  */
 370 pgn_error_t pgn_validate_move (GAME g, BOARD b, char **m, char **frfr);
 371
 372 /*
 373  * Returns the total number of moves in 'h' or 0 if there are none.
 374  */
 375 int pgn_history_total (HISTORY ** h);
 376
 377 /*
 378  * Returns the history ply 'n' from 'h'. If 'n' is out of range then NULL is
 379  * returned.
 380  */
 381 HISTORY *pgn_history_by_n (HISTORY ** h, int n);
 382
 383 /*
 384  * Appends move 'm' to game 'g' history pointer and creates a FEN tag for the
 385  * current game state using board 'b'. The FEN tag makes things faster than
 386  * validating the entire move history by validating only the current move to
 387  * the previous moves FEN tag. The history pointer may be a in a RAV so
 388  * g->rav.hp is also updated to the new (realloc()'ed) pointer. If not in a
 389  * RAV then g->history will be updated. Returns E_PGN_ERR if realloc() failed
 390  * or E_PGN_OK on success.
 391  */
 392 pgn_error_t pgn_history_add (GAME g, BOARD b, const char *m);
 393
 394 /*
 395  * Deallocates all of the history data from position 'start' in the array 'h'.
 396  * Returns nothing.
 397  */
 398 void pgn_history_free (HISTORY ** h, int start);
 399
 400 /*
 401  * Resets the game 'g' using board 'b' up to history move (g.hindex) 'n'.
 402  * Returns E_PGN_OK on success or E_PGN_PARSE if there was a FEN tag but the
 403  * parsing of it failed. Or returns E_PGN_INVALID if somehow the move failed
 404  * validation while resetting.
 405  */
 406 pgn_error_t pgn_board_update (GAME g, BOARD b, int n);
 407
 408 /*
 409  * Updates the game 'g' using board 'b' to the next 'n'th history move.
 410  * Returns nothing.
 411  */
 412 void pgn_history_prev (GAME g, BOARD b, int n);
 413
 414 /*
 415  * Updates the game 'g' using board 'b' to the previous 'n'th history move.
 416  * Returns nothing.
 417  */
 418 void pgn_history_next (GAME g, BOARD b, int n);
 419
 420 /*
 421  * Converts the character piece 'p' to an integer. Returns the integer
 422  * associated with 'p' or E_PGN_ERR if 'p' is invalid.
 423  */
 424 int pgn_piece_to_int (int p);
 425
 426 /*
 427  * Converts the integer piece 'n' to a character whose turn is 'turn'. WHITE
 428  * piece are uppercase and BLACK pieces are lowercase. Returns the character
 429  * associated with 'n' or E_PGN_ERR if 'n' is an invalid piece.
 430  */
 431 pgn_error_t pgn_int_to_piece (char turn, int n);
 432
 433 /*
 434  * Toggles g->turn. Returns nothing.
 435  */
 436 void pgn_switch_turn (GAME);
 437
 438 /*
 439  * Toggles g->side and switches the White and Black roster tags. Returns
 440  * nothing.
 441  */
 442 void pgn_switch_side (GAME g, int t);
 443
 444 /*
 445  * Clears the enpassant flag for all positions on board 'b'. Returns nothing.
 446  */
 447 void pgn_reset_enpassant (BOARD b);
 448
 449 /*
 450  * Clears the valid move flag for all positions on board 'b'. Returns nothing.
 451  */
 452 void pgn_reset_valid_moves (BOARD b);
 453
 454 /*
 455  * Sets valid moves (b.valid) from game 'g' using board 'b'. The valid moves
 456  * are for the piece on the board 'b' at 'rank' and 'file'. Returns nothing.
 457  */
 458 void pgn_find_valid_moves (GAME g, BOARD b, int rank, int file);
 459
 460 /*
 461  * Returns the version string of the library.
 462  */
 463 const char *pgn_version (void);
 464
 465 #endif