chess_data

= chess-data

Install from {RubyGems}[https://rubygems.org/gems/chess-data/]:

> gem install chess-data

source:: {chess-data.zip}[http://peterlane.info/downloads/chess-data.zip]

== Description

For searching/filtering datasets of chess games.

Features

* Read and save collections of PGN files
* Filter games looking for games containing positions with certain combinations
of pieces
* Save collections of PGN games or individual positions after filtering.
* PGN lexer follows specification in https://www.chessclub.com/help/PGN-spec
* note that the lexer recognises but ignores comments and NAGs, so they will
not appear in any resaved games

== Position Definitions

Games are stored in an instance of +ChessData+::+Database+, and can be filtered using
the +search+ method. The search method takes a block defining the numbers of pieces of
each type and returns a new database containing just those games which match the
definition. For example, the following filters for 5-4 rook endings:

rook_endings_database = database.search do
exactly 1, "R", "r"
exactly 5, "P"
exactly 4, "p"
end

Filters include:

* 'exactly n, *pieces'
* 'at_least n, *pieces'
* 'at_most n, *pieces'

== Example: Extracting all 5-4 R+P endings

# Read database of games and query

require 'chess-data'

# create a database
database = ChessData::Database.new

# read in pgn files provided on command line and add them to the database
ARGV.each do |file|
puts "Reading from #{file}"
database.add_games_from file
end

# extract those games which at some point reach given position definition
selected = database.search do
exactly 1, "R", "r"
exactly 5, "P"
exactly 4, "p"
end

# report and save result
puts "Found #{selected.size} games"
selected.to_file "selected.pgn"

puts "Selected #{selected.size} out of #{database.size}"

== Example: Study a game move-by-move

The ChessData::Game#play_game method takes a block, which is passed the current
board and next move after each half move. The following example prints out the
board position and information to create a trace of the game:

$game.play_game do |board, next_move|
puts board.to_s
puts
puts "Move #{board.fullmove_number}: #{if board.to_move == "w" then "" else "... " end}#{next_move}"
end

Sample output:

Move 32: Rxd7+
........
..kR...p
....pb.Q
........
..P..Pq.
.Pn.....
......P.
......BK

Move 32: ... Kxd7
........
...k...p
....pb.Q
........
..P..Pq.
.Pn.....
......P.
......BK

Move 33: Qxf6
........
...k...p
....pQ..
........
..P..Pq.
.Pn.....
......P.
......BK

Move 33: ... 1/2-1/2