libagchess Alpha - C++ chess library

Update

I included a small demo file (and absolutely terrible makefile) briefly illustrating how to use the StandardPosition class (which is kinda an important one).  Demo will be updated later to include other aspects of the library too.

As CBase Chess goes through some updates, I wanted to provide the community with something that might be of use - the code for the C++ backend which powers CBase Chess!  It is on Sourceforge available here.  I've put the project in alpha stage simply because the documentation is lacking.  However, if you're interested in seeing what I've come up with, the code is free for you to browse around and is available for your own use under the GNU General Public License v3.  There are numerous comments in the code, but I will try and give a good overview of what libagchess is all about.

The low-level stuff

libagchess is a C++ bitboard-based library meant for use with chess databases (as opposed to chess engines).  There are 5 "primitive" types used extensively in the library:

• Color - for indicating the side to move and color of a piece.
• Piece - King, Queen, Rook, Bishop, Knight, Pawn, or none - used when you don't care what color the piece is
• ColoredPiece - has information for both piece and color.
• Square - one always wants to know what pieces are on what square, and what squares are valid targets to move to, etc.
• Bitboard - a typedef for an unsigned 64-bit integral value.  The merits of using a bitboard as the basis for chess programming can be read here.

The other classes in libagchess use these "primitives" quite extensively.  A bitboard in itself has no meaning without context - is it a bitboard of squares attacked by black pieces?  Maybe it's an occupancy bitboard for white pawns?  There are numerous uses for bitboards, though the one that really stands out is to indicate occupancy.  Occupancy bitboards indicate which squares are occupied by which pieces.  The BasicBoard class wraps occupancy bitboards for each piece of each color, and also provides a means of accessing which ColoredPiece is at a given Square.  A BasicBoard provides no state-dependent context, simply the arrangement of the pieces on the board (think about the information you would get if you walked up to a chess game and just looked at the board - you wouldn't necessarily know whose move it was, or who had castling rights, or if there was an en-passant square).

Chess Position - because you have to represent game state somehow!

The state-aware object is a Position object.  The Position object encapsulates the data about side to move, castling rights, en passant square, piece locations on the board, and even half-move clock (for 50-move rule).  Position itself is an abstract base class that provides the basic accessors to the general information it holds.  There are two concrete subclasses of Position: SimplePosition and EditablePosition.  EditablePositions allow one to directly manipulate the position state, while SimplePosition (and its subclasses) only allow manipulation using Move objects via make (to make a move) and unmake (to undo a move).

The SimplePosition was meant to be a base class which provided the make and unmake interface, but did not enforce any chess rules, thus one could move any piece to any square and not worry about the legality of such a move.  The SimplePosition class is not actually finished because it's usefulness in a chess database program is quite limited.  The class which actually knows and enforces the standard chess rules is StandardPosition.  The StandardPosition can only be manipulated with make and unmake and throws an exception if the Move is illegal.  The StandardPosition is meant to always stay in a consistent, legal chess state.

The EditablePosition provides the methods necessary to set up a position.  It doesn't know any rules, but like it's base class, keeps track of state information such as en-passant square, castling, etc.  When the EditablePosition is ready to be used, theStandardPosition can set its state to that of the EditablePosition using the member function StandardPosition.copy(EditablePosition).  This will throw an exception if theEditablePosition is not a legal chess position.

Chess Game - a collection of Positions

Wow, that was a mouthful.  Ok, so that's the fundamental material for representing a single chess position.  What about playing through a whole game?  In libagchess, a chess game is viewed as two parts - the header information about the game, and the moves it makes, and so the classes are GameHeader and GameTree.  A StandardChessGameinherits from both of these objects and provides an interface for constructing and reviewing a chess game.

The GameHeader is fairly simple, and merely provides access to information on who the players are, when the game was played, the name of the tournament, etc.

The GameTree can be abstractly thought of as a tree of StandardPosition objects (Really should be Position objects, but I was only interested in the concrete case of havingStandardPosition).  It has a root position, and child positions.  Instead of containing aStandardPosition at every node, which would be prohibitively expensive, it contains the information to reach a child position compressed in a Move.  A GameTree is most easily thought of as a container object for positions - thus an iterator class is provided.

The iterator allows for insertion of a Move into the tree, and dereferences to aStandardPosition.  I thought it was most logical to use iterators to access the moves and positions from a GameTree, so hopefully anybody reading this will find it easy to use.  I think I will make it a priority to document this class more carefully and uploaded it to Sourceforge soon, since it's the key method of playing through and creating chess games.

Database - because sometimes you need a collection of collections of Positions, aka a collection of Games

And finally we get to the database.  libagchess was designed as a database for reading PGN files.  The PGNDatabase is actually rather simple - tell it to load a PGN database and it does a quick parse of the file to locate where each game starts and ends.  It knows how many games are in a database, and will return a StandardChessGame object usingdatabase.getGame(int index), assuming that index is less than the number of games in the database.  When a game is loaded, it is parsed and placed entirely into memory ready to review.  A StandardChessGame loaded from a PGNDatabase is guaranteed to have no illegal moves, as an exception is thrown if the database encounters any illegal moves when loading the game.  To access only the header information without loading the rest of the game, use database.headers(int index).

Final words

This post contains a lot more information than I thought it would when I first started writing it.  Hopefully it provides a small overview as to how the classes in libagchess were meant to be used (or at least how they're used by me).  There is also a class for filtering games from a database, DatabaseFilter, which uses subclasses of SearchMask to locate games in a database that match the SearchMask.  I'm not 100% sure that theDatabaseFilter is how I want to go about searching databases, but I included it with the library since somebody might find it useful.