/* book.h -- public interface to the opening book module (book.c).
 *
 * See book.c's own header comment for the file format and how a
 * game's book state is tracked; this file is deliberately just the
 * five entry points the rest of the engine (xboard-engine-tactical.c)
 * ever needs to call, in the order a game actually calls them:
 *
 *   main(), once at startup:        LoadBooks()
 *   the "new"/"setboard" handlers:  BookReset() or BookDisable()
 *   EngineMove(), our own turn:     TryBookMove()
 *   the usermove handler, theirs:   BookNoteOpponentMove()
 *
 * Everything else in book.c -- the tree structure, the parser, the
 * two loaded trees, and which game state they're in -- is private
 * to that file; nothing outside it ever needs to know any of that
 * to use the book.
 */

#ifndef BOOK_H
#define BOOK_H

/*--> LoadBooks: load "white.txt" and "black.txt" from the working
      directory, once, at startup. Call this exactly once, after
      SANInit() (book.c doesn't call it or depend on it, but this
      keeps every other engine start-up step in one place, in
      main()). A missing or unreadable file simply disables the book
      for games where it would have applied -- see TryBookMove()/
      BookNoteOpponentMove() below -- never a fatal error. */
void LoadBooks (void);

/*--> BookReset: (re)enable the book for a fresh game from the
      standard starting position. Call this on "new", and on any
      "setboard" that sets exactly that position -- see
      BookDisable() for every other case. */
void BookReset (void);

/*--> BookDisable: disable the book for the rest of the current
      game. Call this on a "setboard" to anything other than the
      standard starting position (an endgame study, a puzzle,
      resuming a game partway through): neither book file records
      anything starting from a position other than the real
      opening, so there is nothing for it to usefully match against
      in that case. */
void BookDisable (void);

/*--> TryBookMove: if a book move is available for the side to move
      (this engine), choose one at random, advance the book state
      past it, and copy its coordinate text into "coord" (which must
      have room for at least 6 bytes), returning 1. Returns 0, with
      "coord" untouched, if there is no book move to play here --
      the book is disabled, this game never had one to begin with,
      or previous play has already gone somewhere the book doesn't
      cover -- in which case the caller should search normally. */
int TryBookMove (char *coord);

/*--> BookNoteOpponentMove: keep the book state in sync with a move
      the opponent actually played (call this once per opponent
      move, after it's confirmed legal and applied). If it matches a
      recorded continuation, the book advances past it, ready for
      TryBookMove()/BookNoteOpponentMove() to consult one ply
      further next time; if not (including if the book was never
      following anything to begin with), the book is left disabled
      for the rest of this game -- there is no way back into a book
      line once real play has diverged from every one it records. */
void BookNoteOpponentMove (const char *coord);

#endif /* BOOK_H */
