# 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.