pgn_filter/about.md

pgn_filter

For searching/filtering pgn files 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 a collection of type pgn_filter::Games, and can be filtered using the search method. The search method takes a BoardFilter definition, which specifies the permitted number of pieces of each type, and returns a new collection containing just those games which match the definition.

For example, the following filter matches 5-4 rook-and-pawn endings, i.e. those with 5 white pawns, 4 black pawns and a rook on either side:

let filter = pgn_filter::Board::must_have()
    .exactly(1, "R")
    .exactly(1, "r")
    .exactly(5, "P")
    .exactly(4, "p");

Notice that the filter is constructed from a base filter obtained by calling "must_have". This base filter recognises positions with exactly one king of each colour, and no pieces or pawns. You build up the filter by adding a relation for each of the pieces you require. If you add a second filter for a given piece, the second filter will replace the first one.

The available filters are:

• "exactly(n, piece)"
• "at_least(n, piece)"
• "at_most(n, piece)"

Example: Extracting all 5-4 R+P endings

The following example shows how to construct a filter to identify 5-4 rook endings, and save the selected games to a file.

// Create a database and add some games
let mut db = pgn_filter::Games::new();
db.add_games("examples/twic1356.pgn").unwrap();

// Display some information
println!("Database has {} game(s)", db.iter().count());

// Create a position definition for 5-4 rook endings
let filter = pgn_filter::Board::must_have()
    .exactly(1, "R")
    .exactly(1, "r")
    .exactly(5, "P")
    .exactly(4, "p");

// Extract those games which at some point reach 
let selected = db.search(&filter);
selected.to_file("rook-endings.pgn").unwrap();

// Report and save result
println!("Selected {} out of {} games", selected.iter().count(), db.iter().count());

Example: Study a game move-by-move

The Game#play_game method takes a closure/function, 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:

let fischer = pgn_filter::Games::from_file("examples/fischer.pgn").unwrap();

println!("File has {} game(s)", fischer.games.len());

if fischer.games.len() > 0 {
    let game = &fischer.games[0];

    game.play_game(|board, next_move| {
        println!("{}", board.to_string());
        match next_move {
            Some(mv) => {
                // next move in the game
                println!(
                    "Move {}: {}{}",
                    board.fullmove_number,
                    if board.white_to_move { "" } else { "..." },
                    mv
                );
                println!("");
            }
            None => {
                // game over, so display the result
                println!("Result: {}", game.header.get("Result").unwrap());
            }
        };
    });
}

Sample output:

File has 1 game(s)
rnbqkbnr
pppppppp
........
........
........
........
PPPPPPPP
RNBQKBNR

Move 1: e4

rnbqkbnr
pppppppp
........
........
....P...
........
PPPP.PPP
RNBQKBNR

Move 1: ...e5

rnbqkbnr
pppp.ppp
........
....p...
....P...
........
PPPP.PPP
RNBQKBNR

Move 2: Nf3

rnbqkbnr
pppp.ppp
........
....p...
....P...
.....N..
PPPP.PPP
RNBQKB.R

Move 2: ...Nc6

r.bqkbnr
pppp.ppp
..n.....
....p...
....P...
.....N..
PPPP.PPP
RNBQKB.R

Move 3: Bb5

MIT Licence

Copyright (c) 2020-23, Peter Lane peterlane@gmx.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.