projects/lib/src/openingbook.h

   1 #ifndef OPENING_BOOK_H
   2 #define OPENING_BOOK_H
   3
   4 #include <QtGlobal>
   5 #include <QMultiMap>
   6 #include "board/genericmove.h"
   7
   8 class QString;
   9 class QDataStream;
  10 class PgnGame;
  11 class PgnStream;
  12
  13
  14 /*!
  15  * \brief A collection of opening moves for chess.
  16  *
  17  * OpeningBook is a container (binary tree) class for opening moves that
  18  * can be played by the GUI. When the game goes "out of book", control
  19  * of the game is transferred to the players.
  20  *
  21  * The opening book can be stored externally in a binary file. When it's needed,
  22  * it is loaded in memory, and positions can be found quickly by searching
  23  * the book for Zobrist keys that match the current board position.
  24  */
  25 class LIB_EXPORT OpeningBook
  26 {
  27         public:
  28                 /*! Destroys the opening book. */
  29                 virtual ~OpeningBook() {}
  30
  31                 /*!
  32                  * Imports a PGN game.
  33                  *
  34                  * \param pgn The game to import.
  35                  * \param maxMoves The maximum number of halfmoves that
  36                  * can be imported.
  37                  *
  38                  * Returns the number of moves imported.
  39                  */
  40                 int import(const PgnGame& pgn, int maxMoves);
  41                 /*!
  42                  * Imports PGN games from a stream.
  43                  *
  44                  * \param in The PGN stream that contains the games.
  45                  * \param maxMoves The maximum number of halfmoves per game
  46                  * that can be imported.
  47                  *
  48                  * Returns the number of moves imported.
  49                  */
  50                 int import(PgnStream& in, int maxMoves);
  51
  52                 /*!
  53                  * Returns a move that can be played in a position where the
  54                  * Zobrist key is \a key.
  55                  *
  56                  * If no matching moves are found, an empty (illegal) move is
  57                  * returned.
  58                  *
  59                  * If there are multiple matches, a random, weighted move is
  60                  * returned. Popular moves have a higher probablity of being
  61                  * selected than unpopular ones.
  62                  */
  63                 Chess::GenericMove move(quint64 key) const;
  64
  65                 /*!
  66                  * Reads a book from \a filename.
  67                  * Returns true if successfull.
  68                  */
  69                 bool read(const QString& filename);
  70
  71                 /*!
  72                  * Writes the book to \a filename.
  73                  * Returns true if successfull.
  74                  */
  75                 bool write(const QString& filename) const;
  76
  77
  78         protected:
  79                 friend LIB_EXPORT QDataStream& operator>>(QDataStream& in, OpeningBook* book);
  80                 friend LIB_EXPORT QDataStream& operator<<(QDataStream& out, const OpeningBook* book);
  81
  82                 /*!
  83                  * \brief An entry in the opening book.
  84                  *
  85                  * \note Each entry is paired with a Zobrist key.
  86                  * \note The book file may not use the same structure
  87                  * for the entries.
  88                  */
  89                 struct Entry
  90                 {
  91                         /*! A book move. */
  92                         Chess::GenericMove move;
  93                         /*!
  94                          * A weight or score, usually based on popularity
  95                          * of the move. The higher the weight, the more
  96                          * likely the move will be played.
  97                          */
  98                         quint16 weight;
  99                 };
 100
 101                 /*! The type of binary tree. */
 102                 typedef QMultiMap<quint64, Entry> Map;
 103
 104
 105                 /*! Adds a new entry to the book. */
 106                 void addEntry(const Entry& entry, quint64 key);
 107
 108                 /*!
 109                  * Reads a new book entry from \a in.
 110                  *
 111                  * The implementation must call addEntry() to add the
 112                  * entry to the book.
 113                  */
 114                 virtual void readEntry(QDataStream& in) = 0;
 115
 116                 /*! Writes the key and entry pointed to by \a it, to \a out. */
 117                 virtual void writeEntry(const Map::const_iterator& it,
 118                                         QDataStream& out) const = 0;
 119
 120         private:
 121                 Map m_map;
 122 };
 123
 124 /*!
 125  * Reads a book from a data stream.
 126  *
 127  * \note Multiple book files can be appended to the same
 128  * OpeningBook object.
 129  */
 130 extern LIB_EXPORT QDataStream& operator>>(QDataStream& in, OpeningBook* book);
 131
 132 /*!
 133  * Writes a book to a data stream.
 134  *
 135  * \warning Do not write multiple OpeningBook objects to the same
 136  * data stream, because the books are likely to have duplicate
 137  * entries.
 138  */
 139 extern LIB_EXPORT QDataStream& operator<<(QDataStream& out, const OpeningBook* book);
 140
 141 #endif // OPENING_BOOK_H